All Superinterfaces:: AutoCloseable, EntityHandler

public interface EntityAgent extends EntityHandler

Provides entity operations that are performed independently of a persistence context. This interface enables more direct control over interaction with the database than what is possible with EntityManager.

An instance of EntityAgent must be obtained from an EntityManagerFactory and is only able to manage persistence of entities belonging to the associated persistence unit. In the Jakarta EE environment, an entity agent with a lifecycle managed by the container may be obtained by dependency injection.

An EntityAgent obtained directly from an EntityManagerFactory is never thread safe, and it is always wrong to share a reference to such an entity agent between multiple concurrently executing threads.
On the other hand, in the Jakarta EE container environment, a reference to a container-managed, transaction-scoped entity agent obtained by injection is safe to invoke concurrently from distinct threads. The container redirects invocations to distinct instances of EntityAgent based on transaction affinity.

An EntityAgent has no associated persistence context, and works only with detached entity instances. When a method of this interface is called, any necessary interaction with the database happens immediately and synchronously. In particular, update is an explicit operation. Since there is no flush operation, and since the entities themselves are detached, modifications to the entities are never automatically detected and made persistent.

Since:

4.0

See Also:

Method Summary

Modifier and Type

Method

Description

void

delete(Object entity)

Delete a record.

void

deleteMultiple(List<?> entities)

Delete every record in the given list.

<T> T

fetch(T association)

Fetch an association or collection that was configured for lazy loading if it has not yet been fetched from the database.

void

insert(Object entity)

Insert a record.

void

insertMultiple(List<?> entities)

Insert every record in the given list.

void

refresh(Object entity)

Refresh the entity instance state from the database.

void

refresh(Object entity, LockModeType lockMode)

Refresh the entity instance state from the database.

void

refreshMultiple(List<?> entities)

Refresh multiple entities.

void

update(Object entity)

Update a record.

void

updateMultiple(List<?> entities)

Update every record in the given list.

void

upsert(Object entity)

Perform an upsert, that is, insert the record if it does not exist, or update it if it already exists.

void

upsertMultiple(List<?> entities)

Upsert every record in the given list.

Methods inherited from interface EntityHandler
callWithConnection, close, createEntityGraph, createNamedQuery, createNamedQuery, createNamedStatement, createNamedStoredProcedureQuery, createNativeQuery, createNativeQuery, createNativeQuery, createNativeQuery, createNativeStatement, createQuery, createQuery, createQuery, createQuery, createQuery, createQuery, createStatement, createStatement, createStatement, createStoredProcedureQuery, createStoredProcedureQuery, createStoredProcedureQuery, find, find, find, findMultiple, findMultiple, get, get, get, getCacheRetrieveMode, getCacheStoreMode, getCriteriaBuilder, getEntityGraph, getEntityGraph, getEntityGraphs, getEntityManagerFactory, getMetamodel, getMultiple, getMultiple, getProperties, getTransaction, isOpen, runWithConnection, setCacheRetrieveMode, setCacheStoreMode, setProperty, unwrap

Method Details
- insert
  void insert(Object entity)
  
  Insert a record.
  If the entity Id field is declared to be generated, for example, if it is annotated GeneratedValue, the id is generated and assigned to the given instance.
  
  The PreInsert callback is triggered.
  The PostInsert callback is triggered if the operation is successful.
  
  Parameters:
  
  entity - a new or removed entity instance
  
  Throws:
  
  IllegalArgumentException - if the given instance is determined to not be new or removed
  
  EntityExistsException - if the given entity has an identifier assigned by the application, and a record with the assigned identifier already exists in the database
  
  PersistenceException - if a record could not be inserted in the database
- insertMultiple
  void insertMultiple(List<?> entities)
  
  Insert every record in the given list. The records are inserted in the order in which they occur in the given list and according to the requirements of the insert(Object) method.
  
  Parameters:
  
  entities - The entities to be inserted.
  
  Throws:
  
  IllegalArgumentException - if one of the given instances is determined to not be new or removed
  
  EntityExistsException - if one of the given entities has an identifier assigned by the application, and a record with the assigned identifier already exists in the database
  
  PersistenceException - if a record could not be inserted in the database
  
  See Also:
  
  insert(Object)
- update
  void update(Object entity)
  
  Update a record.
  
  The PreUpdate callback is triggered.
  The PostUpdate callback is triggered if the operation is successful.
  
  Parameters:
  
  entity - a detached entity instance
  
  Throws:
  
  IllegalArgumentException - if the given instance is determined to not be detached
  
  OptimisticLockException - if an optimistic locking conflict is detected, that is, if no row matching the identifier of the given entity exists in the database or if an optimistic version check fails
  
  PersistenceException - if a record could not be updated in the database
