@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–2020 The Apache Software Foundation. All rights reserved.