From ad6fe4558adc1531fc7aa0969353564f44e8e98c Mon Sep 17 00:00:00 2001 From: David Webb Date: Sat, 17 May 2014 15:31:02 -0400 Subject: [PATCH] DATACASS-125 WIP Docbook --- src/docbkx/reference/cassandra.xml | 166 +++++++++++++++-------------- 1 file changed, 85 insertions(+), 81 deletions(-) diff --git a/src/docbkx/reference/cassandra.xml b/src/docbkx/reference/cassandra.xml index 54b1b01e5..af38861d6 100644 --- a/src/docbkx/reference/cassandra.xml +++ b/src/docbkx/reference/cassandra.xml @@ -2,30 +2,29 @@ Cassandra support - The Cassandra support contains a wide range of features which - are summarized below. + 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 + 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. + 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 + Feature Rich Object Mapping integrated with Spring's Conversion + Service - Annotation based mapping metadata but extensible to support - other metadata formats + Annotation based mapping metadata but extensible to support other + metadata formats Persistence and mapping lifecycle events @@ -34,34 +33,32 @@ Java based Query, Criteria, and Update DSLs - Automatic implementation of Repository interfaces including - support for custom finder methods. + 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. + 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.
Getting Started - Spring Data Cassandra uses the DataStax Java Driver version - 2.X, which supports DataStax Enterprise 4/Cassandra 2.0, and Java SE - 6 or higher. The latest commercial release (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. + Spring Data Cassandra uses the DataStax Java Driver version 2.X, which + supports DataStax Enterprise 4/Cassandra 2.0, and Java SE 6 or higher. The + latest commercial release (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. + 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> @@ -77,8 +74,8 @@ 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 + repository for maven to your pom.xml which is at the same level of your + <dependencies/> element <repositories> <repository> <id>spring-milestone</id> @@ -181,32 +178,42 @@ public class CassandraApp { } - Even in this simple example, there are a few things to - observe. + Even in this simple example, there are a few things to observe. - You can create an instance of CassandraTemplate with a - Cassandra Session, derived from the Cluster. + You can create an instance of CassandraTemplate with a Cassandra + Session, derived from the Cluster. - You must annotate your POJO as a Cassandra @Table, and also - annotate the @PrimaryKey. Optionally you can override these - mapping names to match your Cassandra database table and column - names. + You must annotate your POJO as a Cassandra @Table, and also annotate + the @PrimaryKey. Optionally you can override these mapping names to match + your Cassandra database table and column names. - You can use CQL String, or the DataStax QueryBuilder to - construct you queries. + You can use CQL String, or the DataStax QueryBuilder to construct you + queries.
Examples Repository - After the initial release of Spring Data Cassandra 1.0.0, we - will start working on a showcase repository with full examples. + After the initial release of Spring Data Cassandra 1.0.0, we will start + working on a showcase repository with full examples.
Connecting to Cassandra with Spring +
+ Externalize Connection Properties + TODO +
+
+ XML Configuration + TODO +
+
+ Java Configuration + TODO +
General auditing configuration @@ -220,15 +227,15 @@ public class CassandraApp {
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. + CassandraTemplate provides a simple way for you + to save, update, and delete your domain objects and map those objects to + documents stored in Cassandra.
- 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. + 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
@@ -255,22 +262,21 @@ public class CassandraApp {
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 + 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 + 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. - For more information on the Spring type conversion service see - the reference docs + For more information on the Spring type conversion service see the + reference docs here. @@ -281,8 +287,7 @@ public class CassandraApp { Reading using a Spring Converter
- Registering Spring Converters with the - CassandraConverter + Registering Spring Converters with the CassandraConverter
Converter disambiguation @@ -299,22 +304,21 @@ public class CassandraApp {
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 + 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. + 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.
Execution callbacks