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

Class MappingCodec<InnerT,OuterT>

java.lang.Object

com.datastax.oss.driver.api.core.type.codec.MappingCodec<InnerT,OuterT>

Type Parameters:

InnerT - The "inner" Java type; must be a driver supported Java type (that is, there must exist a codec registered for it).

OuterT - The "outer", or target Java type; this codec will handle the mapping to and from InnerT and OuterT.

All Implemented Interfaces:

TypeCodec<OuterT>

public abstract class MappingCodec<InnerT,OuterT>
extends Object
implements TypeCodec<OuterT>

A TypeCodec that maps instances of InnerT, a driver supported Java type, to instances of a target OuterT Java type.

This codec can be used to provide support for Java types that are not natively handled by the driver, as long as there is a conversion path to and from another supported Java type.

See Also:

driver documentation on custom codecs, driver supported Java types

Field Summary

Fields

Modifier and Type	Field and Description
protected TypeCodec<InnerT>	innerCodec
protected GenericType<OuterT>	outerJavaType

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MappingCodec(TypeCodec<InnerT> innerCodec, GenericType<OuterT> outerJavaType) Creates a new mapping codec providing support for OuterT based on an existing codec for InnerT.

Method Summary

Modifier and Type	Method and Description
OuterT	decode(ByteBuffer bytes, ProtocolVersion protocolVersion) Decodes a value from the binary format of the CQL type handled by this codec.
ByteBuffer	encode(OuterT value, ProtocolVersion protocolVersion) Encodes the given value in the binary format of the CQL type handled by this codec.
String	format(OuterT value) Formats the given value as a valid CQL literal according to the CQL type handled by this codec.
DataType	getCqlType()
GenericType<InnerT>	getInnerJavaType()
GenericType<OuterT>	getJavaType()
protected abstract OuterT	innerToOuter(InnerT value) Converts from an instance of the inner Java type to an instance of the outer Java type.
protected abstract InnerT	outerToInner(OuterT value) Converts from an instance of the outer Java type to an instance of the inner Java type.
OuterT	parse(String value) Parse the given CQL literal into an instance of the Java type handled by this codec.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.datastax.oss.driver.api.core.type.codec.TypeCodec

accepts, accepts, accepts, accepts

Field Detail

innerCodec

protected final TypeCodec<InnerT> innerCodec

outerJavaType

protected final GenericType<OuterT> outerJavaType

Constructor Detail

MappingCodec

protected MappingCodec(@NonNull
                       TypeCodec<InnerT> innerCodec,
                       @NonNull
                       GenericType<OuterT> outerJavaType)

Creates a new mapping codec providing support for OuterT based on an existing codec for InnerT.

Parameters:

innerCodec - The inner codec to use to handle instances of InnerT; must not be null.

outerJavaType - The outer Java type; must not be null.

Method Detail

getJavaType

@NonNull
public GenericType<OuterT> getJavaType()

Specified by:

getJavaType in interface TypeCodec<OuterT>

Returns:

The type of OuterT.

getInnerJavaType

public GenericType<InnerT> getInnerJavaType()

Returns:

The type of InnerT.

getCqlType

@NonNull
public DataType getCqlType()

Specified by:

getCqlType in interface TypeCodec<OuterT>

encode

public ByteBuffer encode(OuterT value,
                         @NonNull
                         ProtocolVersion protocolVersion)

Description copied from interface: TypeCodec

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.

Specified by:

encode in interface TypeCodec<OuterT>

decode

public OuterT decode(ByteBuffer bytes,
                     @NonNull
                     ProtocolVersion protocolVersion)

Description copied from interface: TypeCodec

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.

Specified by:

decode in interface TypeCodec<OuterT>

format

@NonNull
public String format(OuterT value)

Description copied from interface: TypeCodec

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

Specified by:

format in interface TypeCodec<OuterT>

parse

public OuterT parse(String value)

Description copied from interface: TypeCodec

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.

Specified by:

parse in interface TypeCodec<OuterT>

innerToOuter

@Nullable
protected abstract OuterT innerToOuter(@Nullable
                                                 InnerT value)

Converts from an instance of the inner Java type to an instance of the outer Java type. Used when deserializing or parsing.

Parameters:

value - The value to convert; may be null.

Returns:

The converted value; may be null.

outerToInner

@Nullable
protected abstract InnerT outerToInner(@Nullable
                                                 OuterT value)

Converts from an instance of the outer Java type to an instance of the inner Java type. Used when serializing or formatting.

Parameters:

value - The value to convert; may be null.

Returns:

The converted value; may be null.