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

Interface CodecRegistry

All Known Subinterfaces:

MutableCodecRegistry

public interface CodecRegistry

Provides codecs to convert CQL types to their Java equivalent, and vice-versa.

Implementations MUST provide a default mapping for all CQL types (primitive types, and all the collections, tuples or user-defined types that can recursively be built from them — see DataTypes).

They may also provide additional mappings to other Java types (for use with methods such as GettableByIndex.get(int, Class), SettableByIndex.set(int, Object, Class), etc.)

The default implementation returned by the driver also implements MutableCodecRegistry, and we strongly recommend that custom implementations do as well. The two interfaces are only separate for backward compatibility, because mutability was introduced in 4.3.0.

Field Summary

Fields

Modifier and Type	Field and Description
static CodecRegistry	DEFAULT An immutable instance, that only handles built-in driver types (that is, primitive types, and collections, tuples, and user defined types thereof).

Method Summary

Modifier and Type	Method and Description
default <JavaTypeT> TypeCodec<JavaTypeT>	codecFor(Class<JavaTypeT> javaType) Shortcut for codecFor(GenericType.of(javaType)).
<JavaTypeT> TypeCodec<JavaTypeT>	codecFor(DataType cqlType) Returns a codec to convert the given CQL type to the Java type deemed most appropriate to represent it.
default <JavaTypeT> TypeCodec<JavaTypeT>	codecFor(DataType cqlType, Class<JavaTypeT> javaType) Shortcut for codecFor(cqlType, GenericType.of(javaType)).
<JavaTypeT> TypeCodec<JavaTypeT>	codecFor(DataType cqlType, GenericType<JavaTypeT> javaType) Returns a codec to handle the conversion between the given types.
<JavaTypeT> TypeCodec<JavaTypeT>	codecFor(DataType cqlType, JavaTypeT value) Returns a codec to convert the given Java object to the given CQL type.
<JavaTypeT> TypeCodec<JavaTypeT>	codecFor(GenericType<JavaTypeT> javaType) Returns a codec to convert the given Java type to the CQL type deemed most appropriate to represent it.
<JavaTypeT> TypeCodec<JavaTypeT>	codecFor(JavaTypeT value) Returns a codec to convert the given Java object to the CQL type deemed most appropriate to represent it.

Field Detail

DEFAULT

static final CodecRegistry DEFAULT

An immutable instance, that only handles built-in driver types (that is, primitive types, and collections, tuples, and user defined types thereof).

Note that, due to implementation details, this instance is a MutableCodecRegistry, but any attempt to register new codecs will throw UnsupportedOperationException.

Method Detail

codecFor

@NonNull
<JavaTypeT> TypeCodec<JavaTypeT> codecFor(@NonNull
                                                   DataType cqlType,
                                                   @NonNull
                                                   GenericType<JavaTypeT> javaType)

Returns a codec to handle the conversion between the given types.

This is used internally by the driver, in cases where both types are known, for example row.getString(0) (Java type inferred from the method, CQL type known from the row metadata).

The driver's default registry implementation is invariant with regard to the Java type: for example, if B extends A and an A<=>int codec is registered, codecFor(DataTypes.INT, B.class) will not find that codec. This is because this method is used internally both for encoding and decoding, and covariance wouldn't work when decoding.

Throws:

CodecNotFoundException - if there is no such codec.

codecFor

@NonNull
default <JavaTypeT> TypeCodec<JavaTypeT> codecFor(@NonNull
                                                           DataType cqlType,
                                                           @NonNull
                                                           Class<JavaTypeT> javaType)

Shortcut for codecFor(cqlType, GenericType.of(javaType)).

Implementations may decide to override this method for performance reasons, if they have a way to avoid the overhead of wrapping.

Throws:

CodecNotFoundException - if there is no such codec.

codecFor

@NonNull
<JavaTypeT> TypeCodec<JavaTypeT> codecFor(@NonNull
                                                   DataType cqlType)

Returns a codec to convert the given CQL type to the Java type deemed most appropriate to represent it.

This is used internally by the driver, in cases where the Java type is not explicitly provided, for example row.getObject(0) (CQL type known from the row metadata, Java type unspecified).

The definition of "most appropriate" is left to the appreciation of the registry implementor.

Throws:

CodecNotFoundException - if there is no such codec.

codecFor

@NonNull
<JavaTypeT> TypeCodec<JavaTypeT> codecFor(@NonNull
                                                   GenericType<JavaTypeT> javaType)

Returns a codec to convert the given Java type to the CQL type deemed most appropriate to represent it.

The driver does not use this method. It is provided as a convenience for third-party usage, for example if you were to generate a schema based on a set of Java classes.

The driver's default registry implementation is invariant with regard to the Java type: for example, if B extends A and an A<=>int codec is registered, codecFor(DataTypes.INT, B.class) will not find that codec. This is because we don't know whether this method will be used for encoding, decoding, or both.

Throws:

CodecNotFoundException - if there is no such codec.

codecFor

@NonNull
default <JavaTypeT> TypeCodec<JavaTypeT> codecFor(@NonNull
                                                           Class<JavaTypeT> javaType)

Shortcut for codecFor(GenericType.of(javaType)).

Implementations may decide to override this method for performance reasons, if they have a way to avoid the overhead of wrapping.

Throws:

CodecNotFoundException - if there is no such codec.

codecFor

@NonNull
<JavaTypeT> TypeCodec<JavaTypeT> codecFor(@NonNull
                                                   DataType cqlType,
                                                   @NonNull
                                                   JavaTypeT value)

Returns a codec to convert the given Java object to the given CQL type.

This is used internally by the driver when you bulk-set values in a bound statement, UDT or tuple.

Unlike other methods, the driver's default registry implementation is covariant with regard to the Java type: for example, if B extends A and an A<=>int codec is registered, codecFor(DataTypes.INT, someB) will find that codec. This is because this method is always used in encoding scenarios; if a bound statement has a value with a runtime type of ArrayList<String>, it should be possible to encode it with a codec that accepts a List<String>.

Throws:

CodecNotFoundException - if there is no such codec.

codecFor

@NonNull
<JavaTypeT> TypeCodec<JavaTypeT> codecFor(@NonNull
                                                   JavaTypeT value)

Returns a codec to convert the given Java object to the CQL type deemed most appropriate to represent it.

This is used internally by the driver, in cases where the CQL type is unknown, for example for simple statement variables (simple statements don't have access to schema metadata).

Unlike other methods, the driver's default registry implementation is covariant with regard to the Java type: for example, if B extends A and an A<=>int codec is registered, codecFor(someB) will find that codec. This is because this method is always used in encoding scenarios; if a simple statement has a value with a runtime type of ArrayList<String>, it should be possible to encode it with a codec that accepts a List<String>.

Note that, if value is an empty collection, this method may return a codec that won't accept JavaTypeT; but it will encode value correctly.

Throws:

CodecNotFoundException - if there is no such codec.