@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
. Struct
s 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 HDataType s 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()
DataType
byte[]
'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()
DataType
Order
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()
DataType
DataType
s 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()
DataType
DataType
s 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)
DataType
byte[]
will be.encodedLength
in interface DataType<Object[]>
val
- The value to check.val
.apublic Class<Object[]> encodedClass()
DataType
DataType
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)
DataType
src
's position forward over one encoded value.public Object[] decode(PositionedByteRange src)
DataType
T
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)
DataType
val
into buffer dst
.Copyright © 2007–2020 The Apache Software Foundation. All rights reserved.