Package org.apache.cassandra.db.marshal

Class AbstractType<T>

java.lang.Object
org.apache.cassandra.db.marshal.AbstractType<T>
All Implemented Interfaces:
Comparator<ByteBuffer>, AssignmentTestable
Direct Known Subclasses:
AbstractCompositeType, BooleanType, BytesType, CollectionType, DateType, DurationType, DynamicCompositeType.FixedValueComparator, EmptyType, FrozenType, InetAddressType, LexicalUUIDType, NumberType, PartitionerDefinedOrder, ReversedType, StringType, TemporalType, TupleType, UUIDType, VectorType
public abstract class AbstractType<T> extends Object implements Comparator<ByteBuffer>, AssignmentTestable
Specifies a Comparator for a specific type of ByteBuffer. Note that empty ByteBuffer are used to represent "start at the beginning" or "stop at the end" arguments to get_slice, so the Comparator should always handle those values even if they normally do not represent a valid ByteBuffer for the type being compared.

  • Field Details

  • Constructor Details

  • Method Details

    • asCQLTypeStringList

      public static List<String> asCQLTypeStringList(List<AbstractType<?>> abstractTypes)

    • compose

      public final T compose(ByteBuffer bytes)

    • compose

      public <V> T compose(V value, ValueAccessor<V> accessor)

    • decomposeUntyped

      public ByteBuffer decomposeUntyped(Object value)

    • decompose

      public ByteBuffer decompose(T value)

    • getString

      public <V> String getString(V value, ValueAccessor<V> accessor)
      get a string representation of the bytes used for various identifier (NOT just for log messages)

    • getString

      public final String getString(ByteBuffer bytes)

    • toCQLString

      public String toCQLString(ByteBuffer bytes)

    • fromString

      public abstract ByteBuffer fromString(String source) throws MarshalException
      get a byte representation of the given string.
      Throws:
      MarshalException

    • fromJSONObject

      public abstract Term fromJSONObject(Object parsed) throws MarshalException
      Given a parsed JSON string, return a byte representation of the object.
      Parameters:
      parsed - the result of parsing a json string
      Throws:
      MarshalException

    • toJSONString

      public String toJSONString(ByteBuffer buffer, ProtocolVersion protocolVersion)
      Converts the specified value into its JSON representation.

      The buffer position will stay the same.

      Parameters:
      buffer - the value to convert
      protocolVersion - the protocol version to use for the conversion
      Returns:
      a JSON string representing the specified value

    • toJSONString

      public <V> String toJSONString(V value, ValueAccessor<V> accessor, ProtocolVersion protocolVersion)

    • validate

      public void validate(ByteBuffer bytes) throws MarshalException
      Throws:
      MarshalException

    • validate

      public <V> void validate(V value, ValueAccessor<V> accessor) throws MarshalException
      Throws:
      MarshalException

    • compare

      public final int compare(ByteBuffer left, ByteBuffer right)
      Specified by:
      compare in interface Comparator<T>

    • compare

      public final <VL, VR> int compare(VL left, ValueAccessor<VL> accessorL, VR right, ValueAccessor<VR> accessorR)

    • compareCustom

      public <VL, VR> int compareCustom(VL left, ValueAccessor<VL> accessorL, VR right, ValueAccessor<VR> accessorR)
      Implement IFF ComparisonType is CUSTOM Compares the byte representation of two instances of this class, for types where this cannot be done by simple in-order comparison of the unsigned bytes Standard Java compare semantics
      Parameters:
      left -
      accessorL -
      right -
      accessorR -

    • validateCellValue

      public <V> void validateCellValue(V cellValue, ValueAccessor<V> accessor) throws MarshalException
      Validate cell value. Unlike validate(java.nio.ByteBuffer), cell value is passed to validate its content. Usually, this is the same as validate except collection.
      Parameters:
      cellValue - ByteBuffer representing cell value
      Throws:
      MarshalException

    • asCQL3Type

      public CQL3Type asCQL3Type()

    • udfType

      public AbstractType<?> udfType()

    • compareForCQL

      public int compareForCQL(ByteBuffer v1, ByteBuffer v2)
      Same as compare except that this ignore ReversedType. This is to be use when comparing 2 values to decide for a CQL condition (see Operator.isSatisfiedBy) as for CQL, ReversedType is simply an "hint" to the storage engine but it does not change the meaning of queries per-se.

    • getSerializer

      public abstract TypeSerializer<T> getSerializer()

    • getArgumentDeserializer

      public ArgumentDeserializer getArgumentDeserializer()
      Returns:
      the deserializer used to deserialize the function arguments of this type.

    • getString

      public String getString(Collection<ByteBuffer> names)

    • isCounter

      public boolean isCounter()

    • isFrozenCollection

      public boolean isFrozenCollection()

    • isReversed

      public boolean isReversed()

    • unwrap

      public AbstractType<T> unwrap()

    • parseDefaultParameters

      public static AbstractType<?> parseDefaultParameters(AbstractType<?> baseType, TypeParser parser) throws SyntaxException
      Throws:
      SyntaxException

    • isCompatibleWith

      public boolean isCompatibleWith(AbstractType<?> previous)
      Returns true if this comparator is compatible with the provided previous comparator, that is if previous can safely be replaced by this. A comparator cn should be compatible with a previous one cp if forall columns c1 and c2, if cn.validate(c1) and cn.validate(c2) and cn.compare(c1, c2) == v, then cp.validate(c1) and cp.validate(c2) and cp.compare(c1, c2) == v. Note that a type should be compatible with at least itself and when in doubt, keep the default behavior of not being compatible with any other comparator!

    • isValueCompatibleWith

      public boolean isValueCompatibleWith(AbstractType<?> previous)
      Returns true if values of the other AbstractType can be read and "reasonably" interpreted by the this AbstractType. Note that this is a weaker version of isCompatibleWith, as it does not require that both type compare values the same way. The restriction on the other type being "reasonably" interpreted is to prevent, for example, IntegerType from being compatible with all other types. Even though any byte string is a valid IntegerType value, it doesn't necessarily make sense to interpret a UUID or a UTF8 string as an integer. Note that a type should be compatible with at least itself.

    • isValueCompatibleWithInternal

      protected boolean isValueCompatibleWithInternal(AbstractType<?> otherType)
      Needed to handle ReversedType in value-compatibility checks. Subclasses should implement this instead of isValueCompatibleWith().

    • isSerializationCompatibleWith

      public boolean isSerializationCompatibleWith(AbstractType<?> previous)
      Similar to isValueCompatibleWith(AbstractType), but takes into account Cell encoding. In particular, this method doesn't consider two types serialization compatible if one of them has fixed length (overrides valueLengthIfFixed(), and the other one doesn't.

    • compareCollectionMembers

      public <VL, VR> int compareCollectionMembers(VL left, ValueAccessor<VL> accessorL, VR right, ValueAccessor<VR> accessorR, VL collectionName)
      An alternative comparison function used by CollectionsType in conjunction with CompositeType. This comparator is only called to compare components of a CompositeType. It gets the value of the previous component as argument (or null if it's the first component of the composite). Unless you're doing something very similar to CollectionsType, you shouldn't override this.

    • validateCollectionMember

      public <V> void validateCollectionMember(V value, V collectionName, ValueAccessor<V> accessor) throws MarshalException
      Throws:
      MarshalException

    • isCollection

      public boolean isCollection()

    • isUDT

      public boolean isUDT()

    • isTuple

      public boolean isTuple()

    • isVector

      public boolean isVector()

    • isMultiCell

      public boolean isMultiCell()

    • isFreezable

      public boolean isFreezable()

    • freeze

      public AbstractType<?> freeze()

    • unfreeze

      public AbstractType<?> unfreeze()

    • subTypes

      public List<AbstractType<?>> subTypes()

    • freezeNestedMulticellTypes

      public AbstractType<?> freezeNestedMulticellTypes()
      Returns an AbstractType instance that is equivalent to this one, but with all nested UDTs and collections explicitly frozen. This is only necessary for 2.x -> 3.x schema migrations, and can be removed in Cassandra 4.0. See CASSANDRA-11609 and CASSANDRA-11613.

    • isEmptyValueMeaningless

      public boolean isEmptyValueMeaningless()
      Returns true for types where empty should be handled like null like Int32Type.

    • toString

      public String toString(boolean ignoreFreezing)
      Parameters:
      ignoreFreezing - if true, the type string will not be wrapped with FrozenType(...), even if this type is frozen.

    • getComponents

      public List<AbstractType<?>> getComponents()
      Return a list of the "subcomponents" this type has. This always return a singleton list with the type itself except for CompositeType.

    • valueLengthIfFixed

      public int valueLengthIfFixed()
      The length of values for this type if all values are of fixed length, -1 otherwise. This has an impact on serialization.
    • see writeValue(java.nio.ByteBuffer, org.apache.cassandra.io.util.DataOutputPlus)
    • see read(org.apache.cassandra.db.marshal.ValueAccessor<V>, org.apache.cassandra.io.util.DataInputPlus, int)
    • see writtenLength(java.nio.ByteBuffer)
    • see skipValue(org.apache.cassandra.io.util.DataInputPlus)

    • isValueLengthFixed

      public final boolean isValueLengthFixed()
      Checks if all values are of fixed length.
      Returns:
      true if all values are of fixed length, false otherwise.

    • allowsEmpty

      public boolean allowsEmpty()
      Defines if the type allows an empty set of bytes (new byte[0]) as valid input. The validate(Object, ValueAccessor) and compose(Object, ValueAccessor) methods must allow empty bytes when this returns true, and must reject empty bytes when this is false.

      As of this writing, the main user of this API is for testing to know what types allow empty values and what types don't, so that the data that gets generated understands when ByteBufferUtil.EMPTY_BYTE_BUFFER is allowed as valid data.

    • isNull

      public boolean isNull(ByteBuffer bb)

    • isNull

      public <V> boolean isNull(V buffer, ValueAccessor<V> accessor)

    • writeValue

      public void writeValue(ByteBuffer value, DataOutputPlus out) throws IOException
      Throws:
      IOException

    • writeValue

      public <V> void writeValue(V value, ValueAccessor<V> accessor, DataOutputPlus out) throws IOException
      Throws:
      IOException

    • writtenLength

      public long writtenLength(ByteBuffer value)

    • writtenLength

      public <V> long writtenLength(V value, ValueAccessor<V> accessor)

    • readBuffer

      public ByteBuffer readBuffer(DataInputPlus in) throws IOException
      Throws:
      IOException

    • readBuffer

      public ByteBuffer readBuffer(DataInputPlus in, int maxValueSize) throws IOException
      Throws:
      IOException

    • readArray

      public byte[] readArray(DataInputPlus in, int maxValueSize) throws IOException
      Throws:
      IOException

    • read

      public <V> V read(ValueAccessor<V> accessor, DataInputPlus in, int maxValueSize) throws IOException
      Throws:
      IOException

    • skipValue

      public void skipValue(DataInputPlus in) throws IOException
      Throws:
      IOException

    • referencesUserType

      public final boolean referencesUserType(ByteBuffer name)

    • referencesUserType

      public <V> boolean referencesUserType(V name, ValueAccessor<V> accessor)

    • withUpdatedUserType

      public AbstractType<?> withUpdatedUserType(UserType udt)
      Returns an instance of this type with all references to the provided user type recursively replaced with its new definition.

    • expandUserTypes

      public AbstractType<?> expandUserTypes()
      Replace any instances of UserType with equivalent TupleType-s. We need it for dropped_columns, to allow safely dropping unused user types later without retaining any references to them in system_schema.dropped_columns.

    • referencesDuration

      public boolean referencesDuration()

    • testAssignment

      public AssignmentTestable.TestResult testAssignment(AbstractType<?> receiverType)
      Tests whether a CQL value having this type can be assigned to the provided receiver.

    • asComparableBytes

      public <V> ByteSource asComparableBytes(ValueAccessor<V> accessor, V value, ByteComparable.Version version)
      Produce a byte-comparable representation of the given value, i.e. a sequence of bytes that compares the same way using lexicographical unsigned byte comparison as the original value using the type's comparator. We use a slightly stronger requirement to be able to use the types in tuples. Precisely, for any pair x, y of non-equal valid values of this type and any bytes b1, b2 between 0x10 and 0xEF, (+ stands for concatenation) compare(x, y) == compareLexicographicallyUnsigned(asByteComparable(x)+b1, asByteComparable(y)+b2) (i.e. the values compare like the original type, and an added 0x10-0xEF byte at the end does not change that) and: asByteComparable(x)+b1 is not a prefix of asByteComparable(y) (weakly prefix free) (i.e. a valid representation of a value may be a prefix of another valid representation of a value only if the following byte in the latter is smaller than 0x10 or larger than 0xEF). These properties are trivially true if the encoding compares correctly and is prefix free, but also permits a little more freedom that enables somewhat more efficient encoding of arbitrary-length byte-comparable blobs. Depending on the type, this method can be called for null or empty input, in which case the output is allowed to be null (the clustering/tuple encoding will accept and handle it).

    • asComparableBytes

      public final ByteSource asComparableBytes(ByteBuffer byteBuffer, ByteComparable.Version version)

    • fromComparableBytes

      public <V> V fromComparableBytes(ValueAccessor<V> accessor, ByteSource.Peekable comparableBytes, ByteComparable.Version version)
      Translates the given byte-ordered representation to the common, non-byte-ordered binary representation of a payload for this abstract type (the latter, common binary representation is what we mostly work with in the storage engine internals). If the given bytes don't correspond to the encoding of some payload value for this abstract type, an IllegalArgumentException may be thrown.
      Parameters:
      accessor - value accessor used to construct the value.
      comparableBytes - A byte-ordered representation (presumably of a payload for this abstract type).
      version - The byte-comparable version used to construct the representation.
      Returns:
      A of a payload for this abstract type, corresponding to the given byte-ordered representation, constructed using the supplied value accessor.
      See Also:

    • fromComparableBytes

      public final ByteBuffer fromComparableBytes(ByteSource.Peekable comparableBytes, ByteComparable.Version version)

    • toString

      public String toString()
      This must be overriden by subclasses if necessary so that for any AbstractType, this == TypeParser.parse(toString()). Note that for backwards compatibility this includes the full classname. For CQL purposes the short name is fine.
      Overrides:
      toString in class Object

    • checkComparable

      public void checkComparable()

    • testAssignment

      public final AssignmentTestable.TestResult testAssignment(String keyspace, ColumnSpecification receiver)
      Specified by:
      testAssignment in interface AssignmentTestable
      Returns:
      whether this object can be assigned to the provided receiver. We distinguish between 3 values: - EXACT_MATCH if this object is exactly of the type expected by the receiver - WEAKLY_ASSIGNABLE if this object is not exactly the expected type but is assignable nonetheless - NOT_ASSIGNABLE if it's not assignable Most caller should just call the isAssignable() method on the result, though functions have a use for testing "strong" equality to decide the most precise overload to pick when multiple could match.

    • getCompatibleTypeIfKnown

      public AbstractType<?> getCompatibleTypeIfKnown(String keyspace)
      Specified by:
      getCompatibleTypeIfKnown in interface AssignmentTestable
      Returns:
      A data type that can represent this, or null if we can't determine that type. The returned type won't necessarely be the exact type, but one that is compatible with it.

    • getMaskedValue

      public ByteBuffer getMaskedValue()
      Returns:
      A fixed, serialized value to be used when the column is masked, to be returned instead of the real value.