Hibernate 3.6.10.Final ²Î¿¼ÊÖ²á ÖÐÎÄ°æ

Here is a simple example of @EmbeddedId.

@Entity

class User {

   @EmbeddedId

   @AttributeOverride(name="firstName", column=@Column(name="fld_firstname")

   UserId id;


   Integer age;

}


@Embeddable

class UserId implements Serializable {

   String firstName;

   String lastName;

}

You can notice that the UserId class is serializable. To override the column mapping, use @AttributeOverride.

An embedded id can itself contains the primary key of an associated entity.

@Entity

class Customer {

   @EmbeddedId CustomerId id;

   boolean preferredCustomer;


   @MapsId("userId")

   @JoinColumns({

      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),

      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")

   })

   @OneToOne User user;

}


@Embeddable

class CustomerId implements Serializable {

   UserId userId;

   String customerNumber;


   //implements equals and hashCode

}


@Entity 

class User {

   @EmbeddedId UserId id;

   Integer age;

}


@Embeddable

class UserId implements Serializable {

   String firstName;

   String lastName;


   //implements equals and hashCode

}

In the embedded id object, the association is represented as the identifier of the associated entity. But you can link its value to a regular association in the entity via the @MapsId annotation. The @MapsId value correspond to the property name of the embedded id object containing the associated entity's identifier. In the database, it means that the Customer.user and the CustomerId.userId properties share the same underlying column (user_fk in this case).

In practice, your code only sets the Customer.user property and the user id value is copied by Hibernate into the CustomerId.userId property.

While not supported in JPA, Hibernate lets you place your association directly in the embedded id component (instead of having to use the @MapsId annotation).

@Entity

class Customer {

   @EmbeddedId CustomerId id;

   boolean preferredCustomer;

}


@Embeddable

class CustomerId implements Serializable {

   @OneToOne

   @JoinColumns({

      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),

      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")

   }) 

   User user;

   String customerNumber;


   //implements equals and hashCode

}


@Entity 

class User {

   @EmbeddedId UserId id;

   Integer age;

}


@Embeddable

class UserId implements Serializable {

   String firstName;

   String lastName;



   //implements equals and hashCode

}

Let's now rewrite these examples using the hbm.xml syntax.

<composite-id

        name="propertyName"

        class="ClassName"

        mapped="true|false"

        access="field|property|ClassName"

        node="element-name|.">



        <key-property name="propertyName" type="typename" column="column_name"/>

        <key-many-to-one name="propertyName" class="ClassName" column="column_name"/>

        ......

</composite-id>

First a simple example:

<class name="User">

   <composite-id name="id" class="UserId">

      <key-property name="firstName" column="fld_firstname"/>

      <key-property name="lastName"/>

   </composite-id>

</class>

Then an example showing how an association can be mapped.

<class name="Customer">

   <composite-id name="id" class="CustomerId">

      <key-property name="firstName" column="userfirstname_fk"/>

      <key-property name="lastName" column="userfirstname_fk"/>

      <key-property name="customerNumber"/>

   </composite-id>



   <property name="preferredCustomer"/>



   <many-to-one name="user">

      <column name="userfirstname_fk" updatable="false" insertable="false"/>

      <column name="userlastname_fk" updatable="false" insertable="false"/>

   </many-to-one>

</class>



<class name="User">

   <composite-id name="id" class="UserId">

      <key-property name="firstName"/>

      <key-property name="lastName"/>

   </composite-id>



   <property name="age"/>

</class>

Notice a few things in the previous example:

The last example shows how to map association directly in the embedded id component.

<class name="Customer">

   <composite-id name="id" class="CustomerId">

      <key-many-to-one name="user">

         <column name="userfirstname_fk"/>

         <column name="userlastname_fk"/>

      </key-many-to-one>

      <key-property name="customerNumber"/>

   </composite-id>



   <property name="preferredCustomer"/>

</class>



<class name="User">

   <composite-id name="id" class="UserId">

      <key-property name="firstName"/>

      <key-property name="lastName"/>

   </composite-id>



   <property name="age"/>

