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.
This page covers the following topics:
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.
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.Providerstring. 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.xmlmapping file. Every annotation that is described in this manual can be replaced by equivalent XML in the mapping files (as explained below).
jar-fileelements specify JAR files that should be searched for managed persistable classes.
classelements specify names of managed persistable classes (see below).
propertyelements 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.