JPA 批注参考

2019年11月30日 阅读数:63
这篇文章主要向大家介绍JPA 批注参考,主要内容包括基础应用、实用技巧、原理机制等方面,希望对大家有所帮助。

 

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

      使用 JPA 时,可使用批注配置实体的 JPA 行为。批注是一种使用元数据修饰 Java 源代码的简单表达方法,它编译为相应的 Java 类文件,以便在运行时由 JPA 持续性提供程序解释以管理 JPA 行为。java

 

 

 

    

  · 批注索引      · 完整的 JPA 批注 Javadocsql

  按类别划分的 JPA 批注 数据库

类别 数组

说明 app

批注 ide

实体 性能

默认状况下,JPA 持续性提供程序假设 Java 类是非持续类,而且仅当使用此批注对其进行修饰的状况下才可用于 JPA 服务。 fetch

使用此批注将普通的旧式 Java 对象 (POJO) 类指定为实体,以即可以将它用于 JPA 服务。 spa

要将类用于 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-2 @AssociationOverride 属性

属性

必需

说明

joinColumns

wps_clip_image-8443

 

要指定映射到持久属性的链接列,请将 joinColums 设置为 JoinColumn 实例的数组(请参阅 @JoinColumn)。

映射类型将与可嵌套类或映射的超类中定义的类型相同。

name

wps_clip_image-29637

 

若是使用了基于属性的访问,则映射的为嵌入对象中的属性名称,若是使用了基于字段的访问,则映射的为字段名称。

 
  表 1-3 @AssociationOverrides 属性

属性

必需

说明

value

wps_clip_image-9543

 

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

 

 
表 1-4 @AttributeOverride 属性

属性

必需

说明

column

wps_clip_image-9889

 

映射到持久属性的 @Column。映射类型将与可嵌套类或映射超类中定义的类型相同。

name

wps_clip_image-7053

 

若是使用了基于属性的访问,则映射的为嵌入对象中的属性名称,若是使用了基于字段的访问,则映射的为字段名称。

 

 

  表 1-5 @AttributeOverrides 属性

属性

必需

说明

value

wps_clip_image-10131

 

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

 

 

  表 1-6 @Basic 属性

属性

必需

说明

fetch

wps_clip_image-10523

 

默认值FetchType.EAGER默认状况下,JPA 持续性提供程序使用获取类型 EAGER:这将要求持续性提供程序运行时必须迫切获取数据。若是这不适合于应用程序或特定的持久字段,请将 fetch 设置为 FetchType.LAZY:这将提示持续性提供程序在首次访问数据(若是能够)时应不急于获取数据。

optional

wps_clip_image-27860

 

默认值true

默认状况下,JPA 持续性提供程序假设全部(非基元)字段和属性的值能够为空。若是这并不适合于您的应用程序,请将 optional 设置为 false

 
 
  表 1-7 @Column 属性

属性

必需

说明

columnDefinition

wps_clip_image-10960

 

默认值:空 String

默认状况下,JPA 使用最少许 SQL 建立一个数据库表列。

若是须要使用更多指定选项建立的列,请将 columnDefinition 设置为在针对列生成 DDL 时但愿 JPA 使用的 SQL 片段。

注意:捕获批注中的 DDL 信息时,某些 JPA 持续性提供程序能够在生成数据库模式时使用此 DDL。例如,请参阅“用于 Java2DB 模式生成的 TopLink JPA 扩展”

insertable

wps_clip_image-26355

 

默认值true

默认状况下,JPA 持续性提供程序假设全部列始终包含在 SQL INSERT 语句中。

若是该列不该包含在这些语句中,请将 insertable 设置为 false

length

wps_clip_image-23332

 

默认值: 255

默认状况下,JPA 持续性提供程序假设全部列在用于保存 String 值时的最大长度为 255 个字符。

若是该列不适合于您的应用程序或数据库,请将 length 设置为适合于您的数据库列的 int 值。

name

wps_clip_image-21112

 

默认值:JPA 持续性提供程序假设实体的每一个持久字段都存储在其名称与持久字段或属性的名称相匹配的数据库表列中。

要指定其余列名,请将 name 设置为所需的 String 列名。

nullable

wps_clip_image-18352

 

默认值true

默认状况下,JPA 持续性提供程序假设容许全部列包含空值。

若是不容许该列包含空值,请将 nullable 设置为 false

precision

wps_clip_image-4505

 

默认值: 0.

默认状况下,JPA 持续性提供程序假设全部列在用于保存十进制(精确数字)值时的精度为 0。

若是该精度不适合于您的应用程序或数据库,请将 precision 设置为相应的 int 精度。

scale

wps_clip_image-17821

 

默认值: 0.

默认状况下,JPA 持续性提供程序假设全部列在用于保存十进制(精确数字)值时的伸缩度为 0。

若是该伸缩度不适合于您的应用程序或数据库,请将 scale 设置为相应的 int 精度。

table

wps_clip_image-2314

 

