-
Notifications
You must be signed in to change notification settings - Fork 92
Achilles Annotations
For bean mapping, only field annotation (as opposed to getter/setter annotation) is supported by Achilles. Furthermore, there is no default mapping for fields. If you want a field to be mapped, you must annotate it with @Column
/ @Id
/ @EmbeddedId
. All fields that are not annotated by either annotations are considered transient by Achilles
Below is a list of all Achilles annotations.
#### @Entity
Indicates that an entity is candidate for persistence. By default Achilles creates a table whose name is the short class name of the entity.
If you want to define a specific keyspace name, set the keyspace
attribute.
If you want to define a specific table name, set the table
attribute.
If you want to define a specific comment on this table when Achilles generates the DDL script, set the comment
attribute. Please note that all simple quotes ' in the comment will be escaped according to the CQL syntax
Example:
@Entity(keyspace = "back_end", table="users", comment = "table for users")
public class User
{
...
...
}
> **Please note that Cassandra limits the column family name to 48 characters max (because of limitations in Windows for file path max lengths)**
#### @Id
Indicates a field to be mapped as the primary key for the entity. The primary key can be of any type, even a plain POJO. When the name
attribute of @Id
is given, the field will be mapped to this name. Otherwise the field name will be used.
For non Clustered Entity, the primary key also corresponds to partition key.
#### @EmbeddedId
Indicates a field to be mapped as a compound primary key for an clustered entity. A valid compound primary key should be a POJO having at least 2 fields representing primary key components. When the name
attribute of @EmbeddedId
is given, the field will be mapped to this name. Otherwise the field name will be used.
The first component is the partition key, the remaining components are the clustering keys.
For more details, see Clustered Entity
#### @Column
Indicates a field to be mapped by Achilles. When the name
attribute of @Column
is given, the field
will be mapped to this name. Otherwise the field name will be used.
Example:
@Column(name = "age_in_years")
private Long age;
Remark: the custom
name
set on a column will override any NamingStrategy defined on the table/globally
To define a static column, just set the attribute staticColumn
to true
:
@Column(staticColumn = true)
private String name;
#### @PartitionKey
This annotation indicates which field is part of the partition key for a compound primary key.
Put this annotation on several fields to have a composite partition key.
The attribute value
indicates the ordering of this partition component in a composite partition key.
The attribute value
defaults to 1.
Unlike Java indexes, the ordering starts at 1. It is a design choice since it is more natural for human being to start counting at 1
private static class SimpleCompoundKey
{
@PartitionKey
private Long id;
@ClusteringColumn
private UUID date;
...
}
...
private static class CompositePartitionKey
{
@PartitionKey(1)
private Long id;
@PartitionKey(2)
private String type;
@ClusteringColumn
private UUID date;
...
}
}
In the above example, id
and type
are part of the composite partition key. date
is the clustering key.
Remark: all fields annotated with
@PartitionKey
should be consecutive with respect to their ordering. Failing this condition will raise an exception during Achilles bootstrap
For more detail on this annotation and its usage, please refer to Clustered Entity
#### @ClusteringColumn
This annotation indicates which field is a clustering column.
Put this annotation on several fields to have many clustering columns.
The attribute value
indicates the ordering of this clustering column.
If you want to store the data in reversed order on disk in SSTables, set the attribute reversed
to true
Unlike Java indexes, the ordering starts at 1. It is a design choice since it is more natural for human being to start counting at 1
@Entity
public class MyEntity
{
@EmbeddedId
private CompoundKey id;
...
private static class CompoundKey
{
@PartitionKey
private Long userId;
@ClusteringColumn(value = 1, reversed = true)
private Date date;
@ClusteringColumn(2)
private String type;
...
}
...
}
For more detail on this annotation and its usage, please refer to Clustered Entity
#### @Index
This annotation defines a secondary index on a regular column (not columns part of the PRIMARY KEY though, it will be available in Cassandra 2.0)
Additionally you can define the name of the index using the name
attribute on the annotation.
Example
@Entity
public class UserEntity {
@Id
private Long id;
@Column
@Index(name = "user_name_index")
private String name;
...
}
#### @Consistency
This annotation can be used on an entity or a Counter field
You need to specify the read and write attribute to define the corresponding consistency level.
Example:
@Entity
@Consistency(read=ConsistencyLevel.ONE,write=ConsistencyLevel.QUORUM)
public class MyBean
{
@Id
private Long id;
...
@ConsistencyLevel(read=ConsistencyLevel.ONE,write=ConsistencyLevel.ONE)
@Counter
@Column
private Long counter;
}
#### @TimeUUID
This annotation tells Achilles to map a Java UUID
field to Cassandra timeuuid
type.
Example:
@Entity
@Consistency(read=ConsistencyLevel.ONE,write=ConsistencyLevel.QUORUM)
public class MyBean
{
@Id
private Long id;
@TimeUUID
@Column
private UUID date;
...
This is especially useful in CQL to map to timeuuid
type so you can use Timeuuid functions like dateOf()
/now()
/minTimeuuid()
/maxTimeuuid()
or unixTimestampOf()
on native queries
#### @EmptyCollectionIfNull
For collections and maps, Cassandra does not distinguish between empty collection/map and null collection/map.
Therefore if you save an empty list, it is equivalent to setting null
to this list, thus deleting it. When reading back the list, Cassandra will return a null value so Achilles will map back to a null list.
To avoid having to check for null, you can add the @EmptyCollectionIfNull
annotation on a collection or map, Achilles will then map null
value to an empty instance of the collection/map.
Please note that Achilles exposes the same behavior if the
javax.validation.constraints.NotNull
annotation is set on a collection/map
#### @JSON
Tell Achilles to serialize an un-supported data type into JSON string. Example:
@Column
@JSON
private MyPOJO pojoAsJson;
#### @Strategy
Define the insert and naming strategy on an entity.
For the insert strategy, 2 values are possible: info.archinnov.achilles.type.InsertStrategy.NOT_NULL_FIELDS
and info.archinnov.achilles.type.InsertStrategy.ALL_FIELDS
Upon call to insert()
, depending on the chosen strategy Achilles will
- insert all fields on the entity, even if they are null
- insert only non null fields of the entity
@Entity
@Strategy(insert = InsertStrategy.ALL_FIELDS)
public class MyBean
{
@Id
private Long id;
...
Check here for more details on the Insert strategy
For the naming strategy, 3 values are possible: `info.archinnov.achilles.type.NamingStrategy.SNAKE_CASE`, `info.archinnov.achilles.type.NamingStrategy.LOWER_CASE` and `info.archinnov.achilles.type.NamingStrategy.CASE_SENSITIVE`
- SNAKE_CASE: transform all schema name using snake case
- CASE_SENSITIVE: enclose the name between double quotes (") for escaping the case
- LOWER_CASE: transform the name to lower case
If not set, the strategy defaults to info.archinnov.achilles.type.NamingStrategy.LOWER_CASE
@Entity(keyspace="myKeyspace", table="myTable)
@Strategy(naming = NamingStrategy.SNAKE_CASE)
// final keyspace name will be transformed to 'my_keyspace' and table name to 'my_table'
public class MyBean
{
@Id
private Long id;
@Column
private String firstName; //column name transformed to 'first_name'
@Column(name = "misc")
private String customInfo; //column name will be 'misc' because name defined on @Column will override any NamingStrategy
...
Check here for more details on the Naming strategy
Define the encoding for enum values. This annotation applies on simple field, on value of collections and on key & value of map. The enum exposes 2 attributes:
-
key
: defines the encoding for maps key. Only applies to map types -
value
: defines the encoding for simple types and values of collections (list/set)
There are 2 defined encoding types: Encoding.NAME
and Encoding.ORDINAL
, which use respectively the enum name & ordinal
for encoding.
Example:
@Column(name = "pricing")
@Enumerated(Encoding.ORDINAL)
private Pricing pricing;
@Column(name = "pricings")
@Enumerated(Encoding.NAME)
private List<Pricing> pricings;
@Column(name = "pricing_per_country")
@Enumerated(key = Encoding.ORDINAL, value = Encoding.NAME)
private Map<Country, PricingType> pricingPerCountry;
More details on Enum type
#### @TypeTransformer
Transform a custom Java type into one of native types supported by the Java driver
This annotation defines 2 attributes:
- keyCodecClass: class of Codec for Map key type transformation. Only useful for Map types
- valueCodecClass: class of Codec for simple, List and Set type transformation. Please note that in case of List & Set, the transformation applies to the values inside the List/Set, not to the List/Set itself
The Codec class provided should implement the Codec interface.
Let's consider the following codec transforming a Long to a String
public class LongToString implements Codec<Long,String> {
@Override
public Class<Long> sourceType() {
return Long.class;
}
@Override
public Class<String> targetType() {
return String.class;
}
@Override
public String encode(Long fromJava) throws AchillesTranscodingException {
return fromJava.toString();
}
@Override
public Long decode(String fromCassandra) throws AchillesTranscodingException {
return Long.parseLong(fromCassandra);
}
}
Example of simple Long type to String type transformation
@Column
@TypeTransformer(valueCodecClass = LongToString.class)
private Long longToString;
Example of List<Long> to List<String> transformation
@Column
@TypeTransformer(valueCodecClass = LongToString.class)
private List<Long> listOfLong;
Example of Set<Long> to Set<String> transformation
@Column
@TypeTransformer(valueCodecClass = LongToString.class)
private Set<Long> setOfLong;
Example of key Map transformation: Map<Long,Double> to Map<String,Double>
@Column
@TypeTransformer(keyCodecClass = LongToString.class)
private Map<Long,Double> mapKeyTransformation;
Example of value Map transformation: Map<Integer,Long> to Map<Integer,String>
@Column
@TypeTransformer(valueCodecClass = LongToString.class)
private Map<Integer,Long> mapValueTransformation;
-
Bootstraping Achilles at runtime
- Runtime Configuration Parameters
-
Manager
-
Consistency Level
-
Cassandra Options at runtime
-
Lightweight Transaction (LWT)
-
JSON Serialization
-
Interceptors
-
Bean Validation (JSR-303)