Entities¶

Mutability¶

By default, the mapper expects mutable entity classes:

@Entity
public class Product {
  @PartitionKey private UUID productId;

  public Product() {}

  public UUID getProductId() { return productId; }
  public void setProductId(UUID productId) { this.productId = productId; }
}

With mutable entities:

• each entity property:

  • must have a non-void, no-argument getter method.

  • must have a corresponding setter method: matching name, and exactly one argument matching the getter’s return type. Note that the return type of the setter does not matter.

  • may have a corresponding field: matching name and type.

• the type must expose a non-private, no-argument constructor.

When the mapper reads a mutable entity from the database, it will invoke the no-argument constructor to materialize the instance, and then read and set the properties one by one.

You can switch to an immutable style with the @PropertyStrategy annotation:

@Entity
@PropertyStrategy(mutable = false)
public class ImmutableProduct {
  @PartitionKey private final UUID productId;

  public ImmutableProduct(UUID productId) { this.productId = productId; }

  public UUID getProductId() { return productId; }
}

With immutable entities:

• each entity property:

  • must have a non-void, no-argument getter method. The mapper will not look for a setter.

  • may have a corresponding field: matching name and type. You’ll probably want to make that field final (although that has no impact on the mapper-generated code).

• the type must expose a non-private constructor that takes every non-transient property, in the declaration order.

When the mapper reads an immutable entity from the database, it will first read all properties, then invoke the “all columns” constructor to materialize the instance.

Note: the “all columns” constructor must take the properties in the order that they are declared in the entity. If the entity inherits properties from parent types, those must come last in the constructor signature, ordered from the closest parent to the farthest. If things get too complicated, a good trick is to deliberately omit the constructor to let the mapper processor fail: the error message describes the expected signature.

Accessor styles¶

By default, the mapper looks for JavaBeans-style accessors: getter prefixed with “get” (or “is” for boolean properties) and, if the entity is mutable, setter prefixed with “set”:

@Entity
public class Product {
  @PartitionKey private UUID productId;

  public UUID getProductId() { return productId; }
  public void setProductId(UUID productId) { this.productId = productId; }
}

You can switch to a “fluent” style (no prefixes) with the @PropertyStrategy annotation:

import static com.datastax.oss.driver.api.mapper.entity.naming.GetterStyle;
import static com.datastax.oss.driver.api.mapper.entity.naming.SetterStyle;

@Entity
@PropertyStrategy(getterStyle = GetterStyle.FLUENT, setterStyle = SetterStyle.FLUENT)
public class Product {
  @PartitionKey private UUID productId;

  public UUID productId() { return productId; }
  public void productId(UUID productId) { this.productId = productId; }
}

Note that if you use the fluent style with immutable entities, Java’s built-in hashCode() and toString() methods would qualify as properties. The mapper skips them automatically. If you have other false positives that you’d like to ignore, mark them as transient.

Naming conventions¶

The simplest strategy is to use one of the mapper’s built-in conventions:

import static com.datastax.oss.driver.api.mapper.entity.naming.NamingConvention.UPPER_SNAKE_CASE;

@Entity
@NamingStrategy(convention = UPPER_SNAKE_CASE)
public class Product {
  @PartitionKey private UUID productId;
  ...
}

Conventions convert names according to pre-defined rules. For example, with the UPPER_SNAKE_CASE convention used above, the mapper expects the following schema:

CREATE TABLE "PRODUCT"("PRODUCT_ID" int primary key ...)

For the list of all available conventions, look at the enum constants in NamingConvention.

If you don’t annotate your class with @NamingStrategy, the mapper defaults to the SNAKE_CASE_INSENSITIVE convention.

User-provided name converter¶

If none of the built-in conventions work for you, you can provide your own conversion logic by implementing NameConverter:

public class MyNameConverter implements NameConverter {
  @Override
  public String toCassandraName(String javaName) {
    ... // implement your logic here
  }
}

