Easy-Cassandra User Guide

Document version: 002

Summary
About Easy-Cassandra..........................................................................................................................4
Features.................................................................................................................................................4
Java Objects Supported........................................................................................................................4
About Versions.....................................................................................................................................5
Version: 1.0.8.....................................................................................................................5
Version: 1.0.7.....................................................................................................................5
Version: 1.0.6.....................................................................................................................5
Version: 1.0.5.....................................................................................................................5
Version: 1.0.4.....................................................................................................................5
Version: 1.0.3.....................................................................................................................5
Version: 1.0.2.....................................................................................................................5
Version: 1.0.1.....................................................................................................................5
Beyond version................................................................................................................................6
For use the Easy-Cassandra is necessary: .......................................................................................6
The Thrift's dependence: .................................................................................................................6
Maven:.............................................................................................................................................6
Annotations...........................................................................................................................................8
Used in Class........................................................................................................................................8
ColumnFamilyValue: ........................................................................................................8
Used in Field.........................................................................................................................................8
ColumnValue: ...................................................................................................................8
EmbeddedValue: ...............................................................................................................9
EnumeratedValue: .............................................................................................................9
IndexValue: .......................................................................................................................9
KeyValue: .........................................................................................................................9
Complete Example with Annotation..............................................................................................10
Commands..........................................................................................................................................11
The class org.easycassandra.persistence.Persistence.....................................................................11
ConsistencyLevel...........................................................................................................................11
Enum Options:...............................................................................................................................11
ONE:................................................................................................................................11
QUORUM ....................................................................................................................11
ALL.................................................................................................................................12
DCQUORUM..................................................................................................................12
DCQUORUMSYNC.......................................................................................................12
Insert Commands...........................................................................................................................13
insert(Object object, ConsistencyLevelCQL consistencyLevel).....................................13
insert(Object object)........................................................................................................13
Remove Commands.......................................................................................................................13
delete(Object object)........................................................................................................13
deleteByKeyValue(Object keyValue, Class objectClass)................................................13
Update Commands.........................................................................................................................13
update(Object object, ConsistencyLevel consistencyLevel)...........................................14
update(Object object, ConsistencyLevel consistencyLevel)...........................................14
List Commands..............................................................................................................................14
findAll(Class persistenceClass, ConsistencyLevelCQL consistencyLevel, int limit).....14
findAll(Class persistenceClass, ConsistencyLevelCQL consistencyLevel)....................14
findAll(Class persistenceClass, int limit)........................................................................14
Document version: 002

findAll(Class persistenceClass).......................................................................................15
findByIndex(Object index, Class objectClass, ConsistencyLevelCQL
consistencyLevelCQL, int limit).....................................................................................15
findByIndex(Class persistenceClass, ConsistencyLevelCQL consistencyLevel)...........15
findByIndex(Class persistenceClass, int limit)................................................................15
findByIndex(Class persistenceClass)..............................................................................15
Retrieve from Key row Commands...............................................................................................16
findByKey(Object key, Class persistenceClass, ConsistencyLevelCQL
consistencyLevel)............................................................................................................16
findByKey(Object key, Class persistenceClass)..............................................................16
findByKeyIn(Class baseClass,ConsistencyLevelCQL consistencyLevel,Object... keys)
.........................................................................................................................................16
findByKeyIn(Class baseClass, Object... keys)................................................................16
Count Commands..........................................................................................................................16
count(Class<?> clazz,ConsistencyLevelCQL consistencyLevel)...................................16
count(Class clazz)............................................................................................................17
Sample Abstract DAO...................................................................................................................18
Native Commands..........................................................................................................................20
Get Thrift Client..............................................................................................................20
Get Thrift Client in Current Persistence..........................................................................20
Execute Cassandra Query Language.............................................................................................20
executeUpdateCql(String query).....................................................................................20
executeCql(String query).................................................................................................20
How to Contribute with this project..............................................................................................21
Article:...........................................................................................................................................21

Document version: 002

