diff --git a/spring-cql/.gitignore b/spring-cql/.gitignore new file mode 100644 index 000000000..ea8c4bf7f --- /dev/null +++ b/spring-cql/.gitignore @@ -0,0 +1 @@ +/target diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml new file mode 100644 index 000000000..5892afb4f --- /dev/null +++ b/src/docbkx/index.xml @@ -0,0 +1,80 @@ + + + + + Spring Data Cassandra - Reference Documentation + + &version; + + + + David + Webb + + + + Matthew + Adams + + + + John + McPeek + + + + + 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. + + + + + + 2008-2014 + + The original authors. + + + Spring Data Cassandra - Reference Documentation + + + + + + + + Introduction + + + + + + + + + + + Reference Documentation + + + + + + + + + Appendix + + + + + + + + + + diff --git a/src/docbkx/introduction/getting-started.xml b/src/docbkx/introduction/getting-started.xml new file mode 100644 index 000000000..302c5d5a9 --- /dev/null +++ b/src/docbkx/introduction/getting-started.xml @@ -0,0 +1,55 @@ + + + + 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 Cassandra module. + However, if you encounter issues or you are just looking for an advice, feel free to use one of + the links below: + +
+ Support + + There are a few support options available: + +
+ Community Forum + + The Spring Data forum + is a message board for all Spring Data (not just Cassandra) users to share + information and help each other. Note that registration is needed only + for posting. +
+ +
+ Professional Support + + Professional, from-the-source support, with guaranteed response time, is available from + Prowave Consulting. +
+
+ +
+ Following Development + + For information on the Spring Data Cassandra source code repository, nightly builds and + snapshot artifacts please see the Spring Data Cassandra + homepage. + + You can help make Spring Data best serve the needs of the Spring community by interacting + with developers through the Spring Community forums. To follow developer activity look for the mailing list information on the + Spring Data Cassandra homepage. + + If you encounter a bug or want to suggest an improvement, please create a ticket on the + Spring Data issue tracker. + + To stay up to date with the latest news and announcements in the + Spring eco system, subscribe to the Spring Community Portal. +
+ diff --git a/src/docbkx/introduction/introduction.xml b/src/docbkx/introduction/introduction.xml new file mode 100644 index 000000000..5ed144cb8 --- /dev/null +++ b/src/docbkx/introduction/introduction.xml @@ -0,0 +1,65 @@ + + + + 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 section provides some basic introduction to Spring and the Cassandra database. The rest + of the document refers only to Spring Data Cassandra features and assumes the user is familiar + with Cassandra as well as Spring concepts.
+ Knowing Spring + + Spring Data uses Spring framework's core + functionality, such as the IoC + container, type + conversion system, expression + language, JMX + integration, and portable 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. + + 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) 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 home page for + more information. +
+ 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 + 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. + + The jumping off ground for learning about Cassandra is cassandra.apache.org/. Here is a list of other + useful resources. + + + + The Planet Cassandra site has many + valuable resources for Cassandra best practices. + The DataStax site offers commercial support and many resources. + + +
+ diff --git a/src/docbkx/introduction/requirements.xml b/src/docbkx/introduction/requirements.xml new file mode 100644 index 000000000..79e2cee47 --- /dev/null +++ b/src/docbkx/introduction/requirements.xml @@ -0,0 +1,12 @@ + + Requirements + + Spring Data Cassandra 1.x binaries requires JDK level 6.0 and above, + and + Spring Framework + 3.2.x and above. + + + Currently we support Cassandra 1.X using the DataStax Java Driver (1.0.6-dse) + + \ No newline at end of file diff --git a/src/docbkx/preface.xml b/src/docbkx/preface.xml new file mode 100644 index 000000000..509d31c53 --- /dev/null +++ b/src/docbkx/preface.xml @@ -0,0 +1,13 @@ + + + + Preface + + The Spring Data 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. + + diff --git a/src/docbkx/reference/cassandra-repositories.xml b/src/docbkx/reference/cassandra-repositories.xml new file mode 100644 index 000000000..a80b1a0f8 --- /dev/null +++ b/src/docbkx/reference/cassandra-repositories.xml @@ -0,0 +1,58 @@ + + + + Cassandra repositories + +
+ Introduction + + This chapter will point out the specialties for repository support + for Cassandra. This builds on the core repository support explained in . So make sure you've got a sound understanding of + the basic concepts explained there. +
+ +
+ Usage + + To access domain entities stored in a Cassandra you can leverage our + sophisticated repository support that eases implementing those quite + significantly. To do so, simply create an interface for your + repository: + TODO +
+ +
+ Query methods + +
+ Repository delete queries +
+
+ +
+ Miscellaneous + +
+ CDI Integration + + The Spring Data Cassandra CDI extension will pick up the + CassandraTemplate available as CDI bean and create a proxy for a + Spring Data repository whenever an bean of a repository type is requested by the container. + Thus obtaining an instance of a Spring Data repository is a matter of declaring an + @Inject-ed property: + + class RepositoryClient { + + @Inject + PersonRepository repository; + + public void businessMethod() { + + List<Person> people = repository.findAll(); + } +} +
+
+ diff --git a/src/docbkx/reference/cassandra.xml b/src/docbkx/reference/cassandra.xml new file mode 100644 index 000000000..e6fcc2a9e --- /dev/null +++ b/src/docbkx/reference/cassandra.xml @@ -0,0 +1,245 @@ + + + + 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 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 +
+ +
+ Examples Repository + + TODO +
+ +
+ Connecting to Cassandra with Spring +
+ +
+ 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 +
+ diff --git a/src/docbkx/reference/introduction.xml b/src/docbkx/reference/introduction.xml new file mode 100644 index 000000000..54f8f0c90 --- /dev/null +++ b/src/docbkx/reference/introduction.xml @@ -0,0 +1,21 @@ + + + + Document Structure + + This part of the reference documentation explains the core functionality + offered by Spring Data Cassandra. + + + + + introduces the Cassandra module feature set. + + + + + introduces the repository support for Cassandra. + + + \ No newline at end of file diff --git a/src/docbkx/reference/mapping.xml b/src/docbkx/reference/mapping.xml new file mode 100644 index 000000000..2a716386d --- /dev/null +++ b/src/docbkx/reference/mapping.xml @@ -0,0 +1,130 @@ + + + + Mapping + + + Rich mapping support is provided by the + CassandraMappingConverter + . + CassandraMappingConverter + has a rich metadata model that + provides a full feature set of + functionality to map domain objects to + CQL Tables. The mapping metadata + model is populated using annotations + on your domain objects. However, + the infrastructure is not limited to + using + annotations as the only + source of metadata information. The + CassandraMappingConverter + also allows you to map objects + to documents without providing any + additional metadata, by following a + set + of conventions. + + + In this section we will describe the features of the + CassandraMappingConverter. How to use conventions for mapping objects + to + documents and how to override those conventions with annotation + based + mapping metadata. + + +
+ Convention based Mapping + + + CassandraMappingConverter + has a few conventions + for mapping objects to CQL Tables when no + additional mapping metadata is + provided. The conventions are: + + + + + + The short Java class name is mapped to the table name in + the + following manner. The class + ' + com.bigbank.SavingsAccount + ' maps to + ' + savings_account + ' table name. + + + + + The converter will use any Spring Converters registered with + it + to override the default mapping of object properties to document + field/values. + + + + + The fields of an object are used to convert to and from fields + in the document. Public JavaBean properties are not used. + + + + + +
+ How the CQL Composite Primary Key fields are handled in the + mapping layer + + TODO +
+ +
+ Mapping Configuration + + + Unless explicitly configured, an instance of + CassandraMappingConverter + is created by default when + creating a + CassandraTemplate + . You can create your own + instance of the + MappingCassandraConverter + so as to tell it where to scan the classpath at startup your domain + classes in order + to extract metadata and construct indexes. Also, by + creating your own + instance you can register Spring converters to use + for mapping specific + classes to and from the database. + + + + You can configure the + CassandraMappingConverter + and CassandraTemplate + either using Java or XML based metadata. Here + is an + example using Spring's + Java based configuration + + + + @Configuration class to configure Cassandra mapping support + + TODO + + + XML schema to configure Cassandra mapping support + TODO + + +
+
+