JPA Connections and Transactions

Working with the Java Persistence API (JPA) consists of using the following interfaces:

This page covers the following topics:

Overview EntityManagerFactory EntityManager EntityTransaction

Overview

A connection to a database is represented by an EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. instance, which also provides methods for performing database operations. Many applications require multiple database connections during their lifetime. For example, in a web application, it is common to establish a separate database connection by using a separate EntityManager instance for each HTTP request.

The main role of an EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of EntityManager . instance is to create EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. instances. An EntityManagerFactory is constructed for a specific database. It manages resources efficiently (for example, a pool of sockets) and provides an efficient way to create multiple EntityManager instances for that database. The instantiation of the EntityManagerFactory itself might be less efficient, but it is a one-time operation. Once constructed, it can serve the entire application.

Operations that modify the database require active transactions. Transactions are managed by an EntityTransactionjakarta.persistence.EntityTransactionInterface used to control transactions on resource-local entity managers. instance, which is obtained from the EntityManager.

An EntityManager instance also functions as a factory for Queryjakarta.persistence.QueryInterface used to control query execution. instances, which are used to execute database queries.

Every JPA implementation provides classes that implement these interfaces. When you use ObjectDB, you work with instances of its implementation classes. Because your application uses the standard JPA interfaces, it remains portable across different JPA providers.

EntityManagerFactory

An EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of EntityManager .instance is obtained by using a static factory method of the JPA bootstrap class, Persistencejakarta.persistence.PersistenceBootstrap class used to obtain an EntityManagerFactory in Java SE environments.:

  EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of   EntityManager  . emf =
      Persistencejakarta.persistence.PersistenceBootstrap class used to obtain an   EntityManagerFactory   in Java SE environments..createEntityManagerFactoryjakarta.persistence.Persistence.createEntityManagerFactory(String)Create and return an   EntityManagerFactory   for the named persistence unit.("objectdb:myDbFile.odb");

Another form of the createEntityManagerFactoryjakarta.persistence.Persistence.createEntityManagerFactory(String,Map)Create and return an EntityManagerFactory for the named persistence unit, using the given properties. method takes a map of persistence unit properties as a second parameter:

  Map<String, String> properties = new HashMap<String, String>();
  properties.put("jakarta.persistence.jdbc.user", "admin");
  properties.put("jakarta.persistence.jdbc.password", "admin");
  EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of   EntityManager  . emf = Persistencejakarta.persistence.PersistenceBootstrap class used to obtain an   EntityManagerFactory   in Java SE environments..createEntityManagerFactoryjakarta.persistence.Persistence.createEntityManagerFactory(String,Map)Create and return an   EntityManagerFactory   for the named persistence unit, using the given properties.(
      "objectdb://localhost:6136/myDbFile.odb", properties);

When constructed, the EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of EntityManager . instance opens the database. If the database does not already exist, a new database file is created.

When the application is finished with the EntityManagerFactory, it must be closed:

  emf.closejakarta.persistence.EntityManagerFactory.close()Close the factory, releasing any resources that it holds.();

Closing the EntityManagerFactory closes the database file.

Connection URL

The createEntityManagerFactoryjakarta.persistence.Persistence.createEntityManagerFactory(String)Create and return an EntityManagerFactory for the named persistence unit. method takes a persistence unit name as an argument. As an extension, ObjectDB lets you specify a database URL or path directly, bypassing the need for an explicit persistence unit definition. ObjectDB considers any string that starts with objectdb: or ends with .odb or .objectdb to be a database URL rather than a persistence unit name.

To use ObjectDB embedded directly in your application (embedded mode), you must specify an absolute or relative path to a local database file (for example, "my.odb"). The objectdb: protocol prefix is optional if the database file name extension is .odb or .objectdb. However, the prefix is required for other file name extensions (for example, "objectdb:my-db.tmp").

To use client-server mode, specify a URL in the format objectdb://host:port/path.
In this case, an ObjectDB Database Server must be running on a computer named host (which can be a domain name or an IP address) and listening on the specified port. The default port is 6136. The path indicates the location of the database file on the server, relative to the server data root path.

Connection URL Parameters

The following parameters are supported as part of an ObjectDB connection URL:

user: Specifies a username in client-server mode.
password: Specifies a user password in client-server mode.
drop: Deletes any existing database content. This parameter is useful for tests.

To connect to an ObjectDB server registered username and password must be specified:

  EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of   EntityManager  . emf = Persistencejakarta.persistence.PersistenceBootstrap class used to obtain an   EntityManagerFactory   in Java SE environments..createEntityManagerFactoryjakarta.persistence.Persistence.createEntityManagerFactory(String)Create and return an   EntityManagerFactory   for the named persistence unit.(
      "objectdb://localhost/myDbFile.odb;user=admin;password=admin");

