When designing an application you can usually nicely separate your persistable objects into independent groupings that can be treated separately, perhaps within a different DAO object, if using DAOs. JDO uses the (JPA) idea of a persistence-unit . A persistence-unit provides a convenient way of specifying a set of metadata files, and classes, and jars that contain all classes to be persisted in a grouping. The persistence-unit is named, and the name is used for identifying it. Consequently this name can then be used when defining what classes are to be enhanced, for example.

To define a persistence-unit you first need to add a file persistence.xml to the META-INF/ directory of the CLASSPATH (this may mean WEB-INF/classes/META-INF when using a web-application). This file will be used to define your persistence-unit s. Let's show an example

<?xml version="1.0" encoding="UTF-8" ?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence 
        http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd" version="2.0">

    <!-- Online Store -->
    <persistence-unit name="OnlineStore">
        <class>org.datanucleus.samples.metadata.store.Product</class>
        <class>org.datanucleus.samples.metadata.store.Book</class>
        <class>org.datanucleus.samples.metadata.store.CompactDisc</class>
        <class>org.datanucleus.samples.metadata.store.Customer</class>
        <class>org.datanucleus.samples.metadata.store.Supplier</class>
        <exclude-unlisted-classes/>
        <properties>
            <property name="datanucleus.ConnectionDriverName" value="org.h2.Driver"/>
            <property name="datanucleus.ConnectionURL" value="jdbc:h2:datanucleus"/>
            <property name="datanucleus.ConnectionUserName" value="sa"/>
            <property name="datanucleus.ConnectionPassword" value=""/>
        </properties>
    </persistence-unit>

    <!-- Accounting -->
    <persistence-unit name="Accounting">
        <mapping-file>com/datanucleus/samples/metadata/accounts/package.jdo</mapping-file>
        <properties>
            <property name="datanucleus.ConnectionDriverName" value="org.h2.Driver"/>
            <property name="datanucleus.ConnectionURL" value="jdbc:h2:datanucleus"/>
            <property name="datanucleus.ConnectionUserName" value="sa"/>
            <property name="datanucleus.ConnectionPassword" value=""/>
        </properties>
    </persistence-unit>

</persistence>

In this example we have defined 2 persistence-unit s. The first has the name "OnlineStore" and contains 5 classes (annotated). The second has the name "Accounting" and contains a metadata file called "orm.xml" in a particular package (which will define the classes being part of that unit). This means that once we have defined this we can reference these persistence-unit s in our persistence operations. You can find the XSD for persistence.xml here.

There are several sub-elements of this persistence.xml file

• provider - Not used by JDO
• jta-data-source - JNDI name for JTA connections
• non-jta-data-source - JNDI name for non-JTA connections
• jar-file - name of a JAR file to scan for annotated classes to include in this persistence-unit.
• mapping-file - name of an XML "mapping" file containing persistence information to be included in this persistence-unit. This is the "JDO" mapping file ( not the ORM)
• class - name of an annotated class to include in this persistence-unit
• properties - properties defining the persistence factory to be used.

Use with JDO

JDO accepts the "persistence-unit" name to be specified at runtime when creating the PersistenceManagerFactory , like this

Properties props = new Properties();
props.put("datanucleus.PersistenceUnitName", "MyPersistenceUnit");
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory(props);

Dynamically generated Persistence-Unit

DataNucleus allows an extension to JDO to dynamically create persistence-units at runtime. Use the following code sample as a guide. Obviously any classes defined in the persistence-unit need to have been enhanced.

import org.datanucleus.metadata.PersistenceUnitMetaData;
import org.datanucleus.api.jdo.JDOPersistenceManagerFactory;
 
PersistenceUnitMetaData pumd = new PersistenceUnitMetaData("dynamic-unit", "RESOURCE_LOCAL", null);
pumd.addClassName("org.datanucleus.test.A");
pumd.setExcludeUnlistedClasses();
pumd.addProperty("javax.jdo.ConnectionDriverName", "org.hsqldb.jdbcDriver");
pumd.addProperty("javax.jdo.ConnectionURL", "jdbc:hsqldb:mem:nucleus");
pumd.addProperty("javax.jdo.ConnectionUserName", "sa");
pumd.addProperty("javax.jdo.ConnectionPassword", "");
pumd.addProperty("datanucleus.autoCreateSchema", "true");

PersistenceManagerFactory pmf = new JDOPersistenceManagerFactory(pumd, null);

It should be noted that if you call pumd.toString(); then this returns the text that would have been found in a persistence.xml file.