Package org.apache.hadoop.hbase.types

Class Struct

java.lang.Object
org.apache.hadoop.hbase.types.Struct
All Implemented Interfaces:
DataType<Object[]>
@Public public class Struct extends Object implements DataType<Object[]>

Struct is a simple DataType for implementing "compound rowkey" and "compound qualifier" schema design strategies.

Encoding

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.

Trailing Nulls

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

Sort Order

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.

See Also:

  • Field Details

  • Constructor Details

    • Struct

      public Struct(DataType[] memberTypes)
      Create a new Struct instance defined as the sequence of HDataTypes in memberTypes.

      A Struct is orderPreserving when all of its fields are orderPreserving. A Struct is skippable when all of its fields are skippable.

  • Method Details

    • isOrderPreserving

      public boolean isOrderPreserving()
      Description copied from interface: DataType
      Indicates whether this instance writes encoded byte[]'s which preserve the natural sort order of the unencoded value.
      Specified by:
      isOrderPreserving in interface DataType<Object[]>
      Returns:
      true when natural order is preserved, false otherwise.

    • getOrder

      public Order getOrder()
      Description copied from interface: DataType
      Retrieve the sort 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.
      Specified by:
      getOrder in interface DataType<Object[]>

    • isNullable

      public boolean isNullable()
      Description copied from interface: DataType
      Indicates whether this instance supports encoding null values. This depends on the implementation details of the encoding format. All DataTypes that support null should treat null as comparing less than any non-null value for default sort ordering purposes.
      Specified by:
      isNullable in interface DataType<Object[]>
      Returns:
      true when null is supported, false otherwise.

    • isSkippable

      public boolean isSkippable()
      Description copied from interface: DataType
      Indicates whether this instance is able to skip over it's encoded value. DataTypes that are not skippable can only be used as the right-most field of a Struct.
      Specified by:
      isSkippable in interface DataType<Object[]>

    • encodedLength

      public int encodedLength(Object[] val)
      Description copied from interface: DataType
      Inform consumers how long the encoded byte[] will be.
      Specified by:
      encodedLength in interface DataType<Object[]>
      Parameters:
      val - The value to check.
      Returns:
      the number of bytes required to encode val.a

    • encodedClass

      public Class<Object[]> encodedClass()
      Description copied from interface: DataType
      Inform consumers over what type this DataType operates. Useful when working with bare DataType instances.
      Specified by:
      encodedClass in interface DataType<Object[]>

    • iterator

      public StructIterator iterator(PositionedByteRange src)
      Retrieve an Iterator over the values encoded in src. src's position is consumed by consuming this iterator.

    • skip

      public int skip(PositionedByteRange src)
      Description copied from interface: DataType
      Skip src's position forward over one encoded value.
      Specified by:
      skip in interface DataType<Object[]>
      Parameters:
      src - the buffer containing the encoded value.
      Returns:
      number of bytes skipped.

    • decode

      public Object[] decode(PositionedByteRange src)
      Description copied from interface: DataType
      Read an instance of T from the buffer src.
      Specified by:
      decode in interface DataType<Object[]>
      Parameters:
      src - the buffer containing the encoded value.

    • decode

      public Object decode(PositionedByteRange src, int index)
      Read the field at index. src's position is not affected.

    • encode

      public int encode(PositionedByteRange dst, Object[] val)
      Description copied from interface: DataType
      Write instance val into buffer dst.
      Specified by:
      encode in interface DataType<Object[]>
      Parameters:
      dst - the buffer containing the encoded value.
      val - the value to encode onto dst.
      Returns:
      number of bytes written.