@InterfaceAudience.Public public class Struct extends Object implements DataType<Object[]>
Struct is a simple DataType for implementing "compound
rowkey" and "compound qualifier" schema design strategies.
Struct member values are encoded onto the target byte[] in the order
in which they are declared. A Struct may be used as a member of
another Struct. Structs are not nullable but their
component fields may be.
Struct treats the right-most nullable field members as special.
Rather than writing null values to the output buffer, Struct omits
those records all together. When reading back a value, it will look for the
scenario where the end of the buffer has been reached but there are still
nullable fields remaining in the Struct definition. When this
happens, it will produce null entries for the remaining values. For example:
StructBuilder builder = new StructBuilder()
.add(OrderedNumeric.ASCENDING) // nullable
.add(OrderedString.ASCENDING) // nullable
Struct shorter = builder.toStruct();
Struct longer = builder.add(OrderedNumeric.ASCENDING) // nullable
.toStruct();
PositionedByteRange buf1 = new SimplePositionedByteRange(7);
PositionedByteRange buf2 = new SimplePositionedByteRange(7);
Object[] val = new Object[] { BigDecimal.ONE, "foo" };
shorter.encode(buf1, val); // write short value with short Struct
buf1.setPosition(0); // reset position marker, prepare for read
longer.decode(buf1); // => { BigDecimal.ONE, "foo", null } ; long Struct reads implied null
longer.encode(buf2, val); // write short value with long struct
Bytes.equals(buf1.getBytes(), buf2.getBytes()); // => true; long Struct skips writing null
Struct instances sort according to the composite order of their
fields, that is, left-to-right and depth-first. This can also be thought of
as lexicographic comparison of concatenated members.
StructIterator is provided as a convenience for consuming the
sequence of values. Users may find it more appropriate to provide their own
custom DataType for encoding application objects rather than using
this Object[] implementation. Examples are provided in test.
StructIterator,
DataType.isNullable()| Modifier and Type | Field and Description |
|---|---|
protected DataType[] |
fields |
protected boolean |
isOrderPreserving |
protected boolean |
isSkippable |
| Constructor and Description |
|---|
Struct(DataType[] memberTypes)
Create a new
Struct instance defined as the sequence of
HDataTypes in memberTypes. |
| Modifier and Type | Method and Description |
|---|---|
Object[] |
decode(PositionedByteRange src)
Read an instance of
T from the buffer src. |
Object |
decode(PositionedByteRange src,
int index)
Read the field at
index. |
int |
encode(PositionedByteRange dst,
Object[] val)
Write instance
val into buffer dst. |
Class<Object[]> |
encodedClass()
Inform consumers over what type this
DataType operates. |
int |
encodedLength(Object[] val)
Inform consumers how long the encoded
byte[] will be. |
Order |
getOrder()
Retrieve the sort
Order imposed by this data type, or null when
natural ordering is not preserved. |
boolean |
isNullable()
Indicates whether this instance supports encoding null values.
|
boolean |
isOrderPreserving()
Indicates whether this instance writes encoded
byte[]'s
which preserve the natural sort order of the unencoded value. |
boolean |
isSkippable()
Indicates whether this instance is able to skip over it's encoded value.
|
StructIterator |
iterator(PositionedByteRange src)
Retrieve an
Iterator over the values encoded in src. |
int |
skip(PositionedByteRange src)
Skip
src's position forward over one encoded value. |
protected final boolean isOrderPreserving
protected final boolean isSkippable
public boolean isOrderPreserving()
DataTypebyte[]'s
which preserve the natural sort order of the unencoded value.isOrderPreserving in interface DataType<Object[]>true when natural order is preserved,
false otherwise.public Order getOrder()
DataTypeOrder imposed by this data type, or null when
natural ordering is not preserved. Value is either ascending or
descending. Default is assumed to be Order.ASCENDING.public boolean isNullable()
DataTypeDataTypes that support null should treat null as comparing
less than any non-null value for default sort ordering purposes.isNullable in interface DataType<Object[]>true when null is supported, false otherwise.public boolean isSkippable()
DataTypeDataTypes that are not skippable can only be used as the
right-most field of a Struct.isSkippable in interface DataType<Object[]>public int encodedLength(Object[] val)
DataTypebyte[] will be.encodedLength in interface DataType<Object[]>val - The value to check.val.apublic Class<Object[]> encodedClass()
DataTypeDataType operates. Useful
when working with bare DataType instances.encodedClass in interface DataType<Object[]>public StructIterator iterator(PositionedByteRange src)
Iterator over the values encoded in src.
src's position is consumed by consuming this iterator.public int skip(PositionedByteRange src)
DataTypesrc's position forward over one encoded value.public Object[] decode(PositionedByteRange src)
DataTypeT from the buffer src.public Object decode(PositionedByteRange src, int index)
index. src's position is not affected.public int encode(PositionedByteRange dst, Object[] val)
DataTypeval into buffer dst.Copyright © 2007–2019 The Apache Software Foundation. All rights reserved.