Obtaining a JPA Database Connection

In JPA a database connection is represented by the EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page... interface. Therefore, in order to manipulate an ObjectDB database we need an EntityManager instance. Operations that modify database content also require an EntityTransactionjavax.persistence.EntityTransactionJPA interfaceInterface used to control transactions on resource-local entity managers.See JavaDoc Reference Page... instance.

Obtaining an EntityManagerFactory

Obtaining an EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page... instance consists of two steps. First we need to obtain an instance of EntityManagerFactoryjavax.persistence.EntityManagerFactoryJPA interfaceInterface used to interact with the entity manager factory for the persistence unit.See JavaDoc Reference Page... that represents the relevant database and then we can use that factory instance to get an EntityManager instance.

JPA requires the definition of a persistence unit in an XML file in order to be able to generate an EntityManagerFactory. But when using ObjectDB you can either define a standard persistence unit in an XML file or you can simply provide the file path of the ObjectDB database instead:

  EntityManagerFactoryjavax.persistence.EntityManagerFactoryJPA interfaceInterface used to interact with the entity manager factory
 for the persistence unit.See JavaDoc Reference Page... emf =
     Persistencejavax.persistence.PersistenceJPA classBootstrap class that is used to obtain an EntityManagerFactory
 in Java SE environments.See JavaDoc Reference Page....createEntityManagerFactorycreateEntityManagerFactory(persistenceUnitName)Persistence's static methodCreate and return an EntityManagerFactory for the named
 persistence unit.See JavaDoc Reference Page...(
          "objectdb:$objectdb/db/points.odb");

The createEntityManagerFactorycreateEntityManagerFactory(persistenceUnitName)Persistence's static methodCreate and return an EntityManagerFactory for the named persistence unit.See JavaDoc Reference Page... static method expects a persistence unit name as an argument, but when using ObjectDB, any valid database file path (absolute or relative) is also accepted. Any string that starts with the prefix objectdb: or ends with .odb or .objectdb is considered by ObjectDB to be a database URL rather than a persistence unit name.
The $objectdb variable represents the ObjectDB home directory (by default - the directory in which ObjectDB is installed). If no database file exists yet at the given path ObjectDB will try to create one.

The EntityManagerFactory is also used to close the database once we are finished using it:

  emf.closeclose()EntityManagerFactory's methodClose the factory, releasing any resources that it holds.See JavaDoc Reference Page...();

Obtaining an EntityManager

Once we have an EntityManagerFactoryjavax.persistence.EntityManagerFactoryJPA interfaceInterface used to interact with the entity manager factory for the persistence unit.See JavaDoc Reference Page... we can easily obtain an EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page... instance:

  EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page... em = emf.createEntityManagercreateEntityManager()EntityManagerFactory's methodCreate a new application-managed EntityManager.See JavaDoc Reference Page...();

The EntityManager instance represents a connection to the database. When using JPA, every operation on a database is associated with an EntityManager. Further, in a multithreaded application every thread usually has its own EntityManager instance while at the same time sharing a single application-wide EntityManagerFactory.

When the connection to the database is no longer needed the EntityManager can be closed:

  em.closeclose()EntityManager's methodClose an application-managed entity manager.See JavaDoc Reference Page...();

Closing an EntityManager does not close the database itself (that is the job of the factory as previously explained). Once the EntityManager object is closed it cannot be reused. However, the owning EntityManagerFactory instance may preserve the EntityManager's resources (such as a database file pointer or a socket to a remote server) in a connection pool and use them to speed up future EntityManager construction.

Using an EntityTransaction

Operations that modify database content, such as store, update, and delete should only be performed within an active transaction.

Given an EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page..., em, it is very easy to begin a transaction:

  em.getTransactiongetTransaction()EntityManager's methodReturn the resource-level EntityTransaction object.See JavaDoc Reference Page...().beginbegin()EntityTransaction's methodStart a resource transaction.See JavaDoc Reference Page...();

There is a one to one relationship between an EntityManager instance and its associated EntityTransactionjavax.persistence.EntityTransactionJPA interfaceInterface used to control transactions on resource-local entity managers.See JavaDoc Reference Page... instances that the getTransactiongetTransaction()EntityManager's methodReturn the resource-level EntityTransaction object.See JavaDoc Reference Page... method returns.

When a transaction is active you can invoke EntityManager methods that modify the database content, such as persistpersist(entity)EntityManager's methodMake an instance managed and persistent.See JavaDoc Reference Page... and removeremove(entity)EntityManager's methodRemove the entity instance.See JavaDoc Reference Page.... Database updates are collected and managed in memory and applied to the database when the transaction is committed:

  em.getTransactiongetTransaction()EntityManager's methodReturn the resource-level EntityTransaction object.See JavaDoc Reference Page...().commitcommit()EntityTransaction's methodCommit the current resource transaction, writing any 
 unflushed changes to the database.See JavaDoc Reference Page...();

The next section explains in more detail how to use the EntityManager and transactions for CRUD database operations.