Manager-API

Below is a list of APIs supported by Achilles Manager:

CRUD

This API performs simple INSERT/DELETE operations on the entity. It exposes the following methods:

• findById(...): find an entity providing the complete primary key
• insert(ENTITY instance): insert an instance of the entity
• delete(ENTITY instance): delete the entity
• deleteById(...): delete the entity with the provided complete primary key
• deleteByPartitionKeys(...): delete the entity with the provided complete partition key component(s)

For each of those operations, you can specify runtime values for

1. Consistency level/Serial consistency level
2. Retry policy
3. Fetch size
4. Outgoing payload
5. Paging state (useful only for SELECT)
6. ifExists() for INSERT, ifNotExists() for DELETE
7. tracing ON/OFF
8. ResultSet async listener
9. Row async listener
10. LightWeight Transaction result listener for INSERT/DELETE

The ResultSet async listener is just a function Function<ResultSet, ResultSet> to spy on the returned raw
com.datastax.driver.core.ResultSet object. You are not allowed to call methods that will consume this resultset
like one(), all(), iterator(), fetchMoreResults()

The Row async listener is a function Function<Row, Row> and lets you manipulate the raw
com.datastax.driver.core.ResultSet object. This time, it is possible to read values from the row because it is
already fetched

LightWeight Transaction result listener should implement the interface LWTResultListener

DSL

The DSL API lets you create type-safe SELECT, UPDATE and DELETE queries for your entity.

Select DSL

The Select DSL look like:

   
    User user = manager
        .dsl()
        .select()
        .id()
        .firstname()
        .lastname()
        .fromBaseTable()
        .where()
        .userId().Eq(id)
        .getOne();   

The DSL exposes the following final methods:

• ENTITY getOne(): get the first found entity
• CompletableFuture<ENTITY> getOneAsync(): get the first found entity asynchronously
• Tuple2<ENTITY, ExecutionInfo> getOneWithStats(): get the first found entity with execution info

• CompletableFuture<Tuple2<ENTITY, ExecutionInfo>> getOneAsyncWithStats(): get the first found entity with execution info asynchronously

• List<ENTITY> getList(): get found entities
• CompletableFuture<List<ENTITY>> getListAsync(): get found entities asynchronously
• Tuple2<List<ENTITY>, ExecutionInfo> getListWithStats(): get found entities with execution info

• CompletableFuture<Tuple2<List<ENTITY>, ExecutionInfo>> getListAsyncWithStats(): get found entities with execution info asynchronously

• Iterator<ENTITY> iterator(): return an iterator for found entities

• TypedMap getTypedMap(): get the first found CQL row as an instance of TypedMap
• Tuple2<TypedMap, ExecutionInfo> getTypedMapWithStatus(): get the first found CQL row with execution info as an instance of TypedMap
• CompletableFuture<TypedMap> getTypedMapAsync(): get the first found CQL row asynchronously as an instance of TypedMap

• CompletableFuture<Tuple2<TypedMap, ExecutionInfo>> getTypedMapAsyncWithStats(): get the first found CQL row with execution info asynchronously an instance of TypedMap

• List<TypedMap> getTypedMaps(): get the found CQL rows as a list of TypedMap
• List<Tuple2<TypedMap, ExecutionInfo>> getTypedMapsWithStats(): get the found CQL rows with execution info as a list of TypedMap
• CompletableFuture<List<TypedMap>> getTypedMapsAsync(): get the found CQL rows asynchronously as a list of TypedMap

• CompletableFuture<Tuple2<List<TypedMap>, ExecutionInfo>> getTypedMapsAsyncWithStats(): get the found CQL rows with execution info asynchronously as a list of TypedMap

• Iterator<TypedMap> typedMapIterator(): return an iterator for found CQL rows as TypedMap

It is not mandatory to provide values for the WHERE clause, you can call the method
without_WHERE_Clause() to retrieve values

Please note that as soon as you invoke a function call (with .function(), Achilles can only return the results as TypedMap and not as entities) because it cannot map the result of the function call into a field of your entity.

If you need to map the result of a function call into a field of your entity, use the @Computed annotation instead.

Similar to the CRUD API, you can define runtime values for consistency levels, retry policy, ...

Update DSL

The Update DSL look like:

   
    manager
        .dsl()
        .update()
        .fromBaseTable()
        .firstname().Set("new firstname")
        .where()
        .userId().Eq(id)
        .execute();   

The DSL exposes the following final methods:

• execute(): execute the update
• CompletableFuture<Empty> executeAsync(): execute the update asynchronously
• ExecutionInfo executeWithStats(): execute the update and return the execution info
• CompletableFuture<ExecutionInfo>> executeAsyncWithStats(): execute the update and return the execution info asynchronously

Similar to the CRUD API, you can define runtime values for consistency levels, retry policy, ...

Delete DSL

The Delete DSL look like:

   
    manager
        .dsl()
        .delete()
        .firstname()
        .lastname()
        .fromBaseTable()
        .where()
        .userId().Eq(id)
        .execute();   

The DSL exposes the following final methods:

