public interface TypeCodec<JavaTypeT>
Type codec implementations:
nullvalues and empty byte buffers (i.e.
) in a reasonable way; usually,
NULLCQL values should map to
nullreferences, but exceptions exist; e.g. for varchar types, a
NULLCQL value maps to a
nullreference, whereas an empty buffer maps to an empty String. For collection types, it is also admitted that
NULLCQL values map to empty Java collections instead of
nullreferences. In any case, the codec's behavior with respect to
nullvalues and empty ByteBuffers should be clearly documented.
boolean. This allows the driver to avoid the overhead of boxing when using primitive accessors such as
ByteBufferinstances by performing relative read operations that modify their current position; codecs should instead prefer absolute read methods or, if necessary,
duplicatetheir byte buffers prior to reading them.
|Modifier and Type||Method and Description|
Whether this codec is capable of processing the given Java class.
Whether this codec is capable of processing the given CQL type.
Whether this codec is capable of processing the given Java type.
Whether this codec is capable of encoding the given Java object.
Decodes a value from the binary format of the CQL type handled by this codec.
Encodes the given value in the binary format of the CQL type handled by this codec.
Formats the given value as a valid CQL literal according to the CQL type handled by this codec.
Parse the given CQL literal into an instance of the Java type handled by this codec.
@NonNull GenericType<JavaTypeT> getJavaType()
@NonNull DataType getCqlType()
default boolean accepts(@NonNull GenericType<?> javaType)
The default implementation is invariant with respect to the passed argument
(through the usage of
GenericType.equals(Object)) and it's strongly recommended not
to modify this behavior. This means that a codec will only ever accept the exact
Java type that it has been created for.
If the argument represents a Java primitive type, its wrapper type is considered instead.
default boolean accepts(@NonNull Class<?> javaClass)
This implementation simply compares the given class (or its wrapper type if it is a
primitive type) against this codec's runtime (raw) class; it is invariant with respect
to the passed argument (through the usage of
Object.equals(Object) and it's strongly
recommended not to modify this behavior. This means that a codec will only ever return
true for the exact runtime (raw) Java class that it has been created for.
Implementors are encouraged to override this method if there is a more efficient way. In
particular, if the codec targets a final class, the check can be done with a simple
default boolean accepts(@NonNull Object value)
The object's Java type is inferred from its runtime (raw) type, contrary to
accepts(GenericType) which is capable of handling generic types.
Contrary to other
accept methods, this method's default implementation is
covariant with respect to the passed argument (through the usage of
Class.isAssignableFrom(Class)) and it's strongly recommended not to modify this
behavior. This means that, by default, a codec will accept any subtype of the
Java type that it has been created for. This is so because codec lookups by arbitrary Java
objects only make sense when attempting to encode, never when attempting to decode, and indeed
the encode method is covariant with
It can only handle non-parameterized types; codecs handling parameterized types, such as collection types, must override this method and perform some sort of "manual" inspection of the actual type parameters.
Similarly, codecs that only accept a partial subset of all possible values must override this method and manually inspect the object to check if it complies or not with the codec's limitations.
Finally, if the codec targets a non-generic Java class, it might be possible to implement
this method with a simple
default boolean accepts(@NonNull DataType cqlType)
@Nullable ByteBuffer encode(@Nullable JavaTypeT value, @NonNull ProtocolVersion protocolVersion)
nullinput as the equivalent of an empty collection.
@Nullable JavaTypeT decode(@Nullable ByteBuffer bytes, @NonNull ProtocolVersion protocolVersion)
nullor a default value for the corresponding Java type, if applicable;
null; they should return empty collections instead (the driver's default collection codecs all comply with this rule);
ByteBuffershould never be consumed by read operations that modify its current position; if necessary,
ByteBuffer.duplicate()duplicate} it before consuming.
@NonNull String format(@Nullable JavaTypeT value)
Implementors should take care of quoting and escaping the resulting CQL literal where
applicable. Null values should be accepted; in most cases, implementations should return the
Implementing this method is not strictly mandatory. It is used:
toString()representation of some driver objects (such as
TupleValue), which is only used in driver logs;
@Nullable JavaTypeT parse(@Nullable String value)
Implementors should take care of unquoting and unescaping the given CQL string where
applicable. Null values and empty strings should be accepted, as well as the string
"NULL"; in most cases, implementations should interpret these inputs has equivalent to a
Implementing this method is not strictly mandatory: internally, the driver only uses it to
parse the INITCOND when building the
metadata of an aggregate
function (and in most cases it will use a built-in codec, unless the INITCOND has a custom
If you choose not to implement this method, don't throw an exception but instead return
Copyright © 2017–2023. All rights reserved.