JDO : ORM Meta-Data

JDO defines that MetaData (defined in the MetaData guide) can be found in particular locations in the CLASSPATH, and has a particular format. It also defines that you can split your MetaData for Object Relational Mapping (ORM) into separate files if you so wish. So you would define your basic persistence in a file "package.jdo" and then define the MetaData files "package-mysql.orm" (for MySQL), and "package-oracle.orm" (for Oracle). To make use of this JDO 2 Object-Relational Mapping file separation, you must specify the PersistenceManagerFactory property datanucleus.Mapping. If you set this to, for example, mysql DataNucleus would look for files such as package.jdo and package-mysql.orm in the same locations as specified above.

Simple Example

Let us take a sample class and generate MetaData for it. Suppose I have a class as follows

package mydomain;

public class Person
{
    /** Title of the Person. */
    String title=null;

    /** Forename of the Person. */
    String forename=null;

    /** Surname of the Person. */
    String surname=null;

    ...
}

and I want to use an existing schema. With this case I need to define the table and column names that it maps to. To do this I need to use JDO 2 ORM tags. So I come up with MetaData as follows in package.jdo

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jdo PUBLIC
    "-//Sun Microsystems, Inc.//DTD Java Data Objects Metadata 2.0//EN"
    "http://java.sun.com/dtd/jdo_2_0.dtd">
<jdo>
    <package name="mydomain">
        <class name="Person" identity-type="datastore">
            <field name="title"/>
            <field name="forename"/>
            <field name="surname"/>
        </class>
    </package>
</jdo>

and then I add the ORM information in package-mysql.orm as

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE orm PUBLIC
    "-//Sun Microsystems, Inc.//DTD Java Data Objects Mapping Metadata 2.0//EN"
    "http://java.sun.com/dtd/jdo_orm_2_0.dtd">
<orm>
    <package name="mydomain">
        <class name="Person" table="PERSON">
            <field name="title">
                <column name="TITLE"/>
            </field>
            <field name="forename">
                <column name="FORENAME" length="100" jdbc-type="VARCHAR"/>
            </field>
            <field name="surname">
                <column name="SURNAME" length="100" jdbc-type="VARCHAR"/>
            </field>
        </class>
    </package>
</orm>

So you see that our class is being mapped across to a table "PERSON" in the datastore, with columns "TITLE", "FORENAME", "SURNAME". We have also specified that the upper size limit on the forename and surname fields is 100.

Memory utilisation

The XML files are parsed and populated to memory the first time a pesistent operation is executed over a persistent class (e.g. pm.makePersistent(object) ). If the persistent class has relationships to other persistent classes, the metadata for the classes in the relationships are loaded. In addition to the persistent class and classes in the relationships, all other classes / files that were encountered while searching for the persistent classes are loaded, plus their relationships.

In average, for each persistent class a 3kb of memory is used to hold metadata information. This value will vary according the amount of metadata declared. Although this value can be used as reference in earlier stages of development, you should verify if it corresponds to your persistent classes.

A general formula can be used (with caution) to estimate the amount of memory required:

Amount Required = (# of persistent classes) * 3KB