默认值:JPA 持续性提供程序假设实体的全部持久字段都存储到一个其名称为实体名称的数据库表中(请参阅 @Table)。

若是该列与辅助表关联(请参阅 @SecondaryTable),请将 name 设置为相应辅助表名称的 String 名称,如示例 1-8 所示。

unique

wps_clip_image-8780

 

默认值false

默认状况下,JPA 持续性提供程序假设容许全部列包含重复值。

若是不容许该列包含重复值,请将 unique 设置为 true。设置为 true 时,这至关于在表级别使用 @UniqueConstraint

updatable

wps_clip_image-26139

 

默认值true

默认状况下,JPA 持续性提供程序假设列始终包含在 SQL UPDATE 语句中。

若是该列不该包含在这些语句中,请将 updatable 设置为 false

 

  表 1-8 @ColumnResult 属性

属性

必需

说明

name

wps_clip_image-11271

 

在原生 SQL 查询的 SELECT 语句中将 name 设置为列名的 String 等效形式。若是在 SELECT 中使用列别名(AS 语句),则将 name 设置为列别名。

 

  表 1-9 @DiscriminatorColumn 属性

属性

必需

说明

columnDefinition

wps_clip_image-11555

 

默认值:空 String

默认状况下,JPA 持续性提供程序使用最少许 SQL 建立一个数据库表列。

若是须要使用更多指定选项建立的列,请将 columnDefinition 设置为在针对列生成 DDL 时但愿 JPA 使用的 SQL 片段。

discriminatorType

wps_clip_image-16484

 

默认值DiscriminatorType.STRING

默认状况下,JPA 持续性提供程序假设标识符类型为 String

若是要使用其余类型,请将 discriminatorType 设置为 DiscriminatorType.CHARDiscriminatorType.INTEGER

您的 @DiscriminatorValue 必须符合此类型。

length

wps_clip_image-30579

 

默认值: 31

默认状况下,JPA 持续性提供程序假设标识符列在用于保存 String 值时的最大长度为 255 个字符。

若是该列不适合于您的应用程序或数据库,请将 length 设置为适合于您的数据库列的 int 值。

您的 @DiscriminatorValue 必须符合此长度。

name

wps_clip_image-9723

 

默认值:JPA 持续性提供程序假设标识符列名为“DTYPE”。

要指定其余列名,请将 name 设置为所需的 String 列名。

 

  表 1-10 @DiscriminatorValue 属性

属性

必需

说明

value

wps_clip_image-11718

 

value 设置为符合 @DiscriminatorColumn 属性 discriminatorTypelength 的标识符值的 String 等效形式。

 

  表 1-11 @Entity 属性

属性

必需

说明

name

wps_clip_image-11943

 

默认值:JPA 持续性提供程序假设实体名称是实体类的名称。在示例 1-20 中,默认 name 为“Employee”。

若是实体类名难于处理、是一个保留字、与事先存在的数据模型不兼容或做为数据库中的表名无效,请将 name 设置为其余 String 值。

 

 

表 1-12 @EntityListeners 属性

属性

必需

说明

value

wps_clip_image-12136

 

要为 @Entity@MappedSuperclass 指定实体监听程序类的列表,请将 value 设置为实体监听程序类的 Class 数组。

 

  表 1-13 @EntityResult 属性

属性

必需

说明

entityClass

wps_clip_image-12642

 

entityClass 设置为由 SELECT 语句返回的实体的 Class

discriminatorColumn

wps_clip_image-23992

 

默认值:空 String

默认状况下,JPA 持续性提供程序假设 SELECT 语句中不包含标识符列(请参阅 @Inheritance)。

若是在 SELECT 语句中使用标识符列,请将 discriminatorColumn 设置为所使用的 String 列名。

fields

wps_clip_image-15572

 

默认值:空 FieldResult 数组。

默认状况下,JPA 持续性提供程序假设 SELECT 语句包含与返回的实体的全部字段或属性相对应的全部列,且 SELECT 语句中的列名对应于字段或属性名(未使用 AS 语句)。

若是 SELECT 语句只包含某些与返回的实体的字段或属性相对应的列,或 SELECT 语句中的列名并不对应于字段或属性名(使用了 AS 语句),请将 fields 设置为 @FieldResult 的数组,SELECT 语句中的每一列一个 @FieldResult

 

表 1-14 @Enumerated 属性 

属性

必需

说明

value

wps_clip_image-13766

 

默认值EnumType.ORDINAL

默认状况下,JPA 持续性提供程序假设对于映射到枚举常量的属性或字段,应持久保存序数值。在示例 1-28 中,当持久保存 Employee 时,EmployeeStatus 的序数值将写入数据库。

若是须要持久保存的枚举常量的 String 值,请将 value 设置为 EnumType.STRING

 
 
 
表 1-15 @FieldResult 属性

属性

必需

说明

column

wps_clip_image-14004

 

column 设置为 SELECT 语句中使用的列的 String 名称。若是在 SELECT 中使用列别名(AS 语句),请将 column 设置为列别名。

name

wps_clip_image-16861

 

