Managing JPA Entities

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

Managing an ObjectDB database with JPA requires using entities for many operations, including storing, retrieving, updating, and deleting database objects.

Entities life cycle

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

When an entity is first created, its state is New. In this state, the object is not yet associated with an EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. and has no representation in the database.

An entity becomes Managed when it is persisted to the database by using an EntityManager's persistjakarta.persistence.EntityManager.persist(Object)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 EntityManager.remove . method, which must be invoked within an active transaction. When the transaction is committed, the owning EntityManager stores the new entity in the database. The Storing Entities section provides more details about storing objects.

Entities that an EntityManager retrieves from the database are also in the Managed state. The Retrieving Entities section discusses object retrieval in more detail.

If a managed entity is modified within an active transaction, the owning EntityManager detects the change and propagates the update to the database when the transaction is committed. The Updating Entities section contains more information about making changes to entities.

A managed entity can be marked for deletion by using the EntityManager's removejakarta.persistence.EntityManager.remove(Object)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's state changes from Managed to Removed, and the object is physically deleted from the database when the transaction is committed. The Deleting Entities section provides more details about object deletion.

The last state, Detached, represents entities that have been disconnected from an EntityManager. For example, all the managed objects of an EntityManager become detached when the EntityManager is closed. The Detached Entities section discusses how to work with detached objects, including how to merge them back into an EntityManager.

Persistence context

The persistence context is the collection of all managed objects for a given EntityManager. If an entity that needs to be retrieved already exists in the persistence context, the existing managed entity is returned without accessing the database. An exception is retrieval by refreshjakarta.persistence.EntityManager.refresh(Object,LockModeType)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 lock mode ., which always requires database access.

The main role of the persistence context is to ensure that a database entity is represented by at most one in-memory entity within the same EntityManager. Every EntityManager manages its own persistence context. Therefore, a database object can be represented by different in-memory entities in different EntityManager instances. However, retrieving the same database object more than once by using the same EntityManager always results in the same in-memory object.

You can also think of the persistence context as a local cache for a given EntityManager. ObjectDB also manages a level 2 (L2) shared cache for the EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of EntityManager . and other caches, as explained in the Configuration chapter.

By default, managed entities that have not been modified or removed during a transaction are held in the persistence context by weak references. Therefore, when a managed entity 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 or soft references instead of weak references.

Use the contains method to check if a specified entity is in the persistence context:

    boolean isManaged = em.containsjakarta.persistence.EntityManager.contains(Object)Determine if the given object is a managed entity instance belonging to the current persistence context.(employee);

To clear the persistence context, use the clearjakarta.persistence.EntityManager.clear()Clear the persistence context, causing all managed entities to become detached. method:

    em.clearjakarta.persistence.EntityManager.clear()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 entities that have not been flushed to the database are discarded. The Detached Entities section discusses this subject in more detail.