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.
This page covers the following topics:
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 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.
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.