DataNucleus - Tutorial for JPA for Cassandra

Background

An application can be JPA-enabled via many routes depending on the development process of the
project in question. For example the project could use Eclipse as the IDE for developing classes.
In that case the project would typically use the Dali Eclipse plugin coupled with the DataNucleus
Eclipse plugin. Alternatively the project could use Ant, Maven2 or some other build tool.
In this case this tutorial should be used as a guiding way for using DataNucleus in the application.
The JPA process is quite straightforward.

The tutorial guides you through this. You can obtain the code referenced in this tutorial from
SourceForge (one of the files entitled "datanucleus-samples-jpa-tutorial-*").

Step 0 : Download DataNucleus AccessPlatform

You can download DataNucleus in many ways, but the simplest is to download the distribution
zip appropriate to your datastore (in this case Cassandra). You can do this from
SourceForge DataNucleus download page.
When you open the zip you will find DataNucleus jars in the lib directory, and
dependency jars in the deps directory.

Step 1 : Take your model classes and mark which are persistable

For our tutorial, say we have the following classes representing a store of products for sale.

So we have a relationship (Inventory having a set of Products), and inheritance (Product-Book).
Now we need to be able to persist objects of all of these types, so we need to define persistence
for them. There are many things that you can define when deciding how to persist objects of a type
but the essential parts are

Mark the class as an Entity so it is visible to the persistence mechanism

Identify which field(s) represent the identity of the object.

So this is what we do now. Note that we could define persistence using XML metadata, annotations.
In this tutorial we will use annotations.

Note that we mark each class that can be persisted with @Entity
and their primary key field(s) with @Id In addition we defined a valueStrategy
for Product field id so that it will have its values generated automatically.
In this tutorial we are using application identity which means that all objects of
these classes will have their identity defined by the primary key field(s).
You can read more in
application identity when designing your systems
persistence.

Step 2 : Define the 'persistence-unit'

Writing your own classes to be persisted is the start point, but you now need to define which
objects of these classes are actually persisted. You do this via a file
META-INF/persistence.xml at the root of the CLASSPATH. Like this

Step 3 : Enhance your classes

DataNucleus relies on the classes that you want to persist be enhanced to implement the interface
Persistable. You could write your classes manually to do this but this would be
laborious. Alternatively you can use a post-processing step to compilation that "enhances" your
compiled classes, adding on the necessary extra methods to make them Persistable.
There are several ways to do this, most notably at post-compile, or at runtime. We use the
post-compile step in this tutorial. DataNucleus JPA provides its own byte-code enhancer for
instrumenting/enhancing your classes (in datanucleus-core) and this is included in the
DataNucleus AccessPlatform zip file prerequisite.

To understand on how to invoke the enhancer you need to visualise where the various files are stored

This command enhances all class files specified in the persistence-unit "Tutorial".
If you accidentally omitted this step, at the point of running your application and
trying to persist an object, you would get a ClassNotPersistableException
thrown. The use of the enhancer is documented in more detail in the
Enhancer Guide. The output of this step are a set of
class files that represent persistable classes.

Step 4 : Write the code to persist objects of your classes

Writing your own classes to be persisted is the start point, but you now need to define which
objects of these classes are actually persisted, and when. Interaction with the persistence
framework of JPA is performed via an EntityManager. This provides methods for persisting of
objects, removal of objects, querying for persisted objects, etc. This section gives examples of
typical scenarios encountered in an application.

The initial step is to obtain access to an EntityManager, which you do as follows

Please note that the finally step is important in that it tidies up connections to
the datastore and the EntityManager.

Now we want to retrieve some objects from persistent storage, so we will use a "Query".
In our case we want access to all Product objects that have a price below 150.00 and
ordering them in ascending order.

After that it is simply a question of starting your application and all should be taken care of.
You can access the DataNucleus Log file by specifying the
logging configuration properties, and any messages from
DataNucleus will be output in the normal way. The DataNucleus log is a very powerful way of finding
problems since it can list all SQL actually sent to the datastore as well as many other
parts of the persistence process.

Part 2 : Next steps

In the above simple tutorial we showed how to employ JPA and persist objects to a Cassandra database.
Obviously this just scratches the surface of what you can do, and to use JPA requires minimal
work from the user. In this second part we show some further things that you are likely to want to do.

Step 7 : Generate the database tables where your classes are to be persisted
using SchemaTool.

Step 6 : Controlling the schema

In the above simple tutorial we didn't look at controlling the schema generated for these classes.
Now let's pay more attention to this part by defining XML Metadata for the schema. We define this
in XML to separate schema information from persistence information. So we define a file orm.xml

This file should be placed at the root of the CLASSPATH under META-INF.

Step 7 : Generate any schema required for your domain classes

This step is optional, depending on whether you have an existing database schema. If you haven't,
at this point you can use the DataNucleus SchemaTool to
generate the tables where these domain objects will be persisted. DataNucleus SchemaTool is a
command line utility (it can be invoked from Maven/Ant in a similar way to how the Enhancer
is invoked). The first thing that you need is to update the
src/java/META-INF/persistence.xml file with your database details.
Here we have a sample file (for HSQLDB) that contains

This will generate the required tables, indexes, and foreign keys for the classes defined in
the annotations and orm.xml Meta-Data file.

Any questions?

If you have any questions about this tutorial and how to develop applications for use with
DataNucleus please read the online documentation since answers are to be found there.
If you don't find what you're looking for go to our
Forums.