com.datastax.driver.core

Class CodecRegistry

java.lang.Object

com.datastax.driver.core.CodecRegistry

public final class CodecRegistry
extends Object

A registry for TypeCodecs. When the driver needs to serialize or deserialize an object, it will lookup in the CodecRegistry for a suitable codec.

Usage

To create a default CodecRegistry instance with all the default codecs used by the Java driver, simply use the following:

 CodecRegistry myCodecRegistry = new CodecRegistry();
 

Custom TypeCodecs can be added to a CodecRegistry via the register methods:

 CodecRegistry myCodecRegistry = new CodecRegistry()
    .register(myCodec1, myCodec2, myCodec3)
 

Note that the order in which codecs are registered matters; if a codec is registered while another codec already handles the same CQL-to-Java mapping, that codec will never be used (unless the user forces its usage through e.g. GettableByIndexData.get(int, TypeCodec)). In order words, it is not possible to replace an existing codec, specially the built-in ones; it is only possible to enrich the initial set of codecs with new ones.

To be used by the driver, CodecRegistry instances must then be associated with a Cluster instance:

 CodecRegistry myCodecRegistry = ...
 Cluster cluster = Cluster.builder().withCodecRegistry(myCodecRegistry).build();
 

To retrieve the CodecRegistry instance associated with a Cluster, do the following:

 CodecRegistry registry = cluster.getConfiguration().getCodecRegistry();
 

For most users, a default CodecRegistry instance, containing all the default codecs, should be adequate.

Example

E.g. let's suppose you want to have all your CQL timestamps deserialized as java.time.DateTime instances:

 TypeCodec<DateTime> timestampCodec = ...
 CodecRegistry myCodecRegistry = new CodecRegistry().register(timestampCodec);
 

Read the online documentation for more examples.

Notes

When a CodecRegistry cannot find a suitable codec among all registered codecs, it will attempt to create a suitable codec.

If the creation succeeds, that codec is added to the list of known codecs and is returned; otherwise, a CodecNotFoundException is thrown.

Note that CodecRegistry instances can only create codecs in very limited situations:

1. Codecs for Enums are created on the fly using TypeCodec.EnumStringCodec;
2. Codecs for user types are created on the fly using TypeCodec.UDTCodec;
3. Codecs for tuple types are created on the fly using TypeCodec.TupleCodec;
4. Codecs for collections are created on the fly using TypeCodec.ListCodec, TypeCodec.SetCodec and TypeCodec.MapCodec, if their element types can be handled by existing codecs (or codecs that can themselves be generated).

Other combinations of Java and CQL types cannot have their codecs created on the fly; such codecs must be manually registered.

Note that the default set of codecs has no support for Cassandra custom types; to be able to deserialize values of such types, you need to manually register an appropriate codec.

CodecRegistry instances are not meant to be shared between two or more Cluster instances; doing so could yield unexpected results.

CodecRegistry instances are thread-safe.

Field Summary

Fields

Modifier and Type	Field and Description
static CodecRegistry	IMMUTABLE_INSTANCE An immutable instance of CodecRegistry.

Constructor Summary

Constructors

Constructor and Description
CodecRegistry()

Method Summary

Methods

Modifier and Type	Method and Description
<T> TypeCodec<T>	codecFor(DataType cqlType) Returns a codec that accepts the given CQL type.
<T> TypeCodec<T>	codecFor(DataType cqlType, Class<T> javaType) Returns a codec that accepts the given CQL type and the given Java class.
<T> TypeCodec<T>	codecFor(DataType cqlType, T value) Returns a codec that accepts the given CQL type and the given value.
<T> TypeCodec<T>	codecFor(DataType cqlType, com.google.common.reflect.TypeToken<T> javaType) Returns a codec that accepts the given CQL type and the given Java type.
<T> TypeCodec<T>	codecFor(T value) Returns a codec that accepts the given value.
CodecRegistry	register(Iterable<? extends TypeCodec<?>> codecs) Register the given codecs with this registry.
CodecRegistry	register(Iterable<? extends TypeCodec<?>> codecs, boolean includeDerivedCollectionCodecs) Register the given codecs with this registry.
CodecRegistry	register(TypeCodec<?>... codecs) Register the given codecs with this registry.
CodecRegistry	register(TypeCodec<?> codec) Register the given codec with this registry.
CodecRegistry	register(TypeCodec<?> codec, boolean includeDerivedCollectionCodecs) Register the given codec with this registry.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

IMMUTABLE_INSTANCE

public static final CodecRegistry IMMUTABLE_INSTANCE

An immutable instance of CodecRegistry. This is only meant to be used internally by the driver.

Constructor Detail

CodecRegistry

public CodecRegistry()

Method Detail

register

public CodecRegistry register(TypeCodec<?> codec)

Register the given codec with this registry.

Parameters:

codec - The codec to add to the registry.

Returns:

this CodecRegistry (for method chaining).

register

public CodecRegistry register(TypeCodec<?> codec,
                     boolean includeDerivedCollectionCodecs)

Register the given codec with this registry.

Parameters:

