com.datastax.oss.driver.api.core.type.codec

Interface TypeCodec<JavaTypeT>

All Known Subinterfaces:

PrimitiveBooleanCodec, PrimitiveByteCodec, PrimitiveDoubleCodec, PrimitiveFloatCodec, PrimitiveIntCodec, PrimitiveLongCodec, PrimitiveShortCodec

All Known Implementing Classes:

MappingCodec

public interface TypeCodec<JavaTypeT>

Manages the two-way conversion between a CQL type and a Java type.

Type codec implementations:

1. must be thread-safe.
2. must perform fast and never block.
3. must support all native protocol versions; it is not possible to use different codecs for the same types but under different protocol versions.
4. must comply with the native protocol specifications; failing to do so will result in unexpected results and could cause the driver to crash.
5. should be stateless and immutable.
6. should interpret null values and empty byte buffers (i.e. Buffer.remaining() == 0) in a reasonable way; usually, NULL CQL values should map to null references, but exceptions exist; e.g. for varchar types, a NULL CQL value maps to a null reference, whereas an empty buffer maps to an empty String. For collection types, it is also admitted that NULL CQL values map to empty Java collections instead of null references. In any case, the codec's behavior with respect to null values and empty ByteBuffers should be clearly documented.
7. for Java types that have a primitive equivalent, should implement the appropriate "primitive" codec interface, e.g. PrimitiveBooleanCodec for boolean. This allows the driver to avoid the overhead of boxing when using primitive accessors such as GettableByIndex.getBoolean(int).
8. when decoding, must not consume ByteBuffer instances by performing relative read operations that modify their current position; codecs should instead prefer absolute read methods or, if necessary, duplicate their byte buffers prior to reading them.

Method Summary

Modifier and Type	Method and Description
default boolean	accepts(Class<?> javaClass) Whether this codec is capable of processing the given Java class.
default boolean	accepts(DataType cqlType) Whether this codec is capable of processing the given CQL type.
default boolean	accepts(GenericType<?> javaType) Whether this codec is capable of processing the given Java type.
default boolean	accepts(Object value) Whether this codec is capable of encoding the given Java object.
JavaTypeT	decode(ByteBuffer bytes, ProtocolVersion protocolVersion) Decodes a value from the binary format of the CQL type handled by this codec.
ByteBuffer	encode(JavaTypeT value, ProtocolVersion protocolVersion) Encodes the given value in the binary format of the CQL type handled by this codec.
String	format(JavaTypeT value) Formats the given value as a valid CQL literal according to the CQL type handled by this codec.
DataType	getCqlType()
GenericType<JavaTypeT>	getJavaType()
JavaTypeT	parse(String value) Parse the given CQL literal into an instance of the Java type handled by this codec.

Method Detail

getJavaType

@NonNull
GenericType<JavaTypeT> getJavaType()

getCqlType

@NonNull
DataType getCqlType()

accepts

default boolean accepts(@NonNull
                        GenericType<?> javaType)

Whether this codec is capable of processing the given Java type.

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.

accepts

default boolean accepts(@NonNull
                        Class<?> javaClass)

Whether this codec is capable of processing the given Java class.

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 ==.

accepts

default boolean accepts(@NonNull
                        Object value)

Whether this codec is capable of encoding the given Java object.

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 JavaTypeT.

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 instanceof check.

accepts

default boolean accepts(@NonNull
                        DataType cqlType)

Whether this codec is capable of processing the given CQL type.

encode

@Nullable
ByteBuffer encode(@Nullable
                            JavaTypeT value,
                            @NonNull
                            ProtocolVersion protocolVersion)

Encodes the given value in the binary format of the CQL type handled by this codec.

• Null values should be gracefully handled and no exception should be raised; they should be considered as the equivalent of a NULL CQL value;
• Codecs for CQL collection types should not permit null elements;
• Codecs for CQL collection types should treat a null input as the equivalent of an empty collection.

decode

@Nullable
JavaTypeT decode(@Nullable
                           ByteBuffer bytes,
                           @NonNull
                           ProtocolVersion protocolVersion)

Decodes a value from the binary format of the CQL type handled by this codec.

• Null or empty buffers should be gracefully handled and no exception should be raised; they should be considered as the equivalent of a NULL CQL value and, in most cases, should map to null or a default value for the corresponding Java type, if applicable;
• Codecs for CQL collection types should clearly document whether they return immutable collections or not (note that the driver's default collection codecs return mutable collections);
• Codecs for CQL collection types should avoid returning null; they should return empty collections instead (the driver's default collection codecs all comply with this rule);
• The provided ByteBuffer should never be consumed by read operations that modify its current position; if necessary, ByteBuffer.duplicate() duplicate} it before consuming.

format

@NonNull
String format(@Nullable
                       JavaTypeT value)

Formats the given value as a valid CQL literal according to the CQL type handled by this codec.

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 CQL keyword "NULL" for null inputs.

Implementing this method is not strictly mandatory. It is used:

1. by the request logger, if parameter logging is enabled;
2. to format the INITCOND in AggregateMetadata.describe(boolean);
3. in the toString() representation of some driver objects (such as UdtValue and TupleValue), which is only used in driver logs;
4. for literal values in the query builder (see QueryBuilder#literal(Object, CodecRegistry) and QueryBuilder#literal(Object, TypeCodec)).

If you choose not to implement this method, don't throw an exception but instead return a constant string (for example "XxxCodec.format not implemented").

parse

@Nullable
JavaTypeT parse(@Nullable
                          String value)

Parse the given CQL literal into an instance of the Java type handled by this codec.

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 null reference.

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 type).

If you choose not to implement this method, don't throw an exception but instead return null.