JPA 批注参考(6)

来源：www.oracle.com
■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
本文的主要内容如下：

详细解释了下面10个批注的含义及其批注所包含的属性：
@PersistenceContext
@PersistenceContexts
@PersistenceProperty
@PersistenceUnit
@PersistenceUnits
@PrimaryKeyJoinColumn
@PrimaryKeyJoinColumns
@QueryHint
@SecondaryTable
@SecondaryTables
■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■

 

@PersistenceContext

在使用 JPA 持续性提供程序的应用程序中，可以使用实体管理器执行所有持续性操作（创建、读取、更新和删除）。Java EE 应用程序使用相关性注入或在 JNDI 名称空间中直接查找实体管理器获取实体管理器。

使用 @PersistenceContext 批注获取实体管理器：

● 使用相关性注入

● 使用 JNDI 查找按名称进行

● 与特定的持续性单元关联（另请参阅 @PersistenceUnit）

● 具有扩展的持续性上下文

● 使用特定的持续性属性进行了自定义（请参阅 @PersistenceProperty）

如果有多个要指定的 @PersistenceContext，则必须使用 @PersistenceContexts。

表 1-32 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-32 @PersistenceContext 属性

属性

必需

说明

name		默认值：JPA 持续性提供程序检索默认实体管理器。 如果要注入或查找特定实体管理器，请将 name 设置为要使用的实体管理器的 String 名称。 对于相关性注入，不需要 name。 对于 JNDI 查找，必须将 name 设置为要在环境引用上下文中访问实体管理器所使用的名称。
properties		默认值：JPA 持续性提供程序假设实体管理器将使用默认属性。 如果要配置包含供应商特定属性的 JPA 持续性提供程序属性（例如，请参阅 “TopLink JPA Persistence.xml 文件扩展”），请将 properties 设置为 @PersistenceProperty 实例数组。
type		默认值：PersistenceContextType.TRANSACTION。 默认情况下，JPA 持续性提供程序假设实体管理器是容器管理的，并且它们的持续性上下文的生命周期伸缩到一个事务：即，持续性上下文在事务启动时开始存在，并在事务提交时停止存在。 在以下条件下，将 type 设置为 PersistenceContextType.EXTENDED： ● 您的持续性上下文是应用程序管理的 ● 您希望扩展的持续性上下文在 EntityManager 实例从创建一直到关闭期间存在 ● 您希望实体管理器在事务提交后维护对实体对象的引用 ● 您希望调用 EntityManager 方法 persist、remove、merge 和 refresh，而不论事务是否处于活动状态
unitName		默认值：JPA 持续性提供程序检索默认持续性单元的默认实体管理器。 如果要注入或查找与特定持续性单元关联的实体管理器，则将 unitName 设置为所需的 String 持续性单元名称。或者，如果要指定 EntityManagerFactory 和持续性单元，则可以使用 @PersistenceUnit。 对于相关性注入，不需要 unitName。 对于 JNDI 查找，如果指定 unitName，则由 name 访问的实体管理器必须与此持续性单元关联。

示例 1-67 显示了如何使用此批注在无状态会话中注入实体管理器，示例 1-68 显示了如何使用此批注在 JNDI 中查找实体管理器。

示例 1-67 使用 @PersistenceContext 和相关性注入

@Stateless
public class OrderEntryBean implements OrderEntry {
@PersistenceContext
EntityManager em;
public void enterOrder(int custID, Order newOrder) {
Customer cust = em.find(Customer.class, custID);
cust.getOrders().add(newOrder);
newOrder.setCustomer(cust);
    }
}

示例 1-68 使用 @PersistenceContext 和 JNDI 查找

@Stateless
public class OrderEntryBean implements OrderEntry {
@PersistenceContext(name="OrderEM")
EntityManager em;
public void enterOrder(int custID, Order newOrder) {
em = (EntityManager)ctx.lookup("OrderEM");
Customer cust = em.find(Customer.class, custID);
cust.getOrders().add(newOrder);
newOrder.setCustomer(cust);
    }
}

@PersistenceContexts

