Skip to content

Manager API

Jump to bottom
DuyHai DOAN edited this page Oct 29, 2015 · 8 revisions

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

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

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, ...

Query

The Query 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
        .query()
        .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
        .query()
        .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

Home

Clone this wiki locally