Hibernate4之JPA規範配置詳解

http://zhou137520.iteye.com/blog/1628384

@Table 
Table用來定義entity主表的name，catalog，schema等屬性。 
屬性說明： 

• name：表名
• catalog：對應關係數據庫中的catalog
• schema：對應關係數據庫中的schema
• UniqueConstraints：定義一個UniqueConstraint數組，指定需要建唯一約束的列

@Entity
@Table(name="CUST")
public class Customer { ... }

@SecondaryTable 
一個entity class可以映射到多表，SecondaryTable用來定義單個從表的名字，主鍵名字等屬性。 
屬性說明： 

• name：表名
• catalog：對應關係數據庫中的catalog
• pkJoin：定義一個PrimaryKeyJoinColumn數組，指定從表的主鍵列
• UniqueConstraints：定義一個UniqueConstraint數組，指定需要建唯一約束的列

下面的代碼說明Customer類映射到兩個表，主表名是CUSTOMER，從表名是CUST_DETAIL，從表的主鍵列和主表的主鍵列類型相同，列名爲CUST_ID。 

@Entity
@Table(name="CUSTOMER")
@SecondaryTable(name="CUST_DETAIL",pkJoin=@PrimaryKeyJoinColumn(name="CUST_ID"))
public class Customer { ... }

@SecondaryTables 
當一個entity class映射到一個主表和多個從表時，用SecondaryTables來定義各個從表的屬性。 
屬性說明： 

• value：定義一個SecondaryTable數組，指定每個從表的屬性。

@Table(name = "CUSTOMER")
@SecondaryTables( value = {
@SecondaryTable(name = "CUST_NAME", pkJoin = { @PrimaryKeyJoinColumn(name = "STMO_ID", referencedColumnName = "id") }),
@SecondaryTable(name = "CUST_ADDRESS", pkJoin = { @PrimaryKeyJoinColumn(name = "STMO_ID", referencedColumnName = "id") }) })
public class Customer {}

@UniqueConstraint 
UniqueConstraint定義在Table或SecondaryTable元數據裏，用來指定建表時需要建唯一約束的列。 
屬性說明： 

• columnNames：定義一個字符串數組，指定要建唯一約束的列名。

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

@Column 
Column元數據定義了映射到數據庫的列的所有屬性：列名，是否唯一，是否允許爲空，是否允許更新等。 
屬性說明： 

• unique：是否唯一
• nullable：是否允許爲空
• insertable：是否允許插入
• updatable：是否允許更新
• columnDefinition：定義建表時創建此列的DDL
• secondaryTable：從表名。如果此列不建在主表上（默認建在主表），該屬性定義該列所在從表的名字。

public class Person {
    @Column(name = "PERSONNAME", unique = true, nullable = false, updatable = true)
    private String name;
    @Column(name = "PHOTO", columnDefinition = "BLOB NOT NULL", secondaryTable="PER_PHOTO")
    private byte[] picture;

@JoinColumn 
如果在entity class的field上定義了關係（one2one或one2many等），我們通過JoinColumn來定義關係的屬性。JoinColumn的大部分屬性和Column類似。 
屬性說明： 

• unique：是否唯一
• referencedColumnName：該列指向列的列名（建表時該列作爲外鍵列指向關係另一端的指定列）
• nullable：是否允許爲空
• insertable：是否允許插入
• updatable：是否允許更新
• columnDefinition：定義建表時創建此列的DDL
• secondaryTable：從表名。如果此列不建在主表上（默認建在主表），該屬性定義該列所在從表的名字。

下面的代碼說明Custom和Order是一對一關係。在Order對應的映射表建一個名爲CUST_ID的列，該列作爲外鍵指向Custom對應表中名爲ID的列。 

public class Custom {
    @OneToOne
    @JoinColumn(name="CUST_ID", referencedColumnName="ID", unique=true, nullable=true, updatable=true)
    public Order getOrder() {
    return order;
    }

@JoinColumns 
如果在entity class的field上定義了關係（one2one或one2many等），並且關係存在多個JoinColumn，用JoinColumns定義多個JoinColumn的屬性。 
屬性說明： 

• value：定義JoinColumn數組，指定每個JoinColumn的屬性。

下面的代碼說明Custom和Order是一對一關係。在Order對應的映射表建兩列，一列名爲CUST_ID，該列作爲外鍵指向Custom對應表中名爲ID的列,另一列名爲CUST_NAME，該列作爲外鍵指向Custom對應表中名爲NAME的列。 

public class Custom {
    @OneToOne
    @JoinColumns({
        @JoinColumn(name="CUST_ID", referencedColumnName="ID"),
        @JoinColumn(name="CUST_NAME", referencedColumnName="NAME")
    })
    public Order getOrder() {
    return order;
    }

@Id 
聲明當前field爲映射表中的主鍵列。id值的獲取方式有五種：TABLE, SEQUENCE, IDENTITY, AUTO, NONE。Oracle和DB2支持SEQUENCE，SQL Server和Sybase支持IDENTITY,mysql支持AUTO。所有的數據庫都可以指定爲AUTO，我們會根據不同數據庫做轉換。NONE(默認)需要用戶自己指定Id的值。
屬性說明： 

• generate：主鍵值的獲取類型
• generator：TableGenerator的名字（當generate=GeneratorType.TABLE才需要指定該屬性）

下面的代碼聲明Task的主鍵列id是自動增長的。(Oracle和DB2從默認的SEQUENCE取值，SQL Server和Sybase該列建成IDENTITY，mysql該列建成auto increment。) 

