JPA 批注参考(1)

来源：www.oracle.com
■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
JPA批注是EJB 3标准的一部分，用于为ORM框架提供基于批注的配置方式，但是JPA本身是独立于EJB 3的，可被任何的ORM框架使用。
本文的主要内容如下：

1、按照类别对JPA批注进行划分，划分为11个类别，各个类别及其可以使用的批注(括号内即为可以使用的批注)如下：

⑴ 实体（@Entity）
⑵ 数据库模式属性（@Table、@SecondaryTable、@SecondaryTables、@Column、@JoinColumn、@JoinColumns、@PrimaryKeyJoinColumn、@PrimaryKeyJoinColumns、@JoinTable、@UniqueConstraint）
⑶ 身份（@Id、@IdClass、@EmbeddedId、@GeneratedValue、@SequenceGenerator、@TableGenerator）
⑷ 直接映射（ @Basic、@Enumerated、@Temporal、@Lob、@Transient）
⑸ 关系映射（@OneToOne、@ManyToOne、@OneToMany、@ManyToMany、@MapKey、@OrderBy）
⑹ 组合（@Embeddable、@Embedded、@AttributeOverride、@AttributeOverrides、@AssociationOverride、@AssociationOverrides）
⑺ 继承（@Inheritance、@DiscriminatorColumn、@DiscriminatorValue、@MappedSuperclass、@AssociationOverride、@AssociationOverrides、@AttributeOverride、@AttributeOverrides）
⑻ 锁定（@Version）
⑼ 生命周期回调事件（@PrePersist、@PostPersist、@PreRemove、@PostRemove、@PreUpdate、@PostUpdate、@PostLoad、@EntityListeners、@ExcludeDefaultListeners、@ExcludeSuperclassListeners）
⑽ 实体管理器（@PersistenceUnit、@PersistenceUnits、@PersistenceContext、@PersistenceContexts、@PersistenceProperty）
⑾ 查询（@NamedQuery、@NamedQueries、@NamedNativeQuery、@NamedNativeQueries、@QueryHint、@ColumnResult、@EntityResult、@FieldResult、@SqlResultSetMapping、@SqlResultSetMappings）

2、详细解释了下面4个批注的含义及其批注所包含的属性：
@AssociationOverride
@AssociationOverrides
@AttributeOverride
@AttributeOverrides

注意：原文有错误的之处已经在这里全部更正。
■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■

作为 Java 企业版 5 (Java EE 5) Enterprise Java Bean (EJB) 3.0 规范的组成部分，Java 持续性 API (JPA) 显著简化了 EJB 持续性并提供了一个对象关系映射方法，该方法使您可以采用声明方式定义如何通过一种标准的可移植方式（在 Java EE 5 应用服务器内部以及 Java 标准版 (Java SE) 5 应用程序中的 EJB 容器外部均可使用）将 Java 对象映射到关系数据库表。

在 JPA 之前，Java EE 应用程序将持续类表示为容器管理的实体 bean。使用 JPA，您可以将任何普通的旧式 Java 对象 (POJO) 类指定为 JPA 实体：一个应使用 JPA 持续性提供程序的服务将其非临时字段持久保存到关系数据库（在 Java EE EJB 容器的内部或在简单 Java SE 应用程序中的 EJB 容器的外部）的 Java 对象。

使用 JPA 时，可以使用批注配置实体的 JPA 行为。批注是一种使用元数据修饰 Java 源代码的简单表达方法，它编译为相应的 Java 类文件，以便在运行时由 JPA 持续性提供程序解释以管理 JPA 行为。
例如，要将 Java 类指定为 JPA 实体，请使用 @Entity 批注，如下所示：

@Entity
public class Employee implements Serializable {
    ...
}

您可以有选择地使用批注来修饰实体类以覆盖默认值。这称作按异常进行配置 (configuration by exception)。

本参考广泛引用了 JSR-220 Enterprise JavaBean 版本 3.0 Java 持续性 API 规范，以按类别汇总批注信息（请参阅表 1-1），并解释了何时以及如何使用这些批注来自定义 JPA 行为，以满足应用程序的需要。

有关详细信息，请参阅：

• 批注索引

• 完整的 JPA 批注 Javadoc

表 1-1 按类别划分的 JPA 批注

 

 

类别

说明

批注

