Working with JPA Entity Objects

Entity objects are in-memory instances of entity classes (persistable user defined classes), which can represent physical objects in the database.

Managing an ObjectDB Object Database using JPA requires using entity objects for many operations, including storing, retrieving, updating and deleting database objects.

Entity Object Life Cycle

The life cycle of entity objects consists of four states: New, Managed, Removed and Detached.

When an entity object is initially created its state is New. In this state the object is not yet associated with an EntityManagerjakarta.persistence.EntityManager - JPA Interface Interface used to interact with the persistence context. and has no representation in the database.

An entity object becomes Managed when it is persisted to the database via an EntityManager’s persistEntityManager.persist(entity) - JPA Method Make a new entity instance managed and persistent, resulting in its insertion in the database when the persistence context is synchronized with the database, or make a removed entity managed, undoing the effect of a previous call to #remove(Object). method, which must be invoked within an active transaction. On transaction commit, the owning EntityManager stores the new entity object to the database. More details on storing objects are provided in the Storing Entities section.

Entity objects retrieved from the database by an EntityManager are also in the Managed state. Object retrieval is discussed in more detail in the Retrieving Entities section.

If a managed entity object is modified within an active transaction the change is detected by the owning EntityManager and the update is propagated to the database on transaction commit. See the Updating Entities section for more information about making changes to entities.

A managed entity object can also be retrieved from the database and marked for deletion, using the EntityManager’s removeEntityManager.remove(entity) - JPA Method Mark a managed entity instance as removed, resulting in its deletion from the database when the persistence context is synchronized with the database. method within an active transaction. The entity object changes its state from Managed to Removed, and is physically deleted from the database during commit. More details on object deletion are provided in the Deleting Entities section.

The last state, Detached, represents entity objects that have been disconnected from the EntityManager. For instance, all the managed objects of an EntityManager become detached when the EntityManager is closed. Working with detached objects, including merging them back to an EntityManager, is discussed in the Detached Entities section.

The Persistence Context

The persistence context is the collection of all the managed objects of an EntityManager. If an entity object that has to be retrieved already exists in the persistence context, the existing managed entity object is returned without actually accessing the database (except retrieval by refreshEntityManager.refresh(entity,lockMode) - JPA Method Refresh the state of the given managed entity instance from the database, overwriting unflushed changes made to the entity, if any, and obtain the given {@linkplain LockModeType lock mode}., which always requires accessing the database).

The main role of the persistence context is to make sure that a database entity object is represented by no more than one in-memory entity object within the same EntityManager. Every EntityManager manages its own persistence context. Therefore, a database object can be represented by different memory entity objects in different EntityManager instances. But retrieving the same database object more than once using the same EntityManager should always result in the same in-memory entity object.

Another way of looking at it is that the persistence context also functions as a local cache for a given EntityManager. ObjectDB also manages a level 2 shared cache for the EntityManagerFactoryjakarta.persistence.EntityManagerFactory - JPA Interface Interface used to interact with the persistence unit, and to create new instances of EntityManager. as well as other caches as explained in the Configuration chapter.

By default, managed entity objects that have not been modified or removed during a transaction are held in the persistence context by weak references. Therefore, when a managed entity object is no longer in use by the application the garbage collector can discard it and it is automatically removed from the persistence context. ObjectDB can be configured to use strong references or soft references instead of weak references.

The contains method can check if a specified entity object is in the persistence context:

    boolean isManaged = em.containsEntityManager.contains(entity) - JPA Method
 Determine if the given object is a managed entity instance
 belonging to the current persistence context.(employee);

The persistence context can be cleared by using the clearEntityManager.clear() - JPA Method Clear the persistence context, causing all managed entities to become detached. method:

    em.clearEntityManager.clear() - JPA Method
 Clear the persistence context, causing all managed entities to
 become detached.();

When the persistence context is cleared all of its managed entities become detached and any changes to entity objects that have not been flushed to the database are discarded. Detached entity objects are discussed in more detail in the Detached Entities section.