DATACASS-272 - Enhance the SD Cassandra Reference Guide.
Align documentation structure with other Spring Data Modules. Add chapters for mapping and supported data types. Add new features chapter. Merge existing documentation into the aligned structure. Add John Blum and Mark Paluch to pom.xml.
This commit is contained in:
Mark Paluch
22
pom.xml
22
pom.xml
@@ -54,6 +54,28 @@
|
||||
</roles>
|
||||
<timezone>-8</timezone>
|
||||
</developer>
|
||||
<developer>
|
||||
<id>jblum</id>
|
||||
<name>John Blum</name>
|
||||
<email>jblum at pivotal.io</email>
|
||||
<organization>Pivotal</organization>
|
||||
<organizationUrl>http://www.pivotal.io</organizationUrl>
|
||||
<roles>
|
||||
<role>Developer</role>
|
||||
</roles>
|
||||
<timezone>-8</timezone>
|
||||
</developer>
|
||||
<developer>
|
||||
<id>mpaluch</id>
|
||||
<name>Mark Paluch</name>
|
||||
<email>mpaluch at pivotal.io</email>
|
||||
<organization>Pivotal</organization>
|
||||
<organizationUrl>http://www.pivotal.io</organizationUrl>
|
||||
<roles>
|
||||
<role>Developer</role>
|
||||
</roles>
|
||||
<timezone>+1</timezone>
|
||||
</developer>
|
||||
</developers>
|
||||
|
||||
<modules>
|
||||
|
||||
@@ -15,14 +15,9 @@ in print or electronically.
|
||||
toc::[]
|
||||
include::preface.adoc[]
|
||||
|
||||
[[introduction]]
|
||||
= Introduction
|
||||
|
||||
include::introduction/introduction.adoc[]
|
||||
|
||||
:leveloffset: +1
|
||||
include::introduction/requirements.adoc[]
|
||||
include::introduction/getting-started.adoc[]
|
||||
include::new-features.adoc[]
|
||||
include::{spring-data-commons-docs}/dependencies.adoc[]
|
||||
include::{spring-data-commons-docs}/repositories.adoc[]
|
||||
:leveloffset: -1
|
||||
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
[[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. 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
|
||||
|
||||
There are a few support options available:
|
||||
|
||||
[[get-started.help.community]]
|
||||
=== Questions & Answers
|
||||
|
||||
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]
|
||||
|
||||
[[get-started.help.professional]]
|
||||
=== Professional 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].
|
||||
|
||||
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 in the Spring Data
|
||||
https://jira.spring.io/browse/DATACASS[issue tracker].
|
||||
@@ -1,51 +0,0 @@
|
||||
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 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 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].
|
||||
|
||||
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.
|
||||
|
||||
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 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 starting ground for learning about Cassandra is http://cassandra.apache.org/[cassandra.apache.org/]. Also, here is
|
||||
a list of other useful 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.
|
||||
@@ -1,7 +0,0 @@
|
||||
[[requirements]]
|
||||
= Requirements
|
||||
|
||||
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).
|
||||
9
src/main/asciidoc/new-features.adoc
Normal file
9
src/main/asciidoc/new-features.adoc
Normal file
@@ -0,0 +1,9 @@
|
||||
[[new-features]]
|
||||
= New & Noteworthy
|
||||
|
||||
[[new-features:1-5-0]]
|
||||
== What's new in Spring Data Cassandra 1.5
|
||||
* Assert compatibility with Cassandra 3.0 and Cassandra Java Driver 3.0.
|
||||
* Configurable `ProtocolVersion` and `QueryOptions` on `Cluster` level.
|
||||
* Support for `Optional` as query method result and argument.
|
||||
|
||||
@@ -6,13 +6,118 @@ the Cassandra Columnar data store. A "template" is provided as a high-level abs
|
||||
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]
|
||||
== Project Metadata
|
||||
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 a basic introduction to Spring, Spring Data 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
|
||||
core Spring concepts.
|
||||
|
||||
This section provides some basic introduction to Spring and Cassandra database. The rest of the document
|
||||
refers only to Spring Data Cassandra features and assumes the user is familiar with Apache Cassandra as
|
||||
well as Spring concepts.
|
||||
|
||||
[[get-started:first-steps:spring]]
|
||||
== Knowing Spring
|
||||
|
||||
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].
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
[[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 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 starting ground for learning about Cassandra is http://cassandra.apache.org/[cassandra.apache.org]. Also, here is
|
||||
a list of other useful 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.
|
||||
* The http://www.planetcassandra.org/try-cassandra/[Cassandra Quick Start] provides a convenient way to interact
|
||||
with a Apache Cassandra instance in combination with the online shell.
|
||||
|
||||
[[requirements]]
|
||||
== Requirements
|
||||
|
||||
Spring Data Cassandra 1.x binaries require JDK level 6.0 and above, and http://spring.io/docs[Spring Framework] {springVersion} and above.
|
||||
|
||||
In terms of http://cassandra.apache.org/[Cassandra] at least 2.0.
|
||||
|
||||
== 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:
|
||||
|
||||
[[get-started:help]]
|
||||
=== Support
|
||||
|
||||
There are a few support options available:
|
||||
|
||||
[[get-started:help:community]]
|
||||
==== Community Forum
|
||||
|
||||
Spring Data on http://stackoverflow.com/questions/tagged/spring-data[Stackoverflow] is a
|
||||
tag for all Spring Data (not just Cassandra) users to share information and help each other.
|
||||
Note that registration is needed *only* for posting.
|
||||
|
||||
Developers post questions and answers on . 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]
|
||||
|
||||
[[get-started:help:professional]]
|
||||
==== Professional Support
|
||||
|
||||
Professional, from-the-source support, with guaranteed response time, is available from
|
||||
http://pivotal.io/[Pivotal Sofware, Inc.], the company behind Spring Data and Spring.
|
||||
|
||||
[[get-started:up-to-date]]
|
||||
=== Following Development
|
||||
|
||||
For information on the Spring Data Cassandra source code repository, nightly builds and snapshot artifacts
|
||||
please see the http://projects.spring.io/spring-data-cassandra/[Spring Data Cassandra homepage].
|
||||
You can help make Spring Data best serve the needs of the Spring community by interacting with developers
|
||||
through the Community on http://stackoverflow.com/questions/tagged/spring-data[Stackoverflow].
|
||||
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
|
||||
https://jira.spring.io/browse/DATACASS[tracker]. To stay up to date with the latest news and announcements
|
||||
in the Spring eco system, subscribe to the Spring Community http://spring.io[Portal].
|
||||
Lastly, you can follow the Spring http://spring.io/blog[blog] or the project team on Twitter (http://twitter.com/SpringData[SpringData]).
|
||||
|
||||
|
||||
[[get-started:project-metadata]]
|
||||
=== Project Metadata
|
||||
|
||||
* Version Control - https://github.com/spring-projects/spring-data-cassandra
|
||||
* Bugtacker - https://jira.spring.io/browse/DATACASS
|
||||
* Release repository - https://repo.springsource.org/libs-release
|
||||
* Milestone repository - https://repo.springsource.org/libs-milestone
|
||||
* Snapshot repository - https://repo.springsource.org/libs-snapshot
|
||||
|
||||
* Bugtracker - https://jira.spring.io/browse/DATACASS
|
||||
* Release repository - https://repo.spring.io/libs-release
|
||||
* Milestone repository - https://repo.spring.io/libs-milestone
|
||||
* Snapshot repository - https://repo.spring.io/libs-snapshot
|
||||
@@ -9,9 +9,98 @@ This chapter will point out the specialties for repository support for Cassandra
|
||||
[[cassandra-repo-usage]]
|
||||
== 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:
|
||||
To access domain entities stored in Cassandra you can leverage our sophisticated repository support that eases implementing those quite significantly. To do so, simply create an interface for your repository:
|
||||
|
||||
.Sample Person entity
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Table
|
||||
public class Person {
|
||||
|
||||
@Id
|
||||
private String id;
|
||||
private String firstname;
|
||||
private String lastname;
|
||||
|
||||
// … getters and setters omitted
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
We have a quite simple domain object here. Note that it has a property named `id` of type `String`. The default serialization mechanism used in `CassandraTemplate` (which is backing the repository support) regards properties named id as row id.
|
||||
|
||||
.Basic repository interface to persist Person entities
|
||||
====
|
||||
[source]
|
||||
----
|
||||
public interface PersonRepository extends CrudRepository<Person, String> {
|
||||
|
||||
// additional custom finder methods go here
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Right now this interface simply serves typing purposes but we will add additional methods to it later. In your Spring configuration simply add
|
||||
|
||||
.General Cassandra repository Spring configuration
|
||||
====
|
||||
[source,xml]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<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"
|
||||
xsi:schemaLocation="
|
||||
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-3.0.xsd
|
||||
">
|
||||
|
||||
<cassandra:cluster port="9042"/>
|
||||
<cassandra:session keyspace-name="keyspaceName"/>
|
||||
|
||||
<cassandra:mapping
|
||||
entity-base-packages="com.acme.*.entities">
|
||||
</cassandra:mapping>
|
||||
|
||||
<cassandra:converter/>
|
||||
|
||||
<cassandra:template/>
|
||||
|
||||
<cassandra:repositories base-package="com.acme.*.entities"/>
|
||||
</beans>
|
||||
----
|
||||
====
|
||||
|
||||
This namespace element will cause the base packages to be scanned for interfaces extending `CrudRepository` and create Spring beans for each of them found. By default the repositories will get a `CassandraTemplate` Spring bean wired that is called `cassandraTemplate`, so you only need to configure `cassandra-template-ref` explicitly if you deviate from this convention.
|
||||
|
||||
If you'd rather like to go with JavaConfig use the `@EnableCassandraRepositories` annotation. The annotation carries the very same attributes like the namespace element. If no base package is configured the infrastructure will scan the package of the annotated configuration class.
|
||||
|
||||
.JavaConfig for repositories
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Configuration
|
||||
@EnableCassandraRepositories
|
||||
class ApplicationConfig extends AbstractCassandraConfiguration {
|
||||
|
||||
@Override
|
||||
protected String getKeyspaceName() {
|
||||
return "keyspace";
|
||||
}
|
||||
|
||||
public String[] getEntityBasePackages() {
|
||||
return new String[] { "com.oreilly.springdata.cassandra" };
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
As our domain repository extends `CrudRepository` it provides you with CRUD operations.
|
||||
Working with the repository instance is just a matter of dependency injecting it into a client.
|
||||
|
||||
TODO
|
||||
|
||||
[[cassandradb.repositories.queries]]
|
||||
== Query methods
|
||||
@@ -25,7 +114,49 @@ TODO
|
||||
[[cassandradb.repositories.misc.cdi-integration]]
|
||||
=== CDI Integration
|
||||
|
||||
The Spring Data for Apache 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:
|
||||
Instances of the repository interfaces are usually created by a container, which Spring is the most natural choice when working with Spring Data. Spring Data Cassandra ships with a custom CDI extension that allows using the repository abstraction in CDI environments. The extension is part of the JAR so all you need to do to activate it is dropping the Spring Data Cassandra JAR into your classpath. You can now set up the infrastructure by implementing a CDI Producer for the `CassandraTemplate`:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
class CassandraTemplateProducer {
|
||||
|
||||
@Produces
|
||||
@Singleton
|
||||
public Cluster createCluster() throws Exception {
|
||||
CassandraConnectionProperties properties = new CassandraConnectionProperties();
|
||||
|
||||
Cluster cluster = Cluster.builder().addContactPoint(properties.getCassandraHost())
|
||||
.withPort(properties.getCassandraPort()).build();
|
||||
return cluster;
|
||||
}
|
||||
|
||||
@Produces
|
||||
@Singleton
|
||||
public Session createSession(Cluster cluster) throws Exception {
|
||||
return cluster.connect();
|
||||
}
|
||||
|
||||
@Produces
|
||||
@ApplicationScoped
|
||||
public CassandraOperations createCassandraOperations(Session session) throws Exception {
|
||||
|
||||
MappingCassandraConverter cassandraConverter = new MappingCassandraConverter();
|
||||
|
||||
CassandraAdminTemplate cassandraTemplate = new CassandraAdminTemplate(session, cassandraConverter);
|
||||
return cassandraTemplate;
|
||||
}
|
||||
|
||||
public void close(@Disposes Session session) {
|
||||
session.close();
|
||||
}
|
||||
|
||||
public void close(@Disposes Cluster cluster) {
|
||||
cluster.close();
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
The Spring Data for Apache Cassandra CDI extension will pick up `CassandraOperations` 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:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@@ -35,7 +166,6 @@ class RepositoryClient {
|
||||
PersonRepository repository;
|
||||
|
||||
public void businessMethod() {
|
||||
|
||||
List<Person> people = repository.findAll();
|
||||
}
|
||||
}
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
|
||||
The Cassandra support contains a wide range of features which are summarized below.
|
||||
|
||||
* Spring configuration support using Java-based @Configuration classes or the XML namespace to create
|
||||
* 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.
|
||||
@@ -24,8 +24,7 @@ are familiar and so you can map your existing knowledge onto the Spring APIs.
|
||||
[[cassandra-getting-started]]
|
||||
== Getting Started
|
||||
|
||||
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
|
||||
Spring Data Cassandra uses the DataStax Java Driver, which supports DataStax Enterprise and Apache Cassandra. 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 setup a running Cassandra server.
|
||||
@@ -35,7 +34,7 @@ and press "Yes" when prompted. Then, enter a project and a package name such as
|
||||
|
||||
Then add the following to the `pom.xml` dependencies section.
|
||||
|
||||
[source,xml]
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
----
|
||||
<dependencies>
|
||||
|
||||
@@ -44,7 +43,7 @@ Then add the following to the `pom.xml` dependencies section.
|
||||
<dependency>
|
||||
<groupId>org.springframework.data</groupId>
|
||||
<artifactId>spring-data-cassandra</artifactId>
|
||||
<version>1.4.1.RELEASE</version>
|
||||
<version>{version}</version>
|
||||
</dependency>
|
||||
|
||||
</dependencies>
|
||||
@@ -52,9 +51,9 @@ Then add the following to the `pom.xml` dependencies section.
|
||||
|
||||
Also, change the version of Spring in `pom.xml` to be
|
||||
|
||||
[source,xml]
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
----
|
||||
<spring.framework.version>4.2.5.RELEASE</spring.framework.version>
|
||||
<spring.framework.version>{springVersion}</spring.framework.version>
|
||||
----
|
||||
|
||||
If you are using a milestone version (e.g. M1 or RC1) of Spring Data Cassandra, you will also need to include the
|
||||
@@ -640,7 +639,7 @@ cassandraOperations.execute(cql);
|
||||
|
||||
CQLOperations, which is extended by CassandraOperations is a lower level Template that you can use for just about anything you need to accomplish with Cassandra. CqlOperations includes several overloaded methods named `ingest()`.
|
||||
|
||||
Use these methods to pass a CQL String with Bind Markers, and your preferred flavor of data set (Object[][] and List<List<T>>).
|
||||
Use these methods to pass a CQL String with Bind Markers, and your preferred flavor of data set (`Object[][]` and `List<List<T>>`).
|
||||
|
||||
The ingest method takes advantage of static PreparedStatements that are only prepared once for performance. Each record in your data list is bound to the same PreparedStatement, then executed asynchronously for high performance.
|
||||
|
||||
|
||||
@@ -12,13 +12,109 @@ In this section we will describe the features of the CassandraMappingConverter.
|
||||
|
||||
* 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.
|
||||
* The properties of an object are used to convert to and from properties in the document.
|
||||
|
||||
[[mapping.conventions.id-field]]
|
||||
[[mapping-conventions-id-field]]
|
||||
=== How the CQL Composite Primary Key fields are handled in the mapping layer
|
||||
|
||||
TODO
|
||||
|
||||
[[mapping-conversion]]
|
||||
== Data mapping and type conversion
|
||||
|
||||
This section explain how types are mapped to a Cassandra representation and vice versa. Spring Data Cassandra supports several types that are provided by Apache Cassandra.
|
||||
In addition to these types, Spring Data Cassandra provides a set of built-in converters to map additional types. You can provide your own converters to adjust type conversion, see <<mapping-explicit-converters>> for further details.
|
||||
|
||||
[cols="3,2", options="header"]
|
||||
.Type
|
||||
|===
|
||||
| Type
|
||||
| Cassandra types
|
||||
|
||||
| `String`
|
||||
| `text` (default), `varchar`, `ascii`
|
||||
|
||||
| `double`, `Double`
|
||||
| `double`
|
||||
|
||||
| `float`, `Float`
|
||||
| `float`
|
||||
|
||||
| `long`, `Long`
|
||||
| `bigint` (default), `counter`
|
||||
|
||||
| `int`, `Integer`
|
||||
| `int`
|
||||
|
||||
| `short`, `Short`
|
||||
| `smallint`
|
||||
|
||||
| `byte`, `Byte`
|
||||
| `tinyint`
|
||||
|
||||
| `boolean`, `Boolean`
|
||||
| `boolean`
|
||||
|
||||
| `BigInteger`
|
||||
| `varint`
|
||||
|
||||
| `BigDecimal`
|
||||
| `decimal`
|
||||
|
||||
| `java.util.Date`
|
||||
| `timestamp`
|
||||
|
||||
| `com.datastax.driver.core.LocalDate`
|
||||
| `date`
|
||||
|
||||
| `InetAddress`
|
||||
| `inet`
|
||||
|
||||
| `ByteBuffer`
|
||||
| `blob`
|
||||
|
||||
| `java.util.UUID`
|
||||
| `timeuuid`
|
||||
|
||||
| `java.util.Map<K, V>`
|
||||
| `map`
|
||||
|
||||
| `java.util.List<E>`
|
||||
| `list`
|
||||
|
||||
| `java.util.Set<E>`
|
||||
| `set`
|
||||
|
||||
| `Enum`
|
||||
| `text` (default), `bigint`, `varint`, `int`, `smallint`, `tinyint`
|
||||
|
||||
|===
|
||||
|
||||
Each supported type maps to a default
|
||||
https://docs.datastax.com/en/cql/3.3/cql/cql_reference/cql_data_types_c.html[Cassandra data type].
|
||||
Java types can be mapped to other Cassandra types by using `@CassandraType`.
|
||||
|
||||
.Enum Mapping to Numeric types
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Table
|
||||
public class EnumToOrdinalMapping {
|
||||
|
||||
@PrimaryKey String id;
|
||||
|
||||
@CassandraType(type = Name.INT) Condition asOrdinal;
|
||||
}
|
||||
|
||||
public enum Condition {
|
||||
NEW, USED
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
NOTE: `Enum` mapping using ordinal values requires at least Spring 4.3.0. Using earlier Spring versions require
|
||||
<<mapping-explicit-converters,custom converters>> for each `Enum` type.
|
||||
|
||||
[[mapping-configuration]]
|
||||
=== Mapping Configuration
|
||||
|
||||
@@ -35,3 +131,27 @@ TODO
|
||||
====
|
||||
TODO
|
||||
====
|
||||
|
||||
[[mapping-explicit-converters]]
|
||||
=== Overriding Mapping with explicit Converters
|
||||
|
||||
When storing and querying your objects it is convenient to have a `CassandraConverter` instance handle the mapping of all Java types to Rows. However, sometimes you may want the `CassandraConverter` s do most of the work but allow you to selectively handle the conversion for a particular type or to optimize performance.
|
||||
|
||||
To selectively handle the conversion yourself, register one or more one or more `org.springframework.core.convert.converter.Converter` instances with the `CassandraConverter`.
|
||||
|
||||
NOTE: Spring 3.0 introduced a core.convert package that provides a general type conversion system. This is described in detail in the Spring reference documentation section entitled http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/validation.html#core-convert[Spring Type Conversion].
|
||||
|
||||
Below is an example of a Spring Converter implementation that converts from a Row to a Person POJO.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@ReadingConverter
|
||||
public class PersonReadConverter implements Converter<Row, Person> {
|
||||
|
||||
public Person convert(Row source) {
|
||||
Person p = new Person(row.getString("id"));
|
||||
p.setAge(source.getInt("age");
|
||||
return p;
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Reference in New Issue
Block a user