About Easy-Cassandra
Easy-Cassandra is a framework ORM API and a high client for Apache Cassandra in java, with this is
possible persist information from the Java Object in easy way. For this is only necessary add some
annotations in some fields and your class. It works like an abstraction's tier in the Thrift, doing call for
Cassandra.
The Easy-Cassandra uses the Thrift implementation and has like the main objective be one simple ORM
(Object relational manager). It need the jdk 7 for run, because some parts in your code was replaced
reflection for invoke dynamic. So will have a behavior faster than other framework. The Easy-Cassandra was
the first framework compatible with Cassandra version above 0.8 and the first one to use CQL (Cassandra
Query Language). For read a class, it use the invokedynamic, fifteen time faster than reflection.

Site: https://github.com/otaviojava/Easy-Cassandra
Download: https://github.com/otaviojava/Easy-Cassandra/downloads

Features

An ORM easy to use in Cassandra

Need only use some Annotations in a class to persist
Persists many Java Objects in way extremely easy (e.g: all primitives types, java.Lang.String,
java.lang.BigDecimal, java.io.File, etc.).
Read and Write in Cassandra with Level Consistency.
The first framework ORM in Cassandra to compatibles with version above 0.8.0.
The first to use CQL
compatible with CQL 2.0
The first to use invokedynamic instead to reflection
In the Apache version 2.0 license

Java Objects Supported

The Easy-Cassandra has support for the Object java bellow:

all primitives types (int, long, float, double, short, byte, boolean)
java.lang.Boolean
java.util.Date
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.String
java.lang.Boolean
java.lang.Byte
java.lang.Short
java.lang.Character
java.io.File

Document version: 002

java.nio.file.Path

About Versions
The current and stable version is 1.0.8

Version: 1.0.8

Select Key from 'in' CQL command

Create automatically the ColumnFamily in Run Time
Create automatically the IndexValue in Run Time
Support with cql 2.0
Now, it not necessary create Column Family or Secondary Index. The Easy-Cassandra will create
that in run time.

Version: 1.0.7
update cassandra-thrift to 1.0.7
Version: 1.0.6
Fixes bug with File
Support Calendar interface
Version: 1.0.5
Can now store files
Support java.io.File and java.nio.file.Path
Version: 1.0.4
more performance
Less memory
Now is supported all primitives types
Now is supported Byte, character, Short, BigInteger and BigDecimal
Version: 1.0.3
Fixes bug with result
update for Thrift 1.0.6
Log now using java.util.loggin
Version: 1.0.2
Fixes bug with Boolean's Object
Now the Cassandra's lib is supported this way is possible use every Cassandra above of the version
0.8.0
Version: 1.0.1
Allowed use ColumnValue and ColumnFamilyValue in default mode this way its get the field's name
Fixes bug in Reflection

Document version: 002

