EntityManager (Java EE 5)

用于与持久性上下文交互的接口。

EntityManager 实例与持久性上下文关联。持久性上下文是一组实体实例，其中任何持久实体身份都对应一个唯一的实体实例。在持久性上下文中，可以管理实体实例及其生命周期。此接口定义用于与持久性上下文交互的方法。EntityManager API 用于创建和移除持久性实体实例，根据主键查找实体以及对实体进行查询。

可以由给定 EntityManager 实例管理的实体集是由持久性单元定义的。持久性单元定义与应用程序相关或应用程序组合的所有类的集合，以及那些必须同时映射到单个数据库的类。

since

en Java Persistence 1.0

英文文档：

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. This interface defines the methods that are used to interact with the persistence context. 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.

Since:

Java Persistence 1.0

---

Method Summary
void	clear()           Clear the persistence context, causing all managed entities to become detached.
void	close()           Close an application-managed EntityManager.
boolean	contains(Object entity)           Check if the instance belongs to the current persistence context.
Query	createNamedQuery(String name)           Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL).
Query	createNativeQuery(String sqlString)           Create an instance of Query for executing a native SQL statement, e.g., for update or delete.
Query	createNativeQuery(String sqlString, Class resultClass)           Create an instance of Query for executing a native SQL query.
Query	createNativeQuery(String sqlString, String resultSetMapping)           Create an instance of Query for executing a native SQL query.
Query	createQuery(String qlString)           Create an instance of Query for executing a Java Persistence query language statement.
<T> T

find(Class<T> entityClass, Object primaryKey)
          Find by primary key.  void flush()
          Synchronize the persistence context to the underlying database.  Object getDelegate()
          Return the underlying provider object for the EntityManager, if available.  FlushModeType getFlushMode()
          Get the flush mode that applies to all objects contained in the persistence context. getReference(Class<T> entityClass, Object primaryKey)
          Get an instance, whose state may be lazily fetched.  EntityTransaction getTransaction()
          Returns the resource-level transaction object.  boolean isOpen()
          Determine whether the EntityManager is open.  void joinTransaction()
          Indicate to the EntityManager that a JTA transaction is active.  void lock(Object entity, LockModeType lockMode)
          Set the lock mode for an entity object contained in the persistence context. merge(T entity)
          Merge the state of the given entity into the current persistence context.  void persist(Object entity)
          Make an entity instance managed and persistent.  void refresh(Object entity)
          Refresh the state of the instance from the database, overwriting changes made to the entity, if any.  void remove(Object entity)
          Remove the entity instance.  void setFlushMode(FlushModeType flushMode)
          Set the flush mode that applies to all objects contained in the persistence context.  

Method Detail

public void persist(Object entity)
使实体实例被管理并持久化。

entity
Throws	EntityExistsException: 如果实体已经存在。（调用持久操作时，可能抛出 EntityExistsException；刷新或提交时，可能抛出 EntityExistsException 或另一个 PersistenceException。）
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。
Throws	IllegalArgumentException: 如果不是实体
Throws	TransactionRequiredException: 如果对 PersistenceContextType.TRANSACTION 类型的容器管理的实体管理器调用，但没有事务。

英文文档：

persist

void persist(Object entity)

Make an entity instance managed and persistent.

Parameters:

entity -

Throws:

EntityExistsException - if the entity already exists. (The EntityExistsException may be thrown when the persist operation is invoked, or the EntityExistsException or another PersistenceException may be thrown at flush or commit time.)

IllegalStateException - if this EntityManager has been closed.

IllegalArgumentException - if not an entity

TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

---

英文文档：

merge

<T> T merge(T entity)

Merge the state of the given entity into the current persistence context.

Parameters:

entity -

Returns:

the instance that the state was merged to

Throws:

IllegalStateException - if this EntityManager has been closed.

IllegalArgumentException - if instance is not an entity or is a removed entity

TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

---

public void remove(Object entity)
移除实体实例。

entity
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。
Throws	IllegalArgumentException: 如果不是实体或者为已脱离的实体
Throws	TransactionRequiredException: 如果对 PersistenceContextType.TRANSACTION 类型的容器管理的实体管理器调用，但没有事务。

英文文档：

remove

void remove(Object entity)

Remove the entity instance.

Parameters:

entity -

Throws:

IllegalStateException - if this EntityManager has been closed.

IllegalArgumentException - if not an entity or if a detached entity

TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

---

英文文档：

find

<T> T find(Class<T> entityClass,
           Object primaryKey)

Find by primary key.

Parameters:

entityClass -

primaryKey -

Returns:

the found entity instance or null if the entity does not exist

Throws:

IllegalStateException - if this EntityManager has been closed.

IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key

---

英文文档：

getReference

<T> T getReference(Class<T> entityClass,
                   Object primaryKey)

