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

JPA入门精要系列：

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

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

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

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

1.1常用方法详解

1.1.1 void persist(java.lang.Object entity)

本方法的主要功能，是实现有效实体对象的持久化，即对实例托管并持久化到数据库。

参数：entity，为用户定义的实体实例（或叫实例对象）。

异常：此方法有三种可能的异常抛出，即

• 其一，EntityExistsException –如果实体已存在，则抛出此异常。进一步讲，如果实体已经存在，在调用persist操作时可能会抛出EntityExistsException，或者在刷新或提交时抛出EntityExistsException或另一个PersistenceException。
• 其二，java.lang.IllegalArgumentException：如果实例不是一个有效的实体对象，则抛出此错误。
• 其三，TransactionRequiredException：如果在类型为PersistenceContextType.TRANSACTION 的容器托管的实体管理器上调用此方法，将导致事务失败。

1.1.2 <T> T merge(T entity)

该方法将给定实体的状态合并到当前持久性上下文中。

参数：entity，为实体实例对象；

返回值：合并后的托管实例；

异常情况：

• IllegalArgumentException ：若实例非实体实例或已删除的实体实例，则抛此异常；
• TransactionRequiredException：若在类型为PersistenceContextType.TRANSACTION的容器托管实体管理器上调用此方法，且无事务时，这抛出此异常

1.1.3 void remove(java.lang.Object entity)

调用此方法删除实体实例对象。

参数：entity为删除的实体实例；

方法异常：

• IllegalArgumentException ：如删除的实例不是有效实体或已分离的实体（不受实体管理器管理），则抛出此异常；
• TransactionRequiredException：若在类型为PersistenceContextType.TRANSACTION的容器托管实体管理器上调用此方法，且无事务时，这抛出此异常

1.1.4 <T> T find(java.lang.Class<T> entityClass, java.lang.Object primaryKey)

此方法根据指定的主键查找数据库并生成对应唯一实体返回。也就是说实体管理器会在相应的持久化上下文中查找指定了类和主键的实体，如果上下文上下文中包含，就返回。

参数：

entityClass-实体类，primaryKey-实体唯一主键；

返回值：

找到的实体对象，若没找到则返回null；

方法异常：

IllegalArgumentException:如果第一个参数不表示一个实体类型或第二个参数不是一个有效的实体主键类型或为空，则方法抛出此异常。

1.1.5 <T> T find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, java.util.Map<java.lang.String,java.lang.Object> properties)

功能：使用指定的属性,通过主键查找。换句话说，搜索指定类和主键的实体。如果实体实例包含在持久性上下文中，则从那里返回。如果某个特定于供应商的属性或提示（property和hint）不被识别，它将被默认忽略。

参数：

entityClass-实体类，primaryKey-实体唯一主键；properties标准和特定厂商属性。

返回值：返回找到的实体，若不存在，则返回null。

方法异常：

IllegalArgumentException:如果第一个参数不表示一个实体类型或第二个参数不是一个有效的实体主键类型或为空，则方法抛出此异常。

注：此方法是从Java Persistence 2.0开始加入的。

1.1.6 <T> T find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, LockModeType lockMode)

按主键和锁类型查找。搜索指定类和主键的实体，并根据指定的锁类型将其锁定。如果实体实例包含在持久性上下文中，那么它将从持久性上下文中返回，并且此方法的效果与对实体调用锁方法的效果相同。

如果在持久性上下文中发现实体，并且该实体的锁模式类型是悲观锁，并且该实体具有version属性，则持久化提供器在获取数据库锁时必须执行乐观锁的版本检查。如果这些检查失败，将抛出OptimisticLockException。

如果锁模式类型是悲观的，并且找到了实体实例，但无法锁定，则:

-如果由于数据库锁定失败导致事务级回滚，则会抛出PessimisticLockException异常；

-如果由于数据库锁定失败只导致语句级回滚，那么将抛出LockTimeoutException异常。

方法参数：

entityClass –实体类