Beyond version
Support with one and more Index
Feed Object with Cassandra Query Language
Example: List<Person> persons= cassandraQuery.executeQuery("select * from
Person").getResultList();

For use the Easy-Cassandra is necessary:

JDK 7 or above
Apache Cassandra is running here
Create the Keystore
Do annotations in the class Annotations
Realize call for save the object in Cassandra Here
Add Easy-Cassandra's Lib https://github.com/otaviojava/Easy-Cassandra/downloads
Add Thrift Dependence: Easy Cassandra with Thrift dependencies

The Thrift's dependence:

cassandra-thrift-1.0.7.jar
commons-codec-1.3.jar
commons-lang-2.4.jar
commons-logging-1.1.1.jar
httpclient-4.0.1.jar
httpcore-4.0.1.jar
junit-4.4.jar
libthrift-0.6.1.jar
servlet-api-2.5.jar
slf4j-api-1.6.1.jar

Maven:
For use Easy-Cassandra with maven you must add in your maven application the repository and
then add the tag of the project.

Document version: 002

<project>
.
<dependencies>

<dependency>
<groupId>org.easycassandra</groupId>
<artifactId>EasyCassandra</artifactId>
<version>1.0.8</version>
</dependency>
<!-- other dependencies -->
</dependencies>
<repositories>
<!-- other repositories -->
<repository>
<id>easycassandra</id>
<url>http://otaviojava.googlecode.com/svn/repository/</url>
</repository>
</repositories>
</project>

Document version: 002

Annotations
The annotations are for mapping of the object, then persist and retrieve the information in Cassandra.

Used in Class
ColumnFamilyValue:
Annotations for identify the family column name.
E.g:

@ColumnFamilyValue(name = "Person")
public class Person implements Serializable {...}
@ColumnFamilyValue
public class Person implements Serializable {...}
If this no used the 'name' value, the default value is the Class's name

Used in Field
ColumnValue:
For identify the column in the Family Column, the classes can be used are:

all primitives types (int, long, short, byte, float, double, boolean)
java.lang.Boolean
java.util.Date
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.String
java.lang.Boolean
java.lang.Byte
java.lang.Short
java.lang.Character
java.io.File
java.nio.file.Path

@ColumnValue(name = "year")
private Integer year;
@ColumnValue
private Integer year;
If this no used the 'name' value, the default value is the Field's name

Document version: 002

EmbeddedValue:
The class with this is annotation has fields with ColumnValue inside itself, but the persistence way continues
in the same Family of the Column. This annotation is to do the objects modeling easily.
@EmbeddedValue
private MyObject myObject;

EnumeratedValue:
For be used in Enums
@EnumeratedValue(name="myEnum")
private EnumClass enumClass;
@EnumeratedValue
private EnumClass enumClass;
If this no used the 'name' value, the default value is the Field's name

IndexValue:
The field with this annotation is an index secundary, can search and retrieve information from the row like
KeyValue, need also use the ColumnValue together with this annotation.
@IndexValue
@ColumnValue(name = "name")
private String name;
@IndexValue
@ColumnValue
private String name;

KeyValue:
The field with this annotation is a Key of the Row. If the auto value is true will generate auto increment, each
new Key in the FamilyColumn there are a new value auto numeric.
@KeyValue
private String id;
@KeyValue(auto=true)
private Long id;
The default value for auto equals false, in other words Easy-Cassandra will not generate an auto increment
value, when the auto is false can use all type supported by framework and when is auto is true must use
Long object. Each Class with FamilyColumn annotation must be this annotation in some field.

Document version: 002

Complete Example with Annotation

@ColumnFamilyValue(name = "person")
public class Person implements Serializable {
private static final long serialVersionUID = 3L;
@KeyValue(auto=false)
private Long id;
@ColumnValue(name = "name")
private String name;
@ColumnValue(name = "born")
private Integer year;
//getter and setter
}
//Embedded class
public class Address implements Serializable {
private static final long serialVersionUID = 1L;
@ColumnValue(name="state")
private String state;
@ColumnValue(name="cyte")
private String city;
@ColumnValue(name="street")
private String street;
@ColumnValue(name="cep")
private String cep;
//getter and setter
}

Document version: 002

10

Commands
The class org.easycassandra.persistence.Persistence
The class Persistence is the main Class for do call to Cassandra, for created this class you must inform the
host, port and Keystore where is Cassandra.
Persistence persistence;
persistence = EasyCassandraManager.getPersistence("javabahia", "localhost", 9160);

ConsistencyLevel
The org.easycassandra.ConsistencyLevel is an enum that controls both read and write, in Easy-Cassandra,
the behavior based on the ReplicationFactor of the keyspace.

Enum Options:
ONE:
Read
Will return the record returned by the first replica to respond. A consistency check is always done in a
background thread to fix any consistency issues when ConsistencyLevel.ONE is used. This means
subsequent calls will have correct data even if the initial read gets an older value. (This is called
ReadRepair).
Write
Ensure that the write has been written to at least 1 replica's commit log and memory table before
responding to the client.

QUORUM
Read
Will query all replicas and return the record with the most recent timestamp once it has at least a majority
of replicas (N 2 + 1) reported. Again, the remaining replicas will be checked in the background.
Write
Ensure that the write has been written to N 2 + 1 replicas before responding to the client.

Document version: 002

11

ALL

Read
Will query all replicas and return the record with the most recent timestamp once all replicas have
replied. Any unresponsive replicas will fail the operation.
Write
Ensure that the write is written to all N replicas before responding to the client. Any unresponsive replicas
will fail the operation.

DCQUORUM
Read
Returns the record with the most recent timestamp once a majority of replicas within the local datacenter
have replied.
Write
Ensure that the write has been written to <ReplicationFactor> 2 + 1 nodes, within the local datacenter
(requires NetworkTopologyStrategy) .

DCQUORUMSYNC
Read
Returns the record with the most recent timestamp once a majority of replicas within each datacenter
have replied.
Write
Ensure that the write has been written to <ReplicationFactor> 2 + 1 nodes in each datacenter
(requires NetworkTopologyStrategy).

Document version: 002

12

Insert Commands
This are command for persist class in Cassandra.

insert(Object object, ConsistencyLevelCQL consistencyLevel)

Insert the object with a consistency level defined, it return true if executed with success.
boolean success=persistence.insert(bean,ConsistencyLevelCQL.ALL);

insert(Object object)

Insert the object with a consistency level equal ConsistencyLevelCQL.ONE, it return true if executed with
success.
boolean success=persistence.insert(bean);

Remove Commands

delete(Object object)

Remove all row from key inside of the Object, the key value must be not empty or null. It return true if
executed with success.
boolean success=persistence.delete(bean);

deleteByKeyValue(Object keyValue, Class objectClass)

Remove all row with key value and use the Class for search the respective Column Family. It return true if
executed with success.
boolean success=persistence.deleteByKeyValue(rowKey, baseClass);

Update Commands

Document version: 002

13

update(Object object, ConsistencyLevel consistencyLevel)

Update all row with information present in the object with Consistency level sectioned, this command do an
override in values in the row, the key value must be not empty or null. It return true if executed with success.

boolean success=persistence.update(bean,ConsistencyLevelCQL.DCQUORUM);

update(Object object, ConsistencyLevel consistencyLevel)

Update all row with information present in the object consistency level equal ConsistencyLevelCQL.ONE this
command do an override in values in the row, the key value must be not empty or null. It return true if
executed with success.

boolean success=persistence.update(bean);

List Commands

findAll(Class persistenceClass, ConsistencyLevelCQL consistencyLevel, int limit)

Return all objects in the Column Family, recovered by class, with consistency level selected and with a limit
number defined.
List<BaseObject> list =persistence.findAll(baseClass, ConsistencyLevelCQL.DCQUORUMSYNC, 15000);

findAll(Class persistenceClass, ConsistencyLevelCQL consistencyLevel)

Return all objects in the Column Family, recovered by class, with consistency level selected and with a limit
number 10000.
List<BaseObject> list =persistence.findAll(baseClass, ConsistencyLevelCQL.DCQUORUMSYNC);

findAll(Class persistenceClass, int limit)

Return all objects in the Column Family, recovered by class, with consistency level equal
ConsistencyLevelCQL.ONE and with a limit number defined.

List<BaseObject> list =persistence.findAll(baseClass, 5000);

Document version: 002

14

findAll(Class persistenceClass)
Return all objects in the Column Family, recovered by class, with consistency level equal
ConsistencyLevelCQL.ONE and with a limit number 10000.

List<BaseObject> list =persistence.findAll(baseClass);

findByIndex(Object index, Class objectClass, ConsistencyLevelCQL consistencyLevelCQL, int limit)

Return all objects from secondary index in the Column Family, recovered by class, with consistency level
selected and with a limit number defined. The class must be some field with IndexValue annotations.
List<BaseObject> list =persistence.findByIndex(indexValue,baseClass,
ConsistencyLevelCQL.DCQUORUMSYNC, 15000);

findByIndex(Class persistenceClass, ConsistencyLevelCQL consistencyLevel)

Return all objects from secondary index in the Column Family, recovered by class, with consistency level
selected and with a limit number 10000. The class must be some field with IndexValue annotations.
List<BaseObject> list =persistence.findByIndex(indexValue,baseClass,
ConsistencyLevelCQL.DCQUORUMSYNC);

findByIndex(Class persistenceClass, int limit)

Return all objects from secondary index in the Column Family, recovered by class, with consistency level
equal ConsistencyLevelCQL.ONE and with a limit number defined. The class must be some field with
IndexValue annotations.

List<BaseObject> list =persistence.findAll(indexValue,baseClass, 5000);

findByIndex(Class persistenceClass)
Return all objects from secondary index in the Column Family, recovered by class, with consistency level
equal ConsistencyLevelCQL.ONE and with a limit number 10000. The class must be some field with
IndexValue annotations.

List<BaseObject> list =persistence.findByIndex(indexValue,baseClass);

Document version: 002

15

Retrieve from Key row Commands

findByKey(Object key, Class persistenceClass, ConsistencyLevelCQL consistencyLevel)

Return the object from key row with the value passed in parameter, recovered by class, with the consistency
level selectioned.
BaseObject base=(BaseObject)persistence.findByKey(idValue, baseClass,ConsistencyLevelCQL.ALL);

findByKey(Object key, Class persistenceClass)

Return the object from key row with the value passed in parameter, recovered by class, with the consistency
level selected.
BaseObject base=(BaseObject)persistence.findByKey(idValue, baseClass);

findByKeyIn(Class baseClass,ConsistencyLevelCQL consistencyLevel,Object... keys)

Return the object from key row with N value passed in parameter, recovered by class, with the consistency
level selected.
List<BaseObject> list=persistence.findByKeyIn(
baseClass,ConsistencyLevelCQL.ALL,param1,param2,param3);

findByKeyIn(Class baseClass, Object... keys)

Return the object from key row with N value passed in parameter, recovered by class, with the consistency
level equal ConsistencyLevelCQL.ONE.
List<BaseObject> list=persistence.findByKeyIn( baseClass,param1,param2,param3);

Count Commands

count(Class<?> clazz,ConsistencyLevelCQL consistencyLevel)

Return the number of rows in Column Family with the consistency level selected.
Long numberOfRow=persistence.count(baseClass,ConsistencyLevelCQL.DCQUORUMSYNC);

Document version: 002

16

count(Class clazz)
Return the number of rows in Column Family with consistency level equal ConsistencyLevel.
Long numberOfRow=persistence.count(baseClass);

Document version: 002

17

Sample Abstract DAO

Bellow a simple example DAO using Easy-Cassandra.

public abstract class AbstractDao<T> {

private Persistence persistence;
private Class baseClass;
public AbstractDao(Class<T> baseClass) {
this.baseClass=baseClass;
persistence = EasyCassandraManager.getPersistence("javabahia", "localhost", 9160);
}
public boolean insert(T bean) {
return persistence.insert(bean,ConsistencyLevelCQL.ONE);
}
public boolean remove(T bean) {
return persistence.delete(bean);
}
public boolean removeFromRowKey(Object rowKey) {
return persistence.deleteByKeyValue(rowKey, baseClass);
}
public boolean update(T bean) {
return persistence.update(bean);
}
@SuppressWarnings("unchecked")
public T retrieve(Object id) {
return (T) persistence.findByKey(id, baseClass);
}
@SuppressWarnings("unchecked")
public List<T> listAll() {
return persistence.findAll(baseClass);
}

Document version: 002

18

@SuppressWarnings("unchecked")
public List<T> listByIndex(Object index) {
return persistence.findByIndex(index, baseClass);
}
public Long count() {
return persistence.count(baseClass);
}
public List<T> findKeyIn(Object... key) {
return persistence.findByKeyIn( baseClass,key);
}

Document version: 002

19

Native Commands

Get Thrift Client

If necessary you can call Thrift functions for it, it is necessary inform the host, port, and keystore for the
Class EasyCassandraManager.

Client client=EasyCassandraManager.getClient("javabahia", "localhost", 9160);

Get Thrift Client in Current Persistence

Also is allowed get Thrift's client, used by Persistence.

Client client=persistence.getClient();

Execute Cassandra Query Language

executeUpdateCql(String query)
This Command execute the query in String i f there was success return true otherwise false
boolean success=persistence.executeUpdateCql("DELETE columnName FROM COLUMNFAMILY
WHERE KEY = keyname1");

executeCql(String query)
Retrieve values from Query command and return The values from query like List of the Map<String, String>:
Each List is a row.
Each Map<String, String>: a key in the map is equal a column's name and the value in the map is the
column's value.

List<Map<String, String>> result=persistence.executeCql("select * from ColumnFamily");

Document version: 002

20

How to Contribute with this project

If you would like help the project, report software error, fix bug in the document you can send email for:
otaviojava@java.net or participate in Google Groups: https://groups.google.com/group/easy-cassandra

Article:
http://weblogs.java.net/blog/otaviojava/archive/2012/01/24/persisting-information-cassandra-java-simpleexample
http://weblogs.java.net/blog/otaviojava/archive/2012/02/01/persist-document-cassandra

Document version: 002

21