[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):

datanucleus.storeManagerType=cumulus4j
cumulus4j.cryptoManagerID=dummy

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:

cumulus4j.index.clob.enabled=false

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:

cumulus4j.cryptoManagerID=keyManager

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.