 @Entity
 @Table(name = "OTASK")
 public class Task {
@Id(generate = GeneratorType.AUTO)
public Integer getId() {
 return id;
}
 }

  

@IdClass 
當entity class使用複合主鍵時，需要定義一個類作爲id class。id class必須符合以下要求:類必須聲明爲public，並提供一個聲明爲public的空構造函數。必須實現Serializable接，覆寫equals()和hashCode（）方法。entity class的所有id field在id class都要定義，且類型一樣。 
屬性說明： 

• value：id class的類名

下面的代碼聲明Task的主鍵列id是自動增長的。(Oracle和DB2從默認的SEQUENCE取值，SQL Server和Sybase該列建成IDENTITY，mysql該列建成auto increment。) 

public class EmployeePK implements java.io.Serializable{
   String empName;
   Integer empAge;
public EmployeePK(){}
public boolean equals(Object obj){ ......}
public int hashCode(){......}
}
@IdClass(value=com.acme.EmployeePK.class)
@Entity(access=FIELD)
public class Employee {
    @Id String empName;
    @Id Integer empAge;
}

@MapKey 
在一對多，多對多關係中，我們可以用Map來保存集合對象。默認用主鍵值做key，如果使用複合主鍵，則用id class的實例做key，如果指定了name屬性，就用指定的field的值做key。 
屬性說明： 

• name：用來做key的field名字

下面的代碼說明Person和Book之間是一對多關係。Person的books字段是Map類型，用Book的isbn字段的值作爲Map的key。 

   @Table(name = "PERSON")
   public class Person {
@OneToMany(targetEntity = Book.class, cascade = CascadeType.ALL, mappedBy = "person")
@MapKey(name = "isbn")
private Map books = new HashMap();
   }

@MappedSuperclass 
使用@MappedSuperclass指定一個實體類從中繼承持久字段的超類。當多個實體類共享通用的持久字段或屬性時，這將是一個方便的模式。 

您可以像對實體那樣使用任何直接和關係映射批註（如 @Basic 和 @ManyToMany）對該超類的字段和屬性進行批註，但由於沒有針對該超類本身的表存在，因此這些映射只適用於它的子類。繼承的持久字段或屬性屬於子類的表。 

可以在子類中使用@AttributeOverride或@AssociationOverride來覆蓋超類的映射配置。 
@MappedSuperclass沒有屬性。 

//如何將Employee指定爲映射超類
@MappedSuperclass
public class Employee {
    @Id
    protected Integer empId;

    @Version
    protected Integer version;

