JPA 批註參考

時間 2019-11-30

標籤 jpa 批註參考欄目 Java 简体版

原文原文鏈接

在 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

要指定映射到持久屬性的鏈接列，請將 joinColums 設置爲 JoinColumn 實例的數組（請參閱 @JoinColumn）。

映射類型將與可嵌套類或映射的超類中定義的類型相同。

name

若是使用了基於屬性的訪問，則映射的爲嵌入對象中的屬性名稱，若是使用了基於字段的訪問，則映射的爲字段名稱。

表 1-3 @AssociationOverrides 屬性

屬性

必需

說明

value

要指定兩個或更多覆蓋，請將 value 設置爲 AssociationOverride 實例的數組（請參閱 @AssociationOverride）。

表 1-4 @AttributeOverride 屬性

屬性

必需

說明

column

映射到持久屬性的 @Column。映射類型將與可嵌套類或映射超類中定義的類型相同。

name

若是使用了基於屬性的訪問，則映射的爲嵌入對象中的屬性名稱，若是使用了基於字段的訪問，則映射的爲字段名稱。

表 1-5 @AttributeOverrides 屬性

屬性

必需

說明

value

要指定兩個或更多屬性覆蓋，請將 value 設置爲 AttributeOverride 實例的數組（請參閱 @AttributeOverride）。

表 1-6 @Basic 屬性

屬性

必需

說明

fetch

默認值：FetchType.EAGER。默認狀況下，JPA 持續性提供程序使用獲取類型 EAGER：這將要求持續性提供程序運行時必須迫切獲取數據。若是這不適合於應用程序或特定的持久字段，請將 fetch 設置爲 FetchType.LAZY：這將提示持續性提供程序在首次訪問數據（若是能夠）時應不急於獲取數據。

optional

默認值：true。

默認狀況下，JPA 持續性提供程序假設全部（非基元）字段和屬性的值能夠爲空。若是這並不適合於您的應用程序，請將 optional 設置爲 false。

表 1-7 @Column 屬性

屬性

必需

說明

columnDefinition

默認值：空 String。

默認狀況下，JPA 使用最少許 SQL 建立一個數據庫表列。

若是須要使用更多指定選項建立的列，請將 columnDefinition 設置爲在針對列生成 DDL 時但願 JPA 使用的 SQL 片段。

注意：捕獲批註中的 DDL 信息時，某些 JPA 持續性提供程序能夠在生成數據庫模式時使用此 DDL。例如，請參閱「用於 Java2DB 模式生成的 TopLink JPA 擴展」。

insertable

默認值：true。

默認狀況下，JPA 持續性提供程序假設全部列始終包含在 SQL INSERT 語句中。

若是該列不該包含在這些語句中，請將 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 持續性提供程序假設列始終包含在 SQL UPDATE 語句中。

若是該列不該包含在這些語句中，請將 updatable 設置爲 false。

表 1-8 @ColumnResult 屬性

屬性

必需

說明

name

在原生 SQL 查詢的 SELECT 語句中將 name 設置爲列名的 String 等效形式。若是在 SELECT 中使用列別名（AS 語句），則將 name 設置爲列別名。

表 1-9 @DiscriminatorColumn 屬性

屬性

必需

說明

columnDefinition

默認值：空 String。

默認狀況下，JPA 持續性提供程序使用最少許 SQL 建立一個數據庫表列。

若是須要使用更多指定選項建立的列，請將 columnDefinition 設置爲在針對列生成 DDL 時但願 JPA 使用的 SQL 片段。

discriminatorType

默認值：DiscriminatorType.STRING。

默認狀況下，JPA 持續性提供程序假設標識符類型爲 String。

若是要使用其餘類型，請將 discriminatorType 設置爲 DiscriminatorType.CHAR 或 DiscriminatorType.INTEGER。

您的 @DiscriminatorValue 必須符合此類型。

length

默認值： 31

默認狀況下，JPA 持續性提供程序假設標識符列在用於保存 String 值時的最大長度爲 255 個字符。

若是該列不適合於您的應用程序或數據庫，請將 length 設置爲適合於您的數據庫列的 int 值。

您的 @DiscriminatorValue 必須符合此長度。

name

默認值：JPA 持續性提供程序假設標識符列名爲「DTYPE」。

要指定其餘列名，請將 name 設置爲所需的 String 列名。

表 1-10 @DiscriminatorValue 屬性

屬性

必需

說明

value

將 value 設置爲符合 @DiscriminatorColumn 屬性 discriminatorType 和 length 的標識符值的 String 等效形式。

表 1-11 @Entity 屬性

屬性

必需

說明

name

默認值：JPA 持續性提供程序假設實體名稱是實體類的名稱。在示例 1-20 中，默認 name 爲「Employee」。