Get an instance, whose state may be lazily fetched. If the requested instance does not exist in the database, throws EntityNotFoundException when the instance state is first accessed. (The persistence provider runtime is permitted to throw EntityNotFoundException when getReference(java.lang.Class, java.lang.Object) 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.

Parameters:

entityClass -

primaryKey -

Returns:

the found entity instance

Throws:

IllegalStateException - if this EntityManager has been closed.

IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key

EntityNotFoundException - if the entity state cannot be accessed

---

public void flush()
使持久性上下文与底层数据库同步。

Throws	IllegalStateException: 如果已经关闭了此 EntityManager。
Throws	TransactionRequiredException: 如果没有事务
Throws	PersistenceException: 如果刷新失败

英文文档：

flush

void flush()

Synchronize the persistence context to the underlying database.

Throws:

IllegalStateException - if this EntityManager has been closed.

TransactionRequiredException - if there is no transaction

PersistenceException - if the flush fails

---

public void setFlushMode(FlushModeType flushMode)
设置应用于持久性上下文中包含的所有对象的刷新模式。

flushMode
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。

英文文档：

setFlushMode

void setFlushMode(FlushModeType flushMode)

Set the flush mode that applies to all objects contained in the persistence context.

Parameters:

flushMode -

Throws:

IllegalStateException - if this EntityManager has been closed.

---

public FlushModeType getFlushMode()
获取应用于持久性上下文中包含的所有对象的刷新模式。

return	刷新模式
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。

英文文档：

getFlushMode

FlushModeType getFlushMode()

Get the flush mode that applies to all objects contained in the persistence context.

Returns:

flush mode

Throws:

IllegalStateException - if this EntityManager has been closed.

---

public void lock(Object entity, LockModeType lockMode)
设置持久性上下文中包含的实体对象的锁定模式。

entity
lockMode
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。
Throws	PersistenceException: 如果执行了不受支持的锁定调用
Throws	IllegalArgumentException: 如果实例不是实体，或者是已脱离的实体
Throws	TransactionRequiredException: 如果没有事务

英文文档：

lock

void lock(Object entity,
          LockModeType lockMode)

Set the lock mode for an entity object contained in the persistence context.

Parameters:

entity -

lockMode -

Throws:

IllegalStateException - if this EntityManager has been closed.

PersistenceException - if an unsupported lock call is made

IllegalArgumentException - if the instance is not an entity or is a detached entity

TransactionRequiredException - if there is no transaction

---

public void refresh(Object entity)
从数据库刷新实例的状态，重写对实体所作的更改（如果有）。

entity
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。
Throws	IllegalArgumentException: 如果不是实体或者实体不受管理
Throws	TransactionRequiredException: 如果对 PersistenceContextType.TRANSACTION 类型的容器管理的实体管理器调用，但没有事务。
Throws	EntityNotFoundException: 如果数据库中不再存在该实体。

英文文档：

refresh

void refresh(Object entity)

Refresh the state of the instance from the database, overwriting changes made to the entity, if any.

Parameters:

entity -

Throws:

IllegalStateException - if this EntityManager has been closed.

IllegalArgumentException - if not an entity or entity is not managed

TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

EntityNotFoundException - if the entity no longer exists in the database.

---

public void clear()
清除持久性上下文，使所有被管理的实体变为脱离实体。尚未刷新到数据库的实体更改不具有持久性。

Throws

IllegalStateException: 如果已经关闭了此 EntityManager。

英文文档：

clear

void 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.

Throws:

IllegalStateException - if this EntityManager has been closed.

---

public boolean contains(Object entity)
检查实例是否属于当前持久性上下文。

entity
return	如果实例属于当前持久性上下文，则返回 true。
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。
Throws	IllegalArgumentException: 如果不是实体

英文文档：

contains

boolean contains(Object entity)

Check if the instance belongs to the current persistence context.

Parameters:

entity -

Returns:

true if the instance belongs to the current persistence context.

Throws:

IllegalStateException - if this EntityManager has been closed.

IllegalArgumentException - if not an entity

---

public Query createQuery(String qlString)
创建 Query 实例以执行 Java Persistence 查询语言语句。

qlString	Java Persistence 查询语言查询字符串
return	新的查询实例
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。
Throws	IllegalArgumentException: 如果查询字符串无效

英文文档：

createQuery

Query createQuery(String qlString)

Create an instance of Query for executing a Java Persistence query language statement.

Parameters:

qlString - a Java Persistence query language query string

Returns:

the new query instance

Throws:

IllegalStateException - if this EntityManager has been closed.

IllegalArgumentException - if query string is not valid

---

public Query createNamedQuery(String name)
创建 Query 实例以执行指定的查询（使用 Java Persistence 查询语言或本机 SQL）。

name	元数据中定义的查询名称
return	新的查询实例
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。
Throws	IllegalArgumentException: 如果查询没有使用给定的名称定义

英文文档：

createNamedQuery

Query createNamedQuery(String name)

Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL).

