JPA Persistence Unit

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

Programmatic configuration (PersistenceConfiguration)

Starting with JPA 3.2, it is no longer mandatory to use a persistence.xml file to define a persistence unit. You can now define a persistence unit entirely in Java code using the jakarta.persistence.PersistenceConfiguration interface. This is particularly useful for microservices, dynamic environments, or applications where configuration is managed by the environment rather than static files.

The following example demonstrates how to configure a persistence unit programmatically:

import jakarta.persistence.Persistence;
import jakarta.persistence.EntityManagerFactory;
import jakarta.persistence.PersistenceConfiguration;

// ...

// Create a programmatic configuration:
PersistenceConfiguration config = new PersistenceConfiguration("my-pu")
    .property("jakarta.persistence.jdbc.url", "objectdb://localhost/my.odb")
    .property("jakarta.persistence.jdbc.user", "admin")
    .property("jakarta.persistence.jdbc.password", "admin")
    .managedClass(sample.MyEntity1.class)
    .managedClass(sample.MyEntity2.class);

// Instantiate the EntityManagerFactory using the configuration object:
EntityManagerFactory emf = Persistence.createEntityManagerFactory(config);

• Define Managed Classes: Explicitly add entity classes using .managedClass().

• Set Properties: Pass database credentials and provider-specific settings.

• Avoid XML: Completely bypass the need for a META-INF/persistence.xml file on the classpath.

persistence.xml

Persistence units are defined in a persistence.xml file, which must be located in the META-INF directory on the classpath. A single persistence.xml file can define one or more persistence units. As explained in the JPA Overview section, a persistence unit is required to instantiate an EntityManagerFactoryjakarta.persistence.EntityManagerFactory.close()Close the factory, releasing any resources that it holds. in a portable way.

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="jakarta.persistence.jdbc.url"
                 value="objectdb://localhost/my.odb"/>
       <property name="jakarta.persistence.jdbc.user" value="admin"/>
       <property name="jakarta.persistence.jdbc.password" value="admin"/>
     </properties>
   </persistence-unit>
</persistence>

A persistence unit is defined by the persistence-unit XML element. The required name attribute (my-pu in the example) identifies the persistence unit when instantiating an EntityManagerFactoryjakarta.persistence.EntityManagerFactory.close()Close the factory, releasing any resources that it holds.. It can also have the following optional child elements:

• The provider element specifies which JPA implementation to use. ObjectDB is represented by the string com.objectdb.jpa.Provider. If this element is omitted, the first available JPA implementation is used.
• The mapping-file elements specify XML mapping files to add to the default META-INF/orm.xml mapping file. Every annotation described in this manual can be replaced with equivalent XML in the mapping files, as explained below.
• The jar-file elements specify JAR files to search for managed persistable classes.
• The class elements specify the names of managed persistable classes (see below).
• The property elements specify general properties. JPA defines standard properties for specifying the database URL, user name, and password, as demonstrated above.

XML mapping metadata

ObjectDB supports XML metadata as an alternative to annotations. This manual focuses on annotations, which are more common and usually more convenient. For details about using XML mapping files, see the JPA specification.

Managed persistable classes

JPA requires that you register all user-defined persistable classes (entity classes, embeddable classes, and mapped superclasses) as part of a persistence unit definition. JPA refers to these as managed classes.

Classes listed in mapping files, as well as annotated classes in the JAR file that contains the persistence.xml file, are registered automatically if the application is packaged as a JAR file. If the application is not packaged in a JAR file, ObjectDB (as an extension) automatically registers classes in the classpath root directory that contains the META-INF/persistence.xml file. Other classes must be registered explicitly using class elements (to register a single class) or jar-file elements (to register all classes in a JAR file).

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