实体	默认情况下，JPA 持续性提供程序假设 Java 类是非持续类，并且仅当使用此批注对其进行修饰的情况下才可用于 JPA 服务。使用此批注将普通的旧式 Java 对象 (POJO) 类指定为实体，以便可以将它用于 JPA 服务。要将类用于 JPA 服务，必须将该类指定为 JPA 实体（使用此批注或 orm.xml 文件）。	@Entity
数据库模式属性	默认情况下，JPA 持续性提供程序假设实体名称对应于同名的数据库表，且实体的数据成员名称对应于同名的数据库列。 使用这些批注覆盖此默认行为，并微调对象模型与数据模型之间的关系。	@Table @SecondaryTable @SecondaryTables @Column @JoinColumn @JoinColumns @PrimaryKeyJoinColumn @PrimaryKeyJoinColumns @JoinTable @UniqueConstraint
身份	默认情况下，JPA 持续性提供程序假设每个实体必须至少有一个用作主键的字段或属性。 使用这些批注指定以下项之一： 一个 @Id 多个 @Id 和一个 @IdClass 一个 @EmbeddedId 还可以使用这些批注微调数据库维护实体身份的方式。	@Id @IdClass @EmbeddedId @GeneratedValue @SequenceGenerator @TableGenerator
直接映射	默认情况下，JPA 持续性提供程序为大多数 Java 基元类型、基元类型的包装程序以及 enums 自动配置一个 Basic 映射。 使用这些批注微调数据库实现这些映射的方式。	@Basic @Enumerated @Temporal @Lob @Transient
关系映射	JPA 持续性提供程序要求您显式映射关系。 使用这些批注指定实体关系的类型和特征，以微调数据库实现这些关系的方式。	@OneToOne @ManyToOne @OneToMany @ManyToMany @MapKey @OrderBy
组合	默认情况下，JPA 持续性提供程序假设每个实体均映射到它自己的表。 使用这些批注覆盖其他实体拥有的此种实体行为。	@Embeddable @Embedded @AttributeOverride @AttributeOverrides @AssociationOverride @AssociationOverrides
继承	默认情况下，JPA 持续性提供程序假设所有持久字段均由一个实体类定义。 如果实体类继承了一个或多个超类中的某些或所有持续字段，则使用这些批注。	@Inheritance @DiscriminatorColumn @DiscriminatorValue @MappedSuperclass @AssociationOverride @AssociationOverrides @AttributeOverride @AttributeOverrides
锁定	默认情况下，JPA 持续性提供程序假设应用程序负责数据一致性。 使用此批注启用 JPA 管理的乐观锁定（推荐使用）。	@Version
生命周期回调事件	默认情况下，JPA 持续性提供程序处理所有持续性操作。 如果您要在实体生命周期内随时调用自定义逻辑，请使用这些批注将实体方法与 JPA 生命周期事件关联。图 1-1 演示了这些生命周期事件之间的关系。	@PrePersist @PostPersist @PreRemove @PostRemove @PreUpdate @PostUpdate @PostLoad @EntityListeners @ExcludeDefaultListeners @ExcludeSuperclassListeners
实体管理器	在使用 JPA 持续性提供程序的应用程序中，您可以使用 EntityManager 实例执行所有持续性操作（创建、读取、更新和删除）。 使用这些批注将实体与实体管理器关联并自定义实体管理器的环境。	@PersistenceUnit @PersistenceUnits @PersistenceContext @PersistenceContexts @PersistenceProperty
查询	在使用 JPA 持续性提供程序的应用程序中，可以使用实体管理器动态创建和执行查询，也可以预定义查询并在运行时按名称执行它们。 使用这些批注预定义查询并管理它们的结果集。	@NamedQuery @NamedQueries @NamedNativeQuery @NamedNativeQueries @QueryHint @ColumnResult @EntityResult @FieldResult @SqlResultSetMapping @SqlResultSetMappings

 

图 1-1如下所示：

图 1-1 JPA 实体生命周期回调事件批注

@AssociationOverride

默认情况下，JPA 持续性提供程序自动假设子类继承超类中定义的持久属性及其关联映射。

如果继承的列定义对实体不正确（例如，如果继承的列名与已经存在的数据模型不兼容或作为数据库中的列名无效），请使用 @AssociationOverride 批注自定义从 @MappedSuperclass 或 @Embeddable 继承的 @OneToOne 或 @ManyToOne 映射，以更改与字段或属性关联的 @JoinColumn。

如果有多个要进行的 @AssociationOverride 更改，则必须使用 @AssociationOverrides。

要自定义基本映射以更改它的 @Column，请使用 @AttributeOverride。

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

表 1-2 @AssociationOverride 属性

属性

必需

说明

joinColumns		要指定映射到持久属性的连接列，请将 joinColums 设置为 JoinColumn 实例的数组（请参阅 @JoinColumn）。 映射类型将与可嵌套类或映射的超类中定义的类型相同。
name		如果使用了基于属性的访问，则映射的为嵌入对象中的属性名称，如果使用了基于字段的访问，则映射的为字段名称。

