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. JPA1 and JDO2.1 introduce the 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 your application jar. This file will be used to define your persistence-units. 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_1_0.xsd" version="1.0">

    <!-- Online Store -->
    <persistence-unit name="OnlineStore">
        <provider>org.jpox.jpa.PersistenceProviderImpl</provider>
        <class>org.jpox.samples.metadata.store.Product</class>
        <class>org.jpox.samples.metadata.store.Book</class>
        <class>org.jpox.samples.metadata.store.CompactDisc</class>
        <class>org.jpox.samples.metadata.store.Customer</class>
        <class>org.jpox.samples.metadata.store.Supplier</class>
        <properties>
            <property name="javax.jdo.option.ConnectionDriverName" value="org.h2.Driver"/>
            <property name="javax.jdo.option.ConnectionURL" value="jdbc:h2:jpox"/>
            <property name="javax.jdo.option.ConnectionUserName" value="sa"/>
            <property name="javax.jdo.option.ConnectionPassword" value=""/>
        </properties>
    </persistence-unit>

    <!-- Accounting -->
    <persistence-unit name="Accounting">
        <provider>org.jpox.jpa.PersistenceProviderImpl</provider>
        <mapping-file>org/jpox/samples/metadata/accounts/orm.xml</mapping-file>
        <properties>
            <property name="javax.jdo.option.ConnectionDriverName" value="org.h2.Driver"/>
            <property name="javax.jdo.option.ConnectionURL" value="jdbc:h2:jpox"/>
            <property name="javax.jdo.option.ConnectionUserName" value="sa"/>
            <property name="javax.jdo.option.ConnectionPassword" value=""/>
        </properties>
    </persistence-unit>

</persistence>

In this example we have defined 2 persistence-units. 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-units in our persistence operations.

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

• provider - the JPA persistence provider to be used (if using with JPA). The JPA persistence "provider" for JPOX is org.jpox.jpa.PersistenceProviderImpl Not used by JDO
• jar-file - name of a JAR file to scan for annotated classes to include in this persistence-unit. This is not currently supported for finding package.jdo files when used with JDO
• mapping-file - name of an XML "mapping" file containing persistence information to be included in this persistence-unit (if you use orm.xml). When used with JDO this has to be a "JDO" mapping file (not "ORM")
• class - name of an annotated class to include in this persistence-unit
• properties - properties defining the persistence factory to be used.

Use with JPA1

JPA1 requires the "persistence-unit" name to be specified at runtime when creating the EntityManagerFactory, like this

EntityManagerFactory emf = Persistence.createEntityManagerFactory("MyPersistenceUnit");

Use with JDO2.1

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

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