JPA 批注4

@OrderBy

默认情况下，JPA 持续性提供程序按关联实体的主键以升序顺序检索 Collection 关联的成员。

将 @OrderBy 批注与 和 一起使用以便：

• 指定一个或多个作为排序依据的其他字段或属性

• 为每个这样的字段或属性名指定不同的排序（升序或降序）

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

表 1-31 @OrderBy 属性

属性	必需	说明
value		默认值：JPA 持续性提供程序按关联实体的主键以升序顺序检索 Collection 关联的成员。 如果要按某些其他字段或属性排序并指定了不同的排序，则将 value 设置为以下元素的逗号分隔列表："property-or-field-name ASC|DESC”（请参阅）。

显示了如何使用 @OrderBy 批注指定 Project 方法 getEmployees 应按 Employee 字段 lastname 以升序顺序并按 Employee 字段 seniority 以降序顺序返回 Employee 的 List。 显示了默认情况下，Employee 方法 getProjects 按 Employee 主键 empId 以升序顺序返回 List。

示例 1-65 Project 实体

@Entity public class Project {
    ...
@ManyToMany
@OrderBy("lastname ASC", "seniority DESC")
public List getEmployees() {
    ...
    };
    ...
}

示例 1-66 Employee 实体

@Entity public class Employee {
@Id
private int empId;
    ...
private String lastname;
    ...
private int seniority;
    ...
@ManyToMany(mappedBy="employees")
// By default, returns a List in ascending order by empId
public List getProjects() {
    ...
    };
    ...
}

@PersistenceContext

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

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

• 使用相关性注入

• 使用 JNDI 查找按名称进行

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

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

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

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

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

表 1-32 @PersistenceContext 属性

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

显示了如何使用此批注在无状态会话中注入实体管理器， 显示了如何使用此批注在 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

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

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

表 1-33 @PersistenceContexts 属性

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

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

示例 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 持续性提供程序假设您使用 获取的实体管理器将使用默认属性。

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

• 自定义实体管理器行为

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

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

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

表 1-34 @PersistenceProperty 属性

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

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

示例 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 持续性提供程序使用与默认持续性单元或您使用 属性 unitName 指定的持续性单元关联的默认 EntityManagerFactory。

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

• 获取指定的实体管理器

• 指定 EntityManagerFactory 和持续性单元

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

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

表 1-35 @PersistenceUnit 属性

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

显示了如何使用 @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);
    }
}

显示了一个使用 属性 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

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

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

表 1-36 @PersistenceUnits 属性

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

显示了如何使用此批注指定两个持续性单元。在该示例中， 属性 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（请参阅 ）扩展另一个实体时，JPA 持续性提供程序假设子类的外键列与超类主表的主键列同名。

使用 @PrimaryKeyJoinColumn 批注：

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

• 使用 批注将辅助表连接到主表

• 在 映射中，引用实体的主键用作被引用实体的外键。

• 使用复合外键（请参阅 ）

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

表 1-37 @PrimaryKeyJoinColumn 属性

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

显示了一个实体基类 Customer， 显示了如何使用 @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 @PrimaryKeyJoinColumns 属性

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

显示了如何使用此批注指定一个由列 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 { 
    ... 
}