getentity

GetEntity methods

Annotate a DAO method with @GetEntity to convert a core driver data structure into one or more Entities:

@Dao
public interface ProductDao {
  @GetEntity
  Product asProduct(Row row);
}

The generated code will retrieve each entity property from the source, such as:

Product product = new Product();
product.setId(row.get("id", UUID.class));
product.setDescription(row.get("description", String.class));
...

It does not perform a query. Instead, those methods are intended for cases where you already have a query result, and just need the conversion logic.

Lenient mode

By default, the mapper operates in "strict" mode: the source row must contain a matching column for every property in the entity definition, including computed ones. If such a column is not found, an error will be thrown.

Starting with driver 4.12.0, the @GetEntity annotation has a new lenient attribute. If this attribute is explicitly set to true, the mapper will operate in "lenient" mode: all entity properties that have a matching column in the source row will be set. However, unmatched properties will be left untouched.

As an example to illustrate how lenient mode works, assume that we have the following entity and DAO:

@Entity class Product {

  @PartitionKey int id;
  String description;
  float price;
  // other members omitted
}

interface ProductDao {

  @GetEntity(lenient = true)
  Product getLenient(Row row);

}

Then the following code would be possible:

// row does not contain the price column
Row row = session.execute("SELECT id, description FROM product").one();
Product product = productDao.getLenient(row);
assert product.price == 0.0;

Since no price column was found in the source row, product.price wasn't set and was left to its default value (0.0). Without lenient mode, the code above would throw an error instead.

Lenient mode allows to achieve the equivalent of driver 3.x manual mapping feature.

Beware that lenient mode may result in incomplete entities being produced.

Parameters

The method must have a single parameter. The following types are allowed:

• GettableByName or one of its subtypes (the most likely candidates are Row and UdtValue).
• ResultSet.
• AsyncResultSet.

The data must match the target entity: the generated code will try to extract every mapped property, and fail if one is missing.

Return type

The method can return:

• a single entity instance. If the argument is a result set type, the generated code will extract the first row and convert it, or return null if the result set is empty.

  @GetEntity
  Product asProduct(Row row);
  
  @GetEntity
  Product firstRowAsProduct(ResultSet resultSet);

• a PagingIterable of an entity class. In that case, the type of the parameter must be ResultSet. Each row in the result set will be converted into an entity instance.

  @GetEntity
  PagingIterable<Product> asProducts(ResultSet resultSet);

• a Stream of an entity class. In that case, the type of the parameter must be ResultSet. Each row in the result set will be converted into an entity instance.

  Note: even if streams are lazily evaluated, results are fetched synchronously; therefore, as the returned stream is traversed, blocking calls may occur, as more results are fetched from the server in the background. For details about the stream's characteristics, see PagingIterable.spliterator.

  @GetEntity
  Stream<Product> asProducts(ResultSet resultSet);

• a MappedAsyncPagingIterable of an entity class. In that case, the type of the parameter must be AsyncResultSet. Each row in the result set will be converted into an entity instance.

  @GetEntity
  MappedAsyncPagingIterable<Product> asProducts(AsyncResultSet resultSet);

If the return type doesn't match the parameter type (for example PagingIterable for AsyncResultSet), the mapper processor will issue a compile-time error.