primaryKey –实体主键

lockMode –锁模式

返回值：

返回找到的实体实例，如果不存在则返回null。

方法异常：

• ü java.lang.IllegalArgumentException - 如果第一个参数不表示实体类型，或者第二个参数不是该实体主键的有效类型，或者为null，则抛出此异常。
• ü TransactionRequiredException -如果没有事务，但却指定了非NONE的锁模式，则抛出此异常。
• ü OptimisticLockException - 如果乐观锁版本检查失败，则抛出此异常
• ü PessimisticLockException - 如果悲观锁失败，事务被回滚，则抛出此异常。
• ü LockTimeoutException -如果悲观锁定失败，并且只回滚语句，则抛出此异常。
• ü PersistenceException - 如果调用了不支持的锁被，则抛出此异常。

此方法从Java Persistence 2.0开始

1.1.7 <T> T find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, LockModeType lockMode, java.util.Map<java.lang.String,java.lang.Object> properties)

使用指定的属性，通过主键和锁查找。搜索指定类和主键的实体，并根据指定的锁类型将其锁定。如果实体实例包含在持久性上下文中，则从那里返回；

如果在持久性上下文中发现实体，并且该实体的锁模式类型是悲观的，并且该实体具有version属性，则持久性提供器在获取数据库锁时必须执行乐观版本检查。如果这些检查失败，将抛出OptimisticLockException。

如果锁模式类型是悲观的，并且找到了实体实例，但无法锁定时:

• l 如果数据库锁定失败导致了事务级回滚，则会抛出PessimisticLockException异常；
• l 如果数据库锁定失败只导致了语句级回滚，那么将抛出LockTimeoutException异常；

另外，如果某个特定于供应商的属性或提示不被识别，它将被默认忽略。

可移植应用不应该依赖于标准的超时提示。根据使用的数据库和提供器使用的锁定机制，可能观察到提示，也可能不观察到提示。

方法参数：

entityClass -实体类型

primaryKey -实体主键

lockMode -锁模式

properties - 标准和特定于供应商的属性和提示

返回值：

返回找到的实体实例，如果不存在则返回null。

方法可能抛出的异常：

• l java.lang.IllegalArgumentException -如果第一个参数不表示实体类型，或者第二个参数不是该实体主键的有效类型，或者为null是抛出；
• l TransactionRequiredException - 如果没有事务，而指定了非NONE的锁模式时则抛出；
• l OptimisticLockException - 如果乐观版本检查失败时则抛出；
• l PessimisticLockException - 如果悲观锁定失败，并且事务被回滚时则抛出；
• l LockTimeoutException - 如果悲观锁定失败，并只回滚语句时则抛出；
• l PersistenceException - 如果不支持锁调用时则抛出。

本方法从Java Persistence 2.0开始加入。

1.1.8 <T> T getReference(java.lang.Class<T> entityClass, java.lang.Object primaryKey)

获取一个实例，其状态可能被延迟获取。如果请求的实例在数据库中不存在，则在第一次访问实例状态时抛出EntityNotFoundException。(当调用getReference时，持久性提供器运行时允许抛出EntityNotFoundException。)应用程序不应期望实例状态在分离时可用，除非应用程序在实体管理器打开时访问了它。

方法参数：

-entityClass -实例类

-primaryKey -实例主键

方法返回值：

返回找到的实体实例。

方法可能抛出的异常：

java.lang.IllegalArgumentException - 如果第一个参数不表示一个实体类型或第二个参数不是一个有效的实体的主键类型或者是null;

EntityNotFoundException - 如果无法访问实体状态。

1.1.9 void flush()

本方法的功能是将持久性上下文与底层数据库同步。

方法可能抛出的异常：

TransactionRequiredException - 如果没有事务（要求事务）；

PersistenceException - 刷新失败时；

1.1.10 void setFlushMode(FlushModeType flushMode)

设置应用于持久性上下文中包含的所有对象的刷新模式。

方法参数：

