Home Documentation Forum Tracker Download

Getting started

Cumulus4j makes things as easy as possible. But combining a web server with object-oriented persistence and encryption cannot be simplified below a certain level of complexity.

Anyway, it's easier than you might think: You probably already know many components used, because Cumulus4j builds on top of standards and libraries/frameworks widely known in the field of Java software development.

This page aims at giving you a quick start into understanding and using Cumulus4j.

Understanding persistence

Cumulus4j is a plug-in for DataNucleus and is thus used via one of the standard persistence-APIs: JDO or JPA.

If you have no idea how to make use of JDO (or JPA), it is urgently recommended that you learn about these basics first. You might want to take a look at DataNucleus' Getting started guide or one of the many other tutorials in the web. JDO/JPA are much better than writing plain (error-prone) SQL [i.e. using JDBC], hence learning these basic technologies is a great idea, anyway - even if you don't use Cumulus4j ;-)

The author of this document recommends to start with JDO, because it is more mature, provides more features than JPA and is community-driven (i.e. really free). But it is up to you which API you use with Cumulus4j - DataNucleus (and therefore Cumulus4j) supports both.

Looking at example code

Cumulus4j is thoroughly tested by a multitude of different tests. In order to test its functionality, there are many examples simulating real-world-scenarios in various test-projects. Thus you might want to check out the sources and take a look at the following projects:

The two unit test projects contain the data models and test Cumulus4j without key management (they use a dummy key manager - Cumulus4j is pluggable and the key manager can be exchanged).

The integration tests set up scenarios that come very close to real-world-environments: They start web servers and communicate as remote-clients (using REST) with them.

Understanding the big picture

Cumulus4j is a plug-in for DataNucleus and is thus used via one of the standard persistence-APIs: JDO or JPA.

In order to encrypt or decrypt data, Cumulus4j needs keys which are stored separately from the actual database in a so-called key store.

Because managing keys is not covered by any persistence-standard, Cumulus4j provides its own API for the key management. However, this API is as slim and straight-forward as possible.

Cumulus4j can be used in different deployment scenarios and depending on your scenario, you have to employ different modules at different locations.

When data is queried/read from or written to the database, it is automatically decrypted or encrypted. For this purpose, the application server (or more precisely Cumulus4j's store-plug-in within DataNucleus within the application server) is granted access to the keys in the key store. The keys are only kept in memory and the access to the key store is only granted for the shortest time necessary. Take a look at this diagram about key management and service invocation to get a better understanding of the workflow.

Implementing your first Cumulus4j-protected application

To get your first Cumulus4j-protected application running, you should follow these steps:

[1] Create a simple plain JDO or JPA application.

Decide, which persistence-API you want to use: JDO or JPA?

Start with your data model. Write just one or two entity classes (aka persistence-capable classes) and persist some instances into the database of your choice. Then query them again. If you can read from the database what you have written into it, before, then you're on the right way. Don't continue before you achieved this goal - it makes no sense to add more complexity, before the basics are running well.

Note, that you must use DataNucleus - no other JDO/JPA-implementation is supported by Cumulus4j! Therefore, following DataNucleus' Getting started guide is a good idea.

If this guide isn't answering all your questions, do some more research in the web.

JDO/JPA are much better than writing plain (error-prone) SQL [i.e. using JDBC], hence learning these basic technologies is a great idea, anyway - even if you don't use Cumulus4j ;-)

[2] Enable Cumulus4j with the dummy key manager

If your plain-JDO/JPA-project is running smoothly, you should make sure the necessary libraries (i.e. org.cumulus4j.store and all its dependencies) are present in your classpath. If you're unsure what dependencies the module org.cumulus4j.store requires, consult its pom.xml. Even if you're new to Maven, the <dependencies> tag should be clear. Note, that the pom.xml can be found inside the JAR file (in META-INF/maven) - no need to obtain the source codes.

To enable Cumulus4j, you only need to add the following two persistence-properties (either in your properties file or in your persistence.xml or manually by code):


For now, we use the "dummy" key manager, which must not be used in a productive environment, because it provides no security at all! It encrypts/decrypts with a single hard-coded dummy key.

If you use Derby or any other database which is not capable of indexing (and querying) CLOBs, then you must add the following persistence-property, too:


There are many more persistence-properties to fine-tune the behaviour of both DataNucleus and Cumulus4j, but for the beginning, these are sufficient.

In your source code, you have to add one single line, before using a PersistenceManager or EntityManager:

// for JDO (pm is an instance of PersistenceManager)
pm.setProperty(CryptoSession.PROPERTY_CRYPTO_SESSION_ID, "dummyKeyStoreID_" + UUID.randomUUID() + '*' + UUID.randomUUID());

// for JPA (em is an instance of EntityManager)
em.setProperty(CryptoSession.PROPERTY_CRYPTO_SESSION_ID, "dummyKeyStoreID_" + UUID.randomUUID() + '*' + UUID.randomUUID()); 

The class CryptoSession is located in the package org.cumulus4j.store.crypto.

Make sure, you set the property to exactly this value! The crypto-session-id must be formatted in exactly this way!

You want to take a look at some example code? Check out org.cumulus4j.store.test, if you're using JDO, or org.cumulus4j.store.test.jpa, if you're using JPA.

[3] Move your code into a web application

Cumulus4j can be used inside a single JVM, but that is normally never the case (except for query tools like Vestigo). Usually, your database is located on a server computer and DataNucleus+Cumulus4j are operated in a full-blown JEE server (e.g. GlassFish, JBoss, ...) or a servlet container (e.g. Jetty, Tomcat, ...) on the same computer (or at least a server computer in the same data center).

Therefore, we cover only this one common case here: The so-called 2-computer-scenario.

The easiest way is - at least if you're using Maven - to convert your project into a war-project, put your backend (service) code into src/main/java and your client code into src/test/java. This way, you can simply start up the server (e.g. a Jetty) while running the client code as integration tests (=> Maven Failsafe plug-in). If you're not using Maven, you might want to create two separate projects - one for the backend (running in Jetty or Tomcat) and one for the frontend.

Need a cheat sheet? Take a look at org.cumulus4j.integrationtest.webapp! But note, that we're using a real key manager there, already (i.e. that's one step ahead) - and of course, we're using Maven.

[4] Enable the real key manager

The real key manager needs a real key store (actually one for each mandator, if your application should have multi-client capability). You can create a key-store (for your test) via code - once for every test-run. In a real-world-scenario, you'd probably either use our command-line-utility or integrate the key-store-creation somehow into your application.

Note, that you need additional libraries - check our module-location-matrix and maybe look into the pom.xml files, additionally.

In your client code, you should definitely use our key manager API! Don't be confused that our code in org.cumulus4j.integrationtest.webapp (class IntegrationWithAppServerOnlyTest) contains a low-level-test. After all, this is not only a demo project, but also an integration test. Only the method testTwoComputerScenarioWithUnifiedAPI() is interesting for you (not the low-level tests). What's happening under the hood of the official key manager API might change at any time without further notice!

Anyway, the API is much easier to use than the low-level-code. So, there's really no reason why you shouldn't use the API.

To actually enable the real key manager, you'll have to set the following property in your persistence-properties:


Note that in step [2], you have set this to "dummy". Wherever you have set it in step [2] (in a properties-file, the persistence.xml or in your code) - now, you must change it at the very same location to ensure the correct value is used.

Questions or problems?

If you have any questions not answered by the web site or encounter any problems which you cannot solve yourself, please don't hesitate to contact us!

Of course, we're also happy about positive feed-back or constructive criticism.

Note, that professional support and consulting services are available.

Project Documentation