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 table name, set the table attribute.

Example:

@Entity(table="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; 

To define a static column, just set the attribute staticColumn to true:

@Column(staticColumn = true)
private String name; 

#### @Order

This annotation is used to define components for compound primary keys. It should be used in a class which is an @EmbeddedId for an entity.

If you want to store the data in reversed order on disk in SSTables, set the attribute reversed to true

Please note that you can only set reversed order to true only on the first clustering component in CQL3.

The annotation requires the value attribute to indicates the order of the current component in the key. Example:

@Entity
public class MyEntity 
{
	@EmbeddedId
	private CompoundKey id;
	
	...
		
	private static class CompoundKey 
	{
		@Order(1)
		private Long userId;

		@Order(2)
		private UUID tweetId;
		...
	}
	...
}

> 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

For more detail on this annotation and its usage, please refer to Clustered Entity

#### @PartitionKey

This annotation indicates which component is part of the partition key for a compound primary key.

If you have a simple partition key, this annotation is optional. By default the component having @Order(1) is considered by Achilles as default partition key. If you have a composite partition key with many components, add this annotation on each of them.

@Entity
public class MyEntity 
{
	@EmbeddedId
	private CompoundKey id;
	
	...
		
	private static class CompoundKey 
	{
		@PartitionKey
		@Order(1)
		private Long id;

		@PartitionKey
		@Order(2)
		private String type;

		@Order(3)
		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

#### @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 CQL3 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

#### @Strategy

Define the insert strategy on an entity. Right now only 2 values are possible: info.archinnov.achilles.type.InsertStrategy.NOT_NULL_FIELDS and info.archinnov.achilles.type.InsertStrategy.ALL_FIELDS

Upon call to persist(), depending on the chosen strategy Achilles will

1. insert all fields on the entity, even if they are null
2. 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