</class>

This is the recommended approach to map composite identifier. The following options should not be considered unless some constraint are present.

Another, arguably more natural, approach is to place @Id on multiple properties of your entity. This approach is only supported by Hibernate (not JPA compliant) but does not require an extra embeddable component.

@Entity

class Customer implements Serializable {

   @Id @OneToOne

   @JoinColumns({

      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),

      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")

   })

   User user;

  

   @Id String customerNumber;


   boolean preferredCustomer;


   //implements equals and hashCode

}


@Entity 

class User {

   @EmbeddedId UserId id;

   Integer age;

}


@Embeddable

class UserId implements Serializable {

   String firstName;

   String lastName;


   //implements equals and hashCode

}

In this case Customer is its own identifier representation: it must implement Serializable and must implement equals() and hashCode().

In hbm.xml, the same mapping is:

<class name="Customer">

   <composite-id>

      <key-many-to-one name="user">

         <column name="userfirstname_fk"/>

         <column name="userlastname_fk"/>

      </key-many-to-one>

      <key-property name="customerNumber"/>

   </composite-id>



   <property name="preferredCustomer"/>

</class>



<class name="User">

   <composite-id name="id" class="UserId">

      <key-property name="firstName"/>

      <key-property name="lastName"/>

   </composite-id>



   <property name="age"/>

</class>

@IdClass on an entity points to the class (component) representing the identifier of the class. The properties marked @Id on the entity must have their corresponding property on the @IdClass. The return type of search twin property must be either identical for basic properties or must correspond to the identifier class of the associated entity for an association.

@Entity

@IdClass(CustomerId.class)

class Customer implements Serializable {

   @Id @OneToOne

   @JoinColumns({

      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),

      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")

   }) 

   User user;

  

   @Id String customerNumber;


   boolean preferredCustomer;

}


class CustomerId implements Serializable {

   UserId user;

   String customerNumber;


   //implements equals and hashCode

}


@Entity 

class User {

   @EmbeddedId UserId id;

   Integer age;


   //implements equals and hashCode

}


@Embeddable

class UserId implements Serializable {

   String firstName;

   String lastName;


   //implements equals and hashCode

}

Customer and CustomerId do have the same properties customerNumber as well as user. CustomerId must be Serializable and implement equals() and hashCode().

While not JPA standard, Hibernate let's you declare the vanilla associated property in the @IdClass.

@Entity

@IdClass(CustomerId.class)

class Customer implements Serializable {

   @Id @OneToOne

   @JoinColumns({

      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),

      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")

   }) 

   User user;

  

   @Id String customerNumber;


   boolean preferredCustomer;

}


class CustomerId implements Serializable {

   @OneToOne User user;

   String customerNumber;


   //implements equals and hashCode

}


@Entity 

class User {

   @EmbeddedId UserId id;

   Integer age;


   //implements equals and hashCode

}


@Embeddable

class UserId implements Serializable {

  String firstName;

  String lastName;

}

This feature is of limited interest though as you are likely to have chosen the @IdClass approach to stay JPA compliant or you have a quite twisted mind.

Here are the equivalent on hbm.xml files:

<class name="Customer">

   <composite-id class="CustomerId" mapped="true">

      <key-many-to-one name="user">

         <column name="userfirstname_fk"/>

         <column name="userlastname_fk"/>

      </key-many-to-one>

      <key-property name="customerNumber"/>

   </composite-id>



   <property name="preferredCustomer"/>

</class>



<class name="User">

   <composite-id name="id" class="UserId">

      <key-property name="firstName"/>

      <key-property name="lastName"/>

   </composite-id>



   <property name="age"/>

</class>

所有的生成器都实现 org.hibernate.id.IdentifierGenerator 接口。这是一个非常简单的接口；某些应用程序可以选择提供他们自己特定的实现。当然，Hibernate 提供了很多内置的实现。下面是一些内置生成器的快捷名字：