Parameters:

name - the name of a query defined in metadata

Returns:

the new query instance

Throws:

IllegalStateException - if this EntityManager has been closed.

IllegalArgumentException - if a query has not been defined with the given name

---

public Query createNativeQuery(String sqlString)
创建 Query 实例以执行本机 SQL 语句，例如，更新或删除。

sqlString	本机 SQL 查询字符串
return	新的查询实例
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。

英文文档：

createNativeQuery

Query createNativeQuery(String sqlString)

Create an instance of Query for executing a native SQL statement, e.g., for update or delete.

Parameters:

sqlString - a native SQL query string

Returns:

the new query instance

Throws:

IllegalStateException - if this EntityManager has been closed.

---

public Query createNativeQuery(String sqlString, Class<T> resultClass)
创建 Query 实例以执行本机 SQL 查询。

sqlString	本机 SQL 查询字符串
resultClass	结果实例的类
return	新的查询实例
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。

英文文档：

createNativeQuery

Query createNativeQuery(String sqlString,
                        Class resultClass)

Create an instance of Query for executing a native SQL query.

Parameters:

sqlString - a native SQL query string

resultClass - the class of the resulting instance(s)

Returns:

the new query instance

Throws:

IllegalStateException - if this EntityManager has been closed.

---

public Query createNativeQuery(String sqlString, String resultSetMapping)
创建 Query 实例以执行本机 SQL 查询。

sqlString	本机 SQL 查询字符串
resultSetMapping	结果集映射的名称
return	新的查询实例
Throws	IllegalStateException: 如果已经关闭了此 EntityManager。

英文文档：

createNativeQuery

Query createNativeQuery(String sqlString,
                        String resultSetMapping)

Create an instance of Query for executing a native SQL query.

Parameters:

sqlString - a native SQL query string

resultSetMapping - the name of the result set mapping

Returns:

the new query instance

Throws:

IllegalStateException - if this EntityManager has been closed.

---

public void joinTransaction()
指示 EntityManager JTA 事务处于活动状态。此方法应该对管理 JTA 应用程序的 EntityManager（在活动事务的作用域以外创建）调用，以使其与当前的 JTA 事务关联。

Throws	IllegalStateException: 如果已经关闭了此 EntityManager。
Throws	TransactionRequiredException: 如果没有事务。

英文文档：

joinTransaction

void joinTransaction()

Indicate to the EntityManager that a JTA transaction is active. This method should be called on a JTA application managed EntityManager that was created outside the scope of the active transaction to associate it with the current JTA transaction.

Throws:

IllegalStateException - if this EntityManager has been closed.

TransactionRequiredException - if there is no transaction.

---

public Object getDelegate()
返回 EntityManager 的底层提供者对象（如果存在）。此方法的结果与实现有关。

Throws

IllegalStateException: 如果已经关闭了此 EntityManager。

英文文档：

getDelegate

Object getDelegate()

Return the underlying provider object for the EntityManager, if available. The result of this method is implementation specific.

Throws:

IllegalStateException - if this EntityManager has been closed.

---

public void close()
关闭应用程序管理的 EntityManager。调用 close 方法后，EntityManager 实例的所有方法以及从中获得的任何 Query 对象都将对 getTransaction 和 isOpen（返回 false）抛出 IllegalStateException 异常。如果在 EntityManager 与活动事务关联时调用此方法，则持久性上下文保持被管理状态，直到事务完成为止。

Throws

IllegalStateException: 如果 EntityManager 是容器管理的，或者已经关闭。

英文文档：

close

void close()

Close an application-managed EntityManager. After the close method has been invoked, all methods on the EntityManager instance and any Query objects obtained from it will throw the IllegalStateException except for getTransaction and isOpen (which will return false). If this method is called when the EntityManager is associated with an active transaction, the persistence context remains managed until the transaction completes.

Throws:

IllegalStateException - if the EntityManager is container-managed or has been already closed..

---

public boolean isOpen()
确定 EntityManager 是否打开。

return

在 EntityManager 关闭前返回 true。

英文文档：

isOpen

boolean isOpen()

Determine whether the EntityManager is open.

Returns:

true until the EntityManager has been closed.

---

public EntityTransaction getTransaction()
返回资源级的事务对象。EntityTransaction 实例可以连续使用，以开始和提交多个事务。

return	EntityTransaction 实例
Throws	IllegalStateException: 如果对 JTA EntityManager 调用。

英文文档：

getTransaction

EntityTransaction getTransaction()

Returns the resource-level transaction object. The EntityTransaction instance may be used serially to begin and commit multiple transactions.

Returns:

EntityTransaction instance

Throws:

IllegalStateException - if invoked on a JTA EntityManager.

---

Overview  Package   Class  Tree  Deprecated  Index  Help
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.