OGM-122 cassandra backend

initial skeleton manual chapter

documentation/manual/src/main/asciidoc/en-US/master.asciidoc

@@ -27,3 +27,5 @@ include::modules/mongodb.asciidoc[]
 include::modules/neo4j.asciidoc[]
 
 include::modules/couchdb.asciidoc[]
+
+include::modules/cassandra.asciidoc[]

documentation/manual/src/main/asciidoc/en-US/modules/cassandra.asciidoc

@@ -0,0 +1,106 @@
+[[ogm-cassandra]]
+
+== Cassandra
+
+http://cassandra.apache.org/[Cassandra] is a distributed column family database.
+
+This implementation uses http://docs.datastax.com/en/cql/3.1/cql/cql_intro_c.html[CQL3]
+ over the native wire protocol with https://github.com/datastax/java-driver[java-driver]
+The currently supported version is Cassandra 2.1
+
+=== Configuring Cassandra
+
+Configuring Hibernate OGM to use Cassandra is easy:
+
+* Add the Cassandra module and driver to the classpath
+* provide the Cassandra connection information to Hibernate OGM
+
+==== Adding Cassandra dependencies
+
+To add the dependencies via Maven, add the following module:
+
+[source, XML]
+[subs="verbatim,attributes"]
+----
+<dependency>
+    <groupId>org.hibernate.ogm</groupId>
+    <artifactId>hibernate-ogm-cassandra</artifactId>
+    <version>{hibernate-ogm-version}</version>
+</dependency>
+----
+
+This will pull the cassandra java-driver transparently.
+
+If you're not using a dependency management tool,
+copy all the dependencies from the distribution in the directories:
+
+* +/lib/required+
+* +/lib/cassandra+
+* Optionally - depending on your container - you might need some of the jars from +/lib/provided+
+
+==== Cassandra specific configuration properties
+
+To get started quickly, pay attention to the following options:
+
+* +hibernate.ogm.datastore.provider+
+* +hibernate.ogm.datastore.host+
+* +hibernate.ogm.datastore.database+
+
+And we should have you running.
+The following properties are available to configure Cassandra support:
+
+.Cassandra datastore configuration properties
+hibernate.ogm.datastore.provider::
+To use Cassandra as a datastore provider, this property must be set to +cassandra+
+hibernate.ogm.datastore.host::
+The hostname of the Cassandra instance. The default value is +127.0.0.1+.  Listing multiple initial hosts for fault tolerance is not currently supported.
+hibernate.ogm.datastore.port::
+The port used by the Cassandra instance. The default value is +9042+.
+hibernate.ogm.datastore.database::
+The database to connect to. This property has no default value.
+hibernate.ogm.datastore.username::
+The username used when connecting to the Cassandra server.
+This property has no default value.
+hibernate.ogm.datastore.password::
+The password used to connect to the Cassandra server.
+This property has no default value.
+
+
+[[ogm-cassandra-storage-principles]]
+=== Storage principles
+
+Each Entity type maps to one Cassandra table. Each Entity instance maps to one CQL3 row of the table, each property of the Entity being one CQL3 column.
+
+CQL3 table and column names are always quoted to preserve case consistency with the Java layer, with the table name matching the Entity class and the column names matching the Entity's properties.
+The @Table and @Column annotations can be used to override identifier names in the usual manner.
+
+Embedded objects are stored as additional columns in the owning Entitie's table. The columns are named as +EmbeddedTypeName.FieldOfEmbeddedType+
+The type and field names can be overridden by annotations, but concatenation token delimiter cannot.
+
+[[cassandra-types]]
+==== Properties and built-in types
+
+http://docs.datastax.com/en/cql/3.1/cql/cql_reference/cql_data_types_c.html[CQL3 types]
+
+CQL3 supports a smaller selection of numeric data types than Hibernate, so the missing types are autotmatically converted. byte and short values are promoted to integer.
+
+CQL3 has no character type, so character is promoted to varchar i.e. String. Strings are UTF-8, not ascii.
+
+CQL3 does not distinguish between byte[] and BLOB types for binary storage. These are handled equivalently.
+
+CQL3 does not have a Calendar type, so these are converted to Dates, which are stores as time offset from the unix epoch.
+
+===== Identifier generation strategies
+
+You can assign id values yourself or let Hibernate OGM generate the value using the
+[classname]+@GeneratedValue+ annotation.
+
+The preferred identifier approach in Cassandra is to use UUIDs.
+
+Cassandra does not natively support sequence (auto increment identifiers) at present. This approach is supported though use of an additional table to store sequence state, but incurs additional access overheads that make it undesirable for tables with frequent inserts.
+
+=== Transactions and Concurrency
+
+Cassandra does not support transactions.  Changes to a single Entity are atomic. Changes to more than one are neither atomic not isolated.
+
+Cassandra does not distinguish between update and insert operations and will not prevent creation of an Entity with duplicate Id, instead treating it as modification of the existing Entity.