This is equivalent to specifying a username and a password in the persistence unit or in a map of properties (as demonstrated above).

To connect to an empty database and discard any existing content, specify the drop parameter:

  EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of   EntityManager  . emf =
      Persistencejakarta.persistence.PersistenceBootstrap class used to obtain an   EntityManagerFactory   in Java SE environments..createEntityManagerFactoryjakarta.persistence.Persistence.createEntityManagerFactory(String)Create and return an   EntityManagerFactory   for the named persistence unit.("objectdb:myDbFile.tmp;drop");

This feature is useful for tests because it provides a simple way to get an empty database. However, to avoid accidental data loss, the drop parameter is ignored unless the database file name extension indicates a temporary database. By default, the .tmp and .temp file name extensions represent temporary databases that can be dropped, but this behavior can be configured.

EntityManager

An EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. instance can represent either a connection to a remote database server (in client-server mode) or a connection to a local database file (in embedded mode). The functionality is the same in both cases. Given an EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of EntityManager . instance named emf, a short-term connection to the database might have the following form:

  EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. em = emf.createEntityManagerjakarta.persistence.EntityManagerFactory.createEntityManager()Create a new application-managed   EntityManager  .();
  try {
      // TODO: Use the EntityManager to access the database
  }
  finally {
      em.closejakarta.persistence.EntityManager.close()Close an application-managed entity manager.();
  }

The EntityManager instance is obtained from the EntityManagerFactory. Calling the closejakarta.persistence.EntityManager.close()Close an application-managed entity manager. method is essential to release resources (such as a socket in client-server mode) back to the EntityManagerFactory.

EntityManagerFactory also defines a createEntityManager method that takes a map of properties as an argument. This form is useful when you need to specify a username and password that are different from the EntityManagerFactory's default credentials:

  Map<String, String> properties = new HashMap<String, String>();
  properties.put("jakarta.persistence.jdbc.user", "user1");
  properties.put("jakarta.persistence.jdbc.password", "user1pwd");
  EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. em = emf.createEntityManagerjakarta.persistence.EntityManagerFactory.createEntityManager(Map)Create a new application-managed   EntityManager   with the given   Map<K,V>   specifying property settings.(properties);

EntityTransaction

Operations that modify the database (such as storing, updating, or deleting data) must be performed within an active transaction. The EntityTransactionjakarta.persistence.EntityTransactionInterface used to control transactions on resource-local entity managers. interface represents and manages database transactions. Each EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. has an associated EntityTransaction instance that is available through the getTransactionjakarta.persistence.EntityManager.getTransaction()Return the resource-level EntityTransaction object. method:

  try {
      em.getTransactionjakarta.persistence.EntityManager.getTransaction()Return the resource-level   EntityTransaction   object.().beginjakarta.persistence.EntityTransaction.begin()Start a resource transaction.();
      // Operations that modify the database should come here.
      em.getTransactionjakarta.persistence.EntityManager.getTransaction()Return the resource-level   EntityTransaction   object.().commitjakarta.persistence.EntityTransaction.commit()Commit the current resource transaction, writing any unflushed changes to the database.();
  }
  finally {
      if (em.getTransactionjakarta.persistence.EntityManager.getTransaction()Return the resource-level   EntityTransaction   object.().isActivejakarta.persistence.EntityTransaction.isActive()Indicate whether a resource transaction is in progress.())
          em.getTransactionjakarta.persistence.EntityManager.getTransaction()Return the resource-level   EntityTransaction   object.().rollbackjakarta.persistence.EntityTransaction.rollback()Roll back the current resource transaction.();
  }

A transaction is started by calling beginjakarta.persistence.EntityTransaction.begin()Start a resource transaction. and completed by calling either commitjakarta.persistence.EntityTransaction.commit()Commit the current resource transaction, writing any unflushed changes to the database. or rollbackjakarta.persistence.EntityTransaction.rollback()Roll back the current resource transaction.. All database operations between these calls are part of the transaction and are considered temporary until the transaction is completed. If the transaction is rolled back, all modifications to the database are discarded. However, by default, a rollback does not affect the in-memory state of managed entities or revert them to their pre-modified state.

Committing a transaction propagates all modifications to the database. If a commit fails for any reason, the transaction is automatically rolled back. This rollback includes any modifications that were propagated to the database before the failure. A RollbackExceptionjakarta.persistence.RollbackExceptionThrown by the persistence provider when EntityTransaction.commit fails. is then thrown.

< Using JPA ^ Using JPA Managing Entities >