@Column
默认情况下，JPA 持续性提供程序假设每个实体的持久字段存储在其名称与持久字段的名称相匹配的数据库表列中。
使用 @Column 批注：
表 1-7 列出了此批注的属性
示例 1-8 显示了如何使用此批注使 JPA 将 empId 持久保存到辅助表 EMP_HR 中的列 EMP_NUM。默认情况下，JPA 将 empName 持久保存到主表 Employee 中的列 empName。
示例 1-8 @Column
@Entity
@SecondaryTable(name="EMP_HR")
public class Employee implements Serializable {
...
@Column(name="EMP_NUM", table="EMP_HR")
private Long empId;
private String empName;
...
}
@ColumnResult
执行 @NamedNativeQuery 时，它可以返回实体（包括不同类型的实体）、标量值或实体和标量值的组合。
使用 @ColumnResult 批注返回标量值。标量类型由您在 @ColumnResult 中标识的列类型确定。
有关详细信息，另请参阅 @EntityResult、@FieldResult 和 @SqlResultSetMapping。
表 1-8 列出了此批注的属性
示例 1-9 显示了如何使用此批注将 Item（请参阅示例 1-10）标量 name 包含在结果列表（请参阅示例 1-11）中。在该示例中，结果列表将为 Object 数组的 List，如：{[Order, "Shoes"], [Order, "Socks"], ...}。
示例 1-9 使用 @ColumnResult 的 Order 实体
@SqlResultSetMapping(
name="OrderResults",
entities={
@EntityResult(
entityClass=Order.class,
fields={
@FieldResult(name="id", column="order_id"),
@FieldResult(name="quantity", column="order_quantity"),
@FieldResult(name="item", column="order_item")
}
)
},
columns={
@ColumnResult(
name="item_name"
)
}
)
@Entity
public class Order {
@Id
protected int id;
protected long quantity;
protected Item item;
...
}
示例 1-10 Item 实体
@Entity
public class Item {
@Id
protected int id;
protected String name;
...
}
示例 1-11 结合使用 @SqlResultSetMapping 与 @ColumnResult 的原生查询
Query q = entityManager.createNativeQuery(
"SELECT o.id AS order_id, " +
"o.quantity AS order_quantity, " +
"o.item AS order_item, " +
"i.name AS item_name, " +
"FROM Order o, Item i " +
"WHERE (order_quantity > 25) AND (order_item = i.id)",
"OrderResults"
);
List resultList = q.getResultList();
// List of Object arrays:{[Order, "Shoes"], [Order, "Socks"], ...}
@DiscriminatorColumn
默认情况下，当 @Inheritance 属性策略为 InheritanceType.SINGLE_TABLE 或 JOINED 时，JPA 持续性提供程序将创建一个名为 DTYPE 的标识符列以区分继承层次中的类。
使用 @DiscriminatorColumn 批注：
表 1-9 列出了此批注的属性
示例 1-12 显示了如何使用此批注指定一个名为 DISC、类型为 STRING、长度为 20 的标识符列。在本示例中，该类的 @DiscriminatorValue 指定为 CUST。示例 1-13 中的子类将它自己的 @DiscriminatorValue 指定为 VIP。在 Customer 和 ValuedCustomer 中，@DiscriminatorValue 的值必须可以转换为由 @DiscriminatorColumn 属性 discriminatorType 指定的类型，并且必须符合 @DiscriminatorColumn 属性 length。
示例 1-12 @DiscriminatorColumn 和 @DiscriminatorValue — 根类
@Entity
@Table(name="CUST")
@Inheritance(strategy=SINGLE_TABLE)
@DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20)
@DiscriminatorValue(value-"CUST")
public class Customer {
...
}
示例 1-13 @DiscriminatorValue — 子类
@Entity
@DiscriminatorValue(value="VIP")
public class ValuedCustomer extends Customer {
...
}
@DiscriminatorValue
默认情况下，当 @Inheritance 属性策略为 InheritanceType.SINGLE_TABLE 或 JOINED 时，JPA 持续性提供程序使用 @DiscriminatorColumn 按实体名称区分继承层次中的类（请参阅 @Entity）。
使用 @DiscriminatorValue 批注指定用于区分此继承层次中的实体的标识符值：
-
如果实体名称不适合于此应用程序
-
匹配现有的数据库模式
表 1-10 列出了此批注的属性
示例 1-14 显示了如何使用此批注指定一个名为 DISC、类型为 STRING、长度为 20 的标识符列。在本示例中，该类的 @DiscriminatorValue 指定为 CUST。示例 1-15 中的子类将它自己的 @DiscriminatorValue 指定为 VIP。在 Customer 和 ValuedCustomer 中，@DiscriminatorValue 的值必须可以转换为由 @DiscriminatorColumn 属性 discriminatorType 指定的类型，并且必须符合 @DiscriminatorColumn 属性 length。
示例 1-14 @DiscriminatorColumn 和 @DiscriminatorValue — 根类
@Entity
@Table(name="CUST")
@Inheritance(strategy=SINGLE_TABLE)
@DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20)
@DiscriminatorValue(value-"CUST")
public class Customer {
...
}
示例 1-15 @DiscriminatorValue — 子类
@Entity
@DiscriminatorValue(value="VIP")
public class ValuedCustomer extends Customer {
...
}
@Embeddable
默认情况下，JPA 持续性提供程序假设每个实体均持久保存到它自己的数据库表。
使用 @Embeddable 批注指定一个类，该类的实例存储为拥有实体的固有部分并共享该实体的身份。嵌入对象的每个持久属性或字段都将映射到实体的数据库表。
此批注没有属性
示例 1-16 显示了如何使用此批注指定：类 EmploymentPeriod 在用作批注为 @Embedded 的持久字段的类型时可以嵌套到实体中（请参阅示例 1-17）
示例 1-16 @Embeddable
@Embeddable
public class EmploymentPeriod {
java.util.Date startDate;
java.util.Date endDate;
...
}
@Embedded
默认情况下，JPA 持续性提供程序假设每个实体均持久保存到它自己的数据库表。
使用 @Embedded 批注指定一个持久字段，该字段的 @Embeddable 类型可以存储为拥有实体的固有部分，并共享该实体的身份。嵌入对象的每个持久属性或字段均映射到拥有实体的数据库表。
可以结合使用 @Embedded 和 @Embeddable 以建立严格所有权关系的模型，以便在删除了拥有对象的情况下还将删除被拥有的对象。
嵌入的对象不应映射到多个表。
默认情况下，@Embeddable 类中指定的列定义（请参阅 @Column）适用于 @Embedded 类。如果要覆盖这些列定义，请使用 @AttributeOverride。
此批注没有属性。有关更多详细信息，请参阅 API。
示例 1-17 显示了如何使用该批注指定：@Embeddable 类 EmploymentPeriod（请参阅示例 1-16）可以使用指定的属性覆盖（请参阅 @AttributeOverride）嵌入到实体类中。如果不需要属性覆盖，则可以完全忽略 @Embedded 批注：JPA 持续性提供程序将推断出 EmploymentPeriod 是从它的 @Embeddable 批注进行嵌套。
示例 1-17 @Embedded
@Entity
public class Employee implements Serializable {
...
@Embedded
@AttributeOverrides({
@AttributeOverride(name="startDate", column=@Column("EMP_START")),
@AttributeOverride(name="endDate", column=@Column("EMP_END"))
)
public EmploymentPeriod getEmploymentPeriod() {
...
}
...
}
@EmbeddedId
使用 @EmbeddedId 批注指定一个由实体拥有的可嵌入复合主键类（通常由两个或更多基元类型或 JDK 对象类型组成）。从原有数据库映射时（此时数据库键由多列组成），通常将出现复合主键。
复合主键类具有下列特征：
-
它是一个普通的旧式 Java 对象 (POJO) 类。
-
它必须为 public，并且必须有一个 public 无参数构造函数。
-
如果使用基于属性的访问，则主键类的属性必须为 public 或 protected。
-
它必须是可序列化的。
-
它必须定义 equals 和 hashCode 方法。
这些方法的值相等性的语义必须与键映射到的数据库类型的数据库相等性一致。
或者，您可以使复合主键类成为非嵌入类（请参阅 @IdClass）。
此批注没有属性
示例 1-18 显示了一个批注为 @Embeddable 的典型复合主键类。示例1-19 显示了如何使用可嵌入的复合主键类（使用 @EmbeddedId 批注）配置一个实体。
示例 1-18 可嵌入复合主键类
@Embeddable
public class EmployeePK implements Serializable
{
private String name;
private long id;
public EmployeePK()
{
}
public String getName()
{
return name;
}
public void setName(String name)
{
this.name = name;
}
public long getId()
{
return id;
}
public void setId(long id)
{
this.id = id;
}
public int hashCode()
{
return (int) name.hashCode() + id;
}
public boolean equals(Object obj)
{
if (obj == this) return true;
if (!(obj instanceof EmployeePK)) return false;
if (obj == null) return false;
EmployeePK pk = (EmployeePK) obj;
return pk.id == id && pk.name.equals(name);
}
}
示例 1-19 @EmbeddedId
@Entity
public class Employee implements Serializable
{
EmployeePK primaryKey;
public Employee()
{
}
@EmbeddedId
public EmployeePK getPrimaryKey()
{
return primaryKey;
}
public void setPrimaryKey(EmployeePK pk)
{
primaryKey = pk;
}
...
}
@Entity
使用 @Entity 批注将普通的旧式 Java 对象 (POJO) 类指定为实体，并使其可用于 JPA 服务。必须将 POJO 类指定为实体，然后才可以使用任何其他 JPA 批注。
表 1-11 列出了此批注的属性
示例 1-20 显示了该批注的用法。
示例 1-20 @Entity
@Entity
public class Employee implements Serializable {
...
}
@EntityListeners
可以使用生命周期批注（请参阅生命周期事件批注）指定实体中的方法，这些方法在指定的生命周期事件发生时执行您的逻辑。
使用 @EntityListeners 批注将一个或多个实体监听程序类与 @Entity 或 @MappedSuperclass 关联，条件是您需要在指定的生命周期事件发生时执行逻辑，以及：
当实体或子类上发生生命周期事件时，JPA 持续性提供程序将按监听程序定义的顺序通知每个实体监听程序，并调用使用相应的生命周期事件类型进行批注的实体监听程序方法（如果有）。
实体监听程序类具有以下特征：
-
它是一个普通的旧式 Java 对象 (POJO) 类
-
它有一个或多个具有以下签名的回调方法：
public void <MethodName>(Object)
可以指定参数类型 Object，或实体监听程序将与其关联的实体类的类型。
-
它用一个或多个生命周期事件批注对每个回调方法进行批注。
一个生命周期事件只能与一个回调监听程序方法关联，但某个给定的回调监听程序方法可以与多个生命周期事件关联。
如果使用实体监听程序，则可以管理哪些实体监听程序使用 @ExcludeDefaultListeners 和 @ExcludeSuperclassListeners 调用。
表 1-12 列出了此批注的属性
示例 1-21 显示了如何使用此批注将实体监听程序类 EmployeePersistListener（请参阅示例 1-22）和 EmployeeRemoveListener（请参阅示例 1-23）与实体 Employee 关联。示例 1-23 显示了您可以将多个生命周期事件与给定的实体监听程序类方法关联，但任何给定的生命周期事件只能在实体监听程序类中出现一次。
示例 1-21 @EntityListeners
@Entity
@EntityListeners(value={EmployeePersistListner.class, EmployeeRemoveListener.class})
public class Employee implements Serializable {
...
}
示例 1-22 EmployeePersistListener
public class EmployeePersistListener {
@PrePersist
employeePrePersist(Object employee) {
...
}
...
}
示例 1-23 EmployeeRemoveListener
public class EmployeeRemoveListener {
@PreRemove
@PostRemove
employeePreRemove(Object employee) {
...
}
...
}
@EntityResult
执行 @NamedNativeQuery 时，它可以返回实体（包括不同类型的实体）、标量值或实体和标量值的组合。
使用 @EntityResult 批注返回实体。
有关详细信息，另请参阅 @ColumnResult、@FieldResult 和 @SqlResultSetMapping。
表 1-8 列出了此批注的属性
示例 1-24 显示了如何使用此批注将 Order 和 Item（请参阅示例 1-25）实体包含在结果列表（请参阅示例 1-26）中。在该示例中，结果列表将为 Object 数组的 List，如：{[Order, Item], [Order, Item], ...}。
示例 1-24 使用 @EntityResult 的 Order 实体
@SqlResultSetMapping(
name="OrderResults",
entities={
@EntityResult(
entityClass=Order.class,
fields={
@FieldResult(name="id", column="order_id"),
@FieldResult(name="quantity", column="order_quantity"),
@FieldResult(name="item", column="order_item")
}
),
@EntityResult(
entityClass=Item.class,
fields={
@FieldResult(name="id", column="item_id"),
@FieldResult(name="name", column="item_name"),
}
)
}
)
@Entity
public class Order {
@Id
protected int id;
protected long quantity;
protected Item item;
...
}
示例 1-25 Item 实体
@Entity
public class Item {
@Id
protected int id;
protected String name;
...
}
示例 1-26 结合使用 @SqlResultSetMapping 与 @EntityResult 的原生查询
Query q = entityManager.createNativeQuery(
"SELECT o.id AS order_id, " +
"o.quantity AS order_quantity, " +
"o.item AS order_item, " +
"i.id AS item_id, " +
"i.name AS item_name, " +
"FROM Order o, Item i " +
"WHERE (order_quantity > 25) AND (order_item = i.id)",
"OrderResults"
);
List resultList = q.getResultList();
// List of Object arrays:{[Order, Item], [Order, Item], ...}
@Enumerated
默认情况下，JPA 持续性提供程序持久保存枚举常量的序数值。
使用 @Enumerated 批注指定在 String 值适合应用程序要求或与现有数据库模式匹配的情况下，JPA 持续性提供程序是否应持久保存枚举常量的序数值或 String 值。
该批注可以与 @Basic 一起使用。
表 1-14 列出了此批注的属性
根据示例 1-27 中的枚举常量，示例 1-28 显示了如何使用此批注指定在持久保存 Employee 时应将 SalaryRate 的 String 值写入数据库。默认情况下，会将 EmployeeStatus 的序数值写入数据库。
示例 1-27 枚举常量
public enum EmployeeStatus {FULL_TIME, PART_TIME, CONTRACT}
public enum SalaryRate {JUNIOR, SENIOR, MANAGER, EXECUTIVE}
示例 1-28 @Enumerated
@Entity
public class Employee {
...
public EmployeeStatus getStatus() {
...
}
@Enumerated(STRING)
public SalaryRate getPayScale() {
...
}
...
}
@ExcludeDefaultListeners
默认监听程序是 orm.xml 文件中指定的一个生命周期事件监听程序类，该类应用于持续性单元（请参阅 @PersistenceUnit）中的所有实体。在调用任何其他实体监听程序（请参阅 @EntityListeners）之前，JPA 持续性提供程序首先按照 orm.xml 文件中定义的顺序调用默认监听程序（如果有）。
如果默认监听程序行为不适用，请使用 @ExcludeDefaultListeners 批注覆盖（并阻止）针对给定 @Entity 或 @MappedSuperclass 执行的默认监听程序。
此批注没有属性
示例 1-29 显示了如何使用此批注指定不应对 Employee 实体执行默认监听程序。
示例 1-29 @ExcludeDefaultListeners
@Entity
@ExcludeDefaultListeners
public class Employee implements Serializable {
...
}
@ExcludeSuperclassListeners
如果继承层次中的 @Entity 和 @MappedSuperclass 类定义了 @EntityListeners，则默认情况下，JPA 持续性提供程序将在调用子类监听程序之前调用超类监听程序。
如果超类监听程序行为不适用，则使用 @ExcludeSuperclassListeners 批注覆盖（并阻止）针对给定 @Entity 或 @MappedSuperclass 执行的超类监听程序。
@ExcludeSuperclassListeners 批注不影响默认监听程序（请参阅 @ExcludeDefaultListeners）。
此批注没有属性
示例 1-29 显示了如何使用此批注指定不应对 PartTimeEmployee 实体执行超类监听程序 EmployeeListener，而是执行默认监听程序和子类监听程序 PartTimeEmployeeListener1 和 PartTimeEmployeeListener2。
示例 1-30 超类级别的实体监听程序
@MappedSuperclass
@EntityListeners(value={EmployeeListener.class})
public class Employee {
...
}
示例 1-31 子类级别的 @ExcludeSuperclassListeners
@Entity
@ExcludeSuperclassListeners
@EntityListners(value={PartTimeEmployeeListener1.class, PartTimeEmployeeListener2.class})
public class PartTimeEmployee extends Employee {
...
}
@FieldResult
执行 @NamedNativeQuery 时，它可以返回实体（包括不同类型的实体）、标量值或实体和标量值的组合。
默认情况下，JPA 持续性提供程序假设在使用 @EntityResult 返回实体时，SELECT 语句将包含与返回的实体的所有字段或属性相对应的所有列，且 SELECT 语句中的列名对应于字段或属性名（未使用 AS 语句）。
如果 SELECT 语句只包含某些与返回的实体的字段或属性相对应的列，或 SELECT 语句中的列名并不对应于字段或属性名（使用了 AS 语句），则在使用 @EntityResult 返回实体时，请使用 @FieldResult 批注将 SELECT 语句中的列映射到字段或属性。
有关详细信息，另请参阅 @ColumnResult 和 @SqlResultSetMapping。
表 1-15 列出了此批注的属性
示例 1-32 显示了如何使用此批注将 Order 和 Item（请参阅示例 1-33）实体包含在结果列表（请参阅示例 1-34）中。在该示例中，结果列表将为 Object 数组的 List，如：{[Order, Item], [Order, Item], ...}。
示例 1-32 使用 @EntityResult 和 @FieldResult 的 Order 实体
@SqlResultSetMapping(
name="OrderResults",
entities={
@EntityResult(
entityClass=Order.class,
fields={
@FieldResult(name="id", column="order_id"),
@FieldResult(name="quantity", column="order_quantity"),
@FieldResult(name="item", column="order_item")
}
),
@EntityResult(
entityClass=Item.class,
fields={
@FieldResult(name="id", column="item_id"),
@FieldResult(name="name", column="item_name"),
}
)
}
)
@Entity
public class Order {
@Id
protected int id;
protected long quantity;
protected Item item;
...
}
示例 1-33 Item 实体
@Entity
public class Item {
@Id
protected int id;
protected String name;
...
}
示例 1-34 结合使用 @SqlResultSetMapping 与 @EntityResult 的原生查询
Query q = entityManager.createNativeQuery(
"SELECT o.id AS order_id, " +
"o.quantity AS order_quantity, " +
"o.item AS order_item, " +
"i.id AS item_id, " +
"i.name AS item_name, " +
"FROM Order o, Item i " +
"WHERE (order_quantity > 25) AND (order_item = i.id)",
"OrderResults"
);
List resultList = q.getResultList();
// List of Object arrays:{[Order, Item], [Order, Item], ...}
@GeneratedValue
默认情况下，JPA 持续性提供程序管理为实体主键提供的唯一标识符（请参阅 @Id）。
如果要微调此机制以实现以下目的，请使用 @GeneratedValue 批注：
表 1-16 列出了此批注的属性
示例 1-35 显示了如何使用此批注指示持续性提供程序使用名为 CUST_SEQ、类型为 GeneratorType.SEQUENCE 的主键生成器。
示例 1-35 @GeneratedValue
@Entity
public class Employee implements Serializable {
...
@Id
@GeneratedValue(strategy=SEQUENCE, generator="CUST_SEQ")
@Column(name="CUST_ID")
public Long getId() {
return id;
}
...
}
@Id
使用 @Id 批注将一个或多个持久字段或属性指定为实体的主键。
对于每个实体，必须至少指定以下项之一：
此批注没有属性
默认情况下，JPA 持续性提供程序选择最合适的主键生成器（请参阅 @GeneratedValue）并负责管理主键值：您不必采取任何进一步的操作。如果要使用 JPA 持续性提供程序的默认键生成机制，则不必采取任何进一步的操作。
示例 1-36 显示了如何使用此批注将持久字段 empID 指定为 Employee 表的主键。
示例 1-36 @Id
@Entity
public class Employee implements Serializable {
@Id
private int empID;
...
}
@IdClass
使用 @IdClass 批注为实体指定一个复合主键类（通常由两个或更多基元类型或 JDK 对象类型组成）。从原有数据库映射时（此时数据库键由多列组成），通常将出现复合主键。
复合主键类具有下列特征：
-
它是一个普通的旧式 Java 对象 (POJO) 类。
-
它必须为 public，并且必须有一个 public 无参数构造函数。
-
如果使用基于属性的访问，则主键类的属性必须为 public 或 protected。
-
它必须是可序列化的。
-
它必须定义 equals 和 hashCode 方法。
这些方法的值相等性的语义必须与键映射到的数据库类型的数据库相等性一致。
-
它的字段或属性的类型和名称必须与使用 @Id 进行批注的实体主键字段或属性的类型和名称相对应。
或者，您可以使复合主键类成为由实体拥有的嵌入类（请参阅 @EmbeddedId）。
表 1-17 列出了此批注的属性
示例 1-37 显示了一个非嵌入的复合主键类。在该类中，字段 empName 和 birthDay 的名称和类型必须对应于实体类中属性的名称和类型。示例 1-38 显示了如何使用这个非嵌入的复合主键类（使用 @IdClass 批注）配置 EJB 3.0 实体。由于实体类字段 empName 和 birthDay 在主键中使用，因此还必须使用 @Id 批注对其进行批注。
示例 1-37 非嵌入的复合主键类
public class EmployeePK implements Serializable
{
private String empName;
private Date birthDay;
public EmployeePK()
{
}
public String getName()
{
return empName;
}
public void setName(String name)
{
empName = name;
}
public long getDateOfBirth()
{
return birthDay;
}
public void setDateOfBirth(Date date)
{
birthDay = date;
}
public int hashCode()
{
return (int) empName.hashCode();
}
public boolean equals(Object obj)
{
if (obj == this) return true;
if (!(obj instanceof EmployeePK)) return false;
if (obj == null) return false;
EmployeePK pk = (EmployeePK) obj;
return pk.birthDay == birthDay && pk.empName.equals(empName);
}
}
示例 1-38 @IdClass
@IdClass(EmployeePK.class)
@Entity
public class Employee
{
@Id String empName;
@Id Date birthDay;
...
}
@Inheritance
默认情况下，JPA 持续性提供程序自动管理继承层次中实体的持续性。
使用 @Inheritance 批注自定义持续性提供程序的继承层次支持，以提高应用程序性能或匹配现有的数据模型。
表 1-18 列出了此批注的属性
示例 1-39 显示了如何使用此批注指定 Customer 的所有子类将使用 InheritanceType.JOINED。示例 1-40 中的子类将映射到它自己的表（该表针对 ValuedCustomer 的每个持久属性包含一列）和一个外键列（包含 Customer 表的主键）。
示例 1-39 @Inheritance — 使用 JOINED 的根类
@Entity@Inheritance(strategy=JOINED)public class Customer {
@Id
private int customerId;
...
}
示例 1-40 @Inheritance — 使用 JOINED 的子类
@Entity
public class ValuedCustomer extends Customer {
...
}
在示例 1-41 中，默认情况下，InheritanceType.SINGLE_TABLE 应用于 Customer 及其所有子类。在该示例中，默认标识符表列 DTYPE（请参阅 @DiscriminatorColumn）指定为具有标识符类型 INTEGER，且 Customer 的 @DiscriminatorValue 指定为 1。示例 1-42 显示了如何将子类 ValuedCustomer 的标识符值指定为 2。在该示例中，Customer 和 ValuedCustomer 的所有持久属性将映射到一个表。
示例 1-41 @Inheritance — 指定其标识符列的根类
@Entity
@DiscriminatorColumn(discriminatorType=DiscriminatorType.INTEGER)
@DiscriminatorValue(value="1")
public class Customer {
...
}
示例 1-42 @Inheritance — 指定其标识符值的子类
@Entity
@DiscriminatorValue(value="2")
public class ValuedCustomer extends Customer {
...
}
