JDO : Metadata Overview

JDO requires a definition of how to persist classes by way of Metadata. This Metadata can be provided in the following forms

So you can provide the metadata via annotations solely, or via annotations plus ORM XML Metadata overrides, or via JDO XML Metadata solely, or via JDO XML Metadata plus ORM XML Metadata overrides, or finally via a Metadata API. If you are using XML overrides for ORM, this definition will be merged in to the base definition (annotations or JDO XML Metadata). Note that you can utilise annotations for one class, and then JDO XML Metadata for another class should you so wish.

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).

JDO XML Metadata

JDO expects the XML metadata to be specified in a file or files in particular locations in the CLASSPATH. For example, if you have a class com.mycompany.sample.MyExample, JDO will look for any of the following resources 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 to the above, you can split your metadata definitions between JDO XML 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.


ORM XML Metadata

You can use ORM XML metadata to override particular datastore-specific things like table and column names. JDO expects any ORM XML metadata to be specified in a file or files in particular locations in the CLASSPATH. These filenames depend on the javax.jdo.option.mapping persistence property. For example, if you have a class com.mycompany.sample.MyExample, and the persistence property is set to "mysql" then JDO will look for any of the following resources until it finds one (in the order stated) :- 

META-INF/package-mysql.orm
WEB-INF/package-mysql.orm
package-mysql.orm
com/package-mysql.orm
com/mycompany/package-mysql.orm
com/mycompany/sample/package-mysql.orm
com/mycompany/sample/MyExample-mysql.orm

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.


XML Metadata validation

By default any XML Metadata (JDO or ORM) 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.xml.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.


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).