JPA帮助文档.docx
《JPA帮助文档.docx》由会员分享，可在线阅读，更多相关《JPA帮助文档.docx（108页珍藏版）》请在冰豆网上搜索。
JPA帮助文档
JPA批注参考
版本：
5/12/06
作为Java企业版5（JavaEE5）EnterpriseJavaBean（EJB）3.0规范的组成部分，Java持续性API（JPA）显著简化了EJB持续性并提供了一个对象关系映射方法，该方法使您可以采用声明方式定义如何通过一种标准的可移植方式（在JavaEE5应用服务器内部以及Java标准版（JavaSE）5应用程序中的EJB容器外部均可使用）将Java对象映射到关系数据库表。
在JPA之前，JavaEE应用程序将持续类表示为容器管理的实体bean。
使用JPA，您可以将任何普通的旧式Java对象（POJO）类指定为JPA实体：
一个应使用JPA持续性提供程序的服务将其非临时字段持久保存到关系数据库（在JavaEEEJB容器的内部或在简单JavaSE应用程序中的EJB容器的外部）的Java对象。
使用JPA时，可以使用批注配置实体的JPA行为。
批注是一种使用元数据修饰Java源代码的简单表达方法，它编译为相应的Java类文件，以便在运行时由JPA持续性提供程序解释以管理JPA行为。
例如，要将Java类指定为JPA实体，请使用@Entity批注，如下所示：
@Entity
publicclassEmployeeimplementsSerializable{
...
}
您可以有选择地使用批注来修饰实体类以覆盖默认值。
这称作按异常进行配置（configurationbyexception）。
本参考广泛引用了JSR-220EnterpriseJavaBean版本3.0Java持续性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
@AssociationOverride
默认情况下，JPA持续性提供程序自动假设子类继承超类中定义的持久属性及其关联映射。
如果继承的列定义对实体不正确（例如，如果继承的列名与已经存在的数据模型不兼容或作为数据库中的列名无效），请使用@AssociationOverride批注自定义从@MappedSuperclass或@Embeddable继承的@OneToOne或@ManyToOne映射，以更改与字段或属性关联的@JoinColumn。
如果有多个要进行的@AssociationOverride更改，则必须使用@AssociationOverrides。
要自定义基本映射以更改它的@Column，请使用@AttributeOverride。
表1-4列出了此批注的属性。
有关更多详细信息，请参阅API。
表1-2@AssociationOverride属性
属性
必需
说明
joinColumns
要指定映射到持久属性的连接列，请将joinColums设置为JoinColumn实例的数组（请参阅@JoinColumn）。
映射类型将与可嵌套类或映射的超类中定义的类型相同。
name
如果使用了基于属性的访问，则映射的为嵌入对象中的属性名称，如果使用了基于字段的访问，则映射的为字段名称。
示例1-4显示了示例1-5中的实体扩展的@MappedSuperclass。
示例1-5显示了如何在实体子类中使用@AssociationOverride覆盖@MappedSuperclassEmployee中定义（默认情况下）的@JoinColumn以便关联到Address。
如果使用@AssociationOverride，则Employee表包含以下列：
∙ID
∙VERSION
∙ADDR_ID
∙WAGE
如果不使用@AssociationOverride，则Employee表包含以下列：
∙ID
∙VERSION
∙ADDRESS
∙WAGE
示例1-1@MappedSuperclass
@MappedSuperclass
publicclassEmployee{
@IdprotectedIntegerid;
@VersionprotectedIntegerversion;
@ManyToOneprotectedAddressaddress;
...
}
示例1-2@AssociationOverride
@Entity
@AssociationOverride（
name="address",
joinColumns=@JoinColumn（name="ADDR_ID"
））
publicclassPartTimeEmployeeextendsEmployee{
@Column（name="WAGE"）
protectedFloathourlyWage;
...
}
@AssociationOverrides
如果需要指定多个@AssociationOverride，则必需使用一个@AssociationOverrides批注指定所有关联覆盖。
表1-5列出了此批注的属性。
有关更多详细信息，请参阅API。
表1-3@AssociationOverrides属性
属性
必需
说明
value
要指定两个或更多覆盖，请将value设置为AssociationOverride实例的数组（请参阅@AssociationOverride）。
示例1-6显示了如何使用此批注指定两个关联覆盖。
示例1-3@AssociationOverrides
@Entity
@AssociationOverrides（{
@AssociationOverride（name="address",joinColumn=@Column（name="ADDR_ID"））,
@AssociationOverride（name="id",joinColumn=@Column（name="PTID"））
}）
publicclassPartTimeEmployeeextendsEmployee{
@Column（name="WAGE"）
protectedFloathourlyWage;
...
}
@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覆盖@MappedSuperclassEmployee中定义（默认情况下）的@Column，以便基本映射到Address。
如果使用@AttributeOverride，则Employee表包含以下列：
∙ID
∙VERSION
∙ADDR_STRING
∙WAGE
如果不使用@AttributeOverride，则Employee表包含以下列：
∙ID
∙VERSION
∙ADDRESS
∙WAGE
示例1-4@MappedSuperclass
@MappedSuperclass
publicclassEmployee{
@IdprotectedIntegerid;
@VersionprotectedIntegerversion;
protectedStringaddress;
...
}
示例1-5@AttributeOverride
@Entity
@AttributeOverride（name="address",column=@Column（name="ADDR_STRING"））
publicclassPartTimeEmployeeextendsEmployee{
@Column（name="WAGE"）
protectedFloathourlyWage;
...
}
@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"））
}）
publicclassPartTimeEmployeeextendsEmployee{
@Column（name="WAGE"）
protectedFloathourlyWage;
publicPartTimeEmployee（）{
...
}
publicFloatgetHourlyWage（）{
...
}
publicvoidsetHourlyWage（Floatwage）{
...
}
}
@Basic
默认情况下，JPA持续性提供程序为大多数Java基元类型、基元类型的包装程序以及枚举自动配置一个@Basic映射。
使用@Basic批注：
∙将获取类型配置为LAZY
∙如果空值不适合于应用程序，则将映射配置为禁止空值（针对非基元类型）
表1-6列出了此批注的属性。
有关更多详细信息，请参阅API。
表1-6@Basic属性
属性
必需
说明
fetch
默认值：
FetchType.EAGER。
默认情况下，JPA持续性提供程序使用获取类型EAGER：
这将要求持续性提供程序运行时必须迫切获取数据。
如果这不适合于应用程序或特定的持久字段，请将fetch设置为FetchType.LAZY：
这将提示持续性提供程序在首次访问数据（如果可以）时应不急于获取数据。
optional
默认值：
true。
默认情况下，JPA持续性提供程序假设所有（非基元）字段和属性的值可以为空。
如果这并不适合于您的应用程序，请将optional设置为false。
示例1-7显示了如何使用此批注为基本映射指定获取类型LAZY。
示例1-7@Basic
@Entity
publicclassEmployeeimplementsSerializable{
...
@Basic（fetch=LAZY）
protectedStringgetName（）{
returnname;
}
...
}
@Column
默认情况下，JPA持续性提供程序假设每个实体的持久字段存储在其名称与持久字段的名称相匹配的数据库表列中。
使用@Column批注：
∙将持久字段与其他名称关联（如果默认列名难于处理、与事先存在的数据模型不兼容或作为数据库中的列名无效）
∙将持久字段与辅助表中的列关联（请参阅@SecondaryTable）
∙微调数据库中列的特征
表1-7列出了此批注的属性。
有关更多详细信息，请参阅API。
表1-7@Column属性
属性
必需
说明
columnDefinition
默认值：
空String。
默认情况下，JPA使用最少量SQL创建一个数据库表列。
如果需要使用更多指定选项创建的列，请将columnDefinition设置为在针对列生成DDL时希望JPA使用的SQL片断。
注意：
捕获批注中的DDL信息时，某些JPA持续性提供程序可以在生成数据库模式时使用此DDL。
例如，请参阅“用于Java2DB模式生成的TopLinkJPA扩展”。
insertable
默认值：
true。
默认情况下，JPA持续性提供程序假设所有列始终包含在SQLINSERT语句中。
如果该列不应包含在这些语句中，请将insertable设置为false。
length
默认值：
255
默认情况下，JPA持续性提供程序假设所有列在用于保存String值时的最大长度为255个字符。
如果该列不适合于您的应用程序或数据库，请将length设置为适合于您的数据库列的int值。
name
默认值：
JPA持续性提供程序假设实体的每个持久字段都存储在其名称与持久字段或属性的名称相匹配的数据库表列中。
要指定其他列名，请将name设置为所需的String列名。
nullable
默认值：
true。
默认情况下，JPA持续性提供程序假设允许所有列包含空值。
如果不允许该列包含空值，请将nullable设置为false。
precision
默认值：
0.
默认情况下，JPA持续性提供程序假设所有列在用于保存十进制（精确数字）值时的精度为0。
如果该精度不适合于您的应用程序或数据库，请将precision设置为相应的int精度。
scale
默认值：
0.
默认情况下，JPA持续性提供程序假设所有列在用于保存十进制（精确数字）值时的伸缩度为0。
如果该伸缩度不适合于您的应用程序或数据库，请将scale设置为相应的int精度。
table
默认值：
JPA持续性提供程序假设实体的所有持久字段都存储到一个其名称为实体名称的数据库表中（请参阅@Table）。
如果该列与辅助表关联（请参阅@SecondaryTable），请将name设置为相应辅助表名称的String名称，如示例1-8所示。
unique
默认值：
false。
默认情况下，JPA持续性提供程序假设允许所有列包含重复值。
如果不允许该列包含重复值，请将unique设置为true。
设置为true时，这相当于在表级别使用@UniqueConstraint。
updatable
默认值：
true。
默认情况下，JPA持续性提供程序假设列始终包含在SQLUPDATE语句中。
如果该列不应包含在这些语句中，请将updatable设置为false。
示例1-8显示了如何使用此批注使JPA将empId持久保存到辅助表EMP_HR中的列EMP_NUM。
默认情况下，JPA将empName持久保存到主表Employee中的列empName。
示例1-8@Column
@Entity
@SecondaryTable（name="EMP_HR"）
publicclassEmployeeimplementsSerializable{
...
@Column（name="EMP_NUM",table="EMP_HR"）
privateLongempId;
privateStringempName;
...
}
@ColumnResult
执行@NamedNativeQuery时，它可以返回实体（包括不同类型的实体）、标量值或实体和标量值的组合。
使用@ColumnResult批注返回标量值。
标量类型由您在@ColumnResult中标识的列类型确定。
有关详细信息，另请参阅@EntityResult、@FieldResult和@SqlResultSetMapping。
表1-8列出了此批注的属性。
有关更多详细信息，请参阅API。
表1-8@ColumnResult属性
属性
必需
说明
name
在原生SQL查询的SELECT语句中将name设置为列名的String等效形式。
如果在SELECT中使用列别名（AS语句），则将name设置为列别名。
示例1-9显示了如何使用此批注将Item（请参阅示例1-10）标量name包含在结果列表（请参阅示例1-11）中。
在该示例中，结果列表将为Object数组的L
升级会员 