diff --git a/src/main/java/com/noorq/casser/mapping/annotation/Types.java b/src/main/java/com/noorq/casser/mapping/annotation/Types.java index ef62092..973b183 100644 --- a/src/main/java/com/noorq/casser/mapping/annotation/Types.java +++ b/src/main/java/com/noorq/casser/mapping/annotation/Types.java @@ -23,11 +23,36 @@ import java.lang.annotation.Target; import com.datastax.driver.core.DataType; +/** + * Types annotations are using for clarification of Cassandra data type for particular Java type. + * + * Sometimes it is possible to have for single Java type multiple Cassandra data types: + * - @String can be @DataType.Name.ASCII or @DataType.Name.TEXT or @DataType.Name.VARCHAR + * - @Long can be @DataType.Name.BIGINT or @DataType.Name.COUNTER + * + * All those type annotations simplify mapping between Java types and Cassandra data types. + * They are not required, for each Java type there is a default Cassandra data type in Casser, but in some + * cases you would like to control mapping to make sure that the right Cassandra data type is using. + * + * For complex types like collections, UDF and Tuple types all those annotations are using to + * clarify the sub-type(s) or class/UDF names. + * + * Has significant effect on schema operations. + * + * @author Albert Shift + * + */ + public final class Types { private Types() { } + /** + * Says to use @DataType.Name.ASCII data type in schema + * Java type is @String + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) @@ -35,6 +60,11 @@ public final class Types { } + /** + * Says to use @DataType.Name.BIGINT data type in schema + * Java type is @Long + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) @@ -42,6 +72,12 @@ public final class Types { } + /** + * Says to use @DataType.Name.BLOB data type in schema + * Java type is @ByteBuffer or @byte[] + * Using by default + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) @@ -49,26 +85,82 @@ public final class Types { } + /** + * Says to use @DataType.Name.LIST data type in schema with specific sub-type + * Java type is @List + * + * Casser does not allow to use a specific implementation of the collection thereof data retrieval operation + * result can be a collection with another implementation. + * + * This annotation is usually used only for sub-types clarification and only in case if sub-type is Java type that + * corresponds to multiple Cassandra data types. + * + * For this type there are special operations: prepend, prependAll, setIdx, append, appendAll, discard and discardAll in @UpdateOperation + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface List { + /** + * Clarification of using the sub-type data type in the collection. + * It supports only simple data type (not Collection, UDT or Tuple) + * + * In case if you need UDT sub-type in the list, consider @UDTList annotation + */ + DataType.Name value(); } + /** + * Says to use @DataType.Name.MAP data type in schema with specific sub-types + * Java type is @Map + * + * Casser does not allow to use a specific implementation of the collection thereof data retrieval operation + * result can be a collection with another implementation. + * + * This annotation is usually used only for sub-types clarification and only in case if sub-type is Java type that + * corresponds to multiple Cassandra data types. + * + * For this type there are special operations: put and putAll in @UpdateOperation. + * + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface Map { + /** + * Clarification of using the sub-type data type in the collection. + * It supports only simple data type (not Collection, UDT or Tuple) + * + * In case if you need UDT key sub-type in the map, consider @UDTKeyMap or @UDTMap annotations + */ + DataType.Name key(); - + + /** + * Clarification of using the sub-type data type in the collection. + * It supports only simple data type (not Collection, UDT or Tuple) + * + * In case if you need UDT value sub-type in the map, consider @UDTValueMap or @UDTMap annotations + */ + DataType.Name value(); } + /** + * Says to use @DataType.Name.COUNTER type in schema + * Java type is @Long + * + * For this type there are special operations: increment and decrement in @UpdateOperation. + * You do not need to initialize counter value, it will be done automatically by Cassandra. + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) @@ -76,24 +168,63 @@ public final class Types { } + /** + * Says to use @DataType.Name.SET data type in schema with specific sub-type + * Java type is @Set + * + * Casser does not allow to use a specific implementation of the collection thereof data retrieval operation + * result can be a collection with another implementation. + * + * This annotation is usually used only for sub-types clarification and only in case if sub-type is Java type that + * corresponds to multiple Cassandra data types. + * + * For this type there are special operations: add, addAll, remove and removeAll in @UpdateOperation. + * + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface Set { + /** + * Clarification of using the sub-type data type in the collection. + * It supports only simple data type (not Collection, UDT or Tuple) + * + * In case if you need UDT sub-type in the set, consider @UDTSet annotation + */ + DataType.Name value(); } + /** + * Says to use @DataType.Name.CUSTOM type in schema + * Java type is @ByteBuffer or @byte[] + * + * Uses for custom user types that has special implementation. + * Casser does not deal with this class directly for now, uses only in serialized form. + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface Custom { - String className() default ""; + /** + * Class name of the custom user type that is implementation of the type + */ + + String className(); } + /** + * Says to use @DataType.Name.TEXT type in schema + * Java type is @String + * Using by default + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) @@ -101,6 +232,12 @@ public final class Types { } + /** + * Says to use @DataType.Name.TIMESTAMP type in schema + * Java type is @Date + * Using by default + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) @@ -108,6 +245,11 @@ public final class Types { } + /** + * Says to use @DataType.Name.TIMEUUID type in schema + * Java type is @UUID or @Date + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) @@ -115,75 +257,226 @@ public final class Types { } + /** + * Says to use @DataType.Name.TUPLE type in schema + * Java type is @TupleValue or model interface with @Tuple annotation + */ + @Documented @Retention(RetentionPolicy.RUNTIME) public @interface Tuple { - + + /** + * If Java type is the @TupleValue then this field is required. + * Any Cassandra Tuple is the sequence of Cassandra types. + * For now Casser supports only simple data types in tuples for @TupleValue Java type + * + * In case if Java type is the model interface with @Tuple annotation then + * all methods in this interface can have Types annotations that can be complex types as well. + */ + DataType.Name[] value() default {}; } + /** + * Says to use @DataType.Name.UDT type in schema + * Java type is @UDTValue or model interface with @UDT annotation + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface UDT { + /** + * If Java type is the @UDTValue then this field is required. + * Any Cassandra UDT has name and must be created before this use as a Cassandra Type. + * + * This value is the UDT name of the Cassandra Type that was already created in the schema + * + * In case of Java type is the model interface with @UDT annotation then + * this field is not using since model interface defines UserDefinedType with specific name + */ + String value() default ""; + /** + * Only used for JavaType @UDTValue + * + * In case if value() method returns reserved word that can not be used as a name of UDT then + * forceQuote will add additional quotes around this name in all CQL queries. + * + * Default value is false. + */ + boolean forceQuote() default false; } + /** + * Says to use @DataType.Name.MAP data type in schema with specific UDT sub-type as a key and simple sub-type as a value + * Java type is @Map + * + * Casser does not allow to use a specific implementation of the collection thereof data retrieval operation + * result can be a collection with another implementation. + * + * This annotation is usually used only for sub-types clarification and only in case if sub-type is Java type that + * corresponds to multiple Cassandra data types. + * + * For this type there are special operations: put and putAll in @UpdateOperation. + * + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface UDTKeyMap { + /** + * Clarification of using the UDT data type as a key sub-type in the collection. + */ + UDT key(); + /** + * Clarification of using the sub-type data type in the collection. + * It supports only simple data type (not Collection, UDT or Tuple) + * + * In case if you need UDT value sub-type in the map, consider @UDTMap annotations + */ + DataType.Name value(); } + /** + * Says to use @DataType.Name.LIST data type in schema with specific UDT sub-type + * Java type is @List + * + * Casser does not allow to use a specific implementation of the collection thereof data retrieval operation + * result can be a collection with another implementation. + * + * This annotation is usually used only for sub-types clarification and only in case if sub-type is Java type that + * corresponds to multiple Cassandra data types. + * + * For this type there are special operations: prepend, prependAll, setIdx, append, appendAll, discard and discardAll in @UpdateOperation + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface UDTList { + /** + * Clarification of using the UDT data type as a sub-type in the collection. + */ + UDT value(); } + /** + * Says to use @DataType.Name.MAP data type in schema with specific UDT sub-types + * Java type is @Map + * + * Casser does not allow to use a specific implementation of the collection thereof data retrieval operation + * result can be a collection with another implementation. + * + * This annotation is usually used only for sub-types clarification and only in case if sub-type is Java type that + * corresponds to multiple Cassandra data types. + * + * For this type there are special operations: put and putAll in @UpdateOperation. + * + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface UDTMap { + /** + * Clarification of using the UDT data type as a key sub-type in the collection. + */ + UDT key(); + /** + * Clarification of using the UDT data type as a value sub-type in the collection. + */ + UDT value(); } + /** + * Says to use @DataType.Name.SET data type in schema with specific UDT sub-type + * Java type is @Set + * + * Casser does not allow to use a specific implementation of the collection thereof data retrieval operation + * result can be a collection with another implementation. + * + * This annotation is usually used only for sub-types clarification and only in case if sub-type is Java type that + * corresponds to multiple Cassandra data types. + * + * For this type there are special operations: add, addAll, remove and removeAll in @UpdateOperation. + * + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface UDTSet { + /** + * Clarification of using the UDT data type as a sub-type in the collection. + */ + UDT value(); } + /** + * Says to use @DataType.Name.MAP data type in schema with specific simple sub-type as a key and UDT sub-type as a value + * Java type is @Map + * + * Casser does not allow to use a specific implementation of the collection thereof data retrieval operation + * result can be a collection with another implementation. + * + * This annotation is usually used only for sub-types clarification and only in case if sub-type is Java type that + * corresponds to multiple Cassandra data types. + * + * For this type there are special operations: put and putAll in @UpdateOperation. + * + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE }) public @interface UDTValueMap { + /** + * Clarification of using the sub-type data type in the collection. + * It supports only simple data type (not Collection, UDT or Tuple) + * + * In case if you need UDT key sub-type in the map, consider @UDTMap annotations + */ + DataType.Name key(); + /** + * Clarification of using the UDT data type as a value sub-type in the collection. + */ + UDT value(); } + + /** + * Says to use @DataType.Name.UUID type in schema + * Java type is @UUID + * Using by default + */ @Documented @Retention(RetentionPolicy.RUNTIME) @@ -192,6 +485,11 @@ public final class Types { } + /** + * Says to use @DataType.Name.VARCHAR type in schema + * Java type is @String + */ + @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value = { ElementType.METHOD, ElementType.ANNOTATION_TYPE })