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. JPA introduces 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-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_1_0.xsd" version="1.0">

    <!-- Online Store -->
    <persistence-unit name="OnlineStore">
        <provider>org.datanucleus.jpa.PersistenceProviderImpl</provider>
        <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">
        <provider>org.datanucleus.jpa.PersistenceProviderImpl</provider>
        <mapping-file>com/datanucleus/samples/metadata/accounts/orm.xml</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.

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

• provider - the JPA persistence provider to be used. The JPA persistence "provider" for DataNucleus is org.datanucleus.jpa.PersistenceProviderImpl
• 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.
• class - name of an annotated class to include in this persistence-unit
• properties - properties defining the persistence factory to be used. Please refer to Persistence Properties Guide for details

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");

Restricting to specific classes

If you want to just have specific classes in the persistence-unit you can specify them using the class element, and then add exclude-unlisted-classes , like this

    <persistence-unit name="Store">
        <provider>org.datanucleus.jpa.PersistenceProviderImpl</provider>
        <class>org.datanucleus.samples.metadata.store.Product</class>
        <class>org.datanucleus.samples.metadata.store.Book</class>
        <class>org.datanucleus.samples.metadata.store.CompactDisc</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>

If you don't include the exclude-unlisted-classes then DataNucleus will search for annotated classes starting at the root of the persistence-unit (the root directory in the CLASSPATH that contains the "META-INF/persistence.xml" file).