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 EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page... and has no representation in the database.

An entity object becomes Managed when it is persisted to the database via an EntityManager’s persistpersist(entity)EntityManager's methodMake an instance managed and persistent.See JavaDoc Reference Page... persist(entity)EntityManager's methodMake an instance managed and persistent.See JavaDoc Reference Page...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 removeremove(entity)EntityManager's methodRemove the entity instance.See JavaDoc Reference Page... remove(entity)EntityManager's methodRemove the entity instance.See JavaDoc Reference Page...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 refreshrefresh(entity, lockMode)EntityManager's methodRefresh the state of the instance from the database, overwriting changes made to the entity, if any, and lock it with respect to given lock mode type.See JavaDoc Reference Page..., 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 EntityManagerFactoryjavax.persistence.EntityManagerFactoryJPA interfaceInterface used to interact with the entity manager factory for the persistence unit.See JavaDoc Reference Page... 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.containscontains(entity)EntityManager's methodCheck if the instance is a managed entity instance belonging
 to the current persistence context.See JavaDoc Reference Page...(employee);

The persistence context can be cleared by using the clearclear()EntityManager's methodClear the persistence context, causing all managed entities to become detached.See JavaDoc Reference Page... method:

    em.clearclear()EntityManager's methodClear the persistence context, causing all managed
 entities to become detached.See JavaDoc Reference Page...();

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.