userguide-easycassandra_002
TRANSCRIPT
Easy-Cassandra User Guide
Document version: 002 1
SummaryAbout Easy-Cassandra..........................................................................................................................4Features.................................................................................................................................................4Java Objects Supported........................................................................................................................4About Versions.....................................................................................................................................5
Version: 1.0.8.....................................................................................................................5
Version: 1.0.7.....................................................................................................................5
Version: 1.0.6.....................................................................................................................5Version: 1.0.5.....................................................................................................................5Version: 1.0.4.....................................................................................................................5Version: 1.0.3.....................................................................................................................5Version: 1.0.2.....................................................................................................................5Version: 1.0.1.....................................................................................................................5
Beyond version................................................................................................................................6For use the Easy-Cassandra is necessary: .......................................................................................6The Thrift's dependence: .................................................................................................................6Maven:.............................................................................................................................................6
Annotations...........................................................................................................................................8Used in Class........................................................................................................................................8
ColumnFamilyValue: ........................................................................................................8Used in Field.........................................................................................................................................8
ColumnValue: ...................................................................................................................8EmbeddedValue: ...............................................................................................................9EnumeratedValue: .............................................................................................................9IndexValue: .......................................................................................................................9KeyValue: .........................................................................................................................9
Complete Example with Annotation..............................................................................................10Commands..........................................................................................................................................11
The class org.easycassandra.persistence.Persistence.....................................................................11ConsistencyLevel...........................................................................................................................11Enum Options:...............................................................................................................................11
ONE:................................................................................................................................11QUORUM ....................................................................................................................11ALL.................................................................................................................................12DCQUORUM..................................................................................................................12DCQUORUMSYNC.......................................................................................................12
Insert Commands...........................................................................................................................13insert(Object object, ConsistencyLevelCQL consistencyLevel).....................................13insert(Object object)........................................................................................................13
Remove Commands.......................................................................................................................13delete(Object object)........................................................................................................13deleteByKeyValue(Object keyValue, Class objectClass)................................................13
Update Commands.........................................................................................................................13update(Object object, ConsistencyLevel consistencyLevel)...........................................14update(Object object, ConsistencyLevel consistencyLevel)...........................................14
List Commands..............................................................................................................................14findAll(Class persistenceClass, ConsistencyLevelCQL consistencyLevel, int limit).....14findAll(Class persistenceClass, ConsistencyLevelCQL consistencyLevel)....................14findAll(Class persistenceClass, int limit)........................................................................14
Document version: 002 2
findAll(Class persistenceClass).......................................................................................15findByIndex(Object index, Class objectClass, ConsistencyLevelCQL consistencyLevelCQL, int limit).....................................................................................15findByIndex(Class persistenceClass, ConsistencyLevelCQL consistencyLevel)...........15findByIndex(Class persistenceClass, int limit)................................................................15findByIndex(Class persistenceClass)..............................................................................15
Retrieve from Key row Commands...............................................................................................16findByKey(Object key, Class persistenceClass, ConsistencyLevelCQL consistencyLevel)............................................................................................................16findByKey(Object key, Class persistenceClass)..............................................................16findByKeyIn(Class baseClass,ConsistencyLevelCQL consistencyLevel,Object... keys).........................................................................................................................................16findByKeyIn(Class baseClass, Object... keys)................................................................16
Count Commands..........................................................................................................................16count(Class<?> clazz,ConsistencyLevelCQL consistencyLevel)...................................16count(Class clazz)............................................................................................................17
Sample Abstract DAO...................................................................................................................18Native Commands..........................................................................................................................20
Get Thrift Client..............................................................................................................20Get Thrift Client in Current Persistence..........................................................................20
Execute Cassandra Query Language.............................................................................................20executeUpdateCql(String query).....................................................................................20executeCql(String query).................................................................................................20
How to Contribute with this project..............................................................................................21Article:...........................................................................................................................................21
Document version: 002 3
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-CassandraDownload: 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 4
• 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 5
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 6
<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 7
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 {...}
@ColumnFamilyValuepublic 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 8
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 object’s 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 9
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 if 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: [email protected] 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-simple-example
http://weblogs.java.net/blog/otaviojava/archive/2012/02/01/persist-document-cassandra
Document version: 002 21