4. Cassandra support

4. Cassandra support
Prev	Part II. Reference Documentation	Next

The Cassandra support contains a wide range of features which are summarized below.

Spring configuration support using Java based @Configuration classes or an XML namespace for a Cassandra driver instance and replica sets
CassandraTemplate helper class that increases productivity performing common Cassandra operations. Includes integrated object mapping between CQL Tables and POJOs.
Exception translation into Spring's portable Data Access Exception hierarchy
Feature Rich Object Mapping integrated with Spring's Conversion Service
Annotation based mapping metadata but extensible to support other metadata formats
Persistence and mapping lifecycle events
Java based Query, Criteria, and Update DSLs
Automatic implementation of Repository interfaces including support for custom finder methods.

For most tasks you will find yourself using CassandraTemplate or the Repository support that both leverage the rich mapping functionality. CassandraTemplate is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations. CassandraTemplate also provides callback methods so that it is easy for you to get a hold of the low level API artifacts such as com.datastax.driver.core.Session to communicate directly with Cassandra. The goal with naming conventions on various API artifacts is to copy those in the base DataStax Java driver so you can easily map your existing knowledge onto the Spring APIs.

4.1 Getting Started

Spring Cassandra support requires Cassanra 1.1 or higher (but not Cassandra 2.0) and Java SE 6 or higher. The latest commerical release (1.2.X as of this writing) is recommended. An easy way to bootstrap setting up a working environment is to create a Spring based project in STS.

First you need to set up a running Cassandra server.

To create a Spring project in STS go to File -> New -> Spring Template Project -> Simple Spring Utility Project -> press Yes when prompted. Then enter a project and a package name such as org.spring.cassandra.example.

Then add the following to pom.xml dependencies section.

<dependencies>

  <!-- other dependency elements omitted -->

  <dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-cassandra</artifactId>
    <version>1.0.0.RELEASE</version>
  </dependency>

</dependencies>

Also change the version of Spring in the pom.xml to be

<spring.framework.version>3.2.8.RELEASE</spring.framework.version>

You will also need to add the location of the Spring Milestone repository for maven to your pom.xml which is at the same level of your <dependencies/> element

<repositories>
  <repository>
    <id>spring-milestone</id>
    <name>Spring Maven MILESTONE Repository</name>
    <url>http://repo.spring.io/libs-milestone</url>
  </repository>
</repositories>

The repository is also browseable here.

TODO

4.2 Examples Repository

TODO

4.3 Connecting to Cassandra with Spring

4.4 General auditing configuration

Auditing support is not available in the current version.

4.5 Introduction to CassandraTemplate

4.5. Instantiating CassandraTemplate

4.6 Saving, Updating, and Removing Rows

CassandraTemplate provides a simple way for you to save, update, and delete your domain objects and map those objects to documents stored in Cassandra.

4.6.1 How the Composite Primary Key fields are handled in the mapping layer

Cassandra requires that you have at least 1 Partition Key field for a CQL Table. Alternately, you can have one or more Clustering Key fields.

TODO With Examples

4.6.2 Type mapping

4.6.3 Methods for saving and inserting rows

4.6.4 Updating rows in a CQL table

4.6.5 Upserting rows in a CQL table

4.6.6 Finding and Upserting rowa in a CQL table

4.6.7 Methods for removing rows

4.7 Querying CQL Tables

4.8 Overriding default mapping with custom converters

In order to have more fine grained control over the mapping process you can register Spring converters with the CassandraConverter implementations such as the MappingCassandraConverter.

The MappingCassandraConverter checks to see if there are any Spring converters that can handle a specific class before attempting to map the object itself. To 'hijack' the normal mapping strategies of the MappingCassandraConverter, perhaps for increased performance or other custom mapping needs, you first need to create an implementation of the Spring Converter interface and then register it with the MappingConverter.

	Note
	For more information on the Spring type conversion service see the reference docs here.

4.8.1 Saving using a registered Spring Converter

4.8.2 Reading using a Spring Converter

4.8.3 Registering Spring Converters with the CassandraConverter

4.8.4 Converter disambiguation

4.9 Executing Commands

4.9.1 Methods for executing commands

4.10 Lifecycle Events

4.11 Exception Translation

The Spring framework provides exception translation for a wide variety of database and mapping technologies. This has traditionally been for JDBC and JPA. The Spring support for Cassandra extends this feature to the Cassandra Database by providing an implementation of the org.springframework.dao.support.PersistenceExceptionTranslator interface.

The motivation behind mapping to Spring's consistent data access exception hierarchy is that you are then able to write portable and descriptive exception handling code without resorting to coding against Cassandra Exceptions. All of Spring's data access exceptions are inherited from the root DataAccessException class so you can be sure that you will be able to catch all database related exception within a single try-catch block.