JPA入门精要系列：
（1）：JPA框架组件核心组成
本文由牛旦教育原创出品，欢迎收藏、点赞、分享。
转载请注明来源@牛旦教育IT课堂
EntityManager常用方法详解
1.1.1 void refresh(java.lang.Object entity, LockModeType lockMode)
功能説明：
从数据库中刷新实例的状态，覆盖对实体所做的更改(如果有的话)，并根据给定的锁类型锁定它。
如果锁定模式类型是悲观的，并且找到了实体实例，但无法锁定时:
- -如果数据库锁定失败导致事务级回滚，则会抛出PessimisticLockException;
- -如果数据库锁定失败仅导致语句级回滚，则会抛出LockTimeoutException。
方法参数：
Entity-要刷新的实体；
lockMode-锁类型。
方法异常：
? IllegalArgumentException—如果实例不是有效实体或者实体为非托管实体;
? TransactionRequiredException—如果没有事务，而使用类型PersistenceContextType.TRANSACTION或非NONE模式的锁，在容器管理的EntityManager实例上调用时抛出此异常。
? EntityNotFoundException—如果实体在数据库中不再存在;
? PessimisticLockException——如果悲观锁失败，事务被回滚;
? LockTimeoutException——如果悲观锁定失败，并且只有语句被回滚;
? PersistenceException——如果进行了不支持的锁调用。
本方法是在Java Persistence 2.0开始加入的。
1.1.2 void refresh(java.lang.Object entity,LockModeType lockMode,java.util.Map<java.lang.String,java.lang.Object> properties)
功能说明：
从数据库中刷新实例的状态，覆盖对实体所做的更改(如果有的话)，并根据给定的锁模式类型和指定的属性对其进行锁定。
如果锁定模式类型是悲观的，并且找到了实体实例，但无法锁定时:
- -如果数据库锁定失败导致事务级回滚，则会抛出PessimisticLockException;
- -如果数据库锁定失败仅导致语句级回滚，则会抛出LockTimeoutException。
如果某个特定于供应商的属性或提示不被识别，它将被默认忽略。
可移植应用程序不应该依赖于标准的超时提示。根据使用的数据库和提供者使用的锁定机制，可能观察到提示，也可能不观察到提示。
方法参数：
entity –实体；
lockMode –锁模式；
properties –标准的和特定厂商的属性提示。
方法异常：
? IllegalArgumentException—如果实例不是有效实体或者实体为非托管实体;
? TransactionRequiredException—如果没有事务，而使用类型PersistenceContextType.TRANSACTION或非NONE模式的锁，在容器管理的EntityManager实例上调用时抛出此异常。
? EntityNotFoundException—如果实体在数据库中不再存在;
? PessimisticLockException——如果悲观锁失败，事务被回滚;
? LockTimeoutException——如果悲观锁定失败，并且只有语句被回滚;
? PersistenceException——如果进行了不支持的锁调用。
本方法是在Java Persistence 2.0开始加入的。
1.1.3 void clear()
方法功能：
清除持久性上下文，导致所有托管实体被分离（可以理解为游离态或飘忽态）。对未刷新到数据库的实体所做的更改将不会持久。
1.1.4 void detach(java.lang.Object entity)
方法功能：
从持久性上下文中删除给定的实体，从而使托管实体分离。如果对实体进行了未刷新的更改(包括删除实体)，则不会同步到数据库。以前引用分离实体的实体将继续引用它。
方法参数：
entity-要分离的实体对象；
方法异常：
- IllegalArgumentException ：如果参数实例不是个有效的实体则抛出此异常。
本方法是在Java Persistence 2.0开始加入的。
1.1.5 boolean contains(java.lang.Object entity)
方法功能：
检查实例是否是属于当前持久性上下文的托管实体实例。
方法参数：
entity –要检查的实体对象；
返回值：
布尔值true和false，表示是否在当前的持久化上下文中。t
方法异常：
IllegalArgumentException：如果不是有效实体就会抛出此异常。
1.1.6 LockModeType getLockMode(java.lang.Object entity)
方法功能：
获取当前实体的锁模式；
方法参数：
Entity-指定的实体对象。
返回值：
返回实体对象用的锁类型；
方法异常：
TransactionRequiredException - 如果没有事务，则有从此异常
java.lang.IllegalArgumentException - 如果实例不是托管实体且事务处于活动状态
本方法是在Java Persistence 2.0开始加入的。
1.1.7 void setProperty(java.lang.String propertyName, java.lang.Object value)
方法功能：
设置实体管理器的属性。如果某个特定于供应商的属性无法识别，它将被默认忽略。
方法参数：
propertyName –属性名子；
value –对应的属性值；
方法异常：
java.lang.IllegalArgumentException-如果第二个参数对实现是无效的，则抛出该异常
本方法是在Java Persistence 2.0开始加入的。
1.1.8 java.util.Map<java.lang.String,java.lang.Object> getProperties()
方法功能：
获取对实体管理器有效的属性和关联值。若更改此映射的内容则并不会更改配置。
返回值：
返回实体管理器有效的属性映射。
本方法是在Java Persistence 2.0开始加入的。
1.1.9 java.util.Set<java.lang.String> getSupportedProperties()
方法功能：
获取支持与实体管理器一起使用的属性的名称。这些与属性和提示相对应属性名，这些属性和提示可以传递给EntityManager接口的方法，该接口接受properties参数或与PersistenceContext注释一起使用。这些属性包括所有标准的实体管理器提示和属性，以及提供器支持的特定于供应商的提示和属性。这些属性可能有效，也可能不有效。
返回值：
以集合的形式返回所有属性的名子。
本方法是在Java Persistence 2.0开始加入的。
1.1.10 Query createQuery(java.lang.String qlString)
方法功能：
创建用于执行Java持久性查询语言语句的查询(Query)实例。
方法参数：
qlString-一条有效的Java Persistence 查询字符串
方法返回值：
一个Query类型的查询实例。
方法异常：
java.lang.IllegalArgumentException - 如果查询字符串无效，则抛出该异常
1.1.11 <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery)
方法功能：
为执行条件查询创建TypedQuery类型实例。
方法参数：
criteriaQuery - 一个标准查询对象；
返回值：
返回一个新的查询实例；
方法异常：
java.lang.IllegalArgumentException - 若条件查询无效，这抛出该异常。
本方法是在Java Persistence 2.0开始加入的。
1.1.12 <T> TypedQuery<T> createQuery(java.lang.String qlString, java.lang.Class<T> resultClass)
方法功能：
创建用于执行Java持久性查询语言语句(JPQL)的TypedQuery实例。查询的select列表必须只包含一个项，该项必须可赋值给resultClass参数指定的类型。
方法参数：
qlString - 有效的Java持久性查询字符串；（ a Java Persistence query string）
resultClass - 指定的查询结果类型 ；（ the type of the query result）
方法返回值：
返回新的查询示例。
方法异常：
java.lang.IllegalArgumentException - 如果发现查询字符串无效，或者发现查询结果不能分配给指定的类型,则抛出此类型。
本方法是在Java Persistence 2.0开始加入的。
1.1.13 Query createNamedQuery(java.lang.String name)
方法功能：
创建用于执行命名查询的查询（Query）实例(在Java持久性查询语言JPQL中或在原生SQL中)。
方法参数：
name -在元数据中定义的查询的名称。
方法返回值：
返回一个新的查询实例。
方法异常：
java.lang.IllegalArgumentException -如果给定名称的查询没定义，或者发现查询字符串无效。
1.1.14 <T> TypedQuery<T> createNamedQuery(java.lang.String name, java.lang.Class<T> resultClass)
方法功能：
创建TypedQuery实例以执行JPQL（Java持久性查询语言）命名查询。查询的select列表必须只包含一个项，该项必须可赋值给resultClass参数指定的类型。
方法参数：
? name - 在元数据中定义的查询名称；
? resultClass - 查询结果类型。
返回结果：
新的查询实例 。
方法异常：
IllegalArgumentException - 如果给定名称的查询没定义，或者发现查询字符串无效，或者发现查询结果不能分配给指定的类型，则抛出此异常。
本方法是在Java Persistence 2.0开始加入的。
1.1.15 Query createNativeQuery(java.lang.String sqlString)
方法功能：
创建用于执行原生SQL语句(例如，用于更新或删除)的Query类型查询实例。
方法参数：
sqlString - 原生SQL查询字符串。
返回结果：
新的查询实例。
1.1.16 Query createNativeQuery(java.lang.String sqlString,java.lang.Class resultClass)
方法功能：
创建用于执行原生SQL查询的Query类型查询实例。
方法参数：
sqlString - 一条原生SQL查询语句；
resultClass - 返回结果的实例类型。
返回结果：
一个新的查询实例。
1.1.17 Query createNativeQuery(java.lang.String sqlString,java.lang.String resultSetMapping)
方法功能：
创建用于执行原生SQL查询的Query类型查询实例。
方法参数：
sqlString - 一条原生SQL查询字符串；
resultSetMapping - 结果集映射的名子。
返回结果：
新的Query类型的查询实例。
1.1.18 void joinTransaction()
方法功能：
向实体管理器表明JTA事务处于活动状态。应该在活动事务范围之外创建的应用托管的JTA实体管理器上调用此方法，以将其与当前JTA事务关联起来。
方法异常：
TransactionRequiredException - 若无事务，则抛出此异常。
1.1.19 <T> T unwrap(java.lang.Class<T> cls)
方法功能：
返回指定类型的对象，以允许访问特定于提供器（provider）的API。如果提供器的EntityManager实现不支持指定的类，则抛出PersistenceException。比如可通过实体管理器返回一个数据库连接对象（Connection）。
方法参数：
cls - 要返回的对象的类。这通常是底层的EntityManager实现类或它实现的接口。
返回结果：
返回指定类（class）的实例（比如数据库连接对象）。
返法异常：
PersistenceException -如果提供器不支持此调用，则会抛出该异常
本方法是在Java Persistence 2.0开始加入的。
1.1.20 java.lang.Object getDelegate()
方法功能：
返回EntityManager的底层提供器对象(如果可用)。此方法的结果是特定于实现的。unwrap方法是新应用程序中的首选方法。
返回结果：
返回EntityManager底层提供器对象。
1.1.21 void close()
方法功能：
关闭应用程序管理的或说托管的实体管理器。调用close方法之后，EntityManager实例上的所有方法以及从中获得的任何Query和TypedQuery对象都将抛出IllegalStateException,但 getProperties、getSupportedProperties、getTransaction和isOpen(将返回false)除外。如果在实体管理器与活动事务关联时调用此方法，则在事务完成之前将一直处于管理持久性上下文中。
方法异常：
java.lang.IllegalStateException -如果实体管理器是容器管理的，调用此方法会抛出此异常。
1.1.22 boolean isOpen()
方法功能：
判断实体管理器是否已打开。
返回结果：
在实体管理器关闭之前为总是true。
1.1.23 EntityTransaction getTransaction()
方法功能：
返回资源级的EntityTransaction对象。EntityTransaction实例可以串行地用于开始和提交多个事务。
返回结果：
返回EntityTransaction类对象。
方法异常：
java.lang.IllegalStateException - 如果在JTA类型的实体管理器上调用此方法，则抛出此异常。
1.1.24 EntityManagerFactory getEntityManagerFactory()
方法功能：
为当前实体管理器返回实体管理器工厂。
返回结果：
返回EntityManagerFactory实 例
方法异常：
java.lang.IllegalStateException - 如果实体管理器已关闭，调用此方法则抛出该异常。
本方法是在Java Persistence 2.0开始加入的。
1.1.25 QueryBuilder getQueryBuilder()
方法功能：
返回用于创建CriteriaQuery对象的QueryBuilder实例。
返回结果：
返回QueryBuilder类型实例。
方法异常：
IllegalStateException-如果实体管理器已关闭，调用此方法时抛出该异常。
本方法是在Java Persistence 2.0开始加入的。
1.1.26 Metamodel getMetamodel()
方法功能：
返回一个Metamodel接口实例，用于访问持久性单元的元模型。
返回结果：
返回Metamodel实例。
方法异常：
IllegalStateException-如果实体管理器已关闭，调用此方法时抛出该异常。
本方法是在Java Persistence 2.0开始加入的。
至此，EntityManager接口的API功能详细参考就介绍完了。
下一篇，将综合应用几个核心接口及相关类，
来构建一个JPA项目，较全面的应用几个核心组件接口。