• execute(): execute the delete
• CompletableFuture<Empty> executeAsync(): execute the delete asynchronously
• ExecutionInfo executeWithStats(): execute the delete and return the execution info
• CompletableFuture<ExecutionInfo>> executeAsyncWithStats(): execute the delete and return the execution info asynchronously

Similar to the CRUD API, you can define runtime values for consistency levels, retry policy, ...

Raw Queries

The RAW queries API lets you inject any instance of:

• com.datastax.driver.core.RegularStatement
• com.datastax.driver.core.PreparedStatement
• com.datastax.driver.core.BoundStatement

and execute the query for you.

Typed Query

The Typed Query API execute the statement and map the returned com.datastax.driver.core.Row object(s) back to entity
instance. Thus this API can only be used for SELECT statements.

    Statement statement = ...;
    
    User instance = userManager
        .raw()
        .typedQueryForSelect(statement)
        .getOne();

This API exposes the following final methods:

• ENTITY getOne(): get the first found entity
• CompletableFuture<ENTITY> getOneAsync(): get the first found entity asynchronously
• Tuple2<ENTITY, ExecutionInfo> getOneWithStats(): get the first found entity with execution info

• CompletableFuture<Tuple2<ENTITY, ExecutionInfo>> getOneAsyncWithStats(): get the first found entity with execution info asynchronously

• List<ENTITY> getList(): get found entities
• CompletableFuture<List<ENTITY>> getListAsync(): get found entities asynchronously
• Tuple2<List<ENTITY>, ExecutionInfo> getListWithStats(): get found entities with execution info

• CompletableFuture<Tuple2<List<ENTITY>, ExecutionInfo>> getListAsyncWithStats(): get found entities with execution info asynchronously

• Iterator<ENTITY> iterator(): return an iterator for found entities

Similar to the CRUD API, you can define runtime values for consistency levels, retry policy, ...

Native Query

The Native Query API execute the statement and map the returned com.datastax.driver.core.Row object(s) back to
instance(s) of TypedMap.

    Statement statement = ...;
    final TypedMap found = userManager
        .raw()
        .nativeQuery(statement)
        .getOne();

This API exposes the following final methods:

• TypedMap getOne(): get the first found row
• CompletableFuture<TypedMap> getOneAsync(): get the first found row asynchronously
• Tuple2<TypedMap, ExecutionInfo> getOneWithStats(): get the first found row with execution info

• CompletableFuture<Tuple2<TypedMap, ExecutionInfo>> getOneAsyncWithStats(): get the first found row with execution info asynchronously

• List<TypedMap> getList(): get found entities
• CompletableFuture<List<TypedMap>> getListAsync(): get found rows asynchronously
• Tuple2<List<TypedMap>, ExecutionInfo> getListWithStats(): get found rows with execution info

• CompletableFuture<Tuple2<List<TypedMap>, ExecutionInfo>> getListAsyncWithStats(): get found rows with execution info asynchronously

• Iterator<ENTITY> iterator(): return an iterator for found rows

• execute(): execute the statement
• CompletableFuture<Empty> executeAsync(): execute the statement asynchronously
• ExecutionInfo executeWithStats(): execute the statement and return the execution info

• CompletableFuture<ExecutionInfo>> executeAsyncWithStats(): execute the statement and return the execution info asynchronously

Similar to the CRUD API, you can define runtime values for consistency levels, retry policy, ...

Dynamic Schema Name

In some multi-tenant environment, the keyspace/table name cannot be known ahead of time but only during runtime.
For this purpose, Achilles introduces a SchemaNameProvider interface to let people bind keyspace/table names
dynamically at runtime.

This provider can be used with CRUD API and DSL API:

    
    final SchemaNameProvider dynamicProvider = ...;
    
    userManager
        .crud()
        ...
        .withSchemaNameProvider(dynamicProvider)
        .execute();
        
    userManager
        .dsl()
        .select()
        ...
        .from(dynamicProvider)
        .where()
        ...
            
    userManager
        .dsl()
        .update()
        .from(dynamicProvider)
        ...
        .where()
        ...

    userManager
        .dsl()
        .delete()
        ...
        .from(dynamicProvider)
        ...
        .where()
        ... 
        

Raw Statement Generation

The Manager instance also exposes the following methods to generate raw com.datastax.driver.core.BoundStatement
and bound values. They are available for all both CRUD API and DSL API

• BoundStatement generateAndGetBoundStatement():

  • generate the prepared statement or get it from the statement cache if it already exists
  • extract values from entity or from the given API
  • bind values to the prepared statement
  • return the com.datastax.driver.core.BoundStatement instance
• String getStatementAsString(): self-explanatory
• List<Object> getBoundValues(): extract raw Java values from entity or from the given API

• List<Object> getEncodedBoundValues(): similar as getBoundValues() but encode the values using the Codec System

Other Methods

Apart from the 3 API (CRUD, DSL and Query), the Manager class also exposes some utility methods:

• public ENTITY mapFromRow(Row row): map a given instance of com.datastax.driver.core.Row
  to an instance of entity
• public Session getNativeSession(): return the native com.datastax.driver.core.Session object used by this
  Manager
• public Cluster getNativeCluster(): return the native com.datastax.driver.core.Cluster object used by this
  Manager