diff --git a/spring-cql/src/main/java/org/springframework/cassandra/core/AsyncCqlOperations.java b/spring-cql/src/main/java/org/springframework/cassandra/core/AsyncCqlOperations.java
index 3984586f8..c9283f081 100644
--- a/spring-cql/src/main/java/org/springframework/cassandra/core/AsyncCqlOperations.java
+++ b/spring-cql/src/main/java/org/springframework/cassandra/core/AsyncCqlOperations.java
@@ -18,25 +18,32 @@ package org.springframework.cassandra.core;
import java.util.List;
import java.util.Map;
-import org.springframework.dao.DataAccessException;
-import org.springframework.dao.IncorrectResultSizeDataAccessException;
-import org.springframework.util.concurrent.ListenableFuture;
-
import com.datastax.driver.core.PreparedStatement;
import com.datastax.driver.core.ResultSet;
import com.datastax.driver.core.Statement;
+import org.springframework.dao.DataAccessException;
+import org.springframework.dao.IncorrectResultSizeDataAccessException;
+import org.springframework.util.concurrent.ListenableFuture;
+
+import reactor.core.publisher.Mono;
+
/**
- * Interface specifying a basic set of CQL asynchronously executed operations. Exposes similar methods as {@link CqlTemplate}, but returns
- * result handles or accepts callbacks as opposed to concrete results. Implemented by {@link AsyncCqlTemplate}. Not
- * often used directly, but a useful option to enhance testability, as it can easily be mocked or stubbed.
+ * Interface specifying a basic set of CQL asynchronously executed operations. Exposes similar methods
+ * as {@link CqlTemplate}, but returns result handles or accepts callbacks as opposed to concrete results.
+ * Implemented by {@link AsyncCqlTemplate}. Not often used directly, but a useful option to enhance testability,
+ * as it can easily be mocked or stubbed.
*
* @author Mark Paluch
+ * @author John Blum
* @since 2.0
* @see AsyncCqlTemplate
+ * @see CqlOperations
*/
public interface AsyncCqlOperations {
+ // TODO many of these data access operations could be implemented as default methods, in terms of other data access operations
+
// -------------------------------------------------------------------------
// Methods dealing with a plain com.datastax.driver.core.Session
// -------------------------------------------------------------------------
@@ -48,7 +55,7 @@ public interface AsyncCqlOperations {
* {@link com.datastax.driver.core.exceptions.DriverException}s into Spring's {@link DataAccessException} hierarchy.
*
* The callback action can return a result object, for example a domain object or a collection of domain objects.
- *
+ *
* @param action the callback object that specifies the action.
* @return a result object returned by the action, or {@literal null}.
* @throws DataAccessException if there is any problem executing the query.
@@ -61,26 +68,68 @@ public interface AsyncCqlOperations {
/**
* Issue a single CQL execute, typically a DDL statement, insert, update or delete statement.
- *
+ *
* @param cql static CQL to execute, must not be empty or {@literal null}.
* @return boolean value whether the statement was applied.
* @throws DataAccessException if there is any problem executing the query.
*/
ListenableFuture execute(String cql) throws DataAccessException;
+ /**
+ * Issue a single CQL operation (such as an insert, update or delete statement) via a prepared statement, binding the
+ * given arguments.
+ *
+ * @param cql static CQL to execute, must not be empty or {@literal null}.
+ * @param args arguments to bind to the query (leaving it to the {@link PreparedStatement} to guess the corresponding
+ * CQL type).
+ * @return boolean value whether the statement was applied.
+ * @throws DataAccessException if there is any problem issuing the execution.
+ */
+ ListenableFuture execute(String cql, Object... args) throws DataAccessException;
+
+ /**
+ * Issue an statement using a {@link PreparedStatementBinder} to set bind parameters, with given CQL. Simpler than
+ * using a {@link AsyncPreparedStatementCreator} as this method will create the {@link PreparedStatement}: The
+ * {@link PreparedStatementBinder} just needs to set parameters.
+ *
+ * @param cql static CQL to execute, must not be empty or {@literal null}.
+ * @param preparedStatementBinder object that knows how to set values on the prepared statement. If this is {@literal null}, the CQL will
+ * be assumed to contain no bind parameters. Even if there are no bind parameters, this object may be used to
+ * set fetch size and other performance options.
+ * @return boolean value whether the statement was applied.
+ * @throws DataAccessException if there is any problem issuing the execution.
+ */
+ ListenableFuture execute(String cql, PreparedStatementBinder preparedStatementBinder) throws DataAccessException;
+
+ /**
+ * Execute a CQL data access operation, implemented as callback action working on a CQL {@link PreparedStatement}.
+ * This allows for implementing arbitrary data access operations on a single Statement, within Spring's managed CQL
+ * environment: that is, participating in Spring-managed transactions and converting CQL
+ * {@link com.datastax.driver.core.exceptions.DriverException}s into Spring's {@link DataAccessException} hierarchy.
+ *
+ * The callback action can return a result object, for example a domain object or a collection of domain objects.
+ *
+ * @param cql static CQL to execute, must not be empty or {@literal null}.
+ * @param action callback object that specifies the action, must not be {@literal null}.
+ * @return a result object returned by the action, or {@literal null}
+ * @throws DataAccessException if there is any problem TODO: Lambda-usage clashes with execute(cql,
+ * PreparedStatementBinder)
+ */
+ ListenableFuture execute(String cql, PreparedStatementCallback action) throws DataAccessException;
+
/**
* Execute a query given static CQL, reading the {@link ResultSet} with a {@link ResultSetExtractor}.
*
* Uses a CQL Statement, not a {@link PreparedStatement}. If you want to execute a static query with a
* {@link PreparedStatement}, use the overloaded {@code query} method with {@literal null} as argument array.
- *
+ *
* @param cql static CQL to execute, must not be empty or {@literal null}.
- * @param rse object that will extract all rows of results, must not be {@literal null}.
+ * @param resultSetExtractor object that will extract all rows of results, must not be {@literal null}.
* @return an arbitrary result object, as returned by the ResultSetExtractor.
* @throws DataAccessException if there is any problem executing the query.
* @see #query(String, ResultSetExtractor, Object...)
*/
- ListenableFuture query(String cql, ResultSetExtractor rse) throws DataAccessException;
+ ListenableFuture query(String cql, ResultSetExtractor resultSetExtractor) throws DataAccessException;
/**
* Execute a query given static CQL, reading the {@link ResultSet} on a per-row basis with a
@@ -88,20 +137,20 @@ public interface AsyncCqlOperations {
*
* Uses a CQL Statement, not a {@link PreparedStatement}. If you want to execute a static query with a
* {@link PreparedStatement}, use the overloaded {@code query} method with {@code null} as argument array.
- *
+ *
* @param cql static CQL to execute, must not be empty or {@literal null}.
- * @param rch object that will extract results, one row at a time, must not be {@literal null}.
+ * @param rowCallbackHandler object that will extract results, one row at a time, must not be {@literal null}.
* @throws DataAccessException if there is any problem executing the query
* @see #query(String, RowCallbackHandler, Object[])
*/
- ListenableFuture query(String cql, RowCallbackHandler rch) throws DataAccessException;
+ ListenableFuture query(String cql, RowCallbackHandler rowCallbackHandler) throws DataAccessException;
/**
* Execute a query given static CQL, mapping each row to a Java object via a {@link RowMapper}.
*
* Uses a CQL Statement, not a {@link PreparedStatement}. If you want to execute a static query with a
* {@link PreparedStatement}, use the overloaded {@code query} method with {@literal null} as argument array.
- *
+ *
* @param cql static CQL to execute, must not be empty or {@literal null}.
* @param rowMapper object that will map one object per row, must not be {@literal null}.
* @return the result {@link List}, containing mapped objects.
@@ -111,59 +160,120 @@ public interface AsyncCqlOperations {
ListenableFuture> query(String cql, RowMapper rowMapper) throws DataAccessException;
/**
- * Execute a query given static CQL, mapping a single result row to a Java object via a {@link RowMapper}.
- *
- * Uses a CQL Statement, not a {@link PreparedStatement}. If you want to execute a static query with a
- * {@link PreparedStatement}, use the overloaded {@link #queryForObject(String, RowMapper, Object...)} method with
- * {@literal null} as argument array.
- *
+ * Query given CQL to create a prepared statement from CQL and a list of arguments to bind to the query, reading the
+ * {@link ResultSet} with a {@link ResultSetExtractor}.
+ *
* @param cql static CQL to execute, must not be empty or {@literal null}.
+ * @param resultSetExtractor object that will extract results, must not be {@literal null}.
+ * @param args arguments to bind to the query (leaving it to the {@link PreparedStatement} to guess the corresponding
+ * CQL type).
+ * @return an arbitrary result object, as returned by the {@link ResultSetExtractor}
+ * @throws DataAccessException if there is any problem executing the query.
+ */
+ ListenableFuture query(String cql, ResultSetExtractor resultSetExtractor, Object... args) throws DataAccessException;
+
+ /**
+ * Query given CQL to create a prepared statement from CQL and a list of arguments to bind to the query, reading the
+ * {@link ResultSet} on a per-row basis with a {@link RowCallbackHandler}.
+ *
+ * @param cql static CQL to execute, must not be empty or {@literal null}.
+ * @param rowCallbackHandler object that will extract results, one row at a time, must not be {@literal null}.
+ * @param args arguments to bind to the query (leaving it to the {@link PreparedStatement} to guess the corresponding
+ * CQL type)
+ * @throws DataAccessException if there is any problem executing the query.
+ */
+ ListenableFuture query(String cql, RowCallbackHandler rowCallbackHandler, Object... args) throws DataAccessException;
+
+ /**
+ * Query given CQL to create a prepared statement from CQL and a list of arguments to bind to the query, mapping each
+ * row to a Java object via a {@link RowMapper}.
+ *
+ * @param cql static CQL to execute, must not be empty or {@literal null}.
+ * @param rowMapper object that will map one object per row
+ * @param args arguments to bind to the query (leaving it to the {@link PreparedStatement} to guess the corresponding
+ * CQL type)
+ * @return the result {@link List}, containing mapped objects
+ * @throws DataAccessException if there is any problem executing the query.
+ */
+ ListenableFuture> query(String cql, RowMapper rowMapper, Object... args) throws DataAccessException;
+
+ /**
+ * Query using a prepared statement, reading the {@link ResultSet} with a {@link ResultSetExtractor}.
+ *
+ * @param cql static CQL to execute, must not be empty or {@literal null}.
+ * @param preparedStatementBinder object that knows how to set values on the prepared statement. If this is {@literal null}, the CQL will
+ * be assumed to contain no bind parameters. Even if there are no bind parameters, this object may be used to
+ * set fetch size and other performance options.
+ * @param resultSetExtractor object that will extract results, must not be {@literal null}.
+ * @return an arbitrary result object, as returned by the {@link ResultSetExtractor}.
+ * @throws DataAccessException if there is any problem
+ */
+ ListenableFuture query(String cql, PreparedStatementBinder preparedStatementBinder, ResultSetExtractor resultSetExtractor)
+ throws DataAccessException;
+
+ /**
+ * Query given CQL to create a prepared statement from CQL and a {@link PreparedStatementBinder} implementation that
+ * knows how to bind values to the query, reading the {@link ResultSet} on a per-row basis with a
+ * {@link RowCallbackHandler}.
+ *
+ * @param cql static CQL to execute, must not be empty or {@literal null}.
+ * @param preparedStatementBinder object that knows how to set values on the prepared statement. If this is {@literal null}, the CQL will
+ * be assumed to contain no bind parameters. Even if there are no bind parameters, this object may be used to
+ * set fetch size and other performance options.
+ * @param rowCallbackHandler object that will extract results, one row at a time, must not be {@literal null}.
+ * @throws DataAccessException if there is any problem executing the query.
+ */
+ ListenableFuture query(String cql, PreparedStatementBinder preparedStatementBinder, RowCallbackHandler rowCallbackHandler)
+ throws DataAccessException;
+
+ /**
+ * Query given CQL to create a prepared statement from CQL and a {@link PreparedStatementBinder} implementation that
+ * knows how to bind values to the query, mapping each row to a Java object via a {@link RowMapper}.
+ *
+ * @param cql static CQL to execute, must not be empty or {@literal null}.
+ * @param preparedStatementBinder object that knows how to set values on the prepared statement. If this is {@literal null}, the CQL will
+ * be assumed to contain no bind parameters. Even if there are no bind parameters, this object may be used to
+ * set fetch size and other performance options.
* @param rowMapper object that will map one object per row, must not be {@literal null}.
- * @return the single mapped object.
- * @throws IncorrectResultSizeDataAccessException if the query does not return exactly one row.
+ * @return the result {@link List}, containing mapped objects.
* @throws DataAccessException if there is any problem executing the query.
- * @see #queryForObject(String, RowMapper, Object[])
*/
- ListenableFuture queryForObject(String cql, RowMapper rowMapper) throws DataAccessException;
+ ListenableFuture> query(String cql, PreparedStatementBinder preparedStatementBinder, RowMapper rowMapper)
+ throws DataAccessException;
/**
- * Execute a query for a result object, given static CQL.
+ * Execute a query for a result {@link List}, given static CQL.
*
* Uses a CQL Statement, not a {@link PreparedStatement}. If you want to execute a static query with a
- * {@link PreparedStatement}, use the overloaded {@link #queryForObject(String, Class, Object...)} method with
- * {@literal null} as argument array.
+ * {@link PreparedStatement}, use the overloaded {@code queryForList} method with {@literal null} as argument array.
*
- * This method is useful for running static CQL with a known outcome. The query is expected to be a single row/single
- * column query; the returned result will be directly mapped to the corresponding object type.
- *
+ * The results will be mapped to a {@link List} (one item for each row) of {@link Map}s (one entry for each column
+ * using the column name as the key). Each item in the {@link List} will be of the form returned by this interface's
+ * queryForMap() methods.
+ *
* @param cql static CQL to execute, must not be empty or {@literal null}.
- * @param requiredType the type that the result object is expected to match, must not be {@literal null}.
- * @return the result object of the required type, or {@link Mono#empty()} in case of CQL NULL.
- * @throws IncorrectResultSizeDataAccessException if the query does not return exactly one row, or does not return
- * exactly one column in that row.
+ * @return a {@link List} that contains a {@link Map} per row.
* @throws DataAccessException if there is any problem executing the query.
- * @see #queryForObject(String, Class, Object[])
+ * @see #queryForList(String, Object[])
*/
- ListenableFuture queryForObject(String cql, Class requiredType) throws DataAccessException;
+ ListenableFuture>> queryForList(String cql) throws DataAccessException;
/**
- * Execute a query for a result Map, given static CQL.
+ * Query given CQL to create a prepared statement from CQL and a list of arguments to bind to the query, expecting a
+ * result {@link List}.
*
- * Uses a CQL Statement, not a {@link PreparedStatement}. If you want to execute a static query with a
- * {@link PreparedStatement}, use the overloaded {@link #queryForMap(String, Object...)} method with {@literal null}
- * as argument array.
- *
- * The query is expected to be a single row query; the result row will be mapped to a Map (one entry for each column,
- * using the column name as the key).
- *
+ * The results will be mapped to a {@link List} (one item for each row) of {@link Map}s (one entry for each column,
+ * using the column name as the key). Each item in the {@link List} will be of the form returned by this interface's
+ * queryForMap() methods.
+ *
* @param cql static CQL to execute, must not be empty or {@literal null}.
- * @return the result Map (one entry for each column, using the column name as the key), must not be {@literal null}.
- * @throws IncorrectResultSizeDataAccessException if the query does not return exactly one row.
+ * @param args arguments to bind to the query (leaving it to the {@link PreparedStatement} to guess the corresponding
+ * CQL type).
+ * @return a {@link List} that contains a {@link Map} per row
* @throws DataAccessException if there is any problem executing the query.
- * @see #queryForMap(String, Object[])
- * @see ColumnMapRowMapper
+ * @see #queryForList(String)
*/
- ListenableFuture