    @ManyToOne
    @JoinColumn(name="ADDR")
    protected Address address;
}

//如何在實體類中使用@AttributeOverride以覆蓋超類中設置的配置。
@Entity
@AttributeOverride(name="address", column=@Column(name="ADDR_ID"))
public class PartTimeEmployee extends Employee {
    @Column(name="WAGE")
    protected Float hourlyWage;
}

    


@PrimaryKeyJoinColumn 
在三種情況下會用到@PrimaryKeyJoinColumn 

• 繼承。
• entity class映射到一個或多個從表。從表根據主表的主鍵列（列名爲referencedColumnName值的列），建立一個類型一樣的主鍵列，列名由name屬性定義。
• one2one關係，關係維護端的主鍵作爲外鍵指向關係被維護端的主鍵，不再新建一個外鍵列。

屬性說明： 

• name：列名。
• referencedColumnName：該列引用列的列名
• columnDefinition：定義建表時創建此列的DDL

下面的代碼說明Customer映射到兩個表，主表CUSTOMER,從表CUST_DETAIL，從表需要建立主鍵列CUST_ID，該列和主表的主鍵列id除了列名不同，其他定義一樣。 

   @Entity
   @Table(name="CUSTOMER")
@SecondaryTable(name="CUST_DETAIL",pkJoin=@PrimaryKeyJoinColumn(name="CUST_ID"，referencedColumnName="id"))
   public class Customer {
       @Id(generate = GeneratorType.AUTO)
       public Integer getId() {
    return id;
}
   }

下面的代碼說明Employee和EmployeeInfo是一對一關係，Employee的主鍵列id作爲外鍵指向EmployeeInfo的主鍵列INFO_ID。 

   @Table(name = "Employee")
   public class Employee {
@OneToOne
@PrimaryKeyJoinColumn(name = "id", referencedColumnName="INFO_ID")
EmployeeInfo info;
   }

    
    

@PrimaryKeyJoinColumns 
如果entity class使用了複合主鍵，指定單個PrimaryKeyJoinColumn不能滿足要求時，可以用PrimaryKeyJoinColumns來定義多個PrimaryKeyJoinColumn 
屬性說明： 

• value： 一個PrimaryKeyJoinColumn數組，包含所有PrimaryKeyJoinColumn

下面的代碼說明了Employee和EmployeeInfo是一對一關係。他們都使用複合主鍵，建表時需要在Employee表建立一個外鍵，從Employee的主鍵列id,name指向EmployeeInfo的主鍵列INFO_ID和INFO_NAME 

   @Entity
   @IdClass(EmpPK.class)
   @Table(name = "EMPLOYEE")
   public class Employee {
private int id;
private String name;
private String address;
@OneToOne(cascade = CascadeType.ALL)
@PrimaryKeyJoinColumns({
@PrimaryKeyJoinColumn(name="id", referencedColumnName="INFO_ID"),
@PrimaryKeyJoinColumn(name="name" , referencedColumnName="INFO_NAME")})
EmployeeInfo info;
   }


