dn accessplatform overview

There are two standard API’s for persistence in Java - Java Data Objects (JDO) and Java Persistence API (JPA). DataNucleus v5.1 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.1 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!

Contributing

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

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

Dependencies

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

JDO API definition, provided by DataNucleus

3.2

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

JPA API definition, provided by DataNucleus

2.2*

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

3.5+

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

ODFDOM

ODF Toolkit for Java

0.8.7

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

Apache HBase

hbase-client

1.1+

Required if you want to persist to HBase datastores

MongoDB Java driver

MongoDB Java driver

3.1+

Required if you want to persist to MongoDB datastores.

Cassandra Datastax Java driver

Cassandra Datastax driver

3.0

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

Neo4j driver

Neo4j driver

2.3+

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

jaxb-api

JAXB API

2.1

Required if you are using an XML datastore

jaxb-impl

JAXB Reference Implementation

2.x

Required if you are using an XML datastore

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

Log4j

Log4J logging library.

1.2+

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

VividSolutions JTS

JTS

1.12

Required if you want to persist JTS geospatial types

JodaTime

JodaTime

2.0+

Required if you want to persist JodaTime java types

Google Guava

Google Guava

1.0

Required if you want to persist Google Guava java types

Google Collections

GoogleCollections

1.0

Required if you want to use BoneCP connection pool for RDBMS

EHCache

EHCache caching product

1.0+

Required if you want to use EHCache for level 2 caching

OSCache

OSCache caching product

2.1

Required if you want to use OSCache for level 2 caching

C3P0

C3P0 RDBMS connection pooling library

0.9.0+

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

proxool

Proxool RDBMS connection pooling library

0.9.0RC3

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

commons-logging

Apache commons logging library

1.0+

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

bonecp

BoneCP RDBMS connection pooling library

0.6.5

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

SLF4J

SLF4J logging library

1.5.6

Required if you are using BoneCP for connection pooling

sdoapi

Oracle Spatial library

11.2+

Required if you want to persist Oracle geospatial types

mx4j

MX4J management library

3.0+

Required if you want to use JMX with DataNucleus via MX4J

mx4j-tools

MX4J tools

1.2+

Required if you want to use JMX with DataNucleus via MX4J

jta

JTA transaction API

1.0+

Required if you want to use JTA transactions

cache-api

Cache API

1.0+

Required if you want to use javax.cache L2 caching

validation-api

Bean validation API

1.0+

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