转-JPA 批注参考(7)

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

详细解释了下面9个批注的含义及其批注所包含的属性：
@SequenceGenerator
@SqlResultSetMapping
@SqlResultSetMappings
@Table
@TableGenerator
@Temporal
@Transient
@UniqueConstraint
@Version
■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■

 

 

@SequenceGenerator

如果使用 @GeneratedValue 批注指定一个 SEQUENCE 类型的主键生成器，则可以使用 @SequenceGenerator 批注微调该主键生成器以：

● 更改分配大小以匹配应用程序要求或数据库性能参数

● 更改初始值以匹配现有的数据模型（例如，如果基于已经为其分配或保留了一组主键值的现有数据集构建）

● 使用现有数据模型中预定义的序列

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

表 1-42 @SequenceGenerator 属性

 

属性

必需

说明

name		SequenceGenerator 的名称必须匹配其 startegy 设置为 SEQUENCE 的 GeneratedValue 的名称。
allocationSize		默认值 ： 50。 默认情况下，JPA 持续性提供程序使用的分配大小为 50。 如果此分配大小与应用程序要求或数据库性能参数不匹配，请将 allocationSize 设置为所需的 int 值。
initialValue		默认值 ： 0。 默认情况下，JPA 持续性提供程序假设持续性提供程序将所有主键值的起始值设置为 0。 如果这与现有数据模型不匹配，请将 initialValue 设置为所需的 int 值。
sequenceName		默认值：JPA 持续性提供程序分配它自己创建的序列名。 如果要使用事先存在或预定义的序列，请将 sequenceName 设置为所需的 String 名称。

示例 1-80 显示了如何使用此批注为名为 CUST_SEQ 的 SEQUENCE 主键生成器指定分配大小。

示例 1-80 @SequenceGenerator

@Entity
public class Employee implements Serializable {
    ...
@Id
@SequenceGenerator(name="CUST_SEQ", allocationSize=25)
@GeneratedValue(strategy=SEQUENCE, generator="CUST_SEQ")
@Column(name="CUST_ID")
public Long getId() {
return id;
    }
    ...

@SqlResultSetMapping

执行 @NamedNativeQuery 时，它可以返回实体（包括不同类型的实体）、标量值或实体和标量值的组合。

默认情况下（如示例 1-81 所示），JPA 持续性提供程序假设原生 SQL 查询中的 SELECT 语句：

● 返回一个实体类型

● 包含与返回的实体的所有字段或属性相对应的所有列

● 使用与字段或属性名（未使用 AS 语句）相对应的列名

示例 1-81 简单的原生 SQL 查询

Query q = entityManager.createNativeQuery(
"SELECT o.id, o.quantity, o.item " +
"FROM Order o, Item i " +
"WHERE (o.item = i.id) AND (i.name = "widget")",
Order.class
);
List resultList = q.getResultList();
// List of Order entity objects:{Order, Order, ...}

如果原生 SQL 查询满足以下条件，请使用 @SqlResultSetMapping 批注控制 JPA 持续性提供程序如何将 JDBC 结果集映射到实体字段或属性以及标量：

● 返回多个类型的实体

● 只返回标量值或实体和标量值的组合

● 使用列别名（AS 语句）

如果有多个 @SqlResultSetMapping，则必须使用 @SqlResultSetMappings。

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

表 1-43 @SqlResultSetMapping 属性

 

属性

必需

说明

name		将 name 设置为此 @SqlResultSetMapping 的 String 名称。 这是用于将 @SqlResultSetMapping 与原生 SQL 查询关联的名称（请参阅示例 1-84）。
columns		默认值 ：空 ColumnResult 数组。 默认情况下，JPA 持续性提供程序假设 SELECT 语句只返回实体。 如果 SELECT 语句返回标量值，则将 columns 设置为 ColumnResult 实例的数组，每个标量结果一个 @ColumnResult。
entities		默认值 ：空 EntityResult 数组。 默认情况下，JPA 持续性提供程序假设 SELECT 语句返回一个类型的实体。 如果 SELECT 语句返回多个类型的实体，请将实体设置为 EntityResult 实例的数组，每个返回的实体类型一个 @EntityResult。

示例 1-82 显示了如何使用此批注将 Order 和 Item（请参阅示例 1-83）实体和标量 name 包含在结果列表（请参阅示例 1-84）中。在该示例中，结果列表将为 Object 数组的 List，如：{[Order, Item, "Shoes"], [Order, Item, "Socks"], ...}。

示例 1-82 使用 @SqlResultSetMapping 的 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"),
            }
        )
    }
columns={
@ColumnResult(
name="item_name"
        )
    }
)
@Entity
public class Order {
@Id
protected int id;
protected long quantity;
protected Item item;
    ...
}

示例 1-83 Item 实体

@Entity
public class Item {
@Id
protected int id;
protected String name;
    ...
}