如果要指定多个 @PersistenceContext，则必须使用一个 @PersistenceContexts 批注指定所有持续性上下文。

表 1-33 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-33 @PersistenceContexts 属性

属性

必需

说明

value		要指定两个或更多持续性上下文，请将 value 设置为 PersistenceContext 实例数组（请参阅 @PersistenceContext）。

示例 1-69 显示了如何使用此批注指定两个持续性上下文。

示例 1-69 @PersistenceContexts

@Stateless
public class OrderEntryBean implements OrderEntry {
@PersistenceContexts({
@PersistenceContext(name="OrderEM")
@PersistenceContext(name="ItemEM"),
    })
public void enterOrder(int custID, Order newOrder) {
EntityManager em = (EntityManager)ctx.lookup("OrderEM");
Customer cust = em.find(Customer.class, custID);
cust.getOrders().add(newOrder);
newOrder.setCustomer(cust);
    }
public void enterItem(int orderID, Item newItem) {
EntityManager em = (EntityManager)ctx.lookup("ItemEM");
    ...
    }
}

@PersistenceProperty

默认情况下，JPA 持续性提供程序假设您使用 @PersistenceContext 获取的实体管理器将使用默认属性。

使用 @PersistenceProperty 批注指定属性（包括供应商特定的属性），以便容器或持续性提供程序：

● 自定义实体管理器行为

● 利用供应商的 JPA 持续性提供程序实现中的特定特性

创建实体管理器时将属性传递给持续性提供程序。无法识别的属性被简单地忽略。

表 1-34 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-34 @PersistenceProperty 属性

属性

必需

说明

name		要指定持续性属性的名称，请将 name 设置为 String 属性名。 有关持续性属性的详细信息，请参阅 JPA 持续性提供程序文档。
value		要指定持续性属性的值，请将 value 设置为所需的 String 属性值。 有关持续性属性值的详细信息，请参阅 JPA 持续性提供程序文档。

示例 1-70 显示了如何使用 @PersistenceProperty 批注自定义查询以利用由 TopLink Essentials 提供的供应商 JPA 扩展：在该示例中，该属性确保在此持续性上下文中使用一个完整的 TopLink 缓存。有关详细信息，请参阅 “TopLink JPA Persistence.xml 文件扩展” 。

示例 1-70 @PersistenceProperty

@Stateless
public class OrderEntryBean implements OrderEntry {
@PersistenceContext(
properties={
@PersistenceProperty={name="toplink.cache.type.default", value="CacheType.Full"}
        }
    )
EntityManager em;
public void enterOrder(int custID, Order newOrder) {
Customer cust = em.find(Customer.class, custID);
cust.getOrders().add(newOrder);
newOrder.setCustomer(cust);
    }
}

@PersistenceUnit

默认情况下，JPA 持续性提供程序使用与默认持续性单元或您使用 @PersistenceContext 属性 unitName 指定的持续性单元关联的默认 EntityManagerFactory。

使用 @PersistenceUnit 批注指定EntityManagerFactory，您希望 JPA 持续性提供程序使用它来：

● 获取指定的实体管理器

● 指定 EntityManagerFactory 和持续性单元

如果有多个要指定的 @PersistenceUnit，则必须使用 @PersistenceUnits。

表 1-35 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-35 @PersistenceUnit 属性

属性

必需

说明

name		默认值：JPA 持续性提供程序从默认 EntityManagerFactory 中获取它的 EntityManager 实例。 如果希望 JPA 持续性提供程序在注入或查找实体管理器时使用特定的 EntityManagerFactory，请将 name 设置为所需的实体管理器工厂的 String 名称。 对于相关性注入，不需要 name。 对于 JNDI 查找，必须将 name 设置为要在环境引用上下文中访问实体管理器所使用的名称。
unitName		默认值：JPA 持续性提供程序检索默认持续性单元的默认实体管理器。 如果要注入或查找与特定持续性单元关联的实体管理器，则将 unitName 设置为所需的 String 持续性单元名称。另请参阅 @PersistenceContext。 对于相关性注入，不需要 unitName。 对于 JNDI 查找，如果指定 unitName，则由 name 访问的 EntityManagerFactory 必须与此持续性单元关联。