示例 1-1 显示了示例 1-2 中的实体扩展的 @MappedSuperclass。示例 1-2 显示了如何在实体子类中使用 @AssociationOverride 覆盖 @MappedSuperclass Employee 中定义（默认情况下）的 @JoinColumn 以便关联到 Address。

如果使用 @AssociationOverride，则 Employee 表包含以下列：

• ID

• VERSION

• ADDR_ID

• WAGE

如果不使用 @AssociationOverride，则 Employee 表包含以下列：

• ID

• VERSION

• ADDRESS

• WAGE

示例 1-1 @MappedSuperclass

@MappedSuperclass
public class Employee {
@Id protected Integer id;
@Version protected Integer version;
@ManyToOne protected Address address;
    ...
}

示例 1-2 @AssociationOverride

@Entity
@AssociationOverride(name="address", joinColumns=@JoinColumn(name="ADDR_ID"))
public class PartTimeEmployee extends Employee {
    @Column(name="WAGE")
    protected Float hourlyWage;
    ...
}

@AssociationOverrides

如果需要指定多个 @AssociationOverride，则必需使用一个 @AssociationOverrides 批注指定所有关联覆盖。

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

表 1-3 @AssociationOverrides 属性

属性

必需

说明

value		要指定两个或更多覆盖，请将 value 设置为 AssociationOverride 实例的数组（请参阅 @AssociationOverride）。

示例 1-3 显示了如何使用此批注指定指定多个 @AssociationOverride。

示例 1-3 @AssociationOverrides

@Entity
@AssociationOverrides({
@AssociationOverride(name="address", joinColumn=@Column(name="ADDR_ID")),
@AssociationOverride(name="id", joinColumn=@Column(name="PTID"))
})
public class PartTimeEmployee extends Employee {
@Column(name="WAGE")
protected Float hourlyWage;
    ...
}

@AttributeOverride

默认情况下，JPA 持续性提供程序自动假设子类继承超类中定义的持久属性及其基本映射。

如果针对实体继承的列定义不正确，请使用 @AttributeOverride 批注自定义一个从 @MappedSuperclass 或 @Embeddable 继承的基本映射以更改与字段或属性关联的 @Column。（例如，如果继承的列名与事先存在的数据模型不兼容，或者作为数据库中的列名无效）。

如果有多个要进行的 @AttributeOverride 更改，则必须使用 @AttributeOverrides。

要自定义关联映射以更改它的 @JoinColumn，请使用 @AssociationOverride。

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

表 1-4 @AttributeOverride 属性

属性

必需

说明

column		映射到持久属性的 @Column。映射类型将与可嵌套类或映射超类中定义的类型相同。
name		如果使用了基于属性的访问，则映射的为嵌入对象中的属性名称，如果使用了基于字段的访问，则映射的为字段名称。

示例 1-4 显示了示例 1-5 中的实体扩展的 @MappedSuperclass。示例 1-5 显示了如何使用实体子类中的 @AttributeOverride 覆盖 @MappedSuperclass Employee 中定义（默认情况下）的 @Column，以便基本映射到 Address。

如果使用 @AttributeOverride，则 Employee 表包含以下列：

• ID

• VERSION

• ADDR_STRING

• WAGE

如果不使用 @AttributeOverride，则 Employee 表包含以下列：

• ID

• VERSION

• ADDRESS

• WAGE

示例 1-4 @MappedSuperclass

@MappedSuperclass
public class Employee {
@Id protected Integer id;
@Version protected Integer version;
protected String address;
    ... 
}

示例 1-5 @AttributeOverride

@Entity
@AttributeOverride(name="address", column=@Column(name="ADDR_STRING"))
public class PartTimeEmployee extends Employee {
@Column(name="WAGE")
protected Float hourlyWage;
    ...
}

@AttributeOverrides

如果需要指定多个 @AttributeOverride，则必需使用一个 @AttributeOverrides 批注指定所有属性覆盖。

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

表 1-5 @AttributeOverrides 属性

属性

必需

说明

value		要指定两个或更多属性覆盖，请将 value 设置为 AttributeOverride 实例的数组（请参阅 @AttributeOverride）。

示例 1-6 显示了如何使用此批注指定两个属性覆盖。

示例 1-6 @AttributeOverrides

@Entity
@AttributeOverrides({
@AttributeOverride(name="address", column=@Column(name="ADDR_ID")),
@AttributeOverride(name="id", column=@Column(name="PTID"))
})
public class PartTimeEmployee extends Employee {

@Column(name="WAGE")
protected Float hourlyWage;

public PartTimeEmployee() {
        ...
    }

public Float getHourlyWage() { 
        ... 
    }

public void setHourlyWage(Float wage) { 
        ... 
    }
}