diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 66c288a6b..f5fdee1cd 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -1,14 +1,16 @@ = Spring Data for Apache Cassandra - Reference Documentation -David Webb, Matthew Adams +David Webb, Matthew Adams, John Blum, Mark Paluch :revnumber: {version} :revdate: {localdate} :toc: :toc-placement!: :spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc -(C) 2008-2015 The original author(s). +(C) 2008-2016 The original author(s). -NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. +NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not +charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed +in print or electronically. toc::[] include::preface.adoc[] diff --git a/src/main/asciidoc/introduction/getting-started.adoc b/src/main/asciidoc/introduction/getting-started.adoc index 5c8616435..09d97da9b 100644 --- a/src/main/asciidoc/introduction/getting-started.adoc +++ b/src/main/asciidoc/introduction/getting-started.adoc @@ -1,7 +1,9 @@ [[get-started]] = Additional Help Resources -Learning a new framework is not always straight forward. In this section, we try to provide what we think is an easy to follow guide for starting with Spring Data for Apache Cassandra module. However, if you encounter issues or you are just looking for an advice, feel free to use one of the links below: +Learning a new framework is not always straight forward. In this section, we try to provide what we think is an easy +to follow guide for starting with Spring Data for Apache Cassandra. However, if you encounter issues or you are just looking +for advice, feel free to use one of the links below: [[get-started.help]] == Support @@ -11,7 +13,8 @@ There are a few support options available: [[get-started.help.community]] === Questions & Answers -Developers post questions and answers on Stack Overflow. The two key tags to search for related answers to this project are: +Developers post questions and answers on _StackOverflow_. The two key tags to search for related answers to +this project are: * http://stackoverflow.com/questions/tagged/spring-data[spring-data] * http://stackoverflow.com/questions/tagged/spring-data-cassandra[spring-data-cassandra] @@ -19,14 +22,16 @@ Developers post questions and answers on Stack Overflow. The two key tags to sea [[get-started.help.professional]] === Professional Support -Professional, from-the-source support, with guaranteed response time, is available from http://www.pivotal.io/support[Pivotal Support]. +From-the-source professional support, with guaranteed response time, is available from +http://www.pivotal.io/support[Pivotal Support]. [[get-started.up-to-date]] == Following Development -For information on the Spring Data for Apache Cassandra source code repository, nightly builds and snapshot artifacts please see the http://projects.spring.io/spring-data-cassandra/[Spring Data for Apache Cassandra homepage]. +For information on the Spring Data for Apache Cassandra source code repository, nightly builds and snapshot artifacts +please see the http://projects.spring.io/spring-data-cassandra/[Spring Data for Apache Cassandra homepage]. To follow developer activity look for the mailing list information on the Spring Data for Apache Cassandra homepage. -If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue https://jira.spring.io/browse/DATACASS[tracker]. - +If you encounter a bug or want to suggest an improvement, please create a ticket in the Spring Data +https://jira.spring.io/browse/DATACASS[issue tracker]. diff --git a/src/main/asciidoc/introduction/introduction.adoc b/src/main/asciidoc/introduction/introduction.adoc index ad3ba49ef..822fe0d21 100644 --- a/src/main/asciidoc/introduction/introduction.adoc +++ b/src/main/asciidoc/introduction/introduction.adoc @@ -1,25 +1,51 @@ -This document is the reference guide for Spring Data - Cassandra Support. It explains Cassandra module concepts and semantics and the syntax for various stores namespaces. +This document is the reference guide for Spring Data support for Cassandra. It explains Cassandra module concepts, +semantics and the syntax for various stores namespaces. -This section provides some basic introduction to Spring and the Cassandra database. The rest of the document refers only to Spring Data for Apache Cassandra features and assumes the user is familiar with Cassandra as well as Spring concepts. +This section provides a basic introduction to Spring, Spring Data and the Cassandra database. The rest of the document +refers only to Spring Data for Apache Cassandra features and assumes the user is familiar with Cassandra as well as +core Spring concepts. [float] [[get-started:first-steps:spring]] === Knowing Spring -Spring Data uses Spring framework's http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/spring-core.html[core] functionality, such as the http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/beans.html[IoC] container, http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/validation.html#core-convert[type conversion system], http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/expressions.html[expression language], http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/jmx.html[JMX integration], and portable http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/dao.html#dao-exceptions[DAO exception hierarchy]. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use. +Spring Data uses the Spring Framework's http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/[core] +functionality, such as the http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans[IoC] container, +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#validation[validation, type conversion and data binding], +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#expressions[expression language], +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop[AOP], +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#jmx[JMX integration], +http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#dao[DAO support], and specifically +the http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#dao-exceptions[DAO Exception Hierarchy]. -The core functionality of the Cassandra support can be used directly, with no need to invoke the IoC services of the Spring Container. This is much like `JdbcTemplate` which can be used 'standalone' without any other services of the Spring container. To leverage all the features of Spring Data for Apache Cassandra, such as the repository support, you will need to configure some parts of the library using Spring. +While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea +behind IoC should be familiar no matter what IoC container you choose to use. -To learn more about Spring, you can refer to the comprehensive (and sometimes disarming) documentation that explains in detail the Spring Framework. There are a lot of articles, blog entries and books on the matter - take a look at the Spring framework http://spring.io/docs[home page] for more information. +The core functionality of the Cassandra support can be used directly, with no need to invoke the IoC services +of the Spring container. This is much like `JdbcTemplate`, which can be used 'standalone' without any other services +of the Spring container. To leverage all the features of Spring Data Cassandra, such as the repository support, +you will need to configure some parts of the library using Spring. + +To learn more about Spring, you can refer to the comprehensive (and sometimes disarming) http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/[documentation] +that explains in detail the Spring Framework. There are a lot of articles, blog entries and books on the matter. +Take a look at the Spring Framework http://projects.spring.io/spring-framework/[home page] for more information. [float] [[get-started:first-steps:nosql]] === Knowing NoSQL and Cassandra -NoSQL stores have taken the storage world by storm. It is a vast domain with a plethora of solutions, terms and patterns (to make things worth even the term itself has multiple http://www.google.com/search?q=nosoql+acronym[meanings]). While some of the principles are common, it is crucial that the user is familiar to some degree with the Cassandra Columnar NoSQL Datastore supported by DATACASS. The best way to get acquainted to this solutions is to read their documentation and follow their examples - it usually doesn't take more then 5-10 minutes to go through them and if you are coming from an RDMBS-only background many times these exercises can be an eye opener. +NoSQL stores have taken the storage world by storm. It is a vast domain with a plethora of solutions, terms and patterns +(to make things worse, even the term itself has multiple http://www.google.com/search?q=nosoql+acronym[meanings]). +While some of the principles are common, it is crucial that the user is familiar to some degree with +the Cassandra Columnar NoSQL Datastore supported by Spring Data Cassandra. The best way to get acquainted with Cassandra +is to read the documentation and follow the examples. It usually doesn't take more then 5-10 minutes to go through them +and if you are coming from a RDBMS background, many times these exercises can be an eye opener. -The jumping off ground for learning about Cassandra is http://cassandra.apache.org/[cassandra.apache.org/]. Here is a list of other useful resources. +The starting ground for learning about Cassandra is http://cassandra.apache.org/[cassandra.apache.org/]. Also, here is +a list of other useful resources: -* The http://planetcassandra.org/[Planet Cassandra] site has many valuable resources for Cassandra best practices. - -The http://datastax.com/[DataStax] site offers commercial support and many resources. +* http://planetcassandra.org/[Planet Cassandra] site has many valuable resources for Cassandra best practices. +* The http://datastax.com/[DataStax] site offers http://www.datastax.com/what-we-offer/products-services/support[commercial support] +and many resources, including, but not limited to, http://docs.datastax.com/en/landing_page/doc/landing_page/current.html[documentation], +http://docs.datastax.com/en/landing_page/doc/landing_page/current.html[DataStax Academy], a http://www.datastax.com/dev/blog[Tech Blog] +and so on. diff --git a/src/main/asciidoc/introduction/requirements.adoc b/src/main/asciidoc/introduction/requirements.adoc index e7ad3a017..5028743eb 100644 --- a/src/main/asciidoc/introduction/requirements.adoc +++ b/src/main/asciidoc/introduction/requirements.adoc @@ -1,7 +1,7 @@ [[requirements]] = Requirements -Spring Data for Apache Cassandra 1.x binaries requires JDK level 6.0 and above, and http://spring.io/docs[Spring Framework] 3.2.x and above. - -Currently we support Cassandra 2.X using the DataStax Java Driver (2.0.X) +Spring Data for Apache Cassandra 1.x binaries requires JDK 6.0 and above and http://projects.spring.io/spring-framework/[Spring Framework] 3.2.x +and above. +Currently we support Cassandra 2.X using the DataStax Java Driver (2.0.X). diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index 801e1b771..8cc6551e1 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -1,7 +1,10 @@ [[preface]] = Preface -The Spring Data for Apache Cassandra project applies core Spring concepts to the development of solutions using the Cassandra Columnar data store. We provide a "template" as a high-level abstraction for storing and querying documents. You will notice similarities to the JDBC support in the Spring Framework. +The Spring Data for Apache Cassandra project applies core Spring concepts to the development of solutions using +the Cassandra Columnar data store. A "template" is provided as a high-level abstraction for storing +and querying documents. You will notice similarities to the http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#jdbc[JDBC support] +in the core Spring Framework. [[project]] [preface] diff --git a/src/main/asciidoc/reference/cassandra.adoc b/src/main/asciidoc/reference/cassandra.adoc index 601348f2d..cb95b9bb4 100644 --- a/src/main/asciidoc/reference/cassandra.adoc +++ b/src/main/asciidoc/reference/cassandra.adoc @@ -3,167 +3,215 @@ 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. +* Spring configuration support using Java-based @Configuration classes or the XML namespace to create +a Cassandra instance with replica sets using the driver. +* CassandraTemplate helper class that increases productivity by handling common Cassandra operations properly. +Includes integrated object mapping between CQL Tables and POJOs. +* Exception translation into Spring's portable http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#dao-exceptions[Data Access Exception Hierarchy]. +* Feature rich object mapping integrated with Spring's http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#core-convert[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. +For most data oriented tasks you will use the `CassandraTemplate` or the `Repository` support, which leverage the +rich mapping functionality. `CassandraTemplate` is commonly used to increment counters or perform ad-hoc CRUD +operations. `CassandraTemplate` also provides callback methods making it easy to get a hold of low-level API objects +such as `com.datastax.driver.core.Session` allowing you to communicate directly with Cassandra. Spring Data Cassandra +uses consistent naming conventions on objects in various APIs to those found in the DataStax Java Driver so that they +are familiar and so you can map your existing knowledge onto the Spring APIs. [[cassandra-getting-started]] == Getting Started -Spring Data for Apache 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 http://spring.io/tools/sts[STS]. +Spring Data Cassandra uses the DataStax Java Driver version 2.X, which supports DataStax Enterprise 4/Apache Cassandra 2.0 +with Java SE 6 or higher. The latest commercial or open source release is recommended. The easiest way to setup +a working environment is to create a Spring-based project in http://spring.io/tools/sts[STS]. -First you need to set up a running Cassandra server. +First, you need to setup 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 -> +and press "Yes" when prompted. Then, enter a project and a package name such as "org.spring.data.cassandra.example". -Then add the following to pom.xml dependencies section. +Then add the following to the `pom.xml` dependencies section. [source,xml] ---- - + org.springframework.data spring-data-cassandra - 1.0.0.RELEASE + 1.4.1.RELEASE ---- -Also change the version of Spring in the pom.xml to be +Also, change the version of Spring in `pom.xml` to be [source,xml] ---- -3.2.8.RELEASE +4.2.5.RELEASE ---- -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 element +If you are using a milestone version (e.g. M1 or RC1) of Spring Data Cassandra, you will also need to include the +Spring Milestone repository declaration to your `pom.xml`, like so... [source,xml] ---- spring-milestone - Spring Maven MILESTONE Repository + Spring Milestones Maven Repository http://repo.spring.io/libs-milestone ---- -The repository is also http://shrub.appspot.com/maven.springframework.org/milestone/org/springframework/data/[browseable here]. +If you are on the bleeding edge and use build snapshots, then you will need to include the Spring Snapshots repository +declaration to your `pom.xml`, like so... -Create a simple Employee class to persist. +[source,xml] +---- + + + spring-snapshot + Spring Snapshots Maven Repository + http://repo.spring.io/libs-snapshot + + +---- + +You can also browse the Spring repositories https://repo.spring.io/webapp/#/home[here]. + +Now we will create a simple little Java application that stores and reads a domain object to/from Cassandra. + +First, create a simple domain object class to persist. [source,java] ---- -package org.spring.cassandra.example; - -import org.springframework.data.cassandra.mapping.PrimaryKey; -import org.springframework.data.cassandra.mapping.Table; - -@Table -public class Person { - - @PrimaryKey - private String id; - - private String name; - private int age; - - public Person(String id, String name, int age) { - this.id = id; - this.name = name; - this.age = age; - } - - public String getId() { - return id; - } - - public String getName() { - return name; - } - - public int getAge() { - return age; - } - - @Override - public String toString() { - return "Person [id=" + id + ", name=" + name + ", age=" + age + "]"; - } - +package org.spring.data.cassandra.example; + +import org.springframework.data.cassandra.mapping.PrimaryKey; +import org.springframework.data.cassandra.mapping.Table; + +@Table +public class Person { + + @PrimaryKey + private final String id; + + private final String name; + private final int age; + + public Person(String id, String name, int age) { + this.id = id; + this.name = name; + this.age = age; + } + + public String getId() { + return id; + } + + public String getName() { + return name; + } + + public int getAge() { + return age; + } + + @Override + public String toString() { + return String.format("{ @type = %1$s, id = %2$s, name = %3$s, age = %4$d }", + getClass().getName(), getId(), getName(), getAge()); + } } ---- -And a main application to run +Next, create the main application to run. [source,java] ---- -package org.spring.cassandra.example; - -import java.net.InetAddress; -import java.net.UnknownHostException; - -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; -import org.springframework.data.cassandra.core.CassandraOperations; -import org.springframework.data.cassandra.core.CassandraTemplate; - -import com.datastax.driver.core.Cluster; -import com.datastax.driver.core.Session; -import com.datastax.driver.core.querybuilder.QueryBuilder; -import com.datastax.driver.core.querybuilder.Select; - -public class CassandraApp { - - private static final Logger LOG = LoggerFactory.getLogger(CassandraApp.class); - - private static Cluster cluster; - private static Session session; - - public static void main(String[] args) { - - try { - - cluster = Cluster.builder().addContactPoints(InetAddress.getLocalHost()).build(); - - session = cluster.connect("mykeyspace"); - - CassandraOperations cassandraOps = new CassandraTemplate(session); - - cassandraOps.insert(new Person("1234567890", "David", 40)); - - Select s = QueryBuilder.select().from("person"); - s.where(QueryBuilder.eq("id", "1234567890")); - - LOG.info(cassandraOps.queryForObject(s, Person.class).getId()); - - cassandraOps.truncate("person"); - - } catch (UnknownHostException e) { - e.printStackTrace(); - } - - } -} +package org.spring.data.cassandra.example; + +import java.io.Closeable; +import java.net.InetAddress; +import java.net.UnknownHostException; +import java.util.UUID; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.data.cassandra.core.CassandraOperations; +import org.springframework.data.cassandra.core.CassandraTemplate; + +import com.datastax.driver.core.Cluster; +import com.datastax.driver.core.Session; +import com.datastax.driver.core.querybuilder.QueryBuilder; +import com.datastax.driver.core.querybuilder.Select; + +public class CassandraApplication { + + private static final Logger LOGGER = LoggerFactory.getLogger(CassandraApplication.class); + + private static Cluster cluster; + private static Session session; + + protected static boolean close(Closeable obj) { + if (obj != null) { + try { + obj.close(); + return true; + } + catch (Exception ignore) { + } + } + + return false; + } + + protected static Person newPerson(String name, int age) { + return newPerson(UUID.randomUUID().toString(), name, age); + } + + protected static Person newPerson(String id, String name, int age) { + return new Person(id, name, age); + } + + public static void main(String[] args) throws UnknownHostException { + try { + cluster = Cluster.builder().addContactPoints(InetAddress.getLocalHost()).build(); + session = cluster.connect("mykeyspace"); + + CassandraOperations template = new CassandraTemplate(session); + + Person jonDoe = template.insert(newPerson("Jon Doe", 40)); + + Select selectStatement = QueryBuilder.select().from("person"); + selectStatement.where(QueryBuilder.eq("id", jonDoe.getId())); + + LOGGER.info(template.queryForObject(selectStatement, Person.class).getId()); + + template.truncate("person"); + } + finally { + close(session); + close(cluster); + } + } +} ---- 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. +* You can create an instance of `CassandraTemplate` with a Cassandra `Session`, derived from a `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 either use a CQL String or the DataStax `QueryBuilder` API to construct you queries. == Examples Repository @@ -175,9 +223,10 @@ After the initial release of Spring Data for Apache Cassandra 1.0.0, we will sta [[cassandra-connectors.ext_properties]] === 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. +Create a properties file containing the information needed to connect to Cassandra. `contactpoints` and `keyspace` +are required fields; `port` has been added for clarity. -We will call this cassandra.properties +We will call this properties file, `cassandra.properties`. [source] ---- @@ -186,7 +235,7 @@ cassandra.port=9042 cassandra.keyspace=showcase ---- -We will use spring to load these properties into the Spring Context in the next two examples. +We will use Spring to load these properties into the Spring context in the next two examples. [[cassandra-connectors.xmlconfig]] === XML Configuration