Class AsyncCassandraTemplate
- All Implemented Interfaces:
Aware
,ApplicationContextAware
,ApplicationEventPublisherAware
,AsyncCassandraOperations
AsyncCassandraOperations
. It simplifies the use of asynchronous Cassandra usage and
helps to avoid common errors. It executes core Cassandra workflow. This class executes CQL queries or updates,
initiating iteration over ResultSet
and catching Cassandra exceptions and translating them to the generic,
more informative exception hierarchy defined in the org.springframework.dao
package.
Can be used within a service implementation via direct instantiation with a CqlSession
reference, or get
prepared in an application context and given to services as bean reference.
This class supports the use of prepared statements when enabling setUsePreparedStatements(boolean)
. All
statements created by methods of this class (such as select(Query, Class)
or
update(Query, org.springframework.data.cassandra.core.query.Update, Class)
will be executed as prepared
statements. Also, statements accepted by methods (such as select(String, Class)
or
and others
) will be prepared prior to execution. Note that Statement
objects passed to methods must be SimpleStatement
so that these can be prepared.
Note: The CqlSession
should always be configured as a bean in the application context, in the first case
given to the service directly, in the second case to the prepared template.
- Since:
- 2.0
- Author:
- Mark Paluch, John Blum
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic interface
General callback interface used to create and bind prepared CQL statements. -
Constructor Summary
ConstructorDescriptionAsyncCassandraTemplate
(com.datastax.oss.driver.api.core.CqlSession session) Creates an instance ofAsyncCassandraTemplate
initialized with the givenCqlSession
and a defaultMappingCassandraConverter
.AsyncCassandraTemplate
(com.datastax.oss.driver.api.core.CqlSession session, CassandraConverter converter) Creates an instance ofAsyncCassandraTemplate
initialized with the givenCqlSession
andCassandraConverter
.AsyncCassandraTemplate
(AsyncCqlTemplate asyncCqlTemplate, CassandraConverter converter) Creates an instance ofAsyncCassandraTemplate
initialized with the givenAsyncCqlTemplate
andCassandraConverter
.AsyncCassandraTemplate
(SessionFactory sessionFactory, CassandraConverter converter) Creates an instance ofAsyncCassandraTemplate
initialized with the givenSessionFactory
andCassandraConverter
. -
Method Summary
Modifier and TypeMethodDescriptionReturns the number of rows for the given entity class.Returns the number of rows for the given entity class applyingQuery
.createPreparedStatementHandler
(com.datastax.oss.driver.api.core.cql.Statement<?> statement) Create a new statement-basedAsyncCassandraTemplate.AsyncPreparedStatementHandler
using the statement passed in.delete
(Object entity, QueryOptions options) Delete the given entity applyingQueryOptions
and return the entity if the delete statement was applied.Remove entities (rows)/columns from the table byQuery
.<T> CompletableFuture<T>
delete
(T entity) Delete the given entity and return the entity if the delete statement was applied.deleteById
(Object id, Class<?> entityClass) Remove the given object from the table by id.CompletableFuture<com.datastax.oss.driver.api.core.cql.AsyncResultSet>
execute
(com.datastax.oss.driver.api.core.cql.Statement<?> statement) Execute the given CassandraStatement
.Determine whether a row ofentityClass
with the givenid
exists.Determine whether the result forentityClass
Query
yields at least one row.Expose the underlyingAsyncCqlOperations
to allow asynchronous CQL operations.Returns the underlyingCassandraConverter
.protected org.springframework.data.cassandra.core.EntityOperations
Returns theEntityOperations
used to perform data access operations on an entity inside a Cassandra data source.protected SpelAwareProxyProjectionFactory
Deprecated.protected StatementFactory
Returns theStatementFactory
used by this template to construct and run Cassandra CQL statements.<T> CompletableFuture<T>
insert
(T entity) Insert the given entity and return the entity if the insert was applied.<T> CompletableFuture<EntityWriteResult<T>>
insert
(T entity, InsertOptions options) Insert the given entity applyingWriteOptions
and return the entity if the insert was applied.boolean
Returns whether this instance is configured to useprepared statements
.protected <T> T
maybeCallBeforeConvert
(T object, com.datastax.oss.driver.api.core.CqlIdentifier tableName) protected <T> T
maybeCallBeforeSave
(T object, com.datastax.oss.driver.api.core.CqlIdentifier tableName, com.datastax.oss.driver.api.core.cql.Statement<?> statement) protected <E extends CassandraMappingEvent<T>,
T>
voidmaybeEmitEvent
(Supplier<E> event) <T> CompletableFuture<List<T>>
Execute aSELECT
query and convert the resulting items to aList
of entities.<T> CompletableFuture<Void>
select
(com.datastax.oss.driver.api.core.cql.Statement<?> statement, Consumer<T> entityConsumer, Class<T> entityClass) Execute aSELECT
query and convert the resulting items notifyingConsumer
for each entity.<T> CompletableFuture<List<T>>
Execute aSELECT
query and convert the resulting items to aList
of entities.<T> CompletableFuture<Void>
Execute aSELECT
query and convert the resulting items notifyingConsumer
for each entity.<T> CompletableFuture<List<T>>
Execute aSELECT
query and convert the resulting items to aList
of entities.<T> CompletableFuture<Void>
Execute aSELECT
query and convert the resulting items notifyingConsumer
for each entity.<T> CompletableFuture<T>
Execute aSELECT
query and convert the resulting item to an entity.<T> CompletableFuture<T>
Execute aSELECT
query and convert the resulting item to an entity.<T> CompletableFuture<T>
Execute aSELECT
query and convert the resulting item to an entity.<T> CompletableFuture<T>
selectOneById
(Object id, Class<T> entityClass) Execute the Select byid
for the givenentityClass
.void
setApplicationContext
(ApplicationContext applicationContext) void
setApplicationEventPublisher
(ApplicationEventPublisher applicationEventPublisher) void
setEntityCallbacks
(EntityCallbacks entityCallbacks) ConfigureEntityCallbacks
to pre-/post-process entities during persistence operations.void
setEntityLifecycleEventsEnabled
(boolean enabled) Configure whether lifecycle events such asAfterLoadEvent
,BeforeSaveEvent
, etc. should be published or whether emission should be suppressed.void
setUsePreparedStatements
(boolean usePreparedStatements) Enable/disableprepared statements
usage.<T> CompletableFuture<Slice<T>>
Execute aSELECT
query with paging and convert the result set to aSlice
of entities.<T> CompletableFuture<Slice<T>>
Execute aSELECT
query with paging and convert the result set to aSlice
of entities.Execute aTRUNCATE
query to remove all entities of a given class.Update the queried entities and return true if the update was applied.<T> CompletableFuture<T>
update
(T entity) Update the given entity and return the entity if the update was applied.<T> CompletableFuture<EntityWriteResult<T>>
update
(T entity, UpdateOptions options) Update the given entity applyingWriteOptions
and return the entity if the update was applied.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.springframework.data.cassandra.core.AsyncCassandraOperations
delete
-
Constructor Details
-
AsyncCassandraTemplate
public AsyncCassandraTemplate(com.datastax.oss.driver.api.core.CqlSession session) Creates an instance ofAsyncCassandraTemplate
initialized with the givenCqlSession
and a defaultMappingCassandraConverter
.- Parameters:
session
-CqlSession
used to interact with Cassandra; must not be null.- See Also:
-
CassandraConverter
CqlSession
-
AsyncCassandraTemplate
public AsyncCassandraTemplate(com.datastax.oss.driver.api.core.CqlSession session, CassandraConverter converter) Creates an instance ofAsyncCassandraTemplate
initialized with the givenCqlSession
andCassandraConverter
.- Parameters:
session
-CqlSession
used to interact with Cassandra; must not be null.converter
-CassandraConverter
used to convert between Java and Cassandra types; must not be null.- See Also:
-
CassandraConverter
CqlSession
-
AsyncCassandraTemplate
Creates an instance ofAsyncCassandraTemplate
initialized with the givenSessionFactory
andCassandraConverter
.- Parameters:
sessionFactory
-SessionFactory
used to interact with Cassandra; must not be null.converter
-CassandraConverter
used to convert between Java and Cassandra types; must not be null.- See Also:
-
CassandraConverter
CqlSession
-
AsyncCassandraTemplate
Creates an instance ofAsyncCassandraTemplate
initialized with the givenAsyncCqlTemplate
andCassandraConverter
.- Parameters:
asyncCqlTemplate
-AsyncCqlTemplate
used to interact with Cassandra; must not be null.converter
-CassandraConverter
used to convert between Java and Cassandra types; must not be null.- See Also:
-
CassandraConverter
CqlSession
-
-
Method Details
-
setApplicationEventPublisher
- Specified by:
setApplicationEventPublisher
in interfaceApplicationEventPublisherAware
-
setApplicationContext
- Specified by:
setApplicationContext
in interfaceApplicationContextAware
- Throws:
BeansException
-
setEntityCallbacks
ConfigureEntityCallbacks
to pre-/post-process entities during persistence operations.- Parameters:
entityCallbacks
-
-
setEntityLifecycleEventsEnabled
public void setEntityLifecycleEventsEnabled(boolean enabled) Configure whether lifecycle events such asAfterLoadEvent
,BeforeSaveEvent
, etc. should be published or whether emission should be suppressed. Enabled by default.- Parameters:
enabled
-true
to enable entity lifecycle events;false
to disable entity lifecycle events.- Since:
- 4.0
- See Also:
-
getAsyncCqlOperations
Description copied from interface:AsyncCassandraOperations
Expose the underlyingAsyncCqlOperations
to allow asynchronous CQL operations.- Specified by:
getAsyncCqlOperations
in interfaceAsyncCassandraOperations
- Returns:
- the underlying
AsyncCqlOperations
. - See Also:
-
getConverter
Description copied from interface:AsyncCassandraOperations
Returns the underlyingCassandraConverter
.- Specified by:
getConverter
in interfaceAsyncCassandraOperations
- Returns:
- the underlying
CassandraConverter
.
-
isUsePreparedStatements
public boolean isUsePreparedStatements()Returns whether this instance is configured to useprepared statements
. If enabled (default), then all persistence methods (such asselect(java.lang.String, java.lang.Class<T>)
,update(org.springframework.data.cassandra.core.query.Query, org.springframework.data.cassandra.core.query.Update, java.lang.Class<?>)
, and others) will make use of prepared statements. Note that methods accepting aStatement
must be called withSimpleStatement
instances to participate in statement preparation.- Returns:
- true if prepared statements usage is enabled; false otherwise.
- Since:
- 3.2
-
setUsePreparedStatements
public void setUsePreparedStatements(boolean usePreparedStatements) Enable/disableprepared statements
usage. If enabled (default), then all persistence methods (such asselect(java.lang.String, java.lang.Class<T>)
,update(org.springframework.data.cassandra.core.query.Query, org.springframework.data.cassandra.core.query.Update, java.lang.Class<?>)
, and others) will make use of prepared statements. Note that methods accepting aStatement
must be called withSimpleStatement
instances to participate in statement preparation.- Parameters:
usePreparedStatements
- whether to use prepared statements.- Since:
- 3.2
-
getEntityOperations
protected org.springframework.data.cassandra.core.EntityOperations getEntityOperations()Returns theEntityOperations
used to perform data access operations on an entity inside a Cassandra data source.- Returns:
- the configured
EntityOperations
for this template. - See Also:
-
EntityOperations
-
getProjectionFactory
Deprecated.since 3.4, useCassandraConverter.getProjectionFactory()
instead.Returns a reference to the configuredProjectionFactory
used by this template to process CQL query projections.- Returns:
- a reference to the configured
ProjectionFactory
used by this template to process CQL query projections. - Since:
- 2.1
- See Also:
-
getStatementFactory
Returns theStatementFactory
used by this template to construct and run Cassandra CQL statements.- Returns:
- the
StatementFactory
used by this template to construct and run Cassandra CQL statements. - Since:
- 2.1
- See Also:
-
select
Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query and convert the resulting items to aList
of entities.- Specified by:
select
in interfaceAsyncCassandraOperations
- Parameters:
cql
- must not be null.entityClass
- The entity type must not be null.- Returns:
- the converted results
-
select
public <T> CompletableFuture<Void> select(String cql, Consumer<T> entityConsumer, Class<T> entityClass) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query and convert the resulting items notifyingConsumer
for each entity.- Specified by:
select
in interfaceAsyncCassandraOperations
- Parameters:
cql
- must not be null.entityConsumer
- object that will be notified on each entity, one object at a time, must not be null.entityClass
- The entity type must not be null.- Returns:
- the completion handle
- Throws:
DataAccessException
- if there is any problem executing the query.
-
selectOne
Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query and convert the resulting item to an entity.- Specified by:
selectOne
in interfaceAsyncCassandraOperations
- Parameters:
cql
- must not be null.entityClass
- The entity type must not be null.- Returns:
- the converted object or null.
-
execute
public CompletableFuture<com.datastax.oss.driver.api.core.cql.AsyncResultSet> execute(com.datastax.oss.driver.api.core.cql.Statement<?> statement) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Execute the given CassandraStatement
. Any errors that result from executing this command will be converted into Spring's DAO exception hierarchy.- Specified by:
execute
in interfaceAsyncCassandraOperations
- Parameters:
statement
- a CassandraStatement
, must not be null.- Returns:
- the
AsyncResultSet
. - Throws:
DataAccessException
- if there is any problem executing the query.
-
select
public <T> CompletableFuture<List<T>> select(com.datastax.oss.driver.api.core.cql.Statement<?> statement, Class<T> entityClass) Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query and convert the resulting items to aList
of entities.- Specified by:
select
in interfaceAsyncCassandraOperations
- Parameters:
statement
- must not be null.entityClass
- The entity type must not be null.- Returns:
- the converted results
-
select
public <T> CompletableFuture<Void> select(com.datastax.oss.driver.api.core.cql.Statement<?> statement, Consumer<T> entityConsumer, Class<T> entityClass) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query and convert the resulting items notifyingConsumer
for each entity.- Specified by:
select
in interfaceAsyncCassandraOperations
- Parameters:
statement
- must not be null.entityConsumer
- object that will be notified on each entity, one object at a time, must not be null.entityClass
- The entity type must not be null.- Returns:
- the completion handle
- Throws:
DataAccessException
- if there is any problem executing the query.
-
selectOne
public <T> CompletableFuture<T> selectOne(com.datastax.oss.driver.api.core.cql.Statement<?> statement, Class<T> entityClass) Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query and convert the resulting item to an entity.- Specified by:
selectOne
in interfaceAsyncCassandraOperations
- Parameters:
statement
- must not be null.entityClass
- The entity type must not be null.- Returns:
- the converted object or null.
-
slice
public <T> CompletableFuture<Slice<T>> slice(com.datastax.oss.driver.api.core.cql.Statement<?> statement, Class<T> entityClass) Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query with paging and convert the result set to aSlice
of entities. A sliced query translates the effectivefetch size
to the page size.- Specified by:
slice
in interfaceAsyncCassandraOperations
- Parameters:
statement
- the CQL statement, must not be null.entityClass
- The entity type must not be null.- Returns:
- the converted results
- See Also:
-
select
public <T> CompletableFuture<List<T>> select(Query query, Class<T> entityClass) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query and convert the resulting items to aList
of entities.- Specified by:
select
in interfaceAsyncCassandraOperations
- Parameters:
query
- must not be null.entityClass
- The entity type must not be null.- Returns:
- the converted results
- Throws:
DataAccessException
- if there is any problem executing the query.
-
select
public <T> CompletableFuture<Void> select(Query query, Consumer<T> entityConsumer, Class<T> entityClass) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query and convert the resulting items notifyingConsumer
for each entity.- Specified by:
select
in interfaceAsyncCassandraOperations
- Parameters:
query
- must not be null.entityConsumer
- object that will be notified on each entity, one object at a time, must not be null.entityClass
- The entity type must not be null.- Returns:
- the completion handle
- Throws:
DataAccessException
- if there is any problem executing the query.
-
selectOne
public <T> CompletableFuture<T> selectOne(Query query, Class<T> entityClass) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query and convert the resulting item to an entity.- Specified by:
selectOne
in interfaceAsyncCassandraOperations
- Parameters:
query
- must not be null.entityClass
- The entity type must not be null.- Returns:
- the converted object or null.
- Throws:
DataAccessException
- if there is any problem executing the query.
-
slice
public <T> CompletableFuture<Slice<T>> slice(Query query, Class<T> entityClass) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Execute aSELECT
query with paging and convert the result set to aSlice
of entities.- Specified by:
slice
in interfaceAsyncCassandraOperations
- Parameters:
query
- the query object used to create a CQL statement, must not be null.entityClass
- The entity type must not be null.- Returns:
- the converted results
- Throws:
DataAccessException
- if there is any problem executing the query.- See Also:
-
update
public CompletableFuture<Boolean> update(Query query, Update update, Class<?> entityClass) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Update the queried entities and return true if the update was applied.- Specified by:
update
in interfaceAsyncCassandraOperations
- Parameters:
query
- must not be null.update
- must not be null.entityClass
- The entity type must not be null.- Throws:
DataAccessException
- if there is any problem executing the query.
-
delete
public CompletableFuture<Boolean> delete(Query query, Class<?> entityClass) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Remove entities (rows)/columns from the table byQuery
.- Specified by:
delete
in interfaceAsyncCassandraOperations
- Parameters:
query
- must not be null.entityClass
- The entity type must not be null.- Returns:
- true if the deletion was applied.
- Throws:
DataAccessException
- if there is any problem executing the query.
-
count
Description copied from interface:AsyncCassandraOperations
Returns the number of rows for the given entity class.- Specified by:
count
in interfaceAsyncCassandraOperations
- Parameters:
entityClass
-type
of the entity; must not be null.- Returns:
- the number of existing entities.
-
count
Description copied from interface:AsyncCassandraOperations
Returns the number of rows for the given entity class applyingQuery
. This overridden method allows users to further refine the selection criteria using aQuery
predicate to determine how many entities of the giventype
match the criteria.- Specified by:
count
in interfaceAsyncCassandraOperations
- Parameters:
query
- user-provided countQuery
to execute; must not be null.entityClass
-type
of the entity; must not be null.- Returns:
- the number of existing entities.
- Throws:
DataAccessException
- if any problem occurs while executing the query.
-
exists
Description copied from interface:AsyncCassandraOperations
Determine whether a row ofentityClass
with the givenid
exists.- Specified by:
exists
in interfaceAsyncCassandraOperations
- Parameters:
id
- Id value. For single primary keys it's the plain value. For composite primary keys either, it's an instance of eitherPrimaryKeyClass
orMapId
. Must not be null.entityClass
-type
of the entity; must not be null.- Returns:
- true if the object exists.
-
exists
public CompletableFuture<Boolean> exists(Query query, Class<?> entityClass) throws DataAccessException Description copied from interface:AsyncCassandraOperations
Determine whether the result forentityClass
Query
yields at least one row.- Specified by:
exists
in interfaceAsyncCassandraOperations
- Parameters:
query
- user-provided existsQuery
to execute; must not be null.entityClass
-type
of the entity; must not be null.- Returns:
- true if the object exists.
- Throws:
DataAccessException
- if any problem occurs while executing the query.
-
selectOneById
Description copied from interface:AsyncCassandraOperations
Execute the Select byid
for the givenentityClass
.- Specified by:
selectOneById
in interfaceAsyncCassandraOperations
- Parameters:
id
- the Id value. For single primary keys it's the plain value. For composite primary keys either thePrimaryKeyClass
orMapId
. Must not be null.entityClass
- The entity type must not be null.- Returns:
- the converted object or null.
-
insert
Description copied from interface:AsyncCassandraOperations
Insert the given entity and return the entity if the insert was applied.- Specified by:
insert
in interfaceAsyncCassandraOperations
- Parameters:
entity
- The entity to insert, must not be null.- Returns:
- the inserted entity.
-
insert
Description copied from interface:AsyncCassandraOperations
Insert the given entity applyingWriteOptions
and return the entity if the insert was applied.- Specified by:
insert
in interfaceAsyncCassandraOperations
- Parameters:
entity
- The entity to insert, must not be null.options
- must not be null.- Returns:
- the
EntityWriteResult
for this operation. - See Also:
-
update
Description copied from interface:AsyncCassandraOperations
Update the given entity and return the entity if the update was applied.- Specified by:
update
in interfaceAsyncCassandraOperations
- Parameters:
entity
- The entity to update, must not be null.- Returns:
- the updated entity.
-
update
Description copied from interface:AsyncCassandraOperations
Update the given entity applyingWriteOptions
and return the entity if the update was applied.- Specified by:
update
in interfaceAsyncCassandraOperations
- Parameters:
entity
- The entity to update, must not be null.options
- must not be null.- Returns:
- the
EntityWriteResult
for this operation. - See Also:
-
delete
Description copied from interface:AsyncCassandraOperations
Delete the given entity and return the entity if the delete statement was applied.- Specified by:
delete
in interfaceAsyncCassandraOperations
- Parameters:
entity
- must not be null.- Returns:
- the deleted entity.
-
delete
Description copied from interface:AsyncCassandraOperations
Delete the given entity applyingQueryOptions
and return the entity if the delete statement was applied.- Specified by:
delete
in interfaceAsyncCassandraOperations
- Parameters:
entity
- must not be null.options
- must not be null.- Returns:
- the
WriteResult
for this operation. - See Also:
-
deleteById
Description copied from interface:AsyncCassandraOperations
Remove the given object from the table by id.- Specified by:
deleteById
in interfaceAsyncCassandraOperations
- Parameters:
id
- the Id value. For single primary keys it's the plain value. For composite primary keys either thePrimaryKeyClass
orMapId
. Must not be null.entityClass
- The entity type must not be null.- Returns:
- true if the deletion was applied.
-
truncate
Description copied from interface:AsyncCassandraOperations
Execute aTRUNCATE
query to remove all entities of a given class.- Specified by:
truncate
in interfaceAsyncCassandraOperations
- Parameters:
entityClass
- The entity type must not be null.
-
createPreparedStatementHandler
protected AsyncCassandraTemplate.AsyncPreparedStatementHandler createPreparedStatementHandler(com.datastax.oss.driver.api.core.cql.Statement<?> statement) Create a new statement-basedAsyncCassandraTemplate.AsyncPreparedStatementHandler
using the statement passed in.This method allows for the creation to be overridden by subclasses.
- Parameters:
statement
- the statement to be prepared.- Returns:
- the new
AsyncCassandraTemplate.PreparedStatementHandler
to use. - Since:
- 3.3.3
-
maybeEmitEvent
-
maybeCallBeforeConvert
protected <T> T maybeCallBeforeConvert(T object, com.datastax.oss.driver.api.core.CqlIdentifier tableName) -
maybeCallBeforeSave
protected <T> T maybeCallBeforeSave(T object, com.datastax.oss.driver.api.core.CqlIdentifier tableName, com.datastax.oss.driver.api.core.cql.Statement<?> statement)
-
CassandraConverter.getProjectionFactory()
instead.