flushMode – 两个可选值：javax.persistence.FlushModeType.AUTO javax.persistence.FlushModeType.COMMIT，默认是AUTO，即查询时刷新；COMMIT为在事务提交时刷新。

本方法无返回值。

1.1.11 FlushModeType getFlushMode()

本方法用于获取应用于持久性上下文中包含的所有对象的刷新模式。

方法返回值：返回刷新模式值，类型为javax.persistence.FlushModeType的flushMode。

1.1.12 void lock(java.lang.Object entity,LockModeType lockMode)

方法功能描述：

使用指定的锁定模式类型锁定持久性上下文中包含的某一实体实例。

如果指定了悲观锁模式类型，并且实体包含version属性，那么持久性提供者在获取数据库锁时也必须执行乐观版本检查。如果这些检查失败，将抛出OptimisticLockException。

如果锁模式类型是悲观的，并且找到了实体实例，但无法锁定时:

-如果数据库锁定失败导致事务级回滚，则抛出悲观锁异常（PessimisticLockException）;

-如果数据库锁定失败仅导致语句级回滚，则会引发锁超时异常（LockTimeoutException）;

方法参数：

entity –实体对象；

lockMode –锁模式，类型是枚举类型javax.persistence.LockModeType。根据需要，可以通过将LockModeType参数传递给接受锁(Lock、find或refresh)的EntityManager方法之一或传递给Query.setLockMode()方法来指定锁模式。

锁模式可用于指定乐观锁或悲观锁。主要可选择值如下表：

方法可能抛出的异常：

• ? IllegalArgumentException：如果实例不是一个实体或者是一个分离的实体;
• ? TransactionRequiredException—如果没有事务（要求需要事务）;
• ? EntityNotFoundException—如果在执行悲观锁定时数据库中不存在该实体;
• ? OptimisticLockException—如果乐观版本检查失败;
• ? PessimisticLockException—如果悲观锁失败，事务被回滚;
• ? LockTimeoutException——如果悲观锁定失败，并且只有语句被回滚;
• ? PersistenceException——如果不支持锁调用;

1.1.13 void lock(java.lang.Object entity, LockModeType lockMode, java.util.Map<java.lang.String,java.lang.Object> properties)

功能说明：

使用指定的锁模式类型和指定的属性锁定持久性上下文中包含的实体实例。其它方面和上方法类是。

方法参数：

和上一方相同，多了properties参数，指标准和特定于供应商的属性和提示信息

方法异常：

同上一方法。

本方法从Java Persistence2.0开始加入的。

1.1.14 void refresh(java.lang.Object entity)

功能说明：

从数据库中刷新实例的状态、覆盖对当前实体所做的更改(如果有的话)。

方法参数：

entity-指定的刷新实体对象。

方法异常：

调用此方法可能会抛出如下相关异常：

• ? IllegalArgumentException:如果实例不是有效实体或者非受管实体;
• ? TransactionRequiredException：如果在PersistenceContextType.TRANSACTION类型的容器管理的实体管理器上调用，并且无事务;
• ? EntityNotFoundException：如果实体在数据库中不再存在，则抛此异常。

1.1.15 void refresh(java.lang.Object entity, java.util.Map<java.lang.String,java.lang.Object> properties)

功能说明：

使用指定的属性从数据库中刷新实例的状态，并覆盖对实体所做的更改(如果有的话)。如果某个特定于供应商的属性或提示不被识别，它将被默认忽略。

方法参数：

entity -指定的待要刷新的实体；

properties - 标准的和特定厂商的属性。

方法异常：

• ? IllegalArgumentException:如果实例不是有效实体或者非受管实体;
• ? TransactionRequiredException：如果在PersistenceContextType.TRANSACTION类型的容器管理的实体管理器上调用，并且无事务;
• ? EntityNotFoundException：如果实体在数据库中不再存在，则抛此异常。

本方法从Java Persistence 2.0开始加入。

内容偏多，本篇就先到这里，下一篇补充完整补充完整。——未完，待续~~