示例 1-84 将 @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, "Shoes"], [Order, Item, "Socks"], ...}

@SqlResultSetMappings

如果需要指定多个 @SqlResultSetMapping，则必须使用一个 @SqlResultSetMappings 批注指定所有 SQL 结果集映射。

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

表 1-44 @SqlResultSetMappings 属性

 

属性

必需

说明

value		要指定两个或更多 SQL 结果集映射，请将 value 设置为 @SqlResultSetMapping 实例的数组。

示例 1-85 显示了如何使用此批注指定两个 @SqlResultSetMapping 实例。

示例 1-85 @SqlResultSetMappings

SqlResultSetMappings({
@SqlResultSetMapping(
name="OrderItemItemNameResults",
entities={
@EntityResult(entityClass=Order.class),
@EntityResult(entityClass=Item.class)
        }
columns={
@ColumnResult(name="item_name")
        }
    ),
@SqlResultSetMapping(
name="OrderItemResults",
entities={
@EntityResult(entityClass=Order.class),
@EntityResult(entityClass=Item.class)
        }
    )
})
@Entity
public class Order {
@Id
protected int id;
protected long quantity;
protected Item item;
    ...
}

@Table

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

在以下条件下，使用 @Table 批注指定与实体关联的主表：

● 实体名称难于处理、是一个保留字、与预先存在的数据模型不兼容或作为数据库中的表名无效

● 需要控制表所属的目录或模式

如果希望 JPA 将某些字段持久保存到主表，而将其他字段持久保存到一个或多个辅助表，请参阅 @SecondaryTable。

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

表 1-45 @Table 属性

 

属性

必需

说明

catalog		默认值 ：JPA 持续性提供程序使用任何适用于数据库的默认目录。 如果默认目录不适合于应用程序，请将 catalog 设置为要使用的 String 目录名
name		默认值 ：JPA 持续性提供程序假设实体的数据库表与实体类同名。在示例 1-86 中，默认 name 为 Employee。 如果实体类名难以处理、是一个保留字或与预先存在的数据模型不兼容，请将 name 设置为相应的数据表名称。在示例 1-86 中，JPA 将实体类 Employee 持久保存到名为 EMP 的数据库表中。
schema		默认值 ：JPA 持续性提供程序使用任何适用于数据库的默认模式。 如果默认模式不适合于应用程序，请将 schema 设置为要使用的 String 模式名。
uniqueConstraints		默认值 ：JPA 持续性提供程序假设实体的数据库表中的任何列均没有唯一约束。 如果唯一约束应用于该表中的一列或多列，请将 uniqueContraints 设置为一个或多个 UniqueConstraint 实例的数组。有关详细信息，请参阅 @UniqueConstraint。

示例 1-86 显示了如何使用此批注指定主表名。

示例 1-86 @Table

@Entity
@Table(name="EMP")
public class Employee implements Serializable {
    ...
}

@TableGenerator

如果使用 @GeneratedValue 批注指定一个 TABLE 类型的主键生成器，可以使用 @TableGenerator 批注微调该主键生成器以：

● 由于名称难于处理、是一个保留字、与预先存在的数据模型不兼容或作为数据库中的表名无效而更改主键生成器的表名称

● 更改分配大小以匹配应用程序要求或数据库性能参数

● 更改初始值以匹配现有的数据模型（例如，如果基于已经为其分配或保留了一组主键值的现有数据集构建）

● 使用特定目录或模式配置主键生成器的表

● 在主键生成器表的一列或多列商配置一个唯一的约束

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

表 1-46 @TableGenerator 属性

 

属性

必需

说明

catalog		SequenceGenerator 的名称必须匹配其 startegy 设置为 startegy 的 GeneratedValue 的名称。生成器名称的作用域对持续性单元是全局的（跨所有生成器类型）。
allocationSize		默认值 ： 50。 默认情况下，JPA 持续性提供程序使用的分配大小为 50。 如果此分配大小与应用程序要求或数据库性能参数不匹配，请将 allocationSize 设置为所需的 int 值。
catalog		默认值 ：JPA 持续性提供程序使用任何适用于数据库的默认目录。 如果默认目录不适合于应用程序，请将 catalog 设置为要使用的 String 目录名。
initialValue		默认值 ： 0。 默认情况下，JPA 持续性提供程序将所有主键值的起始值设置为 0。 如果这与现有数据模型不匹配，请将 initialValue 设置为所需的 int 值。
pkColumnName		默认值 ：JPA 持续性提供程序为生成器表中的主键列提供名称。 如果该名称不适合于应用程序，请将 pkColumnName 设置为所需的 String 名称。
pkColumnValue		默认值 ：JPA 持续性提供程序为生成器表中的主键列提供一个合适的主键值。 如果该值不适合于应用程序，请将 pkColumnValue 设置为所需的 String 值。
schema		默认值 ：JPA 持续性提供程序使用任何适用于数据库的默认模式。 如果默认模式不适合于应用程序，请将 schema 设置为要使用的 String 模式名。
table		默认值 ：JPA 持续性提供程序为存储生成的 ID 值的表提供了一个合适的名称。 如果默认表名不适合于应用程序，请将 table 设置为所需的 String 表名。
uniqueConstraints		默认值 ：JPA 持续性提供程序假设主键生成器表中的任何列均没有唯一约束。 如果唯一约束应用于该表中的一列或多列，则将 uniqueContraints 设置为一个或多个 UniqueConstraint 实例的数组。有关详细信息，请参阅 @UniqueConstraint。
valueColumnName		默认值 ：JPA 持续性提供程序为存储生成的 ID 值的列提供了一个合适的名称。 如果默认列名不适合于应用程序，请将 valueColumnName 设置为所需的 String 列名。