- updateMultiple
  void updateMultiple(List<?> entities)
  
  Update every record in the given list. The records are updated in the order in which they occur in the given list and according to the requirements of the update(Object) method.
  
  Parameters:
  
  entities - The entities to be updated.
  
  Throws:
  
  IllegalArgumentException - if the one of the given instances is determined to not be detached
  
  OptimisticLockException - if an optimistic locking conflict is detected, that is, if no row matching the identifier of one of the given entities exists in the database or if an optimistic version check fails
  
  PersistenceException - if a record could not be updated in the database
  
  See Also:
  
  update(Object)
- delete
  void delete(Object entity)
  
  Delete a record.
  
  The PreDelete callback is triggered.
  The PostDelete callback is triggered if the operation is successful.
  
  Parameters:
  
  entity - a detached entity instance
  
  Throws:
  
  IllegalArgumentException - if the given instance is determined to not be detached
  
  OptimisticLockException - if an optimistic locking conflict is detected, that is, if no row matching the identifier of the given entity exists in the database or if an optimistic version check fails
  
  PersistenceException - if a record could not be deleted from the database
- deleteMultiple
  void deleteMultiple(List<?> entities)
  
  Delete every record in the given list. The records are deleted in the order in which they occur in the given list and according to the requirements of the delete(Object) method.
  
  Parameters:
  
  entities - The entities to be deleted.
  
  Throws:
  
  IllegalArgumentException - if the one of the given instances is determined to not be detached
  
  OptimisticLockException - if an optimistic locking conflict is detected, that is, if no row matching the identifier of one of the given entities exists in the database or if an optimistic version check fails
  
  PersistenceException - if a record could not be deleted from the database
  
  See Also:
  
  delete(Object)
- upsert
  void upsert(Object entity)
  
  Perform an upsert, that is, insert the record if it does not exist, or update it if it already exists.
  This method never performs id generation and does not accept an entity instance with a null identifier. When id generation is required, use insert(Object).
  On the other hand, upsert() does accept an entity instance with an assigned identifier value, even if the entity Id field is declared to be generated, for example, if it is annotated GeneratedValue. Thus, this method may be used to import data from an external source.
  
  The PreUpsert callback is triggered.
  The PostUpsert callback is triggered if the operation is successful.
  
  Parameters:
  
  entity - a detached entity instance, or a new instance with an assigned identifier
  
  Throws:
  
  IllegalArgumentException - if the given entity has a null identifier value
  
  OptimisticLockException - if an optimistic locking conflict is detected, that is, if an optimistic version check fails
  
  PersistenceException - if a record could not be upserted in the database
- upsertMultiple
  void upsertMultiple(List<?> entities)
  
  Upsert every record in the given list. The records are upserted in the order in which they occur in the given list and according to the requirements of the upsert(Object) method.
  
  Parameters:
  
  entities - The entities to be inserted or updated.
  
  Throws:
  
  IllegalArgumentException - if one of the given entities has a null identifier value
  
  OptimisticLockException - if an optimistic locking conflict is detected, that is, if an optimistic version check fails
  
  PersistenceException - if a record could not be upserted in the database
  
  See Also:
  
  upsert(Object)
- refresh
  
  void refresh(Object entity)
  
  Refresh the entity instance state from the database.
  
  Parameters:
  
  entity - The entity to be refreshed.
  
  Throws:
  
  EntityNotFoundException - if the given entity no longer exists in the database
  
  PersistenceException - if a record could not be read from the database
- refreshMultiple
  void refreshMultiple(List<?> entities)
  
  Refresh multiple entities.
  
  Parameters:
  
  entities - The entities to be refreshed.
  
  Throws:
  
  EntityNotFoundException - if one of the given entities no longer exists in the database
  
  PersistenceException - if a record could not be read from the database
  
  See Also:
  
  refresh(Object)
- refresh
  
  void refresh(Object entity, LockModeType lockMode)
  
  Refresh the entity instance state from the database.
  
  Parameters:
  
  entity - The entity to be refreshed.
  
  lockMode - The LockMode to be applied.
  
  Throws:
  
  EntityNotFoundException - if the given entity no longer exists in the database
  
  PersistenceException - if a record could not be read from the database
- fetch
  <T> T fetch(T association)
  
  Fetch an association or collection that was configured for lazy loading if it has not yet been fetched from the database. If the association or collection is already fetched, this operation has no effect. For convenience, this method always returns its argument.
  
  Book book = agent.get(Book.class, isbn); // book is immediately detached agent.fetch(book.getAuthors()) // fetch the associated authors .forEach(author -> ... ); // iterate the collection
  
  Type Parameters:
  
  T - The type of the entity attribute type, either an entity type or a collection type
  
  Parameters:
  
  association - A lazy association
  
  Returns:
  
  The association with its state fetched.
  
  Throws:
  
  PersistenceException - if a record could not be read from the database

Interface EntityAgent

Method Summary

Methods inherited from interface EntityHandler

Method Details

insert

insertMultiple

update

updateMultiple

delete

deleteMultiple

upsert

upsertMultiple

refresh

refreshMultiple

refresh

fetch