hilo 和 seqhilo 生成器给出了两种 hi/lo 算法的实现， 这是一种很令人满意的标识符生成算法。第一种实现需要一个“特殊”的数据库表来保存下一个可用的“hi”值。 第二种实现使用一个 Oracle 风格的序列（在被支持的情况下）。

<id name="id" type="long" column="cat_id">

        <generator class="hilo">

                <param name="table">hi_value</param>

                <param name="column">next_value</param>

                <param name="max_lo">100</param>

        </generator>

</id>

<id name="id" type="long" column="cat_id">

        <generator class="seqhilo">

                <param name="sequence">hi_value</param>

                <param name="max_lo">100</param>

        </generator>

</id>

可惜的是，你在为 Hibernate 自行提供 Connection 时无法使用 hilo。 当 Hibernate 使用 JTA 获取应用服务器的数据源连接时，你必须正确地配置 hibernate.transaction.manager_lookup_class。

UUID 包含：IP 地址、JVM 的启动时间（精确到 1/4 秒）、系统时间和一个计数器值（在 JVM 中唯一）。 在 Java 代码中不可能获得 MAC 地址或者内存地址，所以这已经是我们在不使用 JNI 的前提下的能做的最好实现了。

对于内部支持标识字段的数据库（DB2、MySQL、Sybase 和 MS SQL），你可以使用 identity 关键字生成。对于内部支持序列的数据库（DB2、Oracle、PostgreSQL、Interbase、McKoi 和 SAP DB），你可以使用 sequence 风格的关键字生成。这两种方式对于插入一个新的对象都需要两次 SQL 查询。例如：

<id name="id" type="long" column="person_id">

        <generator class="sequence">

                <param name="sequence">person_id_sequence</param>

        </generator>

</id>

<id name="id" type="long" column="person_id" unsaved-value="0">

        <generator class="identity"/>

</id>

对于跨平台开发，native 策略会从 identity、sequence 和 hilo 中进行选择，选择哪一个，这取决于底层数据库的支持能力。

If you want the application to assign identifiers, as opposed to having Hibernate generate them, you can use the assigned generator. This special generator uses the identifier value already assigned to the object's identifier property. The generator is used when the primary key is a natural key instead of a surrogate key. This is the default behavior if you do not specify @GeneratedValue nor <generator> elements.

当选择 assigned 生成器时，除非有一个 version 或 timestamp 属性，或者你定义了 Interceptor.isUnsaved()，否则需要让 Hiberante 使用 unsaved-value="undefined"，强制 Hibernatet 查询数据库来确定一个实例是瞬时的（transient） 还是脱管的（detached）。

仅仅用于遗留的 schema 中（Hibernate 不能用触发器生成 DDL）。

<id name="id" type="long" column="person_id">

        <generator class="select">

                <param name="key">socialSecurityNumber</param>

        </generator>

</id>

在上面的例子中，类定义了一个命名为 socialSecurityNumber 的具有唯一值的属性，它是一个自然键（natural key），命名为 person_id 的代理键（surrogate key）的值由触发器生成。

Finally, you can ask Hibernate to copy the identifier from another associated entity. In the Hibernate jargon, it is known as a foreign generator but the JPA mapping reads better and is encouraged.

@Entity

class MedicalHistory implements Serializable {

  @Id @OneToOne

  @JoinColumn(name = "person_id")

  Person patient;

}


@Entity

public class Person implements Serializable {

  @Id @GeneratedValue Integer id;

}

Or alternatively

@Entity

class MedicalHistory implements Serializable {

  @Id Integer id;


  @MapsId @OneToOne

  @JoinColumn(name = "patient_id")

  Person patient;

}


@Entity

class Person {

  @Id @GeneratedValue Integer id;

}

In hbm.xml use the following approach:

<class name="MedicalHistory">

   <id name="id">

      <generator class="foreign">

         <param name="property">patient</param>

      </generator>

   </id>

   <one-to-one name="patient" class="Person" constrained="true"/>

</class>