示例 1-71 显示了如何使用 @PersistenceUnit 批注指定要使用的 EntityManagerFactory 的 JNDI 名称以及与该工厂关联的持续性单元名称。当 JPA 持续性提供程序使用 JNDI 获取一个使用持续性上下文 OrderEM 的实体管理器时，它将使用 JNDI 名称 OrderEMFactory 与持续性单元 OrderEMUnit 关联的 EntityManagerFactory。

示例 1-71 使用 @PersistenceUnit 指定工厂和单元

@Stateless
public class OrderEntryBean implements OrderEntry {
@PersistenceContext(name="OrderEM")
@PersistenceUnit(name="OrderEMFactory", unitName="OrderEMUnit")
EntityManager em;
public void enterOrder(int custID, Order newOrder) {
em = (EntityManager)ctx.lookup("OrderEM");
Customer cust = em.find(Customer.class, custID);
cust.getOrders().add(newOrder);
newOrder.setCustomer(cust);
    }
}

示例 1-72 显示了一个使用 @PersistenceContext 属性 unitName 仅指定持续性单元的其他方法。在该示例中，当 JPA 持续性提供程序使用 JNDI 获取一个使用持续性上下文 OrderEM 的实体管理器时，它将使用与持续性单元 OrderEMUnit 关联的默认 EntityManagerFactory。

示例 1-72 使用 @PersistenceContext 属性 unitName

@Stateless
public class OrderEntryBean implements OrderEntry {
@PersistenceContext(name="OrderEM", unitName="OrderEMUnit")
EntityManager em;
public void enterOrder(int custID, Order newOrder) {
em = (EntityManager)ctx.lookup("OrderEM");
Customer cust = em.find(Customer.class, custID);
cust.getOrders().add(newOrder);
newOrder.setCustomer(cust);
    }
}

@PersistenceUnits

如果要指定多个 @PersistenceUnit，则必须使用一个 @PersistenceUnits 批注指定所有持续性上下文。

表 1-36 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-36 @PersistenceUnits 属性

属性

必需

说明

value		要指定两个或更多持续性单元，请将 value 设置为 PersistenceUnit 实例数组（请参阅 @PersistenceUnit）。

示例 1-73 显示了如何使用此批注指定两个持续性单元。在该示例中，@PersistenceContext 属性 unitName 和 @PersistenceUnit 属性 unitName 必须对应以便关联持续性上下文和持续性单元。

示例 1-73 @PersistenceUnits

@Stateless
public class OrderEntryBean implements OrderEntry {
@PersistenceContexts({
@PersistenceContext(name="OrderEM", unitName="OrderEMUnit")
@PersistenceContext(name="ItemEM", unitName="ItemEMUnit"),
    })
@PersistenceUnits({
@PersistenceUnit(name="OrderEMFactory", unitName="OrderEMUnit"),
@PersistenceUnit(name="ItemEMFactory", unitName="ItemEMUnit")
    })
public void enterOrder(int custID, Order newOrder) {
EntityManager em = (EntityManager)ctx.lookup("OrderEM");
Customer cust = em.find(Customer.class, custID);
cust.getOrders().add(newOrder);
newOrder.setCustomer(cust);
    }
public void enterItem(int orderID, Item newItem) {
EntityManager em = (EntityManager)ctx.lookup("ItemEM");
    ...
    }
}

@PrimaryKeyJoinColumn

默认情况下，当一个实体使用 InheritanceType.JOINED（请参阅 @Inheritance）扩展另一个实体时，JPA 持续性提供程序假设子类的外键列与超类主表的主键列同名。

使用 @PrimaryKeyJoinColumn 批注：

● 如果子类的外键列与该情形中超类的主表的主键列不同名

● 使用 @SecondaryTable 批注将辅助表连接到主表

● 在 @OneToOne 映射中，引用实体的主键用作被引用实体的外键

● 使用复合外键（请参阅 @PrimaryKeyJoinColumns）

表 1-37 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-37 @PrimaryKeyJoinColumn 属性

属性

必需

说明

