JDO Metadata Overview

JDO requires the persistence of classes to be defined via Metadata. This Metadata can be provided in the following forms

  • XML : the traditional mechanism, with XML files containing information for each class to be persisted. As a further complication you can define basic persistence metadata for a class in one file, and then ORM metadata for that class in a separate file (since the ORM metadata is specific to a certain datastore).
  • Annotations : using JDK1.5+ annotations in the classes to be persisted
  • API : a programmatic API allowing definition of which classes are to be persisted at runtime
When not using the MetaData API we recommend that you use either XML or annotations for the basic persistence information, but always use XML for ORM information. This is because it is liable to change at deployment time and hence is accessible when in XML form whereas in annotations you add an extra compile cycle (and also you may need to deploy to some other datastore at some point, hence needing a different deployment).
Metadata priority

JDO defines the priority order for metadata as being

  • API Metadata
  • ORM XML Metadata
  • JDO XML Metadata
  • Annotations

So if a class has Metadata defined by API then that will override all other Metadata. If a class has annotations and JDO XML Metadata then the XML Metadata will take precedence over the annotations (or rather be merged on top of the annotations).



XML Metadata loading

JDO expects the XML Meta-Data to be specified in a file or files in particular locations in the file system. For example, if you have a class com.mycompany.sample.myexample , JDO will look for any of the following files until it finds one (in the order stated) :- 

META-INF/package.jdo
WEB-INF/package.jdo
package.jdo
com/package.jdo
com/mycompany/package.jdo
com/mycompany/sample/package.jdo
com/mycompany/sample/myexample.jdo

In addition, for this example, DataNucleus allows the previous JDO 1.0.0 alternatives of 

com.jdo
com/mycompany.jdo
com/mycompany/sample.jdo

In addition to the above, you can split your MetaData definitions between JDO MetaData files. For example if you have the following classes 

com/mycompany/A.java
com/mycompany/B.java
com/mycompany/C.java
com/mycompany/app1/D.java
com/mycompany/app1/E.java

You could define the MetaData for these 5 classes in many ways -- for example put all class definitions in com/mycompany/package.jdo , or put the definitions for D and E in com/mycompany/app1/package.jdo and the definitions for A, B, C in com/mycompany/package.jdo , or have some in their class named MetaData files e.g com/mycompany/app1/A.jdo , or a mixture of the above. DataNucleus will always search for the MetaData file containing the class definition for the class that it requires.



XML Metadata validation

By default any XML Metadata will be validated for accuracy when loading it. Obviously XML is defined by a DTD or XSD schema and so should follow that. You can turn off such validations by setting the persistence property datanucleus.metadata.validate to false when creating your PMF. Note that this only turns off the XML strictness validation, and not the checks on inconsistency of specification of relations etc.



XML ORM Metadata usage

You can use ORM metadata to override particular datastore-specific things like table and column names. If your application doesn't make use of ORM metadata then you could turn off the searches for ORM Metadata files when a class is loaded up. You do this with the persistence property datanucleus.metadata.supportORM setting it to false.



Metadata discovery at class initialisation

JDO provides a mechanism whereby when a class is initialised (by the ClassLoader) any PersistenceManagerFactory is notified of its existence, and its Metadata can be loaded. This is enabled by the enhancement process. If you decided that you maybe only wanted some classes present in one PMF and other classes present in a different PMF then you can disable this and leave it to DataNucleus to discover the Metadata when operations are performed on that PMF. The persistence property to define to disable this is datanucleus.metadata.autoregistration (setting it to false).