For identifier generators that store values in the database, it is inefficient for them to hit the database on each and every call to generate a new identifier value. Instead, you can group a bunch of them in memory and only hit the database when you have exhausted your in-memory value group. This is the role of the pluggable optimizers. Currently only the two enhanced generators (第 5.1.2.3 节 “增强的标识符生成器” support this operation.

You can also manually specify a type using the @org.hibernate.annotations.Type and some parameters if needed. @Type.type could be:

If you do not specify a type, Hibernate will use reflection upon the named property and guess the correct Hibernate type. Hibernate will attempt to interpret the name of the return class of the property getter using, in order, rules 2, 3, and 4.

@org.hibernate.annotations.TypeDef and @org.hibernate.annotations.TypeDefs allows you to declare type definitions. These annotations can be placed at the class or package level. Note that these definitions are global for the session factory (even when defined at the class level). If the type is used on a single entity, you can place the definition on the entity itself. Otherwise, it is recommended to place the definition at the package level. In the example below, when Hibernate encounters a property of class PhoneNumer, it delegates the persistence strategy to the custom mapping type PhoneNumberType. However, properties belonging to other classes, too, can delegate their persistence strategy to PhoneNumberType, by explicitly using the @Type annotation.

@TypeDef(

   name = "phoneNumber",

   defaultForType = PhoneNumber.class,

   typeClass = PhoneNumberType.class

)


@Entity

public class ContactDetails {

   [...]

   private PhoneNumber localPhoneNumber;

   @Type(type="phoneNumber")

   private OverseasPhoneNumber overseasPhoneNumber;

   [...]

}

The following example shows the usage of the parameters attribute to customize the TypeDef.

//in org/hibernate/test/annotations/entity/package-info.java

@TypeDefs(

    {

    @TypeDef(

        name="caster",

        typeClass = CasterStringType.class,

        parameters = {

            @Parameter(name="cast", value="lower")

        }

    )

    }

)

package org.hibernate.test.annotations.entity;


//in org/hibernate/test/annotations/entity/Forest.java

public class Forest {

    @Type(type="caster")

    public String getSmallText() {

    ...

}      

When using composite user type, you will have to express column definitions. The @Columns has been introduced for that purpose.

@Type(type="org.hibernate.test.annotations.entity.MonetaryAmountUserType")

@Columns(columns = {

    @Column(name="r_amount"),

    @Column(name="r_currency")

})

public MonetaryAmount getAmount() {

    return amount;

}



public class MonetaryAmount implements Serializable {

    private BigDecimal amount;

    private Currency currency;

    ...

}

By default the access type of a class hierarchy is defined by the position of the @Id or @EmbeddedId annotations. If these annotations are on a field, then only fields are considered for persistence and the state is accessed via the field. If there annotations are on a getter, then only the getters are considered for persistence and the state is accessed via the getter/setter. That works well in practice and is the recommended approach.

However in some situations, you need to:

The best use case is an embeddable class used by several entities that might not use the same access type. In this case it is better to force the access type at the embeddable class level.

To force the access type on a given class, use the @Access annotation as showed below:

@Entity

public class Order {

   @Id private Long id;

   public Long getId() { return id; }

   public void setId(Long id) { this.id = id; }


   @Embedded private Address address;

   public Address getAddress() { return address; }

   public void setAddress() { this.address = address; }

}


@Entity

public class User {

   private Long id;

   @Id public Long getId() { return id; }

   public void setId(Long id) { this.id = id; }


   private Address address;

   @Embedded public Address getAddress() { return address; }

   public void setAddress() { this.address = address; }

}


@Embeddable

@Access(AcessType.PROPERTY)

public class Address {

   private String street1;

   public String getStreet1() { return street1; }

   public void setStreet1() { this.street1 = street1; }


   private hashCode; //not persistent

}

You can also override the access type of a single property while keeping the other properties standard.

@Entity

public class Order {

   @Id private Long id;

   public Long getId() { return id; }

   public void setId(Long id) { this.id = id; }

   @Transient private String userId;

   @Transient private String orderId;


   @Access(AccessType.PROPERTY)

   public String getOrderNumber() { return userId + ":" + orderId; }

   public void setOrderNumber() { this.userId = ...; this.orderId = ...; }

}

In this example, the default access type is FIELD except for the orderNumber property. Note that the corresponding field, if any must be marked as @Transient or transient.

It is sometimes useful to avoid increasing the version number even if a given property is dirty (particularly collections). You can do that by annotating the property (or collection) with @OptimisticLock(excluded=true).

More formally, specifies that updates to this property do not require acquisition of the optimistic lock.

The column(s) used for a property mapping can be defined using the @Column annotation. Use it to override default values (see the JPA specification for more information on the defaults). You can use this annotation at the property level for properties that are:

@Entity

public class Flight implements Serializable {

...

@Column(updatable = false, name = "flight_name", nullable = false, length=50)

public String getName() { ... }

            

The name property is mapped to the flight_name column, which is not nullable, has a length of 50 and is not updatable (making the property immutable).

This annotation can be applied to regular properties as well as @Id or @Version properties.

@Column(
    name="columnName";
    boolean unique() default false;
    boolean nullable() default true;
    boolean insertable() default true;
    boolean updatable() default true;
    String columnDefinition() default "";
    String table() default "";
    int length() default 255;
    int precision() default 0; // decimal precision
    int scale() default 0; // decimal scale

Sometimes, you want the Database to do some computation for you rather than in the JVM, you might also create some kind of virtual column. You can use a SQL fragment (aka formula) instead of mapping a property into a column. This kind of property is read only (its value is calculated by your formula fragment).

@Formula("obj_length * obj_height * obj_width")

public long getObjectVolume()

The SQL fragment can be as complex as you want and even include subselects.

If a property is not annotated, the following rules apply:

Discriminators are required for polymorphic persistence using the table-per-class-hierarchy mapping strategy. It declares a discriminator column of the table. The discriminator column contains marker values that tell the persistence layer what subclass to instantiate for a particular row. Hibernate Core supports the follwoing restricted set of types as discriminator column: string, character, integer, byte, short, boolean, yes_no, true_false.

Use the @DiscriminatorColumn to define the discriminator column as well as the discriminator type.

You can also use @DiscriminatorFormula to express in SQL a virtual discriminator column. This is particularly useful when the discriminator value can be extracted from one or more columns of the table. Both @DiscriminatorColumn and @DiscriminatorFormula are to be set on the root entity (once per persisted hierarchy).

@org.hibernate.annotations.DiscriminatorOptions allows to optionally specify Hibernate specific discriminator options which are not standardized in JPA. The available options are force and insert. The force attribute is useful if the table contains rows with "extra" discriminator values that are not mapped to a persistent class. This could for example occur when working with a legacy database. If force is set to true Hibernate will specify the allowed discriminator values in the SELECT query, even when retrieving all instances of the root class. The second option - insert - tells Hibernate whether or not to include the discriminator column in SQL INSERTs. Usually the column should be part of the INSERT statement, but if your discriminator column is also part of a mapped composite identifier you have to set this option to false.

Finally, use @DiscriminatorValue on each class of the hierarchy to specify the value stored in the discriminator column for a given entity. If you do not set @DiscriminatorValue on a class, the fully qualified class name is used.

@Entity

@Inheritance(strategy=InheritanceType.SINGLE_TABLE)

@DiscriminatorColumn(

    name="planetype",

    discriminatorType=DiscriminatorType.STRING

)

@DiscriminatorValue("Plane")

public class Plane { ... }


@Entity

@DiscriminatorValue("A320")

public class A320 extends Plane { ... }          

In hbm.xml, the <discriminator> element is used to define the discriminator column or formula:

<discriminator
        column="discriminator_column"
        type="discriminator_type"
        force="true|false"
        insert="true|false"
        formula="arbitrary sql expression"
/>

鉴别器字段的实际值是根据 <class> 和 <subclass> 元素中的 discriminator-value 属性得来的。

使用 formula 属性你可以定义一个 SQL 表达式，用来判断一行数据的类型。

<discriminator

    formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end"

    type="integer"/>