diff --git a/src/docbkx/reference/cassandra.xml b/src/docbkx/reference/cassandra.xml index af38861d6..0d1e1749e 100644 --- a/src/docbkx/reference/cassandra.xml +++ b/src/docbkx/reference/cassandra.xml @@ -1,66 +1,85 @@ - - - - Cassandra support - 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. -
- 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. - 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> + + + + Cassandra support + + 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. + +
+ 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. + + 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 --> @@ -70,25 +89,31 @@ <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> +</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. - Create a simple Employee class to persist. - - package org.spring.cassandra.example; +</repositories> + + The repository is also + browseable here. + + Create a simple Employee class to persist. + + package org.spring.cassandra.example; import org.springframework.data.cassandra.mapping.PrimaryKey; import org.springframework.data.cassandra.mapping.Table; @@ -122,14 +147,14 @@ public class Person { @Override public String toString() { - return "Person [id=" + id + ", name=" + name + ", age=" + age + "]"; + return "Person [id=" + id + ", name=" + name + ", age=" + age + "]"; } -} - - And a main application to run - - package org.spring.cassandra.example; +} + + And a main application to run + + package org.spring.cassandra.example; import java.net.InetAddress; import java.net.UnknownHostException; @@ -157,18 +182,18 @@ public class CassandraApp { cluster = Cluster.builder().addContactPoints(InetAddress.getLocalHost()).build(); - session = cluster.connect("mykeyspace"); + session = cluster.connect("mykeyspace"); CassandraOperations cassandraOps = new CassandraTemplate(session); - cassandraOps.insert(new Person("1234567890", "David", 40)); + cassandraOps.insert(new Person("1234567890", "David", 40)); - Select s = QueryBuilder.select().from("person"); - s.where(QueryBuilder.eq("id", "1234567890")); + Select s = QueryBuilder.select().from("person"); + s.where(QueryBuilder.eq("id", "1234567890")); LOG.info(cassandraOps.queryForObject(s, Person.class).getId()); - cassandraOps.truncate("person"); + cassandraOps.truncate("person"); } catch (UnknownHostException e) { e.printStackTrace(); @@ -176,151 +201,278 @@ public class CassandraApp { } } - - - 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 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. - - -
-
- Examples Repository - 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 - Auditing support is not available in the current version. -
-
- Introduction to CassandraTemplate -
- Instantiating CassandraTemplate -
-
-
- 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. -
- 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 -
-
- Type mapping -
-
- Methods for saving and inserting rows -
-
- Updating rows in a CQL table -
-
- Upserting rows in a CQL table -
-
- Finding and Upserting rowa in a CQL table -
-
- Methods for removing rows -
-
-
- Querying CQL Tables -
-
- 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. - - For more information on the Spring type conversion service see the - reference docs - - here. - -
- Saving using a registered Spring Converter -
-
- Reading using a Spring Converter -
-
- Registering Spring Converters with the CassandraConverter -
-
- Converter disambiguation -
-
-
- Executing Commands -
- Methods for executing commands -
-
-
- Lifecycle Events -
-
- 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. -
-
- Execution callbacks -
- + + + 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 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. + + +
+ +
+ Examples Repository + + 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 + + Create a properties file with the information you need to connect + to Cassandra. The contact points are keyspace are the minimal required + fields, but port is added here for clarity. + + We will call this cassandra.properties + + cassandra.contactpoints=10.1.55.80,10.1.55.81 +cassandra.port=9042 +cassandra.keyspace=showcaseWe will use spring to load these + properties into the Spring Context in the next two examples. +
+ +
+ XML Configuration + + The XML Configuration elements for a basic Cassandra configuration + are shown below. These elements all use default bean names to keep the + configuration code clean and readable. + + While this example show how easy it is to configure Spring to + connect to Cassandra, there are many other options. Basically, any + option available with the DataStax Java Driver is also available in the + Spring Data Cassandra configuration. This is including, but not limited + to Authentication, Load Balancing Policies, Retry Policies and Pooling + Options. All of the Spring Data Cassandra method names and XML elements + are named exactly (or as close as possible) like the configuration + options on the driver so mapping any existing driver configuration + should be straight forward. + + <?xml version='1.0'?> +<beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cassandra="http://www.springframework.org/schema/data/cassandra" + xmlns:context="http://www.springframework.org/schema/context" + xsi:schemaLocation="http://www.springframework.org/schema/cql http://www.springframework.org/schema/cql/spring-cql-1.0.xsd + http://www.springframework.org/schema/data/cassandra http://www.springframework.org/schema/data/cassandra/spring-cassandra-1.0.xsd + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.2.xsd"> + + + <!-- Loads the properties into the Spring Context and uses them to fill + in placeholders in the bean definitions --> + <context:property-placeholder location="classpath:cassandra.properties" /> + + <!-- REQUIRED: The Cassandra Cluster --> + <cassandra:cluster contact-points="${cassandra.contactpoints}" port="${cassandra.port}" /> + + <!-- REQUIRED: The Cassandra Session, built from the Cluster, and attaching to a keyspace --> + <cassandra:session keyspace-name="${cassandra.keyspace}" /> + + <!-- REQUIRED: The Default Cassandra Converter used by CassandraTemplate --> + <cassandra:converter/> + + <!-- REQUIRED: The Cassandra Template is the building block of all Spring Data Cassandra --> + <cassandra:template/> + + <!-- OPTIONAL: If you are using Spring Data Cassandra Repositories, add your base packages to scan here--> + <cassandra:repositories base-package="org.spring.cassandra.example.repo" /> + +</beans> + +
+ +
+ Java Configuration + + TODO +
+
+ +
+ General auditing configuration + + Auditing support is not available in the current version. +
+ +
+ Introduction to CassandraTemplate + +
+ Instantiating CassandraTemplate + + CassandraTemplate requires a Cassandra Session object. +
+
+ +
+ 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. + +
+ 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 +
+ +
+ Type mapping + + TODO With Examples +
+ +
+ Methods for saving and inserting rows + + TODO With Examples +
+ +
+ Updating rows in a CQL table + + TODO With Examples +
+ +
+ Upserting rows in a CQL table + + TODO With Examples +
+ +
+ Finding and Upserting rowa in a CQL table + + TODO With Examples +
+ +
+ Methods for removing rows + + TODO With Examples +
+
+ +
+ Querying CQL Tables + + TODO With Examples +
+ +
+ 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. + + + For more information on the Spring type conversion service see the + reference docs + here. + + +
+ Saving using a registered Spring Converter + + TODO With Examples +
+ +
+ Reading using a Spring Converter + + TODO With Examples +
+ +
+ Registering Spring Converters with the CassandraConverter + + TODO With Examples +
+ +
+ Converter disambiguation + + TODO With Examples +
+
+ +
+ Executing Commands + +
+ Methods for executing commands + + TODO With Examples +
+
+ +
+ Lifecycle Events + + TODO With Examples +
+ +
+ 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. +
+ +
+ Execution callbacks + + TODO With Examples +
+