Package org.apache.druid.segment.column
Interface TypeStrategy<T>
-
- All Superinterfaces:
Comparator<Object>
- All Known Implementing Classes:
ObjectStrategyComplexTypeStrategy
,TypeStrategies.ArrayTypeStrategy
,TypeStrategies.DoubleTypeStrategy
,TypeStrategies.FloatTypeStrategy
,TypeStrategies.LongTypeStrategy
,TypeStrategies.StringTypeStrategy
public interface TypeStrategy<T> extends Comparator<Object>
TypeStrategy provides value comparison and binary serialization for Druid types. This can be obtained for ANY Druid type viaTypeSignature.getStrategy()
. IMPORTANT!!! DO NOT USE THIS FOR WRITING COLUMNS, THERE ARE VERY LIKELY FAR BETTER WAYS TO DO THIS. However, if you need to store a single value or small number of values, continue reading. ALSO IMPORTANT!!! This is primarily intended for writing ephemeral values within a single process, and is not especially well suited (by itself) for persistent storage of data or cross process transfer. The support typically necessary for such more persistent storage, such as tracking version of a format or endianness of the values, should be handled externally to support these use cases. All implementations of this mechanism support reading and writing ONLY non-null values. To handle nulls inline with your values, considerNullableTypeStrategy
, which might be acceptable to use if you need to read and write nullable values, AND, you have enough memory to burn a full byte for every value you want to store. It will store values with a leading byte containing eitherNullHandling.IS_NULL_BYTE
orNullHandling.IS_NOT_NULL_BYTE
as appropriate. If you have a lot of values to write and a lot of nulls, consider alternative approaches to tracking your nulls instead. This mechanism allows using the naturalBuffer.position()
and modify the underlying position as they operate, and also random access reads are specific offets, which do not modify the underlying position. If a method accepts an offset parameter, it does not modify the position, if not, it does. The only methods implementors are required to provide areread(ByteBuffer)
,write(ByteBuffer, Object, int)
andestimateSizeBytes(Object)
, default implementations are provided to set and reset buffer positions as appropriate for the offset based methods, but may be overridden if a more optimized implementation is needed. Implementations of this interface should be thread safe, but may not useByteBuffer
in a thread safe manner, potentially modifying positions and limits, either temporarily or permanently depending on which set of methods is called. This interface extendsComparator<Object>
instead ofComparator<T>
because trying to specialize the type of the comparison method can run into issues for comparators of objects that can sometimes be of a different java class type. For example,Comparator<Long>
cannot accept Integer objects in its comparison method and there is no easy way for this interface definition to allowTypeStrategy<Long>
to actually be aComparator<Number>
. So, we fall back to effectively erasing the generic type and having them all beComparator<Object>
.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description int
estimateSizeBytes(T value)
Estimate the size in bytes that writing this value to memory would require.default T
fromBytes(byte[] value)
Translate raw byte array into a value.T
read(ByteBuffer buffer)
Read a non-null value from theByteBuffer
at the currentBuffer.position()
.default T
read(ByteBuffer buffer, int offset)
Read a non-null value from theByteBuffer
at the requested position.boolean
readRetainsBufferReference()
Whether theread(java.nio.ByteBuffer)
methods return an object that may retain a reference to the providedByteBuffer
.default int
write(ByteBuffer buffer, int offset, T value, int maxSizeBytes)
Write a non-null value to theByteBuffer
at the requested position.int
write(ByteBuffer buffer, T value, int maxSizeBytes)
Write a non-null value to theByteBuffer
at positionBuffer.position()
.-
Methods inherited from interface java.util.Comparator
compare, equals, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong
-
-
-
-
Method Detail
-
estimateSizeBytes
int estimateSizeBytes(T value)
Estimate the size in bytes that writing this value to memory would require. This method is not required to be exactly correct, but many implementations might be. Implementations should err on the side of over-estimating if exact sizing is not efficient. Example usage of this method is estimating heap memory usage for an aggregator or the amount of buffer which might need allocated to thenwrite(java.nio.ByteBuffer, T, int)
a value
-
read
T read(ByteBuffer buffer)
Read a non-null value from theByteBuffer
at the currentBuffer.position()
. This will move the underlying position by the size of the value read. The value returned from this method may retain a reference to the providedByteBuffer
. If it does, thenreadRetainsBufferReference()
returns true.
-
readRetainsBufferReference
boolean readRetainsBufferReference()
Whether theread(java.nio.ByteBuffer)
methods return an object that may retain a reference to the providedByteBuffer
. If a reference is sometimes retained, this method returns true. It returns false if, and only if, a reference is *never* retained.
-
write
int write(ByteBuffer buffer, T value, int maxSizeBytes)
Write a non-null value to theByteBuffer
at positionBuffer.position()
. This will move the underlying position by the size of the value written. This method returns the number of bytes written. If writing the value would take more than 'maxSizeBytes', this method will return a negative value indicating the number of additional bytes that would be required to fully write the value. Partial results may be written to the buffer when in this state, and the position may be left at whatever point the implementation ran out of space while writing the value. Callers should save the starting position if it is necessary to 'rewind' after a partial write. Callers MUST check that the return value is positive which indicates a successful write, while a negative response a partial write.- Returns:
- number of bytes written
-
read
default T read(ByteBuffer buffer, int offset)
Read a non-null value from theByteBuffer
at the requested position. This will not permanently move the underlyingBuffer.position()
, but may temporarily modify the buffer position during reading so cannot be considered thread safe usage of the buffer. The contract of this method is that any value returned from this method MUST be completely detached from the underlyingByteBuffer
, since it might outlive the memory location being allocated to hold the object. In other words, if an object is memory mapped, it must be copied on heap, or relocated to another memory location that is owned by the caller withwrite(java.nio.ByteBuffer, T, int)
.
-
write
default int write(ByteBuffer buffer, int offset, T value, int maxSizeBytes)
Write a non-null value to theByteBuffer
at the requested position. This will not permanently move the underlyingBuffer.position()
, but may temporarily modify the buffer position during reading so cannot be considered thread safe usage of the buffer. This method returns the number of bytes written. If writing the value would take more than 'maxSizeBytes', this method will return a negative value indicating the number of additional bytes that would be required to fully write the value. Partial results may be written to the buffer when in this state, but the underlying buffer position will be unaffected regardless of whether a write operation was successful or not. Callers MUST check that the return value is positive which indicates a successful write, while a negative response a partial write.- Returns:
- number of bytes written
-
fromBytes
default T fromBytes(byte[] value)
Translate raw byte array into a value. This is primarily useful for transforming self contained values that are serialized into byte arrays, such as happens with 'COMPLEX' types which serialize to base64 strings in JSON responses. 'COMPLEX' types should implement this method to participate in the expression systems built-in function to deserialize base64 encoded values,BuiltInExprMacros.ComplexDecodeBase64ExprMacro
.
-
-