name 设置为实体的字段或属性名(做为 String),该名称对应于 column 属性指定的列名。

 
表 1-16 @GeneratedValue 属性

属性

必需

说明

generator

wps_clip_image-14331

 

默认值:JPA 持续性提供程序为它选择的主键生成器分配一个名称。

若是该名称难于处理、是一个保留字、与事先存在的数据模型不兼容或做为数据库中的主键生成器名称无效,则将 generator 设置为要使用的 String 生成器名称。

strategy

wps_clip_image-10358

 

默认值GenerationType.AUTO

默认状况下,JPA 持续性提供程序选择最适合于基础数据库的主键生成器类型。

若是您感受另外一个生成器类型更适合于数据库或应用程序,请将 strategy 设置为所需的 GeneratorType

· IDENTITY — 指定持续性提供程序使用数据库身份列

· AUTO — 指定持续性提供程序应选择一个最适合于基础数据库的主键生成器。

· SEQUENCE — 指定持续性提供程序使用数据库序列(请参阅 @SequenceGenerator

· TABLE — 指定持续性提供程序为使用基础数据库表的实体分配主键以确保惟一性(请参阅 @TableGenerator

 
  表 1-17 @IdClass 属性

属性

必需

说明

value

wps_clip_image-15647

 

要指定复合主键类,请将 value 设置为所需的 Class(请参阅 @AttributeOverride)。

 
 
 
 
 
 
表 1-18 @Inheritance 属性

属性

必需

说明

 

strategy

wps_clip_image-16087

 

默认值InheritanceType.SINGLE_TABLE

默认状况下,JPA 持续性提供程序假设层次中的全部类均映射到一个由表的标识符列(请参阅 @DiscriminatorColumn)中的标识符值(请参阅 @DiscriminatorValue)区分的表。

若是这并不适合于应用程序,或者若是必须匹配现有的数据模型,请将 strategy 设置为所需的 InheritanceType

· SINGLE_TABLE href="#sthref28" Foot?1? — 层次中的全部类均映射到一个表。该表有一个标识符列(请参阅 @DiscriminatorColumn),它的值(请参阅 @DiscriminatorValue)标识由行表示的实例所属的特定子类。

· TABLE_PER_CLASS — 每一个类均映射到单独的表。该类的全部属性(包括继承的属性)映射到该类的表列。

· JOINED — 类层次的根由一个表表示,而每一个子类由单独的表表示。每一个子类表只包含特定于该子类的那些字段(而非从其超类继承的字段)和主键列,这些主键列用做超类表主键的外键。

 
 
表 1-19 @JoinColumn 属性

属性

必需

说明

columnDefinition

 

默认值:空 String

JPA 使用最少许 SQL 建立一个数据库表列。

若是须要使用更多指定选项建立列,请将 columnDefinition 设置为在针对列生成 DDL 时但愿 JPA 使用的 String SQL 片段。

insertable

 

默认值true

默认状况下,JPA 持续性提供程序假设它能够插入到全部表列中。

若是该列为只读,请将 insertable 设置为 false

name

 

默认值:若是使用一个链接列,则 JPA 持续性提供程序假设外键列的名称是如下名称的链接:

· 引用关系属性的名称 +“_”+ 被引用的主键列的名称。

· 引用实体的字段名称 +“_”+ 被引用的主键列的名称。

若是实体中没有这样的引用关系属性或字段(请参阅 @JoinTable),则链接列名称格式化为如下名称的链接:实体名称 +“_”+ 被引用的主键列的名称。

这是外键列的名称。若是链接针对“一对一”或“多对一”实体关系,则该列位于源实体的表中。若是链接针对“多对多”实体关系,则该列位于链接表(请参阅 @JoinTable)中。

若是链接列名难于处理、是一个保留字、与预先存在的数据模型不兼容或做为数据库中的列名无效,请将 name 设置为所需的 String 列名。

nullable

 

默认值true

默认状况下,JPA 持续性提供程序假设容许全部列包含空值。

若是不容许该列包含空值,请将 nullable 设置为 false

referencedColumnName

 

默认值:若是使用一个链接列,则 JPA 持续性提供程序假设在实体关系中,被引用的列名是被引用的主键列的名称。

若是在链接表(请参阅 @JoinTable)中使用,则被引用的键列位于拥有实体(若是链接是反向链接定义的一部分,则为反向实体)的实体表中。

要指定其余列名,请将 referencedColumnName 设置为所需的 String 列名。

table

 

默认值:JPA 持续性提供程序假设实体的全部持久字段存储到一个名称为实体类名称的数据库表中(请参阅 @Table)。

若是该列与辅助表关联(请参阅 @SecondaryTable),请将 name 设置为相应辅助表名称的 String 名称,如示例 1-8 所示。

unique

 

默认值false

默认状况下,JPA 持续性提供程序假设容许全部列包含重复值。

若是不容许该列包含重复值,请将 unique 设置为 true

updatable

 

默认值true

默认状况下,JPA 持续性提供程序假设它能够更新全部表列。

若是该列为只读,则将 updatable 设置为 false

 
 
    表 1-20 @JoinColumns 属性

属性

必需

说明

value

 

要指定两个或更多链接列,请将 value 设置为 JoinColumn 实例数组(请参阅 @JoinColumn)。

表 1-21 @JoinTable 属性

属性

必需

说明

catalog

 

默认值:空 String

默认状况下,JPA 使用任何适用于数据库的默认目录。

若是默认目录不适合于应用程序,请将 catalog 设置为要使用的 String 目录名。

inverseJoinColumns

 

默认值JoinColumn 的空数组。

默认状况下,JPA 持续性提供程序假设关联的被拥有方(或另外一方)上有一个链接列:被拥有实体的主键列。JPA 经过链接被拥有实体的名称 +“_”+ 被引用的主键列的名称来命名该列。

若是这样的列名难于处理、是一个保留字、与预先存在的数据模型不兼容,或者若是要指定多个链接列,则将 joinColumns 设置为 JoinColumn(请参阅 @JoinColumn)的一个或多个实例。

joinColumns

 

默认值JoinColumn 的空数组。

默认状况下,JPA 持续性提供程序假设:拥有实体的每一个主键列都有一个链接列。该持续性提供程序经过链接拥有实体的名称+“_”+ 被引用主键列的名称来命名这些列。

若是这样的列名难于处理、是一个保留字、与预先存在的数据模型不兼容,或者若是要指定多个链接列,则将 joinColumns 设置为 JoinColumn(请参阅 @JoinColumn)的一个或多个实例。

name

 

默认值:JPA 持续性提供程序经过使用下划线链接关联主表(拥有方优先)的表名来命名链接表。

若是这样的链接表难于处理、是一个保留字或与预先存在的数据模型不兼容,则将 name 设置为相应的链接表名。在示例 1-45 中,JPA 使用名为 EJB_PROJ_EMP 的链接表。

schema

 

默认值:空 String

默认状况下,JPA 使用任何适用于数据库的默认模式。

若是默认模式不适合于应用程序,则将 schema 设置为要使用的 String 模式名。

uniqueConstraints

 

默认值UniqueConstraint 的空数组。

默认状况下,JPA 持续性提供程序假设链接表中的任何列均没有惟一约束。

若是惟一约束应用于该表中的一列或多列,则将 uniqueContraints 设置为一个或多个 UniqueConstraint 实例的数组。有关详细信息,请参阅 @UniqueConstraint

 
表 1-22 @ManyToMany 属性

属性

必需

说明

cascade

 

默认值CascadeType 的空数组。

默认状况下,JPA 不会将任何持续性操做层叠到关联的目标。

若是但愿某些或全部持续性操做层叠到关联的目标,请将 cascade 设置为一个或多个 CascadeType 实例,其中包括:

· ALL — 针对拥有实体执行的任何持续性操做均层叠到关联的目标。

· MERGE — 若是合并了拥有实体,则将 merge 层叠到关联的目标。

· ;PERSIST — 若是持久保存拥有实体,则将 persist 层叠到关联的目标。

· REFRESH — 若是刷新了拥有实体,则 refresh 为关联的层叠目标。

· REMOVE — 若是删除了拥有实体,则还删除关联的目标。

fetch

 

默认值FetchType.EAGER

默认状况下,JPA 持续性提供程序使用获取类型 EAGER:这将要求持续性提供程序运行时必须迫切获取数据。

若是这不适合于应用程序或特定的持久字段,请将 fetch 设置为 FetchType.LAZY:这将提示持续性提供程序在首次访问数据(若是能够)时应不急于获取数据。

mappedBy

 

默认值:若是关系是单向的,则 JPA 持续性提供程序肯定拥有该关系的字段。

若是关系是双向的,则将关联的反向(非拥有)一方上的 mappedBy 属性设置为拥有该关系的字段或属性的名称(如示例 1-48 所示)。

targetEntity

 

默认值:使用通常参数定义的 Collection 的参数化类型。

默认状况下,若是使用经过通常参数定义的 Collection,则持续性提供程序将从被引用的对象类型推断出关联的目标实体。

若是 Collection 不使用通常参数,则必须指定做为关联目标的实体类:将关联拥有方上的 targetEntity 元素设置为做为关系目标的实体的 Class

 

表 1-23 @ManyToOne 属性

属性

必需

说明

cascade

 

默认值CascadeType 的空数组。

默认状况下,JPA 不会将任何持续性操做层叠到关联的目标。

若是但愿某些或全部持续性操做层叠到关联的目标,请将 cascade 设置为一个或多个 CascadeType 实例,其中包括:

· ALL — 针对拥有实体执行的任何持续性操做均层叠到关联的目标。

· MERGE — 若是合并了拥有实体,则将 merge 层叠到关联的目标。

· ;PERSIST — 若是持久保存拥有实体,则将 persist 层叠到关联的目标。

· REFRESH — 若是刷新了拥有实体,则 refresh 为关联的层叠目标。

· REMOVE — 若是删除了拥有实体,则还删除关联的目标。

fetch

 

默认值FetchType.EAGER

默认状况下,JPA 持续性提供程序使用获取类型 EAGER:这将要求持续性提供程序运行时必须迫切获取数据。

若是这不适合于应用程序或特定的持久字段,请将 fetch 设置为 FetchType.LAZY:这将提示持续性提供程序在首次访问数据(若是能够)时应不急于获取数据。

optional

 

默认值true

默认状况下,JPA 持续性提供程序假设全部(非基元)字段和属性的值能够为空。

若是这并不适合于您的应用程序,请将 optional 设置为 false

targetEntity

 

默认值:JPA 持续性提供程序从被引用的对象类型推断出关联的目标实体

若是持续性提供程序没法推断出目标实体的类型,则将关联拥有方上的 targetEntity 元素设置为做为关系目标的实体的 Class

 
 
 

表 1-24 @MapKey 属性

属性

必需

说明

name

 

默认值:默认状况下,JPA 持续性提供程序将关联实体的主键做为 Map 键,以用于映射到非复合主键或复合主键(批注为 @IdClass)的 java.util.Map 的属性或字段。

若是要将某个其余字段或属性用做 Map 键,请将 name 设置为要使用的关联实体的 String 字段或属性名。

 
 

表 1-25 @NamedNativeQueries 属性

属性

必需

说明

value

 

要指定两个或更多属性覆盖,请将 value 设置为 NamedNativeQuery 实例数组(请参阅 @NamedNativeQuery)。

 
 

表 1-26 @NamedNativeQuery 属性

属性

必需

说明

query

 

要指定查询,请将 query 设置为 SQL 查询(做为 String)。

有关原生 SQL 查询语言的详细信息,请参阅数据库文档。

hints

 

默认值:空 QueryHint 数组。

默认状况下,JPA 持续性提供程序假设 SQL 查询应彻底按照 query 属性提供的方式执行。

要微调查询的执行,能够选择将 hints 设置为一个 QueryHint 数组(请参阅 @QueryHint)。在执行时,EntityManager 将向基础数据库传递提示。

name

 

要指定查询名称,请将 name 设置为所需的 String 名称。

这是您在运行时调用查询所使用的名称(请参阅示例 1-60)。

resultClass

 

默认值:JPA 持续性提供程序假设结果类是关联实体的 Class

要指定结果类,请将 resultClass 设置为所需的 Class

resultSetMapping

 

默认值:JPA 持续性提供程序假设原生 SQL 查询中的 SELECT 语句:返回一个类型的实体;包括与返回的实体的全部字段或属性相对应的全部列;并使用与字段或属性名称(未使用 AS 语句)相对应的列名。

要控制 JPA 持续性提供程序如何将 JDBC 结果集映射到实体字段或属性以及标量,请经过将 resultSetMapping 设置为所需的 @SqlResultSetMappingString 名称来指定结果集映射。

 
 
 
 

表 1-27 @NamedQueries 属性

属性

必需

说明

value

 

要指定两个或更多属性覆盖,请将 value 设置为 NamedQuery 实例数组(请参阅 @NamedQuery)。

 
 
 
 
 

表 1-28 @NamedQuery 属性

属性

必需

说明

query

 

要指定查询,请将 query 设置为 JPA 查询语言(做为 String)。

有关 JPA 查询语言的详细信息,请参阅 JSR-000220 Enterprise JavaBeans v.3.0 规范的第 4 章。

hints

 

默认值:空 QueryHint 数组。

默认状况下,JPA 持续性提供程序假设 SQL 查询应彻底按照 query 属性提供的方式执行,而无论基础数据库如何。

若是您知道基础数据库在运行时的状态,则要微调查询的执行,能够选择将 hints 设置为 QueryHint 数组(请参阅 @QueryHint)。在执行时,EntityManager 将向基础数据库传递提示。

name

 

要指定查询名称,请将 name 设置为查询名称(做为 String)。

这是您在运行时调用查询所使用的名称(请参阅示例 1-60)。

 
 
 

表 1-29 @OneToMany 属性

属性

必需

说明

cascade

 

默认值CascadeType 的空数组。

默认状况下,JPA 不会将任何持续性操做层叠到关联的目标。

若是但愿某些或全部持续性操做层叠到关联的目标,请将 cascade 设置为一个或多个 CascadeType 实例,其中包括:

· ALL - 针对拥有实体执行的任何持续性操做均层叠到关联的目标。

· MERGE - 若是合并了拥有实体,则将 merge 层叠到关联的目标。

· ;PERSIST - 若是持久保存拥有实体,则将 persist 层叠到关联的目标。

· REFRESH - 若是刷新了拥有实体,则 refresh 为关联的层叠目标。

· REMOVE - 若是删除了拥有实体,则还删除关联的目标。

fetch

 

默认值FetchType.EAGER

默认状况下,JPA 持续性提供程序使用获取类型 EAGER:它要求持续性提供程序运行时必须急性获取数据。

若是这不适合于应用程序或特定的持久字段,请将 fetch 设置为 FetchType.LAZY:它提示持续性提供程序在首次访问数据(若是能够)时应惰性获取数据。

mappedBy

 

默认值:若是关系是单向的,则该持续性提供程序肯定拥有该关系的字段。

若是关系是双向的,则将关联相反(非拥有)方上的 mappedBy 元素设置为拥有此关系的字段或属性的名称(如示例 1-62 所示)。

targetEntity

 

默认值:使用通常参数定义的 Collection 的参数化类型。

默认状况下,若是使用经过通常参数定义的 Collection,则持续性提供程序从被引用的对象类型推断出关联的目标实体。

若是 Collection 不使用通常参数,则必须指定做为关联目标的实体类:将关联拥有方上的 targetEntity 元素设置为做为关系目标的实体的 Class

 
 
 
 

表 1-30 @OneToOne 属性

属性

必需

说明

cascade

 

默认值:空 CascadeType 数组。

默认状况下,JPA 不会将任何持续性操做层叠到关联的目标。

若是但愿某些或全部持续性操做层叠到关联的目标,请将 cascade 设置为一个或多个 CascadeType 实例,其中包括:

· ALL - 针对拥有实体执行的任何持续性操做均层叠到关联的目标。

· MERGE - 若是合并了拥有实体,则将 merge 层叠到关联的目标。

· ;PERSIST - 若是持久保存拥有实体,则将 persist 层叠到关联的目标。

· REFRESH - 若是刷新了拥有实体,则 refresh 为关联的层叠目标。

· REMOVE - 若是删除了拥有实体,则还删除关联的目标。

fetch

 

默认值FetchType.EAGER

默认状况下,JPA 持续性提供程序使用获取类型 EAGER:它要求持续性提供程序运行时必须急性获取数据。

若是这不适合于应用程序或特定的持久字段,请将 fetch 设置为 FetchType.LAZY:它提示持续性提供程序在首次访问数据(若是能够)时应惰性获取数据。

mappedBy

 

默认值:JPA 持续性提供程序从被引用的对象类型推断出关联的目标实体

若是持续性提供程序没法推断关联的目标实体,则将关联的相反(非拥有)方上的 mappedBy 元素设置为拥有此关系的字段或属性的 String 名称(如示例 1-64)所示。

optional

 

默认值true

默认状况下,JPA 持续性提供程序假设全部(非基元)字段和属性的值能够为空。

若是这并不适合于您的应用程序,请将 optional 设置为 false

targetEntity

 

默认值:JPA 持续性提供程序从被引用的对象类型推断出关联的目标实体

若是持续性提供程序没法推断出目标实体的类型,则将关联的拥有方上的 targetEntity 元素设置为做为关系目标的实体的 Class

 

 

 

表 1-31 @OrderBy 属性

属性

必需

说明

value

 

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

若是要按某些其余字段或属性排序并指定了不一样的排序,则将 value 设置为如下元素的逗号分隔列表:"property-or-field-name ASC|DESC”(请参阅示例 1-65)。

 

 

 

表 1-32 @PersistenceContext 属性

属性

必需

说明

name

 

默认值:JPA 持续性提供程序检索默认实体管理器。

若是要注入或查找特定实体管理器,请将 name 设置为要使用的实体管理器的 String 名称。

对于相关性注入,不须要 name

对于 JNDI 查找,必须将 name 设置为要在环境引用上下文中访问实体管理器所使用的名称。

properties

 

默认值:JPA 持续性提供程序假设实体管理器将使用默认属性。

若是要配置包含供应商特定属性的 JPA 持续性提供程序属性(例如,请参阅“TopLink JPA Persistence.xml 文件扩展”),请将 properties 设置为 @PersistenceProperty 实例数组。

type

 

默认值;PersistenceContextType.TRANSACTION

默认状况下,JPA 持续性提供程序假设实体管理器是容器管理的,而且它们的持续性上下文的生命周期伸缩到一个事务:即,持续性上下文在事务启动时开始存在,并在事务提交时中止存在。

在如下条件下,将 type 设置为 ;PersistenceContextType.EXTENDED

· 您的持续性上下文是应用程序管理的

· 您但愿扩展的持续性上下文在 EntityManager 实例从建立一直到关闭期间存在

· 您但愿实体管理器在事务提交后维护对实体对象的引用

· 您但愿调用 EntityManager 方法 persistremovemergerefresh,而不论事务是否处于活动状态

unitName

 

默认值:JPA 持续性提供程序检索默认持续性单元的默认实体管理器。

若是要注入或查找与特定持续性单元关联的实体管理器,则将 unitName 设置为所需的 String 持续性单元名称。或者,若是要指定 EntityManagerFactory 和持续性单元,则可使用 @PersistenceUnit

对于相关性注入,不须要 unitName

对于 JNDI 查找,若是指定 unitName,则由 name 访问的实体管理器必须与此持续性单元关联。

 

 

表 1-33 @PersistenceContexts 属性

属性

必需

说明

value

 

要指定两个或更多持续性上下文,请将 value 设置为 ;PersistenceContext 实例数组(请参阅 @PersistenceContext)。

 

 

表 1-34 @PersistenceProperty 属性

属性

必需

说明

name

 

要指定持续性属性的名称,请将 name 设置为 String 属性名。

有关持续性属性的详细信息,请参阅 JPA 持续性提供程序文档。

value

 

要指定持续性属性的值,请将 value 设置为所需的 String 属性值。

有关持续性属性值的详细信息,请参阅 JPA 持续性提供程序文档。

 

表 1-35 @PersistenceUnit 属性

属性

必需

说明

name

 

默认值:JPA 持续性提供程序从默认 EntityManagerFactory 中获取它的 EntityManager 实例。

若是但愿 JPA 持续性提供程序在注入或查找实体管理器时使用特定的 EntityManagerFactory,请将 name 设置为所需的实体管理器工厂的 String 名称。

对于相关性注入,不须要 name

对于 JNDI 查找,必须将 name 设置为要在环境引用上下文中访问实体管理器所使用的名称。

unitName

 

默认值:JPA 持续性提供程序检索默认持续性单元的默认实体管理器。

若是要注入或查找与特定持续性单元关联的实体管理器,则将 unitName 设置为所需的 String 持续性单元名称。另请参阅 @PersistenceContext

对于相关性注入,不须要 unitName

对于 JNDI 查找,若是指定 unitName,则由 name 访问的 EntityManagerFactory 必须与此持续性单元关联。

 

 

 

 

表 1-35 @PersistenceUnit 属性

属性

必需

说明

name

 

默认值:JPA 持续性提供程序从默认 EntityManagerFactory 中获取它的 EntityManager 实例。

若是但愿 JPA 持续性提供程序在注入或查找实体管理器时使用特定的 EntityManagerFactory,请将 name 设置为所需的实体管理器工厂的 String 名称。

对于相关性注入,不须要 name

对于 JNDI 查找,必须将 name 设置为要在环境引用上下文中访问实体管理器所使用的名称。

unitName

 

默认值:JPA 持续性提供程序检索默认持续性单元的默认实体管理器。

若是要注入或查找与特定持续性单元关联的实体管理器,则将 unitName 设置为所需的 String 持续性单元名称。另请参阅 @PersistenceContext

对于相关性注入,不须要 unitName

对于 JNDI 查找,若是指定 unitName,则由 name 访问的 EntityManagerFactory 必须与此持续性单元关联。

 
 
 
 

表 1-36 @PersistenceUnits 属性

属性

必需

说明

value

 

要指定两个或更多持续性单元,请将 value 设置为 ;PersistenceUnit 实例数组(请参阅 @PersistenceUnit)。

 
 
 
 
 

表 1-37 @PrimaryKeyJoinColumn 属性

属性

必需

说明

columnDefinition

 

默认值:空 String

默认状况下,JPA 使用最少许 SQL 建立一个数据库表列。

若是须要使用更多指定选项建立的列,请将 columnDefinition 设置为在生成列的 DDL 时但愿 JPA 使用的 String SQL 片段。

不要将此属性与 @OneToOne 映射一块儿使用。

name

 

默认值:JPA 持续性提供程序对当前表的主键列采用如下名称之一(取决于您使用该批注的方式):

· InheritanceType.JOINED(请参阅 @Inheritance):与超类的主键列同名。

· @SecondaryTable 映射:与主表的主键列同名。

· @OneToOne 映射:与引用实体的表的主键列同名。

若是该名称难于处理、是一个保留字、与事先存在的数据模型不兼容或做为数据库中的列名无效,则将 name 设置为所需的 String 列名。

referencedColumnName

 

默认值:JPA 持续性提供程序对链接到的表的主键列采用如下名称之一(取决于您使用该批注的方式):

· InheritanceType.JOINED(请参阅 @Inheritance):与超类的主表的主键列同名。

· @SecondaryTable 映射:与主表的主键列同名。

· @OneToOne 映射:与被引用实体的表的主键列同名。

若是该名称难于处理、是一个保留字、与预先存在的数据模型不兼容或做为数据库中的列名无效,请将 referencedColumnName 设置为所需的 String 列名。

 
 
 

表 1-38 @PrimaryKeyJoinColumns 属性

属性

必需

说明

value

 

要指定一个复合(多列)主键,请将 value 设置为 ;PrimaryKeyJoinColumn 实例的数组(请参阅 @PrimaryKeyJoinColumn)。

 
 

表 1-39 @QueryHint 属性

属性

必需

说明

name

 

要指定提示名称,请将 name 设置为 String 提示名称。

有关提示的详细信息,请参阅 JPA 持续性提供程序文档。

value

 

要指定提示的值,请将 value 设置为所需的 String 提示值。

有关提示值的详细信息,请参阅 JPA 持续性提供程序文档。

 
 
 
 
 
 
 

表 1-40 @SecondaryTable 属性

属性

必需

说明

姓名

 

若是实体使用辅助表,请将 name 设置为 String 表名。

catalog

 

默认值:JPA 持续性提供程序使用任何适用于数据库的默认目录。

若是默认目录不适合于应用程序,请将 catalog 设置为要使用的 String 目录名。

pkJoinColumns

 

默认值:JPA 持续性提供程序假设实体的数据库表中的任何列均不用于主键链接。

若是对该表中的主键链接使用一个或多个列,请将 pkJoinColumns 设置为一个或多个 @PrimaryKeyJoinColumn 实例的数组。有关详细信息,请参阅 @PrimaryKeyJoinColumn

schema

 

默认值:JPA 持续性提供程序使用任何适用于数据库的默认模式。

若是默认模式不适合于应用程序,请将 schema 设置为要使用的 String 模式名。

uniqueConstraints

 

默认值:JPA 持续性提供程序假设实体的数据库表中的任何列均没有惟一约束。

若是惟一约束应用于该表中的一列或多列,请将 uniqueContraints 设置为一个或多个 UniqueConstraint 实例的数组。有关详细信息,请参阅 @UniqueConstraint

 

表 1-41 @SecondaryTables 属性

属性

必需

说明

value

 

要指定两个或更多辅助表,请将 value 设置为 SecondaryTable 实例的数组(请参阅 @SecondaryTable)。

 
 
 

表 1-42 @SequenceGenerator 属性

属性

必需

说明

name

 

SequenceGenerator 的名称必须匹配其 startegy 设置为 SEQUENCEGeneratedValue 的名称。

allocationSize

 

默认值: 50.

默认状况下,JPA 持续性提供程序使用的分配大小为 50。

若是此分配大小与应用程序要求或数据库性能参数不匹配,请将 allocationSize 设置为所需的 int 值。

initialValue

 

默认值: 0.

默认状况下,JPA 持续性提供程序假设持续性提供程序将全部主键值的起始值设置为 0。

若是这与现有数据模型不匹配,请将 initialValue 设置为所需的 int 值。

sequenceName

 

默认值:JPA 持续性提供程序分配它本身建立的序列名。

若是要使用事先存在或预约义的序列,请将 sequenceName 设置为所需的 String 名称。

 

 

表 1-43 @SqlResultSetMapping 属性

属性

必需

说明

name

 

name 设置为此 @SqlResultSetMappingString 名称。

这是用于将 @SqlResultSetMapping 与原生 SQL 查询关联的名称(请参阅示例 1-84)。

columns

 

默认值:空 ColumnResult 数组。

默认状况下,JPA 持续性提供程序假设 SELECT 语句只返回实体。

若是 SELECT 语句返回标量值,则将 columns 设置为 ColumnResult 实例的数组,每一个标量结果一个 @ColumnResult

entities

 

默认值:空 EntityResult 数组。

默认状况下,JPA 持续性提供程序假设 SELECT 语句返回一个类型的实体。

若是 SELECT 语句返回多个类型的实体,请将实体设置为 EntityResult 实例的数组,每一个返回的实体类型一个 @EntityResult

 

 

表 1-44 @SqlResultSetMappings 属性

属性

必需

说明

value

 

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

 
 
 

表 1-45 @Table 属性

属性

必需

说明

catalog

 

默认值:JPA 持续性提供程序使用任何适用于数据库的默认目录。

若是默认目录不适合于应用程序,请将 catalog 设置为要使用的 String 目录名。

name

 

默认值:JPA 持续性提供程序假设实体的数据库表与实体类同名。在示例 1-86 中,默认 nameEmployee

若是实体类名难以处理、是一个保留字或与预先存在的数据模型不兼容,请将 name 设置为相应的数据表名称。在示例 1-86 中,JPA 将实体类 Employee 持久保存到名为 EMP 的数据库表中。

schema

 

默认值:JPA 持续性提供程序使用任何适用于数据库的默认模式。

若是默认模式不适合于应用程序,请将 schema 设置为要使用的 String 模式名。

uniqueConstraints

 

默认值:JPA 持续性提供程序假设实体的数据库表中的任何列均没有惟一约束。

若是惟一约束应用于该表中的一列或多列,请将 uniqueContraints 设置为一个或多个 UniqueConstraint 实例的数组。有关详细信息,请参阅 @UniqueConstraint

 

 

 

 

表 1-46 @TableGenerator 属性

属性

必需

说明

name

 

SequenceGenerator 的名称必须匹配其 startegy 设置为 startegyGeneratedValue 的名称。生成器名称的做用域对持续性单元是全局的(跨全部生成器类型)。

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-47 @Temporal 属性

属性

必需

说明

value

 

value 设置为与但愿 JPA 持续性提供程序使用的数据库类型相对应的 TemporalType

· DATE - 等于 java.sql.Date

· TIME - 等于 java.sql.Time

· TIMESTAMP - 等于 java.sql.Timestamp

 

 

 

表 1-48 @UniqueConstraint 属性

属性

必需

说明

columnNames

 

若是任何列均包含惟一约束,请将 columnNames 设置为 String 列名的数组。