JPA Persistence Unit

A JPA Persistence Unit is a logical grouping of user defined persistable classes (entity classes, embeddable classes and mapped superclasses) with related settings. Defining a persistence unit is optional when using ObjectDB, but required by JPA.

persistence.xml

Persistence units are defined in a persistence.xml file, which has to be located in the META-INF directory in the classpath. One persistence.xml file can include definitions for one or more persistence units. The portable way to instantiate an EntityManagerFactoryclose()EntityManagerFactory's methodClose the factory, releasing any resources that it holds.See JavaDoc Reference Page... in JPA (as explained in the JPA Overview section) requires a persistence unit.

The following persistence.xml file defines one persistence unit:

<?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">

   <persistence-unit name="my-pu">
     <description>My Persistence Unit</description>
     <provider>com.objectdb.jpa.Provider</provider>
     <mapping-file>META-INF/mappingFile.xml</mapping-file>
     <jar-file>packedEntity.jar</jar-file>
     <class>sample.MyEntity1</class>
     <class>sample.MyEntity2</class>
     <properties>
       <property name="javax.persistence.jdbc.url"
                 value="objectdb://localhost/my.odb"/>
       <property name="javax.persistence.jdbc.user" value="admin"/>
       <property name="javax.persistence.jdbc.password" value="admin"/>
     </properties>
   </persistence-unit>

</persistence>

A persistence unit is defined by a persistence-unit XML element. The required name attribute (“my-pu” in the example) identifies the persistence unit when instantiating an EntityManagerFactoryclose()EntityManagerFactory's methodClose the factory, releasing any resources that it holds.See JavaDoc Reference Page.... It may also have optional sub elements:

• The provider element indicates which JPA implementation should be used. ObjectDB is represented by the com.objectdb.jpa.Provider string. If not specified, the first JPA implementation that is found is used.
• The mapping-file elements specify XML mapping files that are added to the default META-INF/orm.xml mapping file. Every annotation that is described in this manual can be replaced by equivalent XML in the mapping files (as explained below).
• The jar-file elements specify JAR files that should be searched for managed persistable classes.
• The class elements specify names of managed persistable classes (see below).
• The property elements specify general properties. JPA 2 defines standard properties for specifying database url, username and password, as demonstrated above.

XML Mapping Metadata

ObjectDB supports using XML metadata as an alternative to annotations. Both JPA mapping files and JDO package.jdo files are supported. This manual focuses on using annotations which are more common and usually more convenient. Details on using XML metadata can be found in the JPA and JDO specifications and books.

Managed Persistable Classes

JPA requires registration of all the user defined persistable classes (entity classes, embeddable classes and mapped superclasses), which are referred to by JPA as managed classes, as part of a persistence unit definition.

Classes that are mentioned in mapping files as well as annotated classes in the JAR that contains the persistence.xml file (if it is packed) are registered automatically. If the application is not packed in a JAR yet, ObjectDB (as an extension) automatically registers classes under the classpath root directory that contains the META-INF/persistence.xml file. Other classes have to be registered explicitly by using class elements (for single class registration) or jar-file elements (for registration of all the classes in the jar file).

ObjectDB does not enforce registration of all the managed classes. However, it might be useful to register classes that define generators and named queries (by annotations). Otherwise, the generators and named queries are available only when the containing classes become known to ObjectDB, for example when a first instance of the class is stored in the database.