columnDefinition		默认值：空 String。 默认情况下，JPA 使用最少量 SQL 创建一个数据库表列。 如果需要使用更多指定选项创建的列，请将 columnDefinition 设置为在生成列的 DDL 时希望 JPA 使用的 String SQL 片断。 不要将此属性与 @OneToOne 映射一起使用。
name		默认值：JPA 持续性提供程序对当前表的主键列采用以下名称之一（取决于您使用该批注的方式）： ● InheritanceType.JOINED（请参阅 @Inheritance）：与超类的主键列同名。 ● @SecondaryTable 映射：与主表的主键列同名。 ● @OneToOne 映射：与引用实体的表的主键列同名。 如果该名称难于处理、是一个保留字、与事先存在的数据模型不兼容或作为数据库中的列名无效，则将 name 设置为所需的 String 列名。
referencedColumnName		默认值：JPA 持续性提供程序对连接到的表的主键列采用以下名称之一（取决于您使用该批注的方式）： ● InheritanceType.JOINED（请参阅 @Inheritance）：与超类的主表的主键列同名。 ● @SecondaryTable 映射：与主表的主键列同名。 ● @OneToOne 映射：与被引用实体的表的主键列同名。 ● 如果该名称难于处理、是一个保留字、与预先存在的数据模型不兼容或作为数据库中的列名无效，请将 referencedColumnName 设置为所需的 String 列名。

示例 1-74 显示了一个实体基类 Customer，示例 1-75 显示了如何使用 @PrimaryKeyJoinColumn 在 ValuedCustomer（Customer 的一个子类）的主表中指定主键连接列 CUST_ID。

示例 1-74 @PrimaryKeyJoinColumn - InheritanceType.JOINED 超类

@Entity
@Table(name="CUST")
@Inheritance(strategy=JOINED)
@DiscriminatorValue("CUST")
public class Customer {
    ...
}

示例 1-75 @PrimaryKeyJoinColumn - InheritanceType.JOINED 子类

@Entity
@Table(name="VCUST")
@DiscriminatorValue("VCUST")
@PrimaryKeyJoinColumn(name="CUST_ID")
public class ValuedCustomer extends Customer {
    ...
}

@PrimaryKeyJoinColumns

默认情况下，JPA 持续性提供程序假设每个实体有一个单列主键。

如果要指定一个由两个或更多列组成的主键，请使用 @PrimaryKeyJoinColumns 批注。

表 1-38 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-38 @PrimaryKeyJoinColumns 属性

属性

必需

说明

value		要指定一个复合（多列）主键，请将 value 设置为 PrimaryKeyJoinColumn 实例的数组（请参阅 @PrimaryKeyJoinColumn）。

示例 1-76 显示了如何使用此批注指定一个由列 CUST_ID 和 CUST_TYPE 组成的复合主键。

示例 1-76 @PrimaryKeyJoinColumns

@Entity
@Table(name="VCUST")
@DiscriminatorValue("VCUST")
@PrimaryKeyJoinColumns({
@PrimaryKeyJoinColumn(name="CUST_ID",referencedColumnName="ID"),
@PrimaryKeyJoinColumn(name="CUST_TYPE",referencedColumnName="TYPE")
})
public class ValuedCustomer extends Customer {
    ...
}

@QueryHint

默认情况下，JPA 持续性提供程序假设 @NamedQuery 或 @NamedNativeQuery 应完全按照查询 String 指定的方式执行。

使用 @QueryHint 批注指定供应商特定的 JPA 查询扩展，以：

● 提高查询性能

● 利用供应商的 JPA 持续性提供程序实现中的特定特性

表 1-39 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-39 @QueryHint 属性

属性

必需

说明

name		要指定提示名称，请将 name 设置为 String 提示名称。 有关提示的详细信息，请参阅 JPA 持续性提供程序文档。
value		要指定提示的值，请将 value 设置为所需的 String 提示值。 有关提示值的详细信息，请参阅 JPA 持续性提供程序文档。

