diff --git a/build.gradle b/build.gradle index c9dae6657..e1507a35b 100644 --- a/build.gradle +++ b/build.gradle @@ -73,13 +73,14 @@ javadoc { ext.tmpDir = file("${buildDir}/api-work") configure(options) { - stylesheetFile = file("${srcDir}/spring-javadoc.css") - overview = "${srcDir}/overview.html" + //stylesheetFile = file("${srcDir}/spring-javadoc.css") + //overview = "${srcDir}/overview.html" docFilesSubDirs = true outputLevel = org.gradle.external.javadoc.JavadocOutputLevel.QUIET breakIterator = true showFromProtected() groups = [ + 'Spring Cassandra' : ['org.springframework.cassandra*'], 'Spring Data Cassandra' : ['org.springframework.data.cassandra*'], ] diff --git a/src/main/java/org/springframework/cassandra/core/CassandraOperations.java b/src/main/java/org/springframework/cassandra/core/CassandraOperations.java index 82d052fce..991c9ec95 100644 --- a/src/main/java/org/springframework/cassandra/core/CassandraOperations.java +++ b/src/main/java/org/springframework/cassandra/core/CassandraOperations.java @@ -22,6 +22,7 @@ import java.util.Map; import org.springframework.dao.DataAccessException; import com.datastax.driver.core.ResultSet; +import com.datastax.driver.core.Session; /** * Operations for interacting with Cassandra at the lowest level. This interface provides Exception Translation. @@ -36,7 +37,7 @@ public interface CassandraOperations { * SessionCallback can decide whether or not to execute() or executeAsync() the operation. * * @param sessionCallback - * @return + * @return Type defined in the SessionCallback */ T execute(SessionCallback sessionCallback) throws DataAccessException; @@ -48,19 +49,19 @@ public interface CassandraOperations { void execute(final String cql) throws DataAccessException; /** - * Executes the supplied CQL Query Asynchrously and returns nothing. + * Executes the supplied CQL Query Asynchronously and returns nothing. * - * @param cql + * @param cql The CQL Statement to execute */ void executeAsynchronously(final String cql) throws DataAccessException; /** - * Executes the provided CQL Query, and extracts the results with the ResultSetExtractor + * Executes the provided CQL Query, and extracts the results with the ResultSetExtractor. * * @param cql The Query - * @param rse The implementation for extracting the results + * @param rse The implementation for extracting the ResultSet * - * @return + * @return Type specified in the ResultSetExtractor * @throws DataAccessException */ T query(final String cql, ResultSetExtractor rse) throws DataAccessException; @@ -69,72 +70,332 @@ public interface CassandraOperations { * Executes the provided CQL Query asynchronously, and extracts the results with the ResultSetFutureExtractor * * @param cql The Query - * @param rse The implementation for extracting the results + * @param rse The implementation for extracting the future results * @return * @throws DataAccessException */ T queryAsynchronously(final String cql, ResultSetFutureExtractor rse) throws DataAccessException; + /** + * Executes the provided CQL Query, and then processes the results with the RowCallbackHandler. + * + * @param cql The Query + * @param rch The implementation for processing the rows returned. + * @throws DataAccessException + */ void query(final String cql, RowCallbackHandler rch) throws DataAccessException; + /** + * Processes the ResultSet through the RowCallbackHandler and return nothing. This is used internal to the Template + * for core operations, but is made available through Operations in the event you have a ResultSet to process. The + * ResultsSet could come from a ResultSetFuture after an asynchronous query. + * + * @param resultSet Results to process + * @param rch RowCallbackHandler with the processing implementation + * @throws DataAccessException + */ void process(ResultSet resultSet, RowCallbackHandler rch) throws DataAccessException; + /** + * Executes the provided CQL Query, and maps all Rows returned with the supplied RowMapper. + * + * @param cql The Query + * @param rowMapper The implementation for mapping all rows + * @return List of processed by the RowMapper + * @throws DataAccessException + */ List query(final String cql, RowMapper rowMapper) throws DataAccessException; + /** + * Processes the ResultSet through the RowMapper and returns the List of mapped Rows. This is used internal to the + * Template for core operations, but is made available through Operations in the event you have a ResultSet to + * process. The ResultsSet could come from a ResultSetFuture after an asynchronous query. + * + * @param resultSet Results to process + * @param rowMapper RowMapper with the processing implementation + * @return List of generated by the RowMapper + * @throws DataAccessException + */ List process(ResultSet resultSet, RowMapper rowMapper) throws DataAccessException; + /** + * Executes the provided CQL Query, and maps ONE Row returned with the supplied RowMapper. + * + *

+ * This expects only ONE row to be returned. More than one Row will cause an Exception to be thrown. + *

+ * + * @param cql The Query + * @param rowMapper The implementation for convert the Row to + * @return Object + * @throws DataAccessException + */ T queryForObject(final String cql, RowMapper rowMapper) throws DataAccessException; + /** + * Process a ResultSet through a RowMapper. This is used internal to the Template for core operations, but is made + * available through Operations in the event you have a ResultSet to process. The ResultsSet could come from a + * ResultSetFuture after an asynchronous query. + * + * @param resultSet + * @param rowMapper + * @return + * @throws DataAccessException + */ T processOne(ResultSet resultSet, RowMapper rowMapper) throws DataAccessException; + /** + * Executes the provided query and tries to return the first column of the first Row as a Class. + * + * @param cql The Query + * @param requiredType Valid Class that Cassandra Data Types can be converted to. + * @return The Object - item [0,0] in the result table of the query. + * @throws DataAccessException + */ T queryForObject(final String cql, Class requiredType) throws DataAccessException; + /** + * Process a ResultSet, trying to convert the first columns of the first Row to Class. This is used internal to the + * Template for core operations, but is made available through Operations in the event you have a ResultSet to + * process. The ResultsSet could come from a ResultSetFuture after an asynchronous query. + * + * @param resultSet + * @param requiredType + * @return + * @throws DataAccessException + */ T processOne(ResultSet resultSet, Class requiredType) throws DataAccessException; + /** + * Executes the provided CQL Query and maps ONE Row to a basic Map of Strings and Objects. If more than one Row + * is returned from the Query, an exception will be thrown. + * + * @param cql The Query + * @return Map representing the results of the Query + * @throws DataAccessException + */ Map queryForMap(final String cql) throws DataAccessException; + /** + * Process a ResultSet with ONE Row and convert to a Map. This is used internal to the Template for core + * operations, but is made available through Operations in the event you have a ResultSet to process. The ResultsSet + * could come from a ResultSetFuture after an asynchronous query. + * + * @param resultSet + * @return + * @throws DataAccessException + */ Map processMap(ResultSet resultSet) throws DataAccessException; + /** + * Executes the provided CQL and returns all values in the first column of the Results as a List of the Type in the + * second argument. + * + * @param cql The Query + * @param elementType Type to cast the data values to + * @return List of elementType + * @throws DataAccessException + */ List queryForList(final String cql, Class elementType) throws DataAccessException; + /** + * Process a ResultSet and convert the first column of the results to a List. This is used internal to the Template + * for core operations, but is made available through Operations in the event you have a ResultSet to process. The + * ResultsSet could come from a ResultSetFuture after an asynchronous query. + * + * @param resultSet + * @param elementType + * @return + * @throws DataAccessException + */ List processList(ResultSet resultSet, Class elementType) throws DataAccessException; + /** + * Executes the provided CQL and converts the results to a basic List of Maps. Each element in the List represents a + * Row returned from the Query. Each Row's columns are put into the map as column/value. + * + * @param cql The Query + * @return List of Maps with the query results + * @throws DataAccessException + */ List> queryForListOfMap(final String cql) throws DataAccessException; + /** + * Process a ResultSet and convert it to a List of Maps with column/value. This is used internal to the Template for + * core operations, but is made available through Operations in the event you have a ResultSet to process. The + * ResultsSet could come from a ResultSetFuture after an asynchronous query. + * + * @param resultSet + * @return + * @throws DataAccessException + */ List> processListOfMap(ResultSet resultSet) throws DataAccessException; + /** + * Converts the CQL provided into a {@link SimplePreparedStatementCreator}. This can only be used for CQL + * Statements that do not have data binding. The results of the PreparedStatement are processed with + * PreparedStatementCallback implementation provided by the Application Code. + * + * @param cql The CQL Statement to Execute + * @param action What to do with the results of the PreparedStatement + * @return Type as determined by the supplied Callback. + * @throws DataAccessException + */ T execute(String cql, PreparedStatementCallback action) throws DataAccessException; + /** + * Uses the provided PreparedStatementCreator to prepare a new Session call, then executes the statement and processes + * the statement using the provided Callback. This can only be used for CQL Statements that do not have data + * binding. The results of the PreparedStatement are processed with PreparedStatementCallback implementation + * provided by the Application Code. + * + * @param psc The implementation to create the PreparedStatement + * @param action What to do with the results of the PreparedStatement + * @return Type as determined by the supplied Callback. + * @throws DataAccessException + */ T execute(PreparedStatementCreator psc, PreparedStatementCallback action) throws DataAccessException; + /** + * Converts the CQL provided into a {@link SimplePreparedStatementCreator}. Then, the PreparedStatementBinder will + * bind its values to the bind variables in the provided CQL String. The results of the PreparedStatement are + * processed with the ResultSetExtractor implementation provided by the Application Code. The can return any object, + * including a List of Objects to support the ResultSet processing. + * + * @param cql The Query to Prepare + * @param psb The Binding implementation + * @param rse The implementation for extracting the results of the query. + * @return Type generated by the ResultSetExtractor + * @throws DataAccessException + */ T query(final String cql, PreparedStatementBinder psb, ResultSetExtractor rse) throws DataAccessException; + /** + * Converts the CQL provided into a {@link SimplePreparedStatementCreator}. Then, the PreparedStatementBinder will + * bind its values to the bind variables in the provided CQL String. The results of the PreparedStatement are + * processed with the RowCallbackHandler implementation provided and nothing is returned. + * + * @param cql The Query to Prepare + * @param psb The Binding implementation + * @param rch The RowCallbackHandler for processing the ResultSet + * @throws DataAccessException + */ void query(final String cql, PreparedStatementBinder psb, RowCallbackHandler rch) throws DataAccessException; + /** + * Converts the CQL provided into a {@link SimplePreparedStatementCreator}. Then, the PreparedStatementBinder will + * bind its values to the bind variables in the provided CQL String. The results of the PreparedStatement are + * processed with the RowMapper implementation provided and a List is returned with elements of Type for each Row + * returned. + * + * @param cql The Query to Prepare + * @param psb The Binding implementation + * @param rowMapper The implementation for Mapping a Row to Type + * @return List of for each Row returned from the Query. + * @throws DataAccessException + */ List query(final String cql, PreparedStatementBinder psb, RowMapper rowMapper) throws DataAccessException; + /** + * Uses the provided PreparedStatementCreator to prepare a new Session call. This can only be used for CQL + * Statements that do not have data binding. The results of the PreparedStatement are processed with + * ResultSetExtractor implementation provided by the Application Code. + * + * @param psc The implementation to create the PreparedStatement + * @param rse Implementation for extracting from the ResultSet + * @return Type which is the output of the ResultSetExtractor + * @throws DataAccessException + */ T query(PreparedStatementCreator psc, ResultSetExtractor rse) throws DataAccessException; + /** + * Uses the provided PreparedStatementCreator to prepare a new Session call. This can only be used for CQL + * Statements that do not have data binding. The results of the PreparedStatement are processed with + * RowCallbackHandler and nothing is returned. + * + * @param psc The implementation to create the PreparedStatement + * @param rch The implementation to process Results + * @throws DataAccessException + */ void query(PreparedStatementCreator psc, RowCallbackHandler rch) throws DataAccessException; + /** + * Uses the provided PreparedStatementCreator to prepare a new Session call. This can only be used for CQL + * Statements that do not have data binding. The results of the PreparedStatement are processed with RowMapper + * implementation provided and a List is returned with elements of Type for each Row returned. + * + * @param psc The implementation to create the PreparedStatement + * @param rowMapper The implementation for mapping each Row returned. + * @return List of Type mapped from each Row in the Results + * @throws DataAccessException + */ List query(PreparedStatementCreator psc, RowMapper rowMapper) throws DataAccessException; + /** + * Uses the provided PreparedStatementCreator to prepare a new Session call. Binds the values from the + * PreparedStatementBinder to the available bind variables. The results of the PreparedStatement are processed with + * ResultSetExtractor implementation provided by the Application Code. + * + * @param psc The implementation to create the PreparedStatement + * @param psb The implementation to bind variables to values + * @param rse Implementation for extracting from the ResultSet + * @return Type which is the output of the ResultSetExtractor + * @throws DataAccessException + */ T query(PreparedStatementCreator psc, final PreparedStatementBinder psb, final ResultSetExtractor rse) throws DataAccessException; + /** + * Uses the provided PreparedStatementCreator to prepare a new Session call. Binds the values from the + * PreparedStatementBinder to the available bind variables. The results of the PreparedStatement are processed with + * RowCallbackHandler and nothing is returned. + * + * @param psc The implementation to create the PreparedStatement + * @param psb The implementation to bind variables to values + * @param rch The implementation to process Results + * @return Type which is the output of the ResultSetExtractor + * @throws DataAccessException + */ void query(PreparedStatementCreator psc, final PreparedStatementBinder psb, final RowCallbackHandler rch) throws DataAccessException; + /** + * Uses the provided PreparedStatementCreator to prepare a new Session call. Binds the values from the + * PreparedStatementBinder to the available bind variables. The results of the PreparedStatement are processed with + * RowMapper implementation provided and a List is returned with elements of Type for each Row returned. + * + * @param psc The implementation to create the PreparedStatement + * @param psb The implementation to bind variables to values + * @param rowMapper The implementation for mapping each Row returned. + * @return Type which is the output of the ResultSetExtractor + * @throws DataAccessException + */ List query(PreparedStatementCreator psc, final PreparedStatementBinder psb, final RowMapper rowMapper) throws DataAccessException; /** - * Describe the current Ring + * Describe the current Ring. This uses the provided {@link RingMemberHostMapper} to provide the basics of the + * Cassandra Ring topology. * * @return The list of ring tokens that are active in the cluster */ List describeRing() throws DataAccessException; + /** + * Describe the current Ring. Application code must provide its own {@link HostMapper} implementation to process the + * lists of hosts returned by the Cassandra Cluster Metadata. + * + * @param hostMapper The implementation to use for host mapping. + * @return Collection generated by the provided HostMapper. + * @throws DataAccessException + */ Collection describeRing(HostMapper hostMapper) throws DataAccessException; + /** + * Get the current Session used for operations in the implementing class. + * + * @return The DataStax Driver Session Object + */ + Session getSession(); + } diff --git a/src/main/java/org/springframework/cassandra/core/CassandraTemplate.java b/src/main/java/org/springframework/cassandra/core/CassandraTemplate.java index 352ef301a..0e599926d 100644 --- a/src/main/java/org/springframework/cassandra/core/CassandraTemplate.java +++ b/src/main/java/org/springframework/cassandra/core/CassandraTemplate.java @@ -40,8 +40,15 @@ import com.datastax.driver.core.Session; import com.datastax.driver.core.exceptions.DriverException; /** - * The CassandraTemplate is a Spring convenience wrapper for low level and explicit operations on the Cassandra - * Database. For working with POJOs, use the {@link CassandraDataTemplate} + * This is the Central class in the Cassandra core package. It simplifies the use of Cassandra and helps to avoid + * common errors. It executes the core Cassandra workflow, leaving application code to provide CQL and result + * extraction. This class execute CQL Queries, provides different ways to extract/map results, and provides Exception + * translation to the generic, more informative exception hierarchy defined in the org.springframework.dao + * package. + * + *

+ * For working with POJOs, use the {@link CassandraDataTemplate}. + *

* * @author David Webb * @author Matthew Adams diff --git a/src/main/java/org/springframework/data/cassandra/convert/AbstractCassandraConverter.java b/src/main/java/org/springframework/data/cassandra/convert/AbstractCassandraConverter.java index c76b3cdcc..9f4195758 100644 --- a/src/main/java/org/springframework/data/cassandra/convert/AbstractCassandraConverter.java +++ b/src/main/java/org/springframework/data/cassandra/convert/AbstractCassandraConverter.java @@ -33,7 +33,7 @@ public abstract class AbstractCassandraConverter implements CassandraConverter, protected EntityInstantiators instantiators = new EntityInstantiators(); /** - * Creates a new {@link AbstractMongoConverter} using the given {@link GenericConversionService}. + * Creates a new {@link AbstractCassandraConverter} using the given {@link GenericConversionService}. * * @param conversionService */