第 5 章 O/R Mapping基础 - Hibernate reference 2.1.8 ga 正式版中文参考手册

所有的XML映射都需要定义如上所示的doctype。DTD可以从上述URL中获取，或者在hibernate-x.x.x/src/net/sf/hibernate目录中，或hibernate.jar文件中找到。Hibernate总是会在它的classptah中首先搜索DTD文件。

这个元素包括三个可选的属性。schema属性，指明了这个映射所引用的表所在的schema名称。假若指定了这个属性，表名会加上所指定的schema的名字扩展为全限定名。假若没有指定，表名就不会使用全限定名。default-cascade指定了未明确注明cascade属性的Java属性和集合类Java会采取什么样的默认级联风格。auto-import属性默认让我们在查询语言中可以使用非全限定名的类名。

<hibernate-mapping
         schema="schemaName"                          (1)
         default-cascade="none|save-update"           (2)
         auto-import="true|false"                     (3)
         package="package.name"                       (4)
 />

假若你有两个持久化类，它们的非全限定名是一样的（就是在不同的包里面--译者注），你应该设置auto-import="false"。假若说你把一个“import过”的名字同时对应两个类， Hibernate会抛出一个异常。

你可以使用class元素来定义一个持久化类：

<class
        name="ClassName"                              (1)
        table="tableName"                             (2)
        discriminator-value="discriminator_value"     (3)
        mutable="true|false"                          (4)
        schema="owner"                                (5)
        proxy="ProxyInterface"                        (6)
        dynamic-update="true|false"                   (7)
        dynamic-insert="true|false"                   (8)
        select-before-update="true|false"             (9)
        polymorphism="implicit|explicit"              (10)
        where="arbitrary sql where condition"         (11)
        persister="PersisterClass"                    (12)
        batch-size="N"                                (13)
        optimistic-lock="none|version|dirty|all"      (14)
        lazy="true|false"                             (15)
/>

若指明的持久化类实际上是一个接口，也可以被完美地接受。其后你可以用<subclass>来指定该接口的实际实现类名。你可以持久化任何static（静态的）内部类。记得应该使用标准的类名格式，就是说比如：Foo$Bar。

不可变类，mutable="false"不可以被应用程序更新或者删除。这可以让Hibernate做一些小小的性能优化。

可选的proxy属性可以允许延迟加载类的持久化实例。Hibernate开始会返回实现了这个命名接口的CGLIB代理。当代理的某个方法被实际调用的时候，真实的持久化对象才会被装载。参见下面的“用于延迟装载的代理”。

Implicit (隐式)的多态是指，如果查询中给出的是任何超类、该类实现的接口或者该类的名字，都会返回这个类的实例；如果查询中给出的是子类的名字，则会返回子类的实例。 Explicit （显式）的多态是指，只有在查询中给出的明确是该类的名字时才会返回这个类的实例；同时只有当在这个<class>的定义中作为<subclass>或者<joined-subclass>出现的子类，才会可能返回。 大多数情况下，默认的polymorphism="implicit"都是合适的。 显式的多态在有两个不同的类映射到同一个表的时候很有用。（允许一个“轻型”的类，只包含部分表字段）。

persister属性可以让你定制这个类使用的持久化策略。你可以指定你自己实现的net.sf.hibernate.persister.EntityPersister的子类，你甚至可以完全从头开始编写一个net.sf.hibernate.persister.ClassPersister接口的实现，可能是用储存过程调用、序列化到文件或者LDAP数据库来实现的。参阅net.sf.hibernate.test.CustomPersister，这是一个简单的例子（“持久化”到一个Hashtable）。

请注意dynamic-update和dynamic-insert的设置并不会继承到子类，所以在<subclass>或者<joined-subclass>元素中可能需要再次设置。这些设置是否能够提高效率要视情形而定。请用你的智慧决定是否使用。

使用select-before-update通常会降低性能.当是在防止数据库不必要的触发update触发器，这就很有用了。

如果你打开了dynamic-update，你可以选择几种乐观锁定的策略：

我们非常强烈建议你在Hibernate中使用version/timestamp字段来进行乐观锁定。对性能来说，这是最好的选择，并且这也是唯一能够处理在session外进行操作的策略（就是说，当使用Session.update()的时候）。 记住version或timestamp属性永远不能使null,不管何种unsaved-value策略，否则实例会被认为是尚未被持久化的。

