Package org.apache.cassandra.cql3.functions.types

Class TypeCodec.AbstractCollectionCodec<E,​C extends java.util.Collection<E>>

  • Enclosing class:
    TypeCodec<T>
    public abstract static class TypeCodec.AbstractCollectionCodec<E,​C extends java.util.Collection<E>>
extends TypeCodec<C>
    Base class for codecs mapping CQL lists and sets to Java collections.

    • Method Detail

      • serialize

        public java.nio.ByteBuffer serialize​(C value,
                                     ProtocolVersion protocolVersion)
        Description copied from class: TypeCodec
        Serialize the given value according to the CQL type handled by this codec.

        Implementation notes:

        1. Null values should be gracefully handled and no exception should be raised; these should be considered as the equivalent of a NULL CQL value;
        2. Codecs for CQL collection types should not permit null elements;
        3. Codecs for CQL collection types should treat a null input as the equivalent of an empty collection.
        Specified by:
        serialize in class TypeCodec<C extends java.util.Collection<E>>
        Parameters:
        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).
        Returns:
        A ByteBuffer instance containing the serialized form of T

      • deserialize

        public C deserialize​(java.nio.ByteBuffer bytes,
                     ProtocolVersion protocolVersion)
        Description copied from class: TypeCodec
        Deserialize the given ByteBuffer instance according to the CQL type handled by this codec.

        Implementation notes:

        1. Null or empty buffers should be gracefully handled and no exception should be raised; these 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;
        2. 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);
        3. 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).
        4. 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:
        deserialize in class TypeCodec<C extends java.util.Collection<E>>
        Parameters:
        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).
        Returns:
        An instance of T

      • format

        public java.lang.String format​(C value)
        Description copied from class: TypeCodec
        Format 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. in the query builder, when values are inlined in the query string (see querybuilder.BuiltStatement for a detailed explanation of when this happens);
        2. in the QueryLogger, if parameter logging is enabled;
        3. to format the INITCOND in AggregateMetadata#asCQLQuery(boolean);
        4. in the toString() implementation of some objects (UDTValue, TupleValue, and the internal representation of a ROWS response), which may appear in driver logs.

        If you choose not to implement this method, you should not throw an exception but instead return a constant string (for example "XxxCodec.format not implemented").

        Specified by:
        format in class TypeCodec<C extends java.util.Collection<E>>
        Parameters:
        value - An instance of T; may be null.
        Returns:
        CQL string

      • parse

        public C parse​(java.lang.String value)
        Description copied from class: 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).

        Specified by:
        parse in class TypeCodec<C extends java.util.Collection<E>>
        Parameters:
        value - The CQL string to parse, may be null or empty.
        Returns:
        An instance of T; may be null on a null input.

      • accepts

        public boolean accepts​(java.lang.Object value)
        Description copied from class: TypeCodec
        Return 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 TypeCodec.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:

        1. The default implementation is covariant with respect to the passed argument (through the usage of 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.
        2. The base implementation provided here can only handle non-parameterized types; codecs handling parameterized types, such as collection types, must override this method and perform some sort of "manual" inspection of the actual type parameters.
        3. Similarly, codecs that only accept a partial subset of all possible values must override this method and manually inspect the object to check if it complies or not with the codec's limitations.
        Overrides:
        accepts in class TypeCodec<C extends java.util.Collection<E>>
        Parameters:
        value - The Java type this codec should serialize from and deserialize to; cannot be null.
        Returns:
        true if the codec is capable of serializing the given javaType, and false otherwise.

      • newInstance

        protected abstract C newInstance​(int size)
        Return a new instance of C with the given estimated size.
        Parameters:
        size - The estimated size of the collection to create.
        Returns:
        new instance of C with the given estimated size.