datanucleus overview

There are two standard API’s for persistence in Java - Java Data Objects (JDO) and Java Persistence API (JPA). DataNucleus v5.2 supports both, fully, and also provides support for a REST API.

Are you migrating to this version from an older version? : if so, please read this first about how to upgrade

Documentation for all aspects of DataNucleus v5.2 support for the JDO and JPA APIs are shown below, including PDF downloads.

In addition to the JDO and JPA API support, we also provide a REST API Guide which approaches persistence from a different viewpoint.

The various aspects specific to datastores are covered in a Datastores Guide

Persistence API choice

When choosing the persistence API to use in your application you should bear the following factors in mind.

  • Target datastore : JDO is designed for all datastores, whereas JPA is just designed around RDBMS and explicitly uses RDBMS/SQL terminology. If using RDBMS then you have the choice. If using, for example, a NoSQL store then JDO makes much more sense, though we have made efforts to make DataNucleus JPA adaptable to non-RDBMS features

  • Datastore interoperability : are you likely to change your datastore type at some point in the future ? If so you likely ought to use JDO due to its design

  • Persistence API : both persistence APIs are very similar. JDO provides more options and control though for basic persistence and retrieval, and there are differences only in the methods

  • ORM : JDO has a more complete ORM definition, as shown on Apache JDO ORM Guide

  • Query API : do you need a flexible query language that is object-oriented and extensible ? JDOQL provides this and the implementation in DataNucleus allows extensions. JPQL is more closely aligned with RDBMS concepts and SQL. If you just want SQL then you can use either JDO or JPA since both provide this

  • Fetch Control : do you need full control of what is fetched, and when ? JDO provides Fetch Groups, whereas JPA now provides Entity Graphs (a subset of Fetch Groups). Use JDO if full fetch groups is an important factor for your design, otherwise either

  • Developer Experience : do your developers know a particular API already ? As mentioned the persistence API’s themselves are very similar, though the metadata definition is different. Remember that you can use JPA metadata with the JDO persistence API, and vice-versa. You are more likely to find developers with JPA experience.

Read more over at Apache JDO.

Development Process

With all APIs supported by DataNucleus the development process is as follows.

  • Develop your classes that are going to be involved in the persistence process as you would do normally. DataNucleus imposes little to no constraints on what you do in this respect.

  • Define the persistence mapping for your classes, using either JDO annotations, JDO XML metadata, JPA annotations or JPA XML metadata, or a mixture of these.

  • Set up your compile process to have a post-compile step that will invoke the DataNucleus enhancer to bytecode enhance your classes for use in persistence.

  • Develop your persistence and query code itself, that uses your persistable classes, and their involvement in the persistence process.

  • Run your application!


If you find something that DataNucleus Access Platform can’t handle you can always extend it using its extension mechanism for one of its defined interfaces. Just look for the nucleus extensionpoint icon.

We provide an Extension Points Guide describing the points where the DataNucleus codebase can be extended with ease.


This version of DataNucleus has dependencies on the following software. Clearly you only require these dependencies if you are using the particular datastore, or API that they are needed for. There is a ZIP download for DataNucleus that includes many of these.

Essential Dependencies
Software Description Version Requirement


JDO API definition, provided by DataNucleus


Required if you are using the JDO API or JDO Annotations. Since Apache JDO haven’t yet released any jar for this we provide our own milestone from the Apache JDO codebase


JPA API definition, provided by DataNucleus


Required if you are using the JPA API or JPA annotations. Note that this uses our own developed JPA API including all JPA 2.2 proposed improvements as well as some vendor extensions.

Datastore Dependencies (driver for your database)
Software Description Version Requirement

JDBC Driver

JDBC Driver for your chosen RDBMS

Required if you want to use an RDBMS datastore. Obtain from your RDBMS vendor

Apache POI

Apache library for writing to Microsoft documents


Required if you want to use Excel (XLS/OOXML) documents


ODF Toolkit for Java


Required if you want to use an ODF document for persistence.

Apache HBase



Required if you want to persist to HBase datastores

MongoDB Java driver

MongoDB Java driver


Required if you want to persist to MongoDB datastores.

Cassandra Datastax Java driver

Cassandra Datastax driver


Required if you want to persist to Cassandra datastores. May work on later releases but not tested by us.

Neo4j driver

Neo4j driver


Required if you want to persist to Neo4j datastores. Tested against v3.0/v3.1 also.




Required if you are using an XML datastore


JAXB Reference Implementation


Required if you are using an XML datastore

Feature Dependencies (optional depending on what you want to use)
Software Description Version Requirement


Log4J logging library.


Required if you wish to log using Log4J. DataNucleus supports Log4J or JRE logging

VividSolutions JTS



Required if you want to persist JTS geospatial types




Required if you want to persist JodaTime java types

Google Guava

Google Guava


Required if you want to persist Google Guava java types

Google Collections



Required if you want to use BoneCP connection pool for RDBMS


EHCache caching product


Required if you want to use EHCache for level 2 caching


OSCache caching product


Required if you want to use OSCache for level 2 caching


C3P0 RDBMS connection pooling library


Required if you are using an RDBMS datastore and want to use C3P0 for connection pooling


BoneCP RDBMS connection pooling library


Required if you are using an RDBMS datastore and want to use BoneCP for connection pooling


SLF4J logging library


Required if you are using BoneCP for connection pooling


Oracle Spatial library


Required if you want to persist Oracle geospatial types


MX4J management library


Required if you want to use JMX with DataNucleus via MX4J


MX4J tools


Required if you want to use JMX with DataNucleus via MX4J


JTA transaction API


Required if you want to use JTA transactions


Cache API


Required if you want to use javax.cache L2 caching


Bean validation API


Required if you want to use bean validation (you also require a bean validation implementation)