   @Entity
   @IdClass(EmpPK.class)
   @Table(name = "EMPLOYEE_INFO")
   public class EmployeeInfo {
@Id
@Column(name = "INFO_ID")
private int id;
@Id
@Column(name = "INFO_NAME")
private String name;
   }

@Transient 
Transient用來註釋entity的屬性，指定的這些屬性不會被持久化，也不會爲這些屬性建表 

@Transient
private String name;

    

@Version 
Version指定實體類在樂觀事務中的version屬性。在實體類重新由EntityManager管理並且加入到樂觀事務中時，保證完整性。每一個類只能有一個屬性被指定爲version，version屬性應該映射到實體類的主表上。 
屬性說明： 

• value： 一個PrimaryKeyJoinColumn數組，包含所有PrimaryKeyJoinColumn

下面的代碼說明versionNum屬性作爲這個類的version，映射到數據庫中主表的列名是OPTLOCK 

@Version
@Column("OPTLOCK")
protected int getVersionNum() { return versionNum; }

@Lob 
Lob指定一個屬性作爲數據庫支持的大對象類型在數據庫中存儲。使用LobType這個枚舉來定義Lob是二進制類型還是字符類型。 
LobType枚舉類型說明： 

• BLOB 二進制大對象，Byte[]或者Serializable的類型可以指定爲BLOB。
• CLOB 字符型大對象，char[]、Character[]或String類型可以指定爲CLOB。

屬性說明： 

• fetch：定義這個字段是lazy loaded還是eagerly fetched。數據類型是FetchType枚舉，默認爲LAZY,即lazy loaded.
• type：定義這個字段在數據庫中的JDBC數據類型。數據類型是LobType枚舉，默認爲BLOB。

下面的代碼定義了一個BLOB類型的屬性和一個CLOB類型的屬性 

@Lob
@Column(name="PHOTO" columnDefinition="BLOB NOT NULL")
protected JPEGImage picture;

@Lob(fetch=EAGER, type=CLOB)
@Column(name="REPORT")
protected String report;

  
   

@JoinTable 
JoinTable在many-to-many關係的所有者一邊定義。如果沒有定義JoinTable，使用JoinTable的默認值。 
屬性說明： 

• table：這個join table的Table定義。
• joinColumns：定義指向所有者主表的外鍵列，數據類型是JoinColumn數組。
• inverseJoinColumns：定義指向非所有者主表的外鍵列，數據類型是JoinColumn數組。

下面的代碼定義了一個連接表CUST和PHONE的join table。join table的表名是CUST_PHONE，包含兩個外鍵，一個外鍵是CUST_ID，指向表CUST的主鍵ID，另一個外鍵是PHONE_ID，指向表PHONE的主鍵ID。 

@JoinTable(
table=@Table(name=CUST_PHONE),
joinColumns=@JoinColumn(name="CUST_ID", referencedColumnName="ID"),
inverseJoinColumns=@JoinColumn(name="PHONE_ID", referencedColumnName="ID")
)

@TableGenerator 
TableGenerator定義一個主鍵值生成器，在Id這個元數據的generate＝TABLE時，generator屬性中可以使用生成器的名字。生成器可以在類、方法或者屬性上定義。 
生成器是爲多個實體類提供連續的ID值的表，每一行爲一個類提供ID值，ID值通常是整數。 
屬性說明： 

• name：生成器的唯一名字，可以被Id元數據使用。
• table：生成器用來存儲id值的Table定義。
• pkColumnName：生成器表的主鍵名稱。
• valueColumnName：生成器表的ID值的列名稱。
• pkColumnValue：生成器表中的一行數據的主鍵值。
• initialValue：id值的初始值。
• allocationSize：id值的增量。

下面的代碼定義了兩個生成器empGen和addressGen，生成器的表是ID_GEN 

@Entity
public class Employee {
...
@TableGenerator(name="empGen",table=@Table(name="ID_GEN"),pkColumnName="GEN_KEY",
                valueColumnName="GEN_VALUE",pkColumnValue="EMP_ID",allocationSize=1)
@Id(generate=TABLE, generator="empGen")
public int id;
...
}

@Entity
public class Address {
...
@TableGenerator(name="addressGen",table=@Table(name="ID_GEN"),pkColumnValue="ADDR_ID")
@Id(generate=TABLE, generator="addressGen")
public int id;
...
}

@SequenceGenerator 
SequenceGenerator定義一個主鍵值生成器，在Id這個元數據的generator屬性中可以使用生成器的名字。生成器可以在類、方法或者屬性上定義。生成器是數據庫支持的sequence對象。 
屬性說明： 

• name：生成器的唯一名字，可以被Id元數據使用。
• sequenceName：數據庫中，sequence對象的名稱。如果不指定，會使用提供商指定的默認名稱。
• initialValue：id值的初始值。
• allocationSize：id值的增量。

下面的代碼定義了一個使用提供商默認名稱的sequence生成器 

@SequenceGenerator(name="EMP_SEQ", allocationSize=25)

    

@DiscriminatorColumn 
DiscriminatorColumn定義在使用SINGLE_TABLE或JOINED繼承策略的表中區別不繼承層次的列 
屬性說明： 

• name：column的名字。默認值爲TYPE。
• columnDefinition：生成DDL的sql片斷。
• length：String類型的column的長度，其他類型使用默認值10。

下面的代碼定義了一個列名爲DISC，長度爲20的String類型的區別列 

@Entity
@Table(name="CUST")
@Inheritance(strategy=SINGLE_TABLE,discriminatorType=STRING,discriminatorValue="CUSTOMER")
@DiscriminatorColumn(name="DISC", length=20)
public class Customer { ... }

@NamedQuery 
在使用JPA持久化規範的應用程序中，可以使用實體管理器動態創建和執行查詢，也可以預定義查詢並在運行時按名稱執行。 
使用@NamedQuery創建與@Entity或@MappedSuperclass關聯的預定義查詢，這些查詢： 

• 使用JPA查詢語言進行基於任何基礎數據庫的可移植執行
• 經常被使用
• 比較複雜並且難於創建
• 可以在不同實體之間共享
• 只返回實體（從不返回標量值），並只返回一個類型的實體

屬性說明： 

• query：(必須屬性)要指定查詢，請將 query 設置爲 JPA 查詢語言（作爲 String）
• hints：默認值：空 QueryHint 數組。默認情況下，JPA 持續性提供程序假設 SQL 查詢應完全按照 query 屬性提供的方式執行。要微調查詢的執行，可以選擇將hints設置爲一個QueryHint數組（請參閱 @QueryHint）。在執行時，EntityManager 將向基礎數據庫傳遞提示。
• name:(必須屬性)要指定查詢名稱，請將name設置爲所需的String名稱

下面的代碼使用@NamedQuery批註定義一個JPA查詢語言查詢，該查詢使用名爲firstname的參數 

//使用 @NamedQuery 實現一個帶參數的查詢
@Entity
@NamedQuery(name="findAllEmployeesByFirstName",
            query="SELECT OBJECT(emp) FROM Employee emp WHERE emp.firstName = :firstname")
public class Employee implements Serializable {
     …
}

//執行命名查詢
Query queryEmployeesByFirstName = em.createNamedQuery(“findAllEmployeesByFirstName”);
queryEmployeeByFirstName.setParameter(“firstName”, “John”);
Collection employees = queryEmployessByFirstName.getResultList();

@NamedQueries 
如果需要指定多個@NamedQuery，則必須使用一個@NamedQueries指定所有命名查詢 
屬性說明： 

• value：要指定兩個或更多屬性覆蓋，請將value設置爲NamedQuery實例數組

@Entity
@NamedQueries({@NamedQuery(name="findAllEmployeesByFirstName",
               query="SELECT OBJECT(emp) FROM Employee emp WHERE emp.firstName = :firstname"),
               @NamedQuery(name="findAllEmployeesByLasttName",
               query="SELECT OBJECT(emp) FROM Employee emp WHERE emp.lasstName = :lastname")})
public class PartTimeEmployee extends Employee {

}

@NamedNativeQuery 
使用@NamedNativeQuery創建與@Entity或@MappedSuperclass關聯的預定義查詢，這些查詢： 

• 使用基礎數據庫的原生SQL
• 經常被使用
• 比較複雜並且難於創建
• 可以在不同實體之間共享
• 返回實體、標量值或兩者的組合（另請參閱 @ColumnResult、@EntityResult、@FieldResult 和@SqlResultSetMapping）

屬性說明： 

• query：(必須屬性)要指定查詢，請將query設置爲SQL查詢（作爲String）
• hints：默認值：空 QueryHint 數組。默認情況下，JPA 持續性提供程序假設 SQL 查詢應完全按照 query 屬性提供的方式執行。要微調查詢的執行，可以選擇將hints設置爲一個QueryHint數組（請參閱 @QueryHint）。在執行時，EntityManager 將向基礎數據庫傳遞提示。
• name：(必須屬性)要指定查詢名稱，請將name設置爲所需的String名稱
• resultClass：默認值：JPA 持續性提供程序假設結果類是關聯實體的Class.要指定結果類，請將resultClass設置爲所需的 Class
• resultSetMapping：默認值：JPA持續性提供程序假設原生SQL查詢中的SELECT語句：返回一個類型的實體；包括與返回的實體的所有字段或屬性相對應的所有列；並使用與字段或屬性名稱（未使用AS語句）相對應的列名。要控制JPA持續性提供程序如何將JDBC結果集映射到實體字段或屬性以及標量，請通過將resultSetMapping設置爲所需的@SqlResultSetMapping的String名稱來指定結果集映射

//定義一個使用基礎數據庫的原生SQL的查詢
@Entity
@NamedNativeQuery(name="findAllEmployees",query="SELECT * FROM EMPLOYEE")
public class Employee implements Serializable {

}

//Hibernate如何使用EntityManager獲取此查詢以及如何通過Query方法getResultList執行該查詢
Query queryEmployees = em.createNamedQuery("findAllEmployees");
Collection employees = queryEmployees.getResultList();

@NamedNativeQueries 
如果需要指定多個@NamedNativeQuery，則必須使用一個@NamedNativeQueries指定所有命名查詢 
屬性說明： 

• value：要指定兩個或更多屬性覆蓋，請將value設置爲NamedNativeQuery實例數組

下面代碼顯示瞭如何使用此批註指定兩個命名原生查詢 

@Entity
@NamedNativeQueries({@NamedNativeQuery(name="findAllPartTimeEmployees",
                     query="SELECT * FROM EMPLOYEE WHERE PRT_TIME=1"),
                     @NamedNativeQuery(name="findAllSeasonalEmployees,
                     query="SELECT * FROM EMPLOYEE WHERE SEASON=1")})

public class PartTimeEmployee extends Employee {

}

@OneToMany和@ManyToOne 
屬性說明： 

cascade	默認值CascadeType的空數組。默認情況下，JPA不會將任何持久化操作層疊到關聯的目標。如果希望某些或所有持久化操作層疊到關聯的目標，應將cascade設置爲一個或多個 CascadeType類型的枚舉值，其中包括：● ALL – 針對擁有實體執行的任何持久化操作均層疊到關聯的目標。● MERGE – 如果合併了擁有實體，則將merge層疊到關聯的目標。● PERSIST – 如果持久保存擁有實體，則將persist層疊到關聯的目標。● REFRESH – 如果刷新了擁有實體，則refresh爲關聯的層疊目標。● REMOVE – 如果刪除了擁有實體，則還刪除關聯的目標。
fetch	在Hibernate裏用時默認值：FetchType.LAZY，它要求程序運行時延遲加載所有的集合和實體。如果這不適合於應用程序或特定的持久字段，將fetch設置爲FetchType.EAGER，它提示程序在首次訪問數據時應馬上加載所有的集合和實體
mappedBy	默認值：如果關係是單向的，則該關聯提供程序確定擁有該關係的字段。如果關係是雙向的，則將關聯相反（非擁有）方上的mappedBy元素設置爲擁有此關係的字段或屬性的名稱
targetEntity	默認值：使用一般參數定義的Collection的參數化類型。默認情況下，如果使用通過一般參數定義的Collection，則程序將從被引用的對象類型推斷出關聯的目標實體。如果Collection不使用一般參數，則必須指定作爲關聯目標的實體類：將關聯擁有方上的 targetEntity元素設置爲作爲關係目標的實體的Class

@OneToOne 
屬性比@OneToMany多一個： 

optionalde

默認值：true。默認情況下，JPA持久化程序假設所有（非基元）字段和屬性的值可以爲空。如果這並不適合於您的應用程序，請將optional設置爲false

@OrderBy 
一般將@OrderBy與@OneToMany和@ManyToMany一起使用 
在一對多，多對多關係中，有時我們希望從數據庫加載出來的集合對象是按一定方式排序的，這可以通過OrderBy來實現，默認是按對象的主鍵升序排列。 
屬性說明： 

• value：字符串類型，指定排序方式。格式爲"fieldName1 [ASC|DESC],fieldName2 [ASC|DESC],......" 
  排序類型可以不指定，默認是ASC升序。 
  

下面的代碼說明Person和Book之間是一對多關係。集合books按照Book的isbn升序，name降序排列。

@Table(name = "MAPKEY_PERSON")
public class Person {
     @OneToMany(targetEntity = Book.class, cascade = CascadeType.ALL, mappedBy = "person")
     @OrderBy(name = "isbn ASC, name DESC")
     private List books = new ArrayList();
}


@Entity
public class Project {
     @ManyToMany
     @OrderBy("lastname ASC", "seniority DESC")
     public List<Employee> getEmployees() {
          …
     }
}


@Entity
public class Employee {
     @Id
     private int empId;

     private String lastname;

     private int seniority;

     @ManyToMany(mappedBy="employees")
     // By default, returns a List in ascending order by empId
     public List<Project> getProjects() {
         …
     }
}