被映射的类必须声明对应数据库表主键字段。大多数类有一个JavaBeans风格的属性，为每一个实例包含唯一的标识。<id> 元素定义了该属性到数据库表主键字段的映射。

<id
        name="propertyName"                      (1)
        type="typename"                          (2)
        column="column_name"                     (3)
        unsaved-value="any|none|null|id_value"   (4)
        access="field|property|ClassName">       (5)

        <generator class="generatorClass"/>
</id>

如果 name属性不存在，会认为这个类没有标识属性。

unsaved-value 属性很重要！如果你的类的标识属性不是默认为null的，你应该指定正确的默认值。

还有一个另外的<composite-id>声明可以访问旧式的多主键数据。我们强烈不鼓励使用这种方式。

<id name="id" type="long" column="uid" unsaved-value="0">
        <generator class="net.sf.hibernate.id.TableHiLoGenerator">
                <param name="table">uid_table</param>
                <param name="column">next_hi_value_column</param>
        </generator>
</id>

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

<id name="id" type="long" column="uid">
        <generator class="sequence">
                <param name="sequence">uid_sequence</param>
        </generator>
</id>

<id name="id" type="long" column="uid" unsaved-value="0">
        <generator class="identity"/>
</id>

<composite-id
        name="propertyName"
        class="ClassName"
        unsaved-value="any|none"
        access="field|property|ClassName">

        <key-property name="propertyName" type="typename" column="column_name"/>
        <key-many-to-one name="propertyName class="ClassName" column="column_name"/>
        ......
</composite-id>

如果表使用联合主键，你可以把类的多个属性组合成为标识符属性。<composite-id>元素接受<key-property>属性映射和<key-many-to-one>属性映射作为子元素。

<composite-id>
        <key-property name="medicareNumber"/>
        <key-property name="dependent"/>
</composite-id>

你的持久化类必须重载equals()和hashCode()方法，来实现组合的标识符判断等价.也必须实现Serializable接口。

不幸的是，这种组合关键字的方法意味着一个持久化类是它自己的标识。除了对象自己之外，没有什么方便的“把手”可用。你必须自己初始化持久化类的实例，在使用组合关键字load()持久化状态之前，必须填充他的联合属性。我们会在第 7.4 节 “组件作为联合标识符(Components as composite identifiers)”章中说明一种更加方便的方法，把联合标识实现为一个独立的类，下面描述的属性只对这种备用方法有效:

在"一棵对象继承树对应一个表"的策略中,<discriminator>元素是必需的,它声明了表的识别器字段。识别器字段包含标志值，用于告知持久化层应该为某个特定的行创建哪一个子类的实例。只能使用如下受到限制的一些类型： string, character, integer, byte, short, boolean, yes_no, true_false.

<discriminator
        column="discriminator_column"  (1)
        type="discriminator_type"      (2)
        force="true|false"             (3)
/>

标识器字段的实际值是根据<class> 和<subclass>元素的discriminator-value得来的.

force属性仅仅是在表包含一些未指定应该映射到哪个持久化类的时候才是有用的。这种情况不是经常会遇到。

<version>元素是可选的，表明表中包含附带版本信息的数据。这在你准备使用 长事务（long transactions）的时候特别有用。（见后）

<version
        column="version_column"                            (1)
        name="propertyName"                                (2)
        type="typename"                                    (3)
        access="field|property|ClassName"                  (4)
        unsaved-value="null|negative|undefined"            (5)
/>

版本号必须是以下类型：long, integer, short, timestamp或者calendar。

可选的<timestamp>元素指明了表中包含时间戳数据。这用来作为版本的替代。时间戳本质上是一种对乐观锁定的一种不是特别安全的实现。当然，有时候应用程序可能在其他方面使用时间戳。

<timestamp
        column="timestamp_column"           (1)
        name="propertyName"                 (2)
        access="field|property|ClassName"   (3)
        unsaved-value="null|undefined"      (4)
/>

注意，<timestamp> 和<version type="timestamp">是等价的。

<property>元素为类声明了一个持久化的,JavaBean风格的属性。

<property
        name="propertyName"                 (1)
        column="column_name"                (2)
        type="typename"                     (3)
        update="true|false"                 (4)
        insert="true|false"                 (4)
        formula="arbitrary SQL expression"  (5)
        access="field|property|ClassName"   (6)
