JPA核心接口EntityManager之API功能详解(三)

JPA入门精要系列：

（1）：JPA框架组件核心组成

（2）：EntityManager概要及API一览表

（3）：EntityManager API功能详解(二)

本文由牛旦教育原创出品，欢迎收藏、点赞、分享。

转载请注明来源@牛旦教育IT课堂

EntityManager常用方法详解

续EntityManager API功能详解(二)

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项目，较全面的应用几个核心组件接口。