Then pass your converter class to the annotation:

@Entity
@NamingStrategy(customConverterClass = MyNameConverter.class)
public class Product {
  ...
}

The mapper will use reflection to build an instance of the converter; it needs to expose a public no-arg constructor.

Note that, unlike built-in conventions, the mapper processor cannot invoke your converter at compile time and use the converted names directly in generated code. Instead, the generated code will invoke the converter at runtime (that is, every time you run a query). If you want to squeeze the last bit of performance from the mapper, we recommend sticking to conventions.

User-provided names¶

Finally, you can override the CQL name manually with the @CqlName annotation:

@PartitionKey
@CqlName("id")
private UUID productId;

It works both on entity properties, and on the entity class itself.

This takes precedence over the entity-level naming strategy, so it’s convenient if almost all of your schema follows a convention, but you need exceptions for a few columns.

Primary key columns¶

If the entity maps to a table, properties that map to partition key columns must be annotated with @PartitionKey:

// CREATE TABLE sales(countryCode text, areaCode text, sales int,
//                    PRIMARY KEY((countryCode, areaCode)));

@PartitionKey(1)
private String countryCode;
@PartitionKey(2)
private String areaCode;

If the partition key is composite, the annotation’s integer value indicates the position of each property in the key. Note that any values can be used, but for clarity it’s probably a good idea to use consecutive integers starting at 0 or 1.

Similarly, properties that map to clustering columns must be annotated with @ClusteringColumn:

// CREATE TABLE sensor_reading(id uuid, year int, month int, day int, value double,
//                             PRIMARY KEY(id, year, month, day));
@PartitionKey
private UUID id;
@ClusteringColumn(1)
private int year;
@ClusteringColumn(2)
private int month;
@ClusteringColumn(3)
private int day;

This information is used by some of the DAO method annotations; for example, @Select’s default behavior is to generate a selection by primary key.

Computed properties¶

Annotating an entity property with @Computed indicates that when retrieving data with the mapper this property should be set to the result of a computation on the Cassandra side, typically a function call:

private int v;

@Computed("writetime(v)")
private long writetime;

The CQL return type of the formula must match the type of the property, otherwise an exception will be thrown.

@Computed does not support case-sensitivity. If the expression contains case-sensitive column or function names, you’ll have to escape them:

@Computed("\"myFunction\"(\"myColumn\")")
private int f;

@Computed fields are only used for select-based queries, so they will not be considered for @Update or @Insert operations.

Also note that like all other properties, the expected name in a query result for a @Computed property is based on the property name and the employed @NamingStrategy. You may override this behavior using @CqlName.

Mapping computed results to property names is accomplished using aliases. If you wish to use entities with @Computed properties with @GetEntity or @Query-annotated dao methods, you must also do the same:

@Entity
class MyEntity {
  @PartitionKey private int k;

  private int v;

  @Computed("ttl(v)")
  private int myTtl;

  @Computed("writetime(v)")
  @CqlName("ts")
  private long writetime;
}

would expect a @Query such as:

@Dao
class MyDao {
  @Query("select k, v, ttl(v) as my_ttl, writetime(v) as ts from ${qualifiedTableId} where k=:id")
  MyEntity findById(int id);
}

Transient properties¶

In some cases, one may opt to exclude properties defined on an entity from being considered by the mapper. In this case, simply annotate these properties with @Transient:

@Transient
private int notAColumn;

In addition, one may specify transient property names at the entity level by leveraging the @TransientProperties annotation:

@TransientProperties({"notAColumn", "x"})
@Entity
public class Product {
  @PartitionKey private UUID id;
  private String description;
  // these columns are not included because their names are specified in @TransientProperties
  private int notAColumn;
  private int x;
}

Finally, any field including the transient keyword modifier will also be considered transient, i.e.:

private transient int notAColumn;

Custom column name¶

Override the CQL name manually with @CqlName, see User-provided names above.