NPersistence Reference Guide
Interface used to interact with the persistence context.

An EntityManager instance is associated with a persistence context. A persistence context is a set of entity instances in which for any persistent entity identity there is a unique entity instance. Within the persistence context, the entity instances and their lifecycle are managed. The EntityManager API is used to create and remove persistent entity instances, to find entities by their primary key, and to query over entities.

The set of entities that can be managed by a given EntityManager instance is defined by a persistence unit. A persistence unit defines the set of all classes that are related or grouped by the application, and which must be colocated in their mapping to a single database.

Namespace: NPersistence
Assembly: NPersistence (in NPersistence.dll) Version: 2.0.0.0 (2.0.0.0)

Syntax

   
 C# 
public interface EntityManager

Members

      
 All Members  Methods  
 Public

 Protected
 Instance

 Static 
 Declared

 Inherited
 XNA Framework Only 

 .NET Compact Framework Only 

 MemberDescription
Clear()()()()
Clear the persistence context, causing all managed entities to become detached. Changes made to entities that have not been flushed to the database will not be persisted.
Close()()()()
Close an application-managed entity manager. After the close method has been invoked, all methods on the EntityManager instance and any Query and TypedQuery objects obtained from it will throw the InvalidOperationException except for getProperties, getTransaction, and isOpen (which will return false). If this method is called when the entity manager is associated with an active transaction, the persistence context remains managed until the transaction completes.
Contains(Object)
Check if the instance is a managed entity instance belonging to the current persistence context.
CreateNamedQuery(String)
Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL).
CreateNamedQuery<(Of <<'(T>)>>)(String, Type)
Create an instance of TypedQuery for executing a Java Persistence query language named query. The select list of the query must contain only a single item, which must be assignable to the type specified by the resultClass argument.
CreateNativeQuery(String)
Create an instance of Query for executing a native SQL statement, e.g., for update or delete.
CreateNativeQuery(String, String)
Create an instance of Query for executing a native SQL query.
CreateNativeQuery(String, Type)
Create an instance of Query for executing a native SQL query.
CreateQuery(String)
Create an instance of Query for executing a Java Persistence query language statement.
CreateQuery<(Of <<'(T>)>>)(String, Type)
Create an instance of TypedQuery for executing a Java Persistence query language statement. The select list of the query must contain only a single item, which must be assignable to the type specified by the resultClass argument.
Detach(Object)
Remove the given entity from the persistence context, causing a managed entity to become detached. Unflushed changes made to the entity if any (including removal of the entity), will not be synchronized to the database. Entities which previously referenced the detached entity will continue to reference it.
Find<(Of <<'(T>)>>)(Type, Object)
Find by primary key. Search for an entity of the specified class and primary key. If the entity instance is contained in the persistence context, it is returned from there.
Find<(Of <<'(T>)>>)(Type, Object, LockModeType)
Find by primary key and lock. Search for an entity of the specified class and primary key and lock it with respect to the specified lock type. If the entity instance is contained in the persistence context, it is returned from there, and the effect of this method is the same as if the lock method had been called on the entity. If the entity is found within the persistence context and the lock mode type is pessimistic and the entity has a version attribute, the persistence provider must perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException will be thrown. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
  • the PessimisticLockException will be thrown if the database locking failure causes transaction-level rollback
  • the LockTimeoutException will be thrown if the database locking failure causes only statement-level rollback
Find<(Of <<'(T>)>>)(Type, Object, Dictionary<(Of <<'(String, Object>)>>))
Find by primary key, using the specified properties. Search for an entity of the specified class and primary key. If the entity instance is contained in the persistence context, it is returned from there. If a vendor-specific property or hint is not recognized, it is silently ignored.
Find<(Of <<'(T>)>>)(Type, Object, LockModeType, Dictionary<(Of <<'(String, Object>)>>))
Find by primary key and lock, using the specified properties. Search for an entity of the specified class and primary key and lock it with respect to the specified lock type. If the entity instance is contained in the persistence context, it is returned from there. If the entity is found within the persistence context and the lock mode type is pessimistic and the entity has a version attribute, the persistence provider must perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException will be thrown. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
  • the PessimisticLockException will be thrown if the database locking failure causes transaction-level rollback
  • the LockTimeoutException will be thrown if the database locking failure causes only statement-level rollback
If a vendor-specific property or hint is not recognized, it is silently ignored. Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, the hint may or may not be observed.
Flush()()()()
Synchronize the persistence context to the underlying database.
GetDelegate()()()()
Return the underlying provider object for the EntityManager, if available. The result of this method is implementation specific. The unwrap method is to be preferred for new applications.
GetEntityManagerFactory()()()()
Return the entity manager factory for the entity manager.
GetFlushMode()()()()
Get the flush mode that applies to all objects contained in the persistence context.
GetLockMode(Object)
Get the current lock mode for the entity instance.
GetProperties()()()()
Get the properties and hints and associated values that are in effect for the entity manager. Changing the contents of the map does not change the configuration in effect.
GetReference<(Of <<'(T>)>>)(Type, Object)
Get an instance, whose state may be lazily fetched. If the requested instance does not exist in the database, the EntityNotFoundException is thrown when the instance state is first accessed. (The persistence provider runtime is permitted to throw the EntityNotFoundException when getReference is called.) The application should not expect that the instance state will be available upon detachment, unless it was accessed by the application while the entity manager was open.
GetTransaction()()()()
Return the resource-level EntityTransaction object. The EntityTransaction instance may be used serially to begin and commit multiple transactions.
IsOpen()()()()
Determine whether the entity manager is open.
JoinTransaction()()()()
Indicate to the entity manager that a JTA transaction is active. This method should be called on a JTA application managed entity manager that was created outside the scope of the active transaction to associate it with the current JTA transaction.
Lock(Object, LockModeType)
Lock an entity instance that is contained in the persistence context with the specified lock mode type. If a pessimistic lock mode type is specified and the entity contains a version attribute, the persistence provider must also perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException will be thrown. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
  • the PessimisticLockException will be thrown if the database locking failure causes transaction-level rollback
  • the LockTimeoutException will be thrown if the database locking failure causes only statement-level rollback
Lock(Object, LockModeType, Dictionary<(Of <<'(String, Object>)>>))
Lock an entity instance that is contained in the persistence context with the specified lock mode type and with specified properties. If a pessimistic lock mode type is specified and the entity contains a version attribute, the persistence provider must also perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException will be thrown. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
  • the PessimisticLockException will be thrown if the database locking failure causes transaction-level rollback
  • the LockTimeoutException will be thrown if the database locking failure causes only statement-level rollback
If a vendor-specific property or hint is not recognized, it is silently ignored. Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, the hint may or may not be observed.
Merge<(Of <<'(T>)>>)(T)
Merge the state of the given entity into the current persistence context.
Persist(Object)
Make an instance managed and persistent.
Refresh(Object)
Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
Refresh(Object, LockModeType)
Refresh 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. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
  • the PessimisticLockException will be thrown if the database locking failure causes transaction-level rollback
  • the LockTimeoutException will be thrown if the database locking failure causes only statement-level
  • rollback.
Refresh(Object, Dictionary<(Of <<'(String, Object>)>>))
Refresh the state of the instance from the database, using the specified properties, and overwriting changes made to the entity, if any. If a vendor-specific property or hint is not recognized, it is silently ignored.
Refresh(Object, LockModeType, Dictionary<(Of <<'(String, Object>)>>))
Refresh 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 and with specified properties. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
  • the PessimisticLockException will be thrown if the database locking failure causes transaction-level rollback
  • the LockTimeoutException will be thrown if the database locking failure causes only statement-level rollback
If a vendor-specific property or hint is not recognized, it is silently ignored. Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, the hint may or may not be observed.
Remove(Object)
Remove the entity instance.
SetFlushMode(FlushModeType)
Set the flush mode that applies to all objects contained in the persistence context.
SetProperty(String, Object)
Set an entity manager property or hint. If a vendor-specific property or hint is not recognized, it is silently ignored.
Unwrap<(Of <<'(T>)>>)(Type)
Return an object of the specified type to allow access to the provider-specific API. If the provider's EntityManager implementation does not support the specified class, the PersistenceException is thrown.

See Also