T
- The codec's Java typepublic abstract class TypeCodec<T> extends Object
CQL type
and a given Java Type
.
serialize(Object, ProtocolVersion)
: used to serialize from the codec's Java type to a
ByteBuffer
instance corresponding to the codec's CQL type;deserialize(ByteBuffer, ProtocolVersion)
: used to deserialize a ByteBuffer
instance
corresponding to the codec's CQL type to the codec's Java type.format(Object)
: formats the Java type handled by the codec as a CQL string;parse(String)
; parses a CQL string into the Java type handled by the codec.accepts(DataType)
: returns true if the codec can deserialize the given CQL type;accepts(TypeToken)
: returns true if the codec can serialize the given Java type;accepts(Object)
; returns true if the codec can serialize the given object.null
values and empty ByteBuffers
(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 in respect to null
values and empty ByteBuffers
should be clearly documented.TypeCodec.PrimitiveBooleanCodec
for primitive boolean
types;
there is one such interface for each Java primitive type).ByteBuffer
instances
by performing relative read operations that modify their current position;
codecs should instead prefer absolute read methods, or, if necessary, they should
duplicate
their byte buffers prior to reading them.Modifier and Type | Class and Description |
---|---|
static class |
TypeCodec.AbstractCollectionCodec<E,C extends Collection<E>>
|
static class |
TypeCodec.AbstractMapCodec<K,V>
|
static class |
TypeCodec.AbstractTupleCodec<T>
Base class for codecs mapping CQL
tuples to Java objects. |
static class |
TypeCodec.AbstractUDTCodec<T>
Base class for codecs mapping CQL
user-defined types (UDTs) to Java objects. |
static class |
TypeCodec.PrimitiveBooleanCodec
A codec that is capable of handling primitive booleans,
thus avoiding the overhead of boxing and unboxing such primitives.
|
static class |
TypeCodec.PrimitiveByteCodec
A codec that is capable of handling primitive bytes,
thus avoiding the overhead of boxing and unboxing such primitives.
|
static class |
TypeCodec.PrimitiveDoubleCodec
A codec that is capable of handling primitive doubles,
thus avoiding the overhead of boxing and unboxing such primitives.
|
static class |
TypeCodec.PrimitiveFloatCodec
A codec that is capable of handling primitive floats,
thus avoiding the overhead of boxing and unboxing such primitives.
|
static class |
TypeCodec.PrimitiveIntCodec
A codec that is capable of handling primitive ints,
thus avoiding the overhead of boxing and unboxing such primitives.
|
static class |
TypeCodec.PrimitiveLongCodec
A codec that is capable of handling primitive longs,
thus avoiding the overhead of boxing and unboxing such primitives.
|
static class |
TypeCodec.PrimitiveShortCodec
A codec that is capable of handling primitive shorts,
thus avoiding the overhead of boxing and unboxing such primitives.
|
Modifier and Type | Field and Description |
---|---|
protected DataType |
cqlType |
protected TypeToken<T> |
javaType |
Modifier | Constructor and Description |
---|---|
protected |
TypeCodec(DataType cqlType,
Class<T> javaClass)
This constructor can only be used for non parameterized types.
|
protected |
TypeCodec(DataType cqlType,
TypeToken<T> javaType) |
Modifier and Type | Method and Description |
---|---|
boolean |
accepts(Class<?> javaType)
Return
true if this codec is capable of serializing
the given javaType . |
boolean |
accepts(DataType cqlType)
Return
true if this codec is capable of deserializing
the given cqlType . |
boolean |
accepts(Object value)
Return
true if this codec is capable of serializing
the given object. |
boolean |
accepts(TypeToken<?> javaType)
Return
true if this codec is capable of serializing
the given javaType . |
static TypeCodec<String> |
ascii()
Return the default codec for the CQL type
ascii . |
static TypeCodec.PrimitiveLongCodec |
bigint()
Return the default codec for the CQL type
bigint . |
static TypeCodec<ByteBuffer> |
blob()
Return the default codec for the CQL type
blob . |
static TypeCodec.PrimitiveBooleanCodec |
cboolean()
Return the default codec for the CQL type
boolean . |
static TypeCodec.PrimitiveDoubleCodec |
cdouble()
Return the default codec for the CQL type
double . |
static TypeCodec.PrimitiveFloatCodec |
cfloat()
Return the default codec for the CQL type
float . |
static TypeCodec.PrimitiveIntCodec |
cint()
Return the default codec for the CQL type
int . |
static TypeCodec.PrimitiveLongCodec |
counter()
Return the default codec for the CQL type
counter . |
static TypeCodec<ByteBuffer> |
custom(DataType.CustomType type)
Return a newly-created codec for the given CQL custom type.
|
static TypeCodec<LocalDate> |
date()
Return the default codec for the CQL type
date . |
static TypeCodec<BigDecimal> |
decimal()
Return the default codec for the CQL type
decimal . |
abstract T |
deserialize(ByteBuffer bytes,
ProtocolVersion protocolVersion)
Deserialize the given
ByteBuffer instance according to the CQL type
handled by this codec. |
static TypeCodec<Duration> |
duration()
Returns the default codec for the
Duration type . |
abstract String |
format(T value)
Format the given value as a valid CQL literal according
to the CQL type handled by this codec.
|
DataType |
getCqlType()
Return the CQL type that this codec deserializes from and serializes to.
|
TypeToken<T> |
getJavaType()
Return the Java type that this codec deserializes to and serializes from.
|
static TypeCodec<InetAddress> |
inet()
Return the default codec for the CQL type
inet . |
static <T> TypeCodec<List<T>> |
list(TypeCodec<T> elementCodec)
Return a newly-created codec for the CQL type
list whose element type
is determined by the given element codec. |
static <K,V> TypeCodec<Map<K,V>> |
map(TypeCodec<K> keyCodec,
TypeCodec<V> valueCodec)
Return a newly-created codec for the CQL type
map whose key type
and value type are determined by the given codecs. |
abstract T |
parse(String value)
Parse the given CQL literal into an instance of the Java type
handled by this codec.
|
abstract ByteBuffer |
serialize(T value,
ProtocolVersion protocolVersion)
Serialize the given value according to the CQL type
handled by this codec.
|
static <T> TypeCodec<Set<T>> |
set(TypeCodec<T> elementCodec)
Return a newly-created codec for the CQL type
set whose element type
is determined by the given element codec. |
static TypeCodec.PrimitiveShortCodec |
smallInt()
Return the default codec for the CQL type
smallint . |
static TypeCodec.PrimitiveLongCodec |
time()
Return the default codec for the CQL type
time . |
static TypeCodec<Date> |
timestamp()
Return the default codec for the CQL type
timestamp . |
static TypeCodec<UUID> |
timeUUID()
Return the default codec for the CQL type
timeuuid . |
static TypeCodec.PrimitiveByteCodec |
tinyInt()
Return the default codec for the CQL type
tinyint . |
String |
toString() |
static TypeCodec<TupleValue> |
tuple(TupleType type)
Return a newly-created codec for the given CQL tuple type.
|
static TypeCodec<UDTValue> |
userType(UserType type)
Return a newly-created codec for the given user-defined CQL type.
|
static TypeCodec<UUID> |
uuid()
Return the default codec for the CQL type
uuid . |
static TypeCodec<String> |
varchar()
Return the default codec for the CQL type
varchar . |
static TypeCodec<BigInteger> |
varint()
Return the default codec for the CQL type
varint . |
protected final DataType cqlType
protected TypeCodec(DataType cqlType, Class<T> javaClass)
TypeCodec(DataType, TypeToken)
instead.javaClass
- The Java class this codec serializes from and deserializes to.public static TypeCodec.PrimitiveBooleanCodec cboolean()
boolean
.
The returned codec maps the CQL type boolean
into the Java type Boolean
.
The returned instance is a singleton.boolean
.public static TypeCodec.PrimitiveByteCodec tinyInt()
tinyint
.
The returned codec maps the CQL type tinyint
into the Java type Byte
.
The returned instance is a singleton.tinyint
.public static TypeCodec.PrimitiveShortCodec smallInt()
smallint
.
The returned codec maps the CQL type smallint
into the Java type Short
.
The returned instance is a singleton.smallint
.public static TypeCodec.PrimitiveIntCodec cint()
int
.
The returned codec maps the CQL type int
into the Java type Integer
.
The returned instance is a singleton.int
.public static TypeCodec.PrimitiveLongCodec bigint()
bigint
.
The returned codec maps the CQL type bigint
into the Java type Long
.
The returned instance is a singleton.bigint
.public static TypeCodec.PrimitiveLongCodec counter()
counter
.
The returned codec maps the CQL type counter
into the Java type Long
.
The returned instance is a singleton.counter
.public static TypeCodec.PrimitiveFloatCodec cfloat()
float
.
The returned codec maps the CQL type float
into the Java type Float
.
The returned instance is a singleton.float
.public static TypeCodec.PrimitiveDoubleCodec cdouble()
double
.
The returned codec maps the CQL type double
into the Java type Double
.
The returned instance is a singleton.double
.public static TypeCodec<BigInteger> varint()
varint
.
The returned codec maps the CQL type varint
into the Java type BigInteger
.
The returned instance is a singleton.varint
.public static TypeCodec<BigDecimal> decimal()
decimal
.
The returned codec maps the CQL type decimal
into the Java type BigDecimal
.
The returned instance is a singleton.decimal
.public static TypeCodec<String> ascii()
ascii
.
The returned codec maps the CQL type ascii
into the Java type String
.
The returned instance is a singleton.ascii
.public static TypeCodec<String> varchar()
varchar
.
The returned codec maps the CQL type varchar
into the Java type String
.
The returned instance is a singleton.varchar
.public static TypeCodec<ByteBuffer> blob()
blob
.
The returned codec maps the CQL type blob
into the Java type ByteBuffer
.
The returned instance is a singleton.blob
.public static TypeCodec<LocalDate> date()
date
.
The returned codec maps the CQL type date
into the Java type LocalDate
.
The returned instance is a singleton.date
.public static TypeCodec.PrimitiveLongCodec time()
time
.
The returned codec maps the CQL type time
into the Java type Long
.
The returned instance is a singleton.time
.public static TypeCodec<Date> timestamp()
timestamp
.
The returned codec maps the CQL type timestamp
into the Java type Date
.
The returned instance is a singleton.timestamp
.public static TypeCodec<UUID> uuid()
uuid
.
The returned codec maps the CQL type uuid
into the Java type UUID
.
The returned instance is a singleton.uuid
.public static TypeCodec<UUID> timeUUID()
timeuuid
.
The returned codec maps the CQL type timeuuid
into the Java type UUID
.
The returned instance is a singleton.timeuuid
.public static TypeCodec<InetAddress> inet()
inet
.
The returned codec maps the CQL type inet
into the Java type InetAddress
.
The returned instance is a singleton.inet
.public static <T> TypeCodec<List<T>> list(TypeCodec<T> elementCodec)
list
whose element type
is determined by the given element codec.
The returned codec maps the CQL type list
into the Java type List
.
This method does not cache returned instances and returns a newly-allocated object
at each invocation.elementCodec
- the codec that will handle elements of this list.list
.public static <T> TypeCodec<Set<T>> set(TypeCodec<T> elementCodec)
set
whose element type
is determined by the given element codec.
The returned codec maps the CQL type set
into the Java type Set
.
This method does not cache returned instances and returns a newly-allocated object
at each invocation.elementCodec
- the codec that will handle elements of this set.set
.public static <K,V> TypeCodec<Map<K,V>> map(TypeCodec<K> keyCodec, TypeCodec<V> valueCodec)
map
whose key type
and value type are determined by the given codecs.
The returned codec maps the CQL type map
into the Java type Map
.
This method does not cache returned instances and returns a newly-allocated object
at each invocation.keyCodec
- the codec that will handle keys of this map.valueCodec
- the codec that will handle values of this map.map
.public static TypeCodec<UDTValue> userType(UserType type)
UDTValue
.
This method does not cache returned instances and returns a newly-allocated object
at each invocation.type
- the user-defined type this codec should handle.public static TypeCodec<TupleValue> tuple(TupleType type)
TupleValue
.
This method does not cache returned instances and returns a newly-allocated object
at each invocation.type
- the tuple type this codec should handle.public static TypeCodec<ByteBuffer> custom(DataType.CustomType type)
ByteBuffer
,
thus providing a (very lightweight) support for Cassandra
types that do not have a CQL equivalent.
Note that the returned codec assumes that CQL literals for the given custom
type are expressed in binary form as well, e.g. 0xcafebabe
. If this is
not the case, the returned codec might be unable to parse
and format
literals for this type.
This is notoriously true for types inheriting from
org.apache.cassandra.db.marshal.AbstractCompositeType
, whose CQL literals
are actually expressed as quoted strings.
This method does not cache returned instances and returns a newly-allocated object
at each invocation.type
- the custom type this codec should handle.public static TypeCodec<Duration> duration()
Duration type
.
This codec maps duration types to the driver's built-in Duration
class,
thus providing a more user-friendly mapping than the low-level mapping provided by regular
custom type codecs
.
The returned instance is a singleton.public TypeToken<T> getJavaType()
public DataType getCqlType()
public abstract ByteBuffer serialize(T value, ProtocolVersion protocolVersion) throws InvalidTypeException
null
input as
the equivalent of an empty collection.value
- An instance of T; may be null
.protocolVersion
- the protocol version to use when serializing
bytes
. In most cases, the proper value to provide for this argument
is the value returned by ProtocolOptions.getProtocolVersion()
(which
is the protocol version in use by the driver).ByteBuffer
instance containing the serialized form of TInvalidTypeException
- if the given value does not have the expected typepublic abstract T deserialize(ByteBuffer bytes, ProtocolVersion protocolVersion) throws InvalidTypeException
ByteBuffer
instance according to the CQL type
handled by this codec.
Implementation notes:
null
or a default value for the corresponding Java type, if applicable;null
;
they should return empty collections instead (the driver's default collection codecs all comply with this rule).ByteBuffer
should never be consumed by read operations that
modify its current position; if necessary,
ByteBuffer.duplicate()
duplicate} it before consuming.bytes
- A ByteBuffer
instance containing the serialized form of T;
may be null
or empty.protocolVersion
- the protocol version to use when serializing
bytes
. In most cases, the proper value to provide for this argument
is the value returned by ProtocolOptions.getProtocolVersion()
(which
is the protocol version in use by the driver).InvalidTypeException
- if the given ByteBuffer
instance cannot be deserializedpublic abstract T parse(String value) throws InvalidTypeException
"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).value
- The CQL string to parse, may be null
or empty.null
on a null input
.InvalidTypeException
- if the given value cannot be parsed into the expected typepublic abstract String format(T value) throws InvalidTypeException
"NULL"
for null
inputs.
Implementing this method is not strictly mandatory. It is used:
BuiltStatement
for a detailed
explanation of when this happens);QueryLogger
, if parameter logging is enabled;AggregateMetadata.asCQLQuery(boolean)
;toString()
implementation of some objects (UDTValue
,
TupleValue
, and the internal representation of a ROWS
response),
which may appear in driver logs.value
- An instance of T; may be null
.InvalidTypeException
- if the given value does not have the expected typepublic boolean accepts(TypeToken<?> javaType)
true
if this codec is capable of serializing
the given javaType
.
The implementation is invariant with respect to the passed
argument (through the usage of TypeToken.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 Java type that it has been created for.
If the argument represents a Java primitive type, its wrapper type
is considered instead.javaType
- The Java type this codec should serialize from and deserialize to; cannot be null
.true
if the codec is capable of serializing
the given javaType
, and false
otherwise.NullPointerException
- if javaType
is null
.public boolean accepts(Class<?> javaType)
true
if this codec is capable of serializing
the given javaType
.
This implementation simply calls accepts(TypeToken)
.javaType
- The Java type this codec should serialize from and deserialize to; cannot be null
.true
if the codec is capable of serializing
the given javaType
, and false
otherwise.NullPointerException
- if javaType
is null
.public boolean accepts(DataType cqlType)
true
if this codec is capable of deserializing
the given cqlType
.cqlType
- The CQL type this codec should deserialize from and serialize to; cannot be null
.true
if the codec is capable of deserializing
the given cqlType
, and false
otherwise.NullPointerException
- if cqlType
is null
.public boolean accepts(Object value)
true
if this codec is capable of serializing
the given object. Note that the object's Java type is inferred
from the object' runtime (raw) type, contrary
to accepts(TypeToken)
which is capable of
handling generic types.
This method is intended mostly to be used by the QueryBuilder
when no type information is available when the codec is used.
Implementation notes:
TypeToken.isAssignableFrom(TypeToken)
or TypeToken.isSupertypeOf(Type)
)
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.value
- The Java type this codec should serialize from and deserialize to; cannot be null
.true
if the codec is capable of serializing
the given javaType
, and false
otherwise.NullPointerException
- if value
is null
.Copyright © 2012–2018. All rights reserved.