若是實體類名難於處理、是一個保留字、與事先存在的數據模型不兼容或做爲數據庫中的表名無效，請將 name 設置爲其餘 String 值。

表 1-12 @EntityListeners 屬性

屬性

必需

說明

value

要爲 @Entity 或 @MappedSuperclass 指定實體監聽程序類的列表，請將 value 設置爲實體監聽程序類的 Class 數組。

表 1-13 @EntityResult 屬性

屬性	必需	說明
entityClass		將 entityClass 設置爲由 SELECT 語句返回的實體的 Class。
discriminatorColumn		默認值：空 String。默認狀況下，JPA 持續性提供程序假設 SELECT 語句中不包含標識符列（請參閱 @Inheritance）。若是在 SELECT 語句中使用標識符列，請將 discriminatorColumn 設置爲所使用的 String 列名。
fields		默認值：空 FieldResult 數組。默認狀況下，JPA 持續性提供程序假設 SELECT 語句包含與返回的實體的全部字段或屬性相對應的全部列，且 SELECT 語句中的列名對應於字段或屬性名（未使用 AS 語句）。若是 SELECT 語句只包含某些與返回的實體的字段或屬性相對應的列，或 SELECT 語句中的列名並不對應於字段或屬性名（使用了 AS 語句），請將 fields 設置爲 @FieldResult 的數組，SELECT 語句中的每一列一個 @FieldResult。

表 1-14 @Enumerated 屬性

屬性

必需

說明

value

默認值：EnumType.ORDINAL。

默認狀況下，JPA 持續性提供程序假設對於映射到枚舉常量的屬性或字段，應持久保存序數值。在示例 1-28 中，當持久保存 Employee 時，EmployeeStatus 的序數值將寫入數據庫。

若是須要持久保存的枚舉常量的 String 值，請將 value 設置爲 EnumType.STRING。

表 1-15 @FieldResult 屬性

屬性

必需

說明

column

將 column 設置爲 SELECT 語句中使用的列的 String 名稱。若是在 SELECT 中使用列別名（AS 語句），請將 column 設置爲列別名。

name

將 name 設置爲實體的字段或屬性名（做爲 String），該名稱對應於 column 屬性指定的列名。

表 1-16 @GeneratedValue 屬性

屬性

必需

說明

generator

默認值：JPA 持續性提供程序爲它選擇的主鍵生成器分配一個名稱。

若是該名稱難於處理、是一個保留字、與事先存在的數據模型不兼容或做爲數據庫中的主鍵生成器名稱無效，則將 generator 設置爲要使用的 String 生成器名稱。

strategy

默認值：GenerationType.AUTO。

默認狀況下，JPA 持續性提供程序選擇最適合於基礎數據庫的主鍵生成器類型。

若是您感受另外一個生成器類型更適合於數據庫或應用程序，請將 strategy 設置爲所需的 GeneratorType：

· IDENTITY — 指定持續性提供程序使用數據庫身份列

· AUTO — 指定持續性提供程序應選擇一個最適合於基礎數據庫的主鍵生成器。

· SEQUENCE — 指定持續性提供程序使用數據庫序列（請參閱 @SequenceGenerator）

· TABLE — 指定持續性提供程序爲使用基礎數據庫表的實體分配主鍵以確保惟一性（請參閱 @TableGenerator）

表 1-17 @IdClass 屬性

屬性

必需

說明

value

要指定複合主鍵類，請將 value 設置爲所需的 Class（請參閱 @AttributeOverride）。

表 1-18 @Inheritance 屬性

屬性

必需

說明

strategy

默認值：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 持續性提供程序假設：擁有實體的每一個主鍵列都有一個鏈接列。該持續性提供程序經過鏈接擁有實體的名稱+「_」+ 被引用主鍵列的名稱來命名這些列。

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：這將要求持續性提供程序運行時必須迫切獲取數據。

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 設置爲所需的 @SqlResultSetMapping 的 String 名稱來指定結果集映射。

表 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 方法 persist、remove、merge 和 refresh，而不論事務是否處於活動狀態

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 設置爲 SEQUENCE 的 GeneratedValue 的名稱。
allocationSize		默認值： 50. 默認狀況下，JPA 持續性提供程序使用的分配大小爲 50。若是此分配大小與應用程序要求或數據庫性能參數不匹配，請將 allocationSize 設置爲所需的 int 值。
initialValue		默認值： 0. 默認狀況下，JPA 持續性提供程序假設持續性提供程序將全部主鍵值的起始值設置爲 0。若是這與現有數據模型不匹配，請將 initialValue 設置爲所需的 int 值。
sequenceName		默認值：JPA 持續性提供程序分配它本身建立的序列名。若是要使用事先存在或預約義的序列，請將 sequenceName 設置爲所需的 String 名稱。

表 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。