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)
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 Detail

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)