Home

Getting Started

This page is designed to provide a quick introduction to get people started with OCM.

The basic usage of OCM is simple 3 step process

1. Define your data model in an OCM spec file.
2. Feed that spec file through the OCM compiler to generate source code.
3. Include the OCM Base library and generated source code in your project.

If you are ever unsure of what OCM is doing you can always look at the generated source code. Its designed to be as close to human hand written code as possible. It even contains comments about key aspects of what its doing.

Below is a simple example of a User Column family for a web site. It stores the basic user info and authentication data most applications with user logins need to.

[Comment="The main users table for a web site"]
ColumnFamily Users
{ 
	[Index]
	String userID;
	
	SuperFamily auth
	{
		String password;
		String salt;
		Boolean enabled;
	}
	
	SuperFamily info
	{
		String firstName;
		String lastName;
		
		[Indexed]
		String email;
	}

	DynamicSuperFamily String roles;
}

The data type of each field matches a data type in the target language. Most of the built in Java data types are supported (int, float, double, byte). Each super family is a Super Column Family in Cassandra. Each Field in the SuperFamily is a column in Cassandra.

You can tell OCM to load specfic SuperFamilies or the entire row from Cassandra. Calling the Save method automatically saves only the changed fields back to the row in Cassandra. All fields have Getter and Setter methods. The key field is read only, if you want to change it you must create a new record and delete the old one. To create a new Cassandra row, provide the key via the objects constructor, populate it with data then call the save method.

Any field can be marked as Indexed via the “[Indexed]” attribute. This will automatically maintain a secondary table to allow efficient lookups via this field. So for the example above you can get a user object by providing their email address using the byEmail static method of the object.

The Dynamic Super Family is simply a column family which contains a list of items. These can change dynamically hence their contents isn’t described in the spec file.

Compiling the Spec File

Once you are ready you need to compile the spec file with the OCM compiler. Its often useful to add the compilier to your development IDE. In eclipse you can add it as an External Tool. However you invoke it the format of the parameters is the same. Below is the format of the command line parameters:

java -jar {Path To OCMCompiler.jar}  {Spec File Path}  {Cassandra KeySpace Name} {Output Language} {Java Package for Generated Source} {Path to Output Folder}

Things to note:

1. The Spec File path can contain wild cards so you can compile many spec files at once.
2. Only Java is currently supported as an output language.
3. The output folder is relative to the current working directory.
4. The compiler will output a sample storage-conf.xml file which contains all the column family definitions.

Below is a sample of a compiler command line argument.

java -jar ../war/WEB-INF/lib/OCMCompiler.jar  spec/*.spec.txt KeySpace1 Java org.example.server.dao.generated generated/

This will generate all the Java classes which your app can use to access the Cassandra database. These need to be compiled like any Java class. The only dependency the generated code has is on the OCMJavaBaseLib.jar which is supplied with OCM.

That’s it for this quick introduction. The source code contains a test harness class which provides a good example of these and more advanced features. Other features include ManyToMany relationships and Range Scanners to get items by a range of keys.