示例 1-77 显示了如何使用 @QueryHint 批注自定义查询以利用由 TopLink Essentials 提供的供应商 JPA 扩展：在该示例中，提示确保在执行查询时始终刷新 TopLink 缓存。有关详细信息，请参阅 “TopLink JPA 查询提示扩展”。

示例 1-77 @QueryHint

@Entity
@NamedQuery(
name="findAllEmployees",
query="SELECT * FROM EMPLOYEE WHERE MGR=1"
hints={@QueryHint={name="toplink.refresh", value="true"}}
)
public class Employee implements Serializable {
    ...
}

@SecondaryTable

默认情况下，JPA 持续性提供程序假设实体的所有持久字段均存储到一个名称为实体名称的数据库表中：该表称作主表（请参阅 @Table）。

如果希望 JPA 分别将实体的某些持久字段持久保存到主表和其他数据库表，请使用 @SecondaryTable 批注将实体与其他数据库表关联。在该示例中，您使用 @Column 批注将实体的持久字段与表关联。

如果要将两个或更多辅助表与实体关联，则可以使用 @SecondaryTables。

表 1-40 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-40 @SecondaryTable 属性

属性

必需

说明

name		如果实体使用辅助表，请将 name 设置为 String 表名。
catalog		默认值：JPA 持续性提供程序使用任何适用于数据库的默认目录。 如果默认目录不适合于应用程序，请将 catalog 设置为要使用的 String 目录名。
pkJoinColumns		默认值：JPA 持续性提供程序假设实体的数据库表中的任何列均不用于主键连接。 如果对该表中的主键连接使用一个或多个列，请将 pkJoinColumns 设置为一个或多个 @PrimaryKeyJoinColumn 实例的数组。有关详细信息，请参阅 @PrimaryKeyJoinColumn。
schema		默认值：JPA 持续性提供程序使用任何适用于数据库的默认模式。 如果默认模式不适合于应用程序，请将 schema 设置为要使用的 String 模式名。
uniqueConstraints		默认值：JPA 持续性提供程序假设实体的数据库表中的任何列均没有唯一约束。 如果唯一约束应用于该表中的一列或多列，请将 uniqueContraints 设置为一个或多个 UniqueConstraint 实例的数组。有关详细信息，请参阅 @UniqueConstraint。

示例 1-78 显示了如何使用此批注指定一个名为 EMP_HR 的辅助表。在该示例中，默认情况下，JPA 将实体持久字段 empId 持久保存到名为 Employee 的主表中的列 empId，并将 empSalary 持久保存到辅助表 EMP_HR 中的列 empSalary。有关详细信息，请参阅 @Column。

示例 1-78 @SecondaryTable

@Entity
@SecondaryTable(name="EMP_HR")
public class Employee implements Serializable {
    ...
private Long empId;

@Column(table="EMP_HR", name="EMP_SALARY"))
private Float empSalary;
    ...
}

@SecondaryTables

如果需要指定多个 @SecondaryTable，可以使用一个 @SecondaryTables 批注指定所有辅助表。

表 1-41 列出了此批注的属性。有关更多详细信息，请参阅 API。

表 1-41 @SecondaryTables 属性

属性

必需

说明

value		要指定两个或更多辅助表，请将 value 设置为 SecondaryTable 实例的数组（请参阅 @SecondaryTable）。

示例 1-79 显示了如何使用此批注指定两个名为 EMP_HR 和 EMP_TR 的辅助表。在该示例中，默认情况下，JPA 将实体持久字段 empId 持久保存到名为 Employee 的主表中的列 empId。JPA 将 empSalary 持久保存到辅助表 EMP_HR 中的列 empSalary，并将 empClass 持久保存到辅助表 EMP_TR 中的列 EMP_HR。有关详细信息，请参阅 @Column。

示例 1-79 @SecondaryTables

@Entity
@SecondaryTables({
@SecondaryTable(name="EMP_HR"),
@SecondaryTable(name="EMP_TR")
    })
public class Employee implements Serializable {
    ...
private Long empId;

@Column(table="EMP_HR", name="EMP_SALARY"))
private Float empSalary;

@Column(table="EMP_TR", name="EMP_CLASS"))
private Float empClass;
    ...
}