Package org.apache.druid.segment.serde.cell

Interface StagedSerde<T>

Type Parameters:
T -
All Known Implementing Classes:
AbstractSerializablePairLongObjectDeltaEncodedStagedSerde, AbstractSerializablePairLongObjectSimpleStagedSerde, SerializablePairLongDoubleDeltaEncodedStagedSerde, SerializablePairLongDoubleSimpleStagedSerde, SerializablePairLongFloatDeltaEncodedStagedSerde, SerializablePairLongFloatSimpleStagedSerde, SerializablePairLongLongDeltaEncodedStagedSerde, SerializablePairLongLongSimpleStagedSerde, SerializablePairLongStringDeltaEncodedStagedSerde, SerializablePairLongStringSimpleStagedSerde
public interface StagedSerde<T>
StagedSerde is useful when you have objects that have their own internal logic to serialize, but you wish to compose the results of multiple serialized objects into a single ByteBuffer (or wrapped byte[]). Serializers can implement serializeDelayed and return a StorableBuffer. This object allows the serialization to be broken up so that serializers do whatever work is necessary to report how many bytes are needed. The caller can then allocate a large enough byte[], wrap it in a ByteBuffer, and use the StorableBuffer.store() method.

This results in superior efficiency over a byte[] toBytes() method because repeated copies of byte[] are avoided.

Since any serialization that returns a byte[] must reach a point in its serialization that it allocates said byte[], that code may be executed to create the StorableBuffer. What code would have written to a byte[] then makes calls to a ByteBuffer in the store() method.

For the cases when it is not easy to break apart the serialization code, increased efficiency may be obtained by overriding serialize() and directly returning bytes

example 


   StagedSerde<Fuu> fuuSerde = new ...;
   StagedSerde<Bar> barerde = new ...;
   StorableBuffer fuuBuffer = fuuSerde.serializeDelayed(fuuInstance);
   StorableBuffer barBuffer = barSerde.serializeDelayed(barInstance);
   int size = fuuBuffer.getSerializedSize() + barBuffer.getSerializedSize();
   byte[] bytes = new byte[size];
   ByteBuffer buffer = ByteBuffer.wrap(bytes).order(ByteOrder.nativeOrder());

   fuuBuffer.store(buffer);
   barBuffer.store(buffer);

Note that for a common case in which you want a byte[] for a single object, a default implementation is provided that does the above code for a single object.

  • Method Summary

    Modifier and Type
    Method
    Description
    default T
    deserialize(byte[] bytes)
     
    T
    deserialize(ByteBuffer byteBuffer)
     
    static StagedSerde<byte[]>
    forBytes()
     
    default byte[]
    serialize(T value)
    Default implementation for when a byte[] is desired.
    StorableBuffer
    serializeDelayed(T value)
    Useful method when some computation is necessary to prepare for serialization without actually writing out all the bytes in order to determine the serialized size.

  • Method Details

    • forBytes

      static StagedSerde<byte[]> forBytes()

    • serializeDelayed

      StorableBuffer serializeDelayed(@Nullable T value)
      Useful method when some computation is necessary to prepare for serialization without actually writing out all the bytes in order to determine the serialized size. It allows encapsulation of the size computation and the final logical to actually store into a ByteBuffer. It also allows for callers to pack multiple serialized objects into a single ByteBuffer without extra copies of a byte[]/ByteBuffer by using the StorableBuffer instance returned
      Parameters:
      value - - object to serialize
      Returns:
      an object that reports its serialized size and how to serialize the object to a ByteBuffer

    • serialize

      default byte[] serialize(T value)
      Default implementation for when a byte[] is desired. Typically, this default should suffice. Implementing serializeDelayed() includes the logic of how to store into a ByteBuffer
      Parameters:
      value - - object to serialize
      Returns:
      serialized byte[] of value

    • deserialize

      @Nullable T deserialize(ByteBuffer byteBuffer)

    • deserialize

      default T deserialize(byte[] bytes)