/>

typename可以是如下几种：

如果你没有指定类型，Hibernarte会使用反射来得到这个名字的属性，以此来猜测正确的Hibernate类型。Hibernate会对属性读取器(getter方法）的返回类进行解释，按照规则2,3,4的顺序。然而，这并不足够。 在某些情况下你仍然需要type属性。（比如，为了区别Hibernate.DATE和Hibernate.TIMESTAMP,或者为了指定一个自定义类型。）

access属性用来让你控制Hibernate如何在运行时访问属性。在默认情况下，Hibernate会使用属性的get/set方法对。如果你指明access="field",Hibernate会忽略get/set方法对，直接使用反射来访问成员变量。你也可以指定你自己的策略，这就需要你自己实现net.sf.hibernate.property.PropertyAccessor接口，再在access中设置你自定义策略类的名字。

通过many-to-one元素,可以定义一种常见的与另一个持久化类的关联。这种关系模型是多对一关联。（实际上是一个对象引用。）

<many-to-one
        name="propertyName"                                (1)
        column="column_name"                               (2)
        class="ClassName"                                  (3)
        cascade="all|none|save-update|delete"              (4)
        outer-join="true|false|auto"                       (5)
        update="true|false"                                (6)
        insert="true|false"                                (6)
        property-ref="propertyNameFromAssociatedClass"     (7)
        access="field|property|ClassName"                  (8)
/>

cascade 属性允许下列值： all, save-update, delete, none。设置除了none以外的其它值会传播特定的操作到关联的（子）对象中。参见后面的“Lifecycle Objects(自动管理生命周期的对象）”。

outer-join参数允许下列三个不同值：

一个典型的简单many-to-one声明例子：

<many-to-one name="product" class="Product" column="PRODUCT_ID"/>

property-ref属性只应该用来对付老旧的数据库系统，可能出现外键指向对方关联表的是个非主键字段（但是应该是一个惟一关键字）的情况。这是一种十分丑陋的关系模型。比如说，假设Product类有一个惟一的序列号，它并不是主键。（unique属性控制Hibernate通过SchemaExport工具生成DDL的过程。）

<property name="serialNumber" unique="true" type="string" column="SERIAL_NUMBER"/>

那么关于OrderItem 的映射可能是：

<many-to-one name="product" property-ref="serialNumber" column="PRODUCT_SERIAL_NUMBER"/>

当然，我们决不鼓励这种用法。

持久化对象之间一对一的关联关系是通过one-to-one元素定义的。

<one-to-one
        name="propertyName"                                (1)
        class="ClassName"                                  (2)
        cascade="all|none|save-update|delete"              (3)
        constrained="true|false"                           (4)
        outer-join="true|false|auto"                       (5)
        property-ref="propertyNameFromAssociatedClass"     (6)
        access="field|property|ClassName"                  (7)
        
/>

有两种不同的一对一关联：

主键关联不需要额外的表字段;两行是通过这种一对一关系相关联的，那么这两行就共享同样的主关键字值。所以如果你希望两个对象通过主键一对一关联，你必须确认它们被赋予同样的标识值！

比如说，对下面的Employee和Person进行主键一对一关联:

<one-to-one name="person" class="Person"/>

<one-to-one name="employee" class="Employee" constrained="true"/>

现在我们必须确保PERSON和EMPLOYEE中相关的字段是相等的。我们使用一个特别的称为foreign的Hibernate标识符生成器策略：

<class name="person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="foreign">
            <param name="property">employee</param>
        </generator>
    </id>
    ...
    <one-to-one name="employee"
        class="Employee"
        constrained="true"/>
</class>

一个刚刚保存的Person实例被赋予和该Person的employee属性所指向的Employee实例同样的关键字值。

另一种方式是一个外键和一个惟一关键字对应，上面的Employee和Person的例子，如果使这种关联方式，应该表达成：

<many-to-one name="person" class="Person" column="PERSON_ID" unique="true"/>

如果在Person的映射加入下面几句，这种关联就是双向的：

<one-to-one name"employee" class="Employee" property-ref="person"/>

<component>元素把子对象的一些元素与父类对应的表的一些字段映射起来。 然后组件可以声明它们自己的属性、组件或者集合。参见后面的“Components”一章。

<component 
        name="propertyName"                 (1)
        class="className"                   (2)
        insert="true|false"                 (3)
        upate="true|false"                  (4)
        access="field|property|ClassName">  (5)
        
        <property ...../>
        <many-to-one .... />
        ........
</component>

其<property>子标签为子类的一些属性和表字段建立映射。

<component>元素允许加入一个<parent>子元素，在组件类内部就可以有一个指向其容器的实体的反向引用。

<dynamic-component>元素允许把一个Map映射为组件，其属性名对应map的键值。

最后，多态持久化需要为父类的每个子类都进行声明。对于我们建议的“每一棵类继承树对应一个表”的策略来说，就需要使用<subclass>声明。

<subclass
        name="ClassName"                              (1)
        discriminator-value="discriminator_value"     (2)
        proxy="ProxyInterface"                        (3)
        lazy="true|false"                             (4)
        dynamic-update="true|false"
        dynamic-insert="true|false">

        <property .... />
        .....
</subclass>

每个子类都应该声明它自己的持久化属性和子类。 <version> 和<id> 属性可以从根父类继承下来。在一棵继承树上的每个子类都必须声明一个唯一的discriminator-value。如果没有指定，就会使用Java类的全限定名。

另外一种情况，如果子类是持久化到一个属于它自己的表（每一个子类对应一个表的映射策略），那么就需要使用<joined-subclass>元素。

<joined-subclass
        name="ClassName"                    (1)
        proxy="ProxyInterface"              (2)
        lazy="true|false"                   (3)
        dynamic-update="true|false"
        dynamic-insert="true|false">

        <key .... >

        <property .... />
        .....
</joined-subclass>

这种映射策略不需要指定辨别标志（discriminator）字段。但是，每一个都必须使用<key>元素指定一个表字段包含对象的标识符。本章开始的映射可以被用如下方式重写：

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD//EN"
        "http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd">

<hibernate-mapping  package="eg">

        <class name="Cat" table="CATS">
                <id name="id" column="uid" type="long">
                        <generator class="hilo"/>
                </id>
                <property name="birthdate" type="date"/>
                <property name="color" not-null="true"/>
                <property name="sex" not-null="true"/>
                <property name="weight"/>
                <many-to-one name="mate"/>
                <set name="kittens">
                        <key column="MOTHER"/>
                        <one-to-many class="Cat"/>
                </set>
                <joined-subclass name="DomesticCat" table="DOMESTIC_CATS">
                	<key column="CAT"/>
                        <property name="name" type="string"/>
                </joined-subclass>
        </class>

        <class name="eg.Dog">
                <!-- mapping for Dog could go here -->
        </class>

</hibernate-mapping>

集合类在后面讨论。

假设你的应用程序有两个同样名字的持久化类，但是你不想在Hibernate查询中使用他们的全限定名。除了依赖auto-import="true"以外，类也可以被显式地“import(引用）”。你甚至可以引用没有明确被映射的类和接口。

<import class="java.lang.Object" rename="Universe"/>

<import
        class="ClassName"              (1)
        rename="ShortName"             (2)
/>

为了理解很多与持久化服务相关的Java语言级对象的行为，我们需要把它们分为两类：

实体entity 独立于任何持有实体引用的对象。与通常的Java模型相比，不再被引用的对象会被当作垃圾收集掉。实体必须被显式的保存和删除（除非保存和删除是从父实体向子实体引发的级联）。这和ODMG模型中关于对象通过可触及保持持久性有一些不同——比较起来更加接近应用程序对象通常在一个大系统中的使用方法。实体支持循环引用和交叉引用，它们也可以加上版本信息。

实体的持久化状态包含有指向其他实体的连接和一些值 类型的实例。值是原始类型、集合、组件或者特定的不可变对象。与实体不同，值（特别是集合和组件）是通过可触及性来进行持久化和删除的。因为值对象（和原始类型数据）是随着包含它们的实体而被持久化和删除的，它们不能够被独立的加上版本信息。值没有独立的标识，所以它们不能被两个实体或者集合共享。

所有的Hibernate对象，除了集合，都支持null语义。

直到现在，我们都一直使用"持久化对象"来代表实体。我们仍然会这么做。然而严格的来说，并不是所有用户定义的，带有持久化状态的类都是实体。组件(component)就是一个用户定义的类，仅仅由值语义构成。

基本类型可以大致的分为：

实体及其集合的唯一标识可以是任何基础类型，除了binary、 blob 和 clob之外。（联合标识也是允许的，后面会说到。）

在net.sf.hibernate.Hibernate中，定义了基础类型对应的Type常量。比如，Hibernate.STRING代表string 类型。

枚举（enumerated）类型是一种常见的Java习惯用语，它是一个类，拥有一些（不多）的不可变实例。你可以为枚举类型实现net.sf.hibernate.PersistentEnum接口，定义toInt() 和 fromInt()方法：

package eg;
import net.sf.hibernate.PersistentEnum;

public class Color implements PersistentEnum {
    private final int code;
    private Color(int code) {
        this.code = code;
    }
    public static final Color TABBY = new Color(0);
    public static final Color GINGER = new Color(1);
    public static final Color BLACK = new Color(2);

    public int toInt() { return code; }

    public static Color fromInt(int code) {
        switch (code) {
            case 0: return TABBY;
            case 1: return GINGER;
            case 2: return BLACK;
            default: throw new RuntimeException("Unknown color code");
        }
    }
}

Hibernate可以使用枚举类的名字作为类型名，这个例子中就是eg.Color。

开发者创建属于他们自己的值类型也是很容易的。比如说，你可能希望持久化java.lang.BigInteger类型的属性，持久化成为VARCHAR字段。Hibernate没有内置这样一种类型。自定义类型能够映射一个属性（或集合元素）到不止一个数据库表字段。比如说，你可能有这样的Java属性：getName()/setName()，这是java.lang.String类型的，对应的持久化到三个字段：FIRST_NAME, INITIAL, SURNAME。

要实现一个自定义类型，可以实现net.sf.hibernate.UserType或net.sf.hibernate.CompositeUserType中的任一个，并且使用类型的Java全限定类名来声明属性。请查看net.sf.hibernate.test.DoubleStringType这个例子，看看它是怎么做的。

<property name="twoStrings" type="net.sf.hibernate.test.DoubleStringType">
    <column name="first_string"/>
    <column name="second_string"/>
</property>

注意使用<column>标签来把一个属性映射到多个字段的做法。

虽然Hibernate内置的丰富类型和对component的支持意味着你可能很少需要使用自定义类型，至少对于你程序中经常出现的自定义类（并非实体）来说，这是一种好方法。比如说，MonetoryAmount(价格总额)对比使用CompositeUserType来说更好,虽然它可以很容易的使用一个component实现。这样做的动机之一是抽象。通过自定义类型，以后假若你改变表示金额值的方法时，你的映射文件不需要更改，这就得到了保护。

这是属性映射的又一种类型。<any>映射元素定义了一种从多个表到类的多形联合。这种类型的映射总是需要多于一个字段。第一个字段持有被从属的实体的类型。其他的字段持有标识符。对于这种类型的联合来说，不可能指定一个外键约束，所以当然这不是（多形）联合映射的通常方式。你只应该在非常特殊的情况下使用它（比如，审计log,用户会话数据等等）。

<any name="anyEntity" id-type="long" meta-type="eg.custom.Class2TablenameType">
    <column name="table_name"/>
    <column name="id"/>
</any>

meta-type属性让应用程序指定一个自定义类型，把数据库字段值映射到一个持久化类，该类的标识属性是用id-type定义的。如果meta-type返回java.lang.Class的实例，不需要其他处理。另一方面，如果是类似string或者character这样的基本类型，你必须指定从值到类的映射。

<any name="anyEntity" id-type="long" meta-type="string">
    <meta-value value="TBL_ANIMAL" class="Animal"/>
    <meta-value value="TBL_HUMAN" class="Human"/>
    <meta-value value="TBL_ALIEN" class="Alien"/>
    <column name="table_name"/>
    <column name="id"/>
</any>

<any
        name="propertyName"                      (1)
        id-type="idtypename"                     (2)
        meta-type="metatypename"                 (3)
        cascade="none|all|save-update"           (4)
        access="field|property|ClassName"        (5)
>
        <meta-value ... />
        <meta-value ... />
        .....
        <column .... />
        <column .... />
        .....
</any>

老式的object 类型是用来在Hibernate 1.2中起到类似作用的，他仍然被支持，但是已经基本废弃了。