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.
JPA References |
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
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.
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 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.
Software | Description | Version | Requirement |
---|---|---|---|
JDO API definition, provided by DataNucleus |
3.2 |
Required if you are using the JDO API or JDO Annotations. Note that this uses our own developed JDO API, including full Apache JDO 3.2 plus some DataNucleus extensions. You can use the official Apache JDO API jar if you so wish. |
|
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 full JPA 2.2 as well as some vendor extensions. You can use the official JPA API jar if you so wish. |
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 library for writing to Microsoft documents |
3.5+ |
Required if you want to use Excel (XLS/OOXML) documents |
|
ODF Toolkit for Java |
0.8.7 |
Required if you want to use an ODF document for persistence. |
|
hbase-client |
1.1+ |
Required if you want to persist to HBase datastores |
|
MongoDB Java driver |
3.1+ |
Required if you want to persist to MongoDB datastores. |
|
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 |
2.3+ |
Required if you want to persist to Neo4j datastores. Tested against v3.0/v3.1 also. |
|
JAXB API |
2.1 |
Required if you are using an XML datastore |
|
JAXB Reference Implementation |
2.x |
Required if you are using an XML datastore |
Software | Description | Version | Requirement |
---|---|---|---|
Log4J logging library. |
1.2+ |
Required if you wish to log using Log4J. DataNucleus supports Log4J or JRE logging |
|
JTS |
1.12 |
Required if you want to persist JTS geospatial types |
|
JodaTime |
2.0+ |
Required if you want to persist JodaTime java types |
|
Google Guava |
1.0 |
Required if you want to persist Google Guava java types |
|
GoogleCollections |
1.0 |
Required if you want to use BoneCP connection pool for RDBMS |
|
EHCache caching product |
1.0+ |
Required if you want to use EHCache for level 2 caching |
|
OSCache caching product |
2.1 |
Required if you want to use OSCache for level 2 caching |
|
C3P0 RDBMS connection pooling library |
0.9.0+ |
Required if you are using an RDBMS datastore and want to use C3P0 for connection pooling |
|
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 logging library |
1.5.6 |
Required if you are using BoneCP for connection pooling |
|
Oracle Spatial library |
11.2+ |
Required if you want to persist Oracle geospatial types |
|
MX4J management library |
3.0+ |
Required if you want to use JMX with DataNucleus via MX4J |
|
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) |