codec - The codec to add to the registry.

includeDerivedCollectionCodecs - If true, register not only the given codec but also collection codecs whose element types are handled by the given codec, i.e.:

• lists of the codec's type;
• sets of the codec's type;
• maps of a primitive type to the codec's type, or of the codec's type to a primitive type;

Returns:

this CodecRegistry (for method chaining).

register

public CodecRegistry register(TypeCodec<?>... codecs)

Register the given codecs with this registry.

Parameters:

codecs - The codecs to add to the registry.

Returns:

this Builder (for method chaining).

register

public CodecRegistry register(Iterable<? extends TypeCodec<?>> codecs)

Register the given codecs with this registry.

Parameters:

codecs - The codecs to add to the registry.

Returns:

this Builder (for method chaining).

register

public CodecRegistry register(Iterable<? extends TypeCodec<?>> codecs,
                     boolean includeDerivedCollectionCodecs)

Register the given codecs with this registry.

Parameters:

codecs - The codecs to add to the registry.

includeDerivedCollectionCodecs - If true, register not only the given codecs but also collection codecs whose element types are handled by the given codecs, i.e. for each codec:

• lists of the codec's type;
• sets of the codec's type;
• maps of a primitive type to the codec's type, or of the codec's type to a primitive type;

Returns:

this Builder (for method chaining).

codecFor

public <T> TypeCodec<T> codecFor(T value)

Returns a codec that accepts the given value.

This method takes an actual Java object and tries to locate a suitable codec for it. For this reason, codecs must perform a "manual" inspection of the object to determine if they can accept it or not, which, depending on the implementations, can be an expensive operation; besides, the resulting codec cannot be cached. Therefore there might be a performance penalty when using this method.

Furthermore, this method would return the first matching codec, regardless of its accepted CQL type. For this reason, this method might not return the most accurate codec and should be reserved for situations where the target CQL type is not available or unknown. In the Java driver, this happens mainly when serializing a value in a SimpleStatement or in the QueryBuilder, where no CQL type information is available.

Regular application code should avoid using this method.

Codecs returned by this method are NOT cached.

Parameters:

value - The value the codec should accept; must not be null.

Returns:

A suitable codec.

Throws:

CodecNotFoundException - if a suitable codec cannot be found.

codecFor

public <T> TypeCodec<T> codecFor(DataType cqlType)
                      throws CodecNotFoundException

Returns a codec that accepts the given CQL type.

This method would return the first matching codec, regardless of its accepted Java type. For this reason, this method might not return the most accurate codec and should be reserved for situations where the runtime type is not available or unknown. In the Java driver, this happens mainly when deserializing a value using the AbstractGettableByIndexData.getObject(int) method.

Codecs returned by this method are cached.

Parameters:

cqlType - The CQL type the codec should accept; must not be null.

Returns:

A suitable codec.

Throws:

CodecNotFoundException - if a suitable codec cannot be found.

codecFor

public <T> TypeCodec<T> codecFor(DataType cqlType,
                        Class<T> javaType)
                      throws CodecNotFoundException

Returns a codec that accepts the given CQL type and the given Java class.

This method can only handle raw (non-parameterized) Java types. For parameterized types, use codecFor(DataType, TypeToken) instead.

Note that type inheritance needs special care. If a codec accepts a Java type that is assignable to the given Java type, that codec may be returned if it is found first in the registry, even if another codec is a better match.

Codecs returned by this method are cached.

Parameters:

cqlType - The CQL type the codec should accept; must not be null.

javaType - The Java type the codec should accept; must not be null.

Returns:

A suitable codec.

Throws:

CodecNotFoundException - if a suitable codec cannot be found.

codecFor

public <T> TypeCodec<T> codecFor(DataType cqlType,
                        com.google.common.reflect.TypeToken<T> javaType)
                      throws CodecNotFoundException

Returns a codec that accepts the given CQL type and the given Java type.

This method handles parameterized types thanks to Guava's TypeToken API.

Note that type inheritance needs special care. If a codec accepts a Java type that is assignable to the given Java type, that codec may be returned if it is found first in the registry, even if another codec is a better match.

Codecs returned by this method are cached.

Parameters:

cqlType - The CQL type the codec should accept; must not be null.

javaType - The Java type the codec should accept; must not be null.

Returns:

A suitable codec.

Throws:

CodecNotFoundException - if a suitable codec cannot be found.

codecFor

public <T> TypeCodec<T> codecFor(DataType cqlType,
                        T value)

Returns a codec that accepts the given CQL type and the given value.

This method takes an actual Java object and tries to locate a suitable codec for it. For this reason, codecs must perform a "manual" inspection of the object to determine if they can accept it or not, which, depending on the implementations, can be an expensive operation; besides, the resulting codec cannot be cached. Therefore there might be a performance penalty when using this method.

Codecs returned by this method may be cached.

Parameters:

cqlType - The CQL type the codec should accept; must not be null.

value - The value the codec should accept; must not be null.

Returns:

A suitable codec.

Throws:

CodecNotFoundException - if a suitable codec cannot be found.