示例 1-87 显示了如何使用此批注为名为 empGen 的 TABLE 主键生成器指定分配大小。

 

 

 

 

示例 1-87 @TableGenerator

@Entity
public class Employee implements Serializable {
    ...
@Id
@TableGenerator(
name="empGen",
allocationSize=1
    )
@GeneratedValue(strategy=TABLE, generator="empGen")
@Column(name="CUST_ID")
public Long getId() {
return id;
    }
    ...

@Temporal

使用 @Temporal 批注指定 JPA 持续性提供程序应只为 java.util.Date 和 java.util.Calendar 类型的字段或属性持久保存的数据库类型。

该批注可以与 @Basic 一起使用。

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

表 1-47 @Temporal 属性

 

属性

必需

说明

value		将 value 设置为与希望 JPA 持续性提供程序使用的数据库类型相对应的 TemporalType： ● DATE - 等于 java.sql.Date ● TIME - 等于 java.sql.Time ● TIMESTAMP - 等于 java.sql.Timestamp

示例 1-88 显示了如何使用此批注指定 JPA 持续性提供程序应将 java.util.Date 字段 startDate 持久保存为 DATE (java.sql.Date) 数据库类型。

示例 1-88 @Temporal

@Entity
public class Employee {
    ...
@Temporal(DATE)    protected java.util.Date startDate;
    ...
}

@Transient

默认情况下，JPA 持续性提供程序假设实体的所有字段均为持久字段。

使用 @Transient 批注指定实体的非持久字段或属性，例如，一个在运行时使用但并非实体状态一部分的字段或属性。

JPA 持续性提供程序不会对批注为 @Transient 的属性或字段持久保存（或创建数据库模式）。

该批注可以与 @Entity、@MappedSuperclass 和 @Embeddable 一起使用。

该批注没有属性。有关更多详细信息，请参阅 API 。

示例 1-89 显示了如何使用此批注将 Employee 字段 currentSession 指定为非持久字段。JPA 持续性提供程序将不持久保存该字段。

示例 1-89 @Transient

@Entity
public class Employee {
@Id
int id;
        @Transient
        Session currentSession;
        ...
}

@UniqueConstraint

默认情况下，JPA 持续性提供程序假设所有列均可以包含重复值。

使用 @UniqueConstraint 批注指定将在为主表或辅助表生成的 DDL 中包含一个唯一约束。或者，您可以在列级别指定唯一约束（请参阅 @Column）。

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

表 1-48 @UniqueConstraint 属性

 

属性

必需

说明

columnNames		如果任何列均包含唯一约束，请将 columnNames 设置为 String 列名的数组。

示例 1-90 显示了如何使用此批注对主表 EMP 中的列 EMP_ID 和 EMP_NAME 指定一个唯一约束。

示例 1-90 使用唯一约束的 @Table

@Entity
@Table(
name="EMP",
uniqueConstraints={@UniqueConstraint(columnNames={"EMP_ID", "EMP_NAME"})}
)
public class Employee implements Serializable {
    ...
}

@Version

默认情况下，JPA 持续性提供程序假设应用程序负责数据一致性。

使用 @Version 批注通过指定用作其乐观锁定值的实体类的版本字段或属性来启用 JPA 管理的乐观锁定（推荐做法）。

选择版本字段或属性时，确保：

● 每个实体只有一个版本字段或属性

● 选择一个持久保存到主表的属性或字段（请参阅 @Table）

● 您的应用程序不修改版本属性或字段

此批注没有属性。有关更多详细信息，请参阅 API 。

示例 1-91 显示了如何使用此批注将属性 getVersionNum 指定为乐观锁定值。在该示例中，该属性的列名设置为 OPTLOCK（请参阅 @Column），而非属性的默认列名。

示例 1-91 @Version

@Entity
public class Employee implements Serializable {
    ...
@Version
@Column(name="OPTLOCK")
protected int getVersionNum() {
return versionNum;
    }
    ...
}