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

Most users won't need to manipulate CodecRegistry instances directly. Only those willing to register user-defined codecs are required to do so. By default, the driver uses DEFAULT_INSTANCE, a shareable instance that initially contains all the built-in codecs required by the driver.

Users willing to customize their CodecRegistry can do so by register registering new TypeCodecs either on DEFAULT_INSTANCE, or on a newly-crated one:

 CodecRegistry myCodecRegistry;
 // use the default instance
 myCodecRegistry = CodecRegistry.DEFAULT_INSTANCE;
 // or alternatively, create a new one
 myCodecRegistry = new CodecRegistry();
 // then
 myCodecRegistry.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();
 

By default, Cluster instances will use DEFAULT_INSTANCE.

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	DEFAULT_INSTANCE A default instance of CodecRegistry.

Constructor Summary

Constructors

Constructor and Description
CodecRegistry() Creates a default CodecRegistry instance with default cache options.

Method Summary

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(TypeCodec<?>... codecs) Register the given codecs with this registry.
CodecRegistry	register(TypeCodec<?> codec) 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

DEFAULT_INSTANCE

public static final CodecRegistry DEFAULT_INSTANCE

A default instance of CodecRegistry. For most applications, sharing a single instance of CodecRegistry is fine. But note that any codec registered with this instance will immediately be available for all its clients.

Constructor Detail

CodecRegistry

public CodecRegistry()

Creates a default CodecRegistry instance with default cache options.

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

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 are NOT 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.