HIBERNATE - 符合Java习惯的关系数据库持久化

我们的第一个持久化类是一个带有一些属性（property）的简单JavaBean类：

package org.hibernate.tutorial.domain;

import java.util.Date;

public class Event {
    private Long id;

    private String title;
    private Date date;

    public Event() {}

    public Long getId() {
        return id;
    }

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

    public Date getDate() {
        return date;
    }

    public void setDate(Date date) {
        this.date = date;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }
}

你可以看到这个类对属性的存取方法（getter and setter method）使用了标准JavaBean命名约定，同时把类属性（field）的访问级别设成私有的（private）。这是推荐的设计，但并不是必须的。Hibernate也可以直接访问这些field，而使用访问方法（accessor method）的好处是提供了重构时的健壮性（robustness）。为了通过反射机制（Reflection）来实例化这个类的对象，我们需要提供一个无参的构造器（no-argument constructor)。

对一特定的event, id 属性持有唯一的标识符（identifier）的值。如果我们希望使用Hibernate提供的所有特性，那么所有的持久化实体（persistent entity）类（这里也包括一些次要依赖类）都需要一个这样的标识符属性。而事实上，大多数应用程序（特别是web应用程序）都需要通过标识符来区别对象，所以你应该考虑使用标识符属性而不是把它当作一种限制。然而，我们通常不会操作对象的标识（identity），因此它的setter方法的访问级别应该声明private。这样当对象被保存的时候，只有Hibernate可以为它分配标识符值。你可看到Hibernate可以直接访问public，private和protected的访问方法和field。所以选择哪种方式完全取决于你，你可以使你的选择与你的应用程序设计相吻合。

所有的持久化类（persistent classes）都要求有无参的构造器，因为Hibernate必须使用Java反射机制来为你创建对象。构造器（constructor）的访问级别可以是private，然而当生成运行时代理（runtime proxy）的时候则要求使用至少是package 级别的访问控制，这样在没有字节码指令（bytecode instrumentation）的情况下，从持久化类里获取数据会更有效率。

把这个Java源代码文件放到开发目录下的src目录里，注意包位置要正确。 现在这个目录看起来应该像这样：

.
+lib
  <Hibernate and third-party libraries>
+src
  +events
    Event.java

下一步，我们把这个持久化类的信息告诉Hibernate。

Hibernate需要知道怎样去加载（load）和存储（store）持久化类的对象。这正是Hibernate映射文件发挥作用的地方。映射文件告诉Hibernate它，应该访问数据库(database)里面的哪个表（table）及应该使用表里面的哪些字段（column）。

一个映射文件的基本结构看起来像这样：

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

<hibernate-mapping>
[...]
</hibernate-mapping>

注意Hibernate的DTD是非常复杂的。你的编辑器或者IDE里使用它来自动完成那些用来映射的XML元素（element）和属性（attribute）。你也可以在文本编辑器里打开DTD－这是最简单的方式来概览所有的元素和attribute，并查看它们的缺省值以及注释。注意Hibernate不会从web加载DTD文件，但它会首先在应用程序的classpath中查找。DTD文件已包括在hibernate3.jar里，同时也在Hibernate发布包的src/目录下。

为缩短代码长度，在以后的例子里我们会省略DTD的声明。当然，在实际的应用程序中，DTD声明是必须的。

在hibernate-mapping标签（tag）之间, 含有一个class元素。所有的持久化实体类（再次声明，或许接下来会有依赖类，就是那些次要的实体）都需要一个这样的映射，来把类对象映射到SQL数据库里的表。

<hibernate-mapping>

    <class name="events.Event" table="EVENTS">

    </class>

</hibernate-mapping>

到目前为止，我们告诉了Hibernate怎样把Events类的对象持久化到数据库的EVENTS表里，以及怎样从EVENTS表加载到Events类的对象。每个实例对应着数据库表中的一行。现在我们将继续讨论有关唯一标识符属性到数据库表的映射。另外，由于我们不关心怎样处理这个标识符，我们就配置由Hibernate的标识符生成策略来产生代理主键字段。

<hibernate-mapping>

    <class name="events.Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
    </class>

</hibernate-mapping>

The id element is the declaration of the identifier property, name="id" declares the name of the Java property - Hibernate will use the getter and setter methods to access the property. The column attribute tells Hibernate which column of the EVENTS table we use for this primary key. The nested generator element specifies the identifier generation strategy, in this case we used native, which picks the best strategy depending on the configured database (dialect). Hibernate supports database generated, globally unique, as well as application assigned identifiers (or any strategy you have written an extension for).

最后我们在映射文件里面包含需要持久化属性的声明。默认情况下，类里面的属性都被视为非持久化的：

<hibernate-mapping>

    <class name="events.Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
        <property name="date" type="timestamp" column="EVENT_DATE"/>
        <property name="title"/>
    </class>

</hibernate-mapping>

和id元素一样，property元素的name属性告诉Hibernate使用哪个getter和setter方法。在此例中，Hibernate会寻找getDate()/setDate(), 以及getTitle()/setTitle()。

为什么date属性的映射含有column attribute，而title却没有？当没有设定column attribute 的时候，Hibernate缺省地使用JavaBean的属性名作为字段名。对于title，这样工作得很好。然而，date在多数的数据库里，是一个保留关键字，所以我们最好把它映射成一个不同的名字。

另一有趣的事情是title属性缺少一个type attribute。我们在映射文件里声明并使用的类型，却不是我们期望的那样，是Java数据类型，同时也不是SQL数据库的数据类型。这些类型就是所谓的Hibernate 映射类型（mapping types），它们能把Java数据类型转换到SQL数据类型，反之亦然。再次重申，如果在映射文件中没有设置type属性的话，Hibernate会自己试着去确定正确的转换类型和它的映射类型。在某些情况下这个自动检测机制（在Java 类上使用反射机制）不会产生你所期待或需要的缺省值。date属性就是个很好的例子，Hibernate无法知道这个属性（java.util.Date类型的）应该被映射成：SQL date，或timestamp，还是time 字段。在此例中，把这个属性映射成timestamp 转换器，这样我们预留了日期和时间的全部信息。

应该把这个映射文件保存为Event.hbm.xml，且就在EventJava类的源文件目录下。映射文件可随意地命名，但hbm.xml的后缀已成为Hibernate开发者社区的约定。现在目录结构看起来应该像这样：

.
+lib
  <Hibernate and third-party libraries>
+src
  +events
    Event.java
    Event.hbm.xml

我们继续进行Hibernate的主要配置。

现在我们已经有了一个持久化类和它的映射文件，该是配置Hibernate的时候了。在此之前，我们需要一个数据库。 HSQL DB是种基于Java 的SQL数据库管理系统（DBMS），可以从HSQL DB的网站上下载。实际上，你只需下载的包中的hsqldb.jar文件，并把这个文件放在开发文件夹的lib/目录下即可。

在开发的根目录下创建一个data目录 － 这是HSQL DB存储数据文件的地方。此时在data目录中运行java -classpath ../lib/hsqldb.jar org.hsqldb.Server就可启动数据库。你可以在log中看到它的启动，及绑定到TCP/IP套结字，这正是我们的应用程序稍后会连接的地方。如果你希望在本例中运行一个全新的数据库，就在窗口中按下CTRL + C来关闭HSQL数据库，并删除data/目录下的所有文件，再重新启动HSQL数据库。

Hibernate是你的应用程序里连接数据库的那层，所以它需要连接用的信息。连接（connection）是通过一个也由我们配置的JDBC连接池（connection pool）来完成的。Hibernate的发布包里包含了许多开源的（open source）连接池，但在我们例子中使用Hibernate内置的连接池。注意，如果你希望使用一个产品级(production-quality)的第三方连接池软件，你必须拷贝所需的库文件到你的classpath下，并使用不同的连接池设置。

为了保存Hibernate的配置，我们可以使用一个简单的hibernate.properties文件，或者一个稍微复杂的hibernate.cfg.xml，甚至可以完全使用程序来配置Hibernate。多数用户更喜欢使用XML配置文件：

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <session-factory>

        <!-- Database connection settings -->
        <property name="connection.driver_class">org.hsqldb.jdbcDriver</property>
        <property name="connection.url">jdbc:hsqldb:hsql://localhost</property>
        <property name="connection.username">sa</property>
        <property name="connection.password"></property>

        <!-- JDBC connection pool (use the built-in) -->
        <property name="connection.pool_size">1</property>

        <!-- SQL dialect -->
        <property name="dialect">org.hibernate.dialect.HSQLDialect</property>

        <!-- Enable Hibernate's automatic session context management -->
        <property name="current_session_context_class">thread</property>

        <!-- Disable the second-level cache  -->
        <property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property>

        <!-- Echo all executed SQL to stdout -->
        <property name="show_sql">true</property>

        <!-- Drop and re-create the database schema on startup -->
        <property name="hbm2ddl.auto">create</property>

        <mapping resource="events/Event.hbm.xml"/>

    </session-factory>

</hibernate-configuration>

注意这个XML配置使用了一个不同的DTD。在这里，我们配置了Hibernate的SessionFactory－一个关联于特定数据库全局的工厂（factory）。如果你要使用多个数据库，就要用多个的<session-factory>，通常把它们放在多个配置文件中（为了更容易启动）。

最开始的4个property元素包含必要的JDBC连接信息。方言（dialect）的property元素指明Hibernate 生成的特定SQL变量。你很快会看到，Hibernate对持久化上下文的自动session管理就会派上用场。 打开hbm2ddl.auto选项将自动生成数据库模式（schema）－ 直接加入数据库中。当然这个选项也可以被关闭（通过去除这个配置选项）或者通过Ant任务SchemaExport的帮助来把数据库schema重定向到文件中。最后，在配置中为持久化类加入映射文件。

把这个文件拷贝到源代码目录下面，这样它就位于classpath的根目录的最后。Hibernate在启动时会自动在classpath的根目录查找名为hibernate.cfg.xml的配置文件。

现在我们用Ant来构建应用程序。你必须先安装Ant－可以从Ant 下载页面得到它。怎样安装Ant就不在这里介绍了，请参考Ant 用户手册。当你安装完了Ant，就可以开始创建build.xml文件，把它直接放在开发目录下面。

一个简单的build文件看起来像这样：

<project name="hibernate-tutorial" default="compile">

    <property name="sourcedir" value="${basedir}/src"/>
    <property name="targetdir" value="${basedir}/bin"/>
    <property name="librarydir" value="${basedir}/lib"/>

    <path id="libraries">
        <fileset dir="${librarydir}">
            <include name="*.jar"/>
        </fileset>
    </path>

    <target name="clean">
        <delete dir="${targetdir}"/>
        <mkdir dir="${targetdir}"/>
    </target>

    <target name="compile" depends="clean, copy-resources">
      <javac srcdir="${sourcedir}"
             destdir="${targetdir}"
             classpathref="libraries"/>
    </target>

    <target name="copy-resources">
        <copy todir="${targetdir}">
            <fileset dir="${sourcedir}">
                <exclude name="**/*.java"/>
            </fileset>
        </copy>
    </target>

</project>

这将告诉Ant把所有在lib目录下以.jar结尾的文件拷贝到classpath中以供编译之用。它也把所有的非Java源代码文件，例如配置和Hibernate映射文件，拷贝到目标目录。如果你现在运行Ant，会得到以下输出：

C:\hibernateTutorial\>ant
Buildfile: build.xml

copy-resources:
     [copy] Copying 2 files to C:\hibernateTutorial\bin

compile:
    [javac] Compiling 1 source file to C:\hibernateTutorial\bin

BUILD SUCCESSFUL
Total time: 1 second 

是时候来加载和储存一些Event对象了，但首先我们得编写一些基础的代码以完成设置。我们必须启动Hibernate，此过程包括创建一个全局的SessoinFactory，并把它储存在应用程序代码容易访问的地方。SessionFactory可以创建并打开新的Session。一个Session代表一个单线程的单元操作，SessionFactory则是个线程安全的全局对象，只需要被实例化一次。

我们将创建一个HibernateUtil辅助类（helper class）来负责启动Hibernate和更方便地操作SessionFactory。让我们来看一下它的实现：

package util;

import org.hibernate.*;
import org.hibernate.cfg.*;

public class HibernateUtil {

    private static final SessionFactory sessionFactory;

    static {
        try {
            // Create the SessionFactory from hibernate.cfg.xml
            sessionFactory = new Configuration().configure().buildSessionFactory();
        } catch (Throwable ex) {
            // Make sure you log the exception, as it might be swallowed
            System.err.println("Initial SessionFactory creation failed." + ex);
            throw new ExceptionInInitializerError(ex);
        }
    }

    public static SessionFactory getSessionFactory() {
        return sessionFactory;
    }

}

这个类不但在它的静态初始化过程（仅当加载这个类的时候被JVM执行一次）中产生全局的SessionFactory，而且隐藏了它使用了静态singleton的事实。它也可能在应用程序服务器中的JNDI查找SessionFactory。

如果你在配置文件中给SessionFactory一个名字，在SessionFactory创建后，Hibernate会试着把它绑定到JNDI。要完全避免这样的代码，你也可以使用JMX部署，让具有JMX能力的容器来实例化HibernateService并把它绑定到JNDI。这些高级可选项在后面的章节中会讨论到。

把HibernateUtil.java放在开发目录的源代码路径下，与放events的包并列：

.
+lib
  <Hibernate and third-party libraries>
+src
  +events
    Event.java
    Event.hbm.xml
  +util
    HibernateUtil.java
  hibernate.cfg.xml
+data
build.xml

再次编译这个应用程序应该不会有问题。最后我们需要配置一个日志（logging)系统 － Hibernate使用通用日志接口，允许你在Log4j和JDK 1.4 日志之间进行选择。多数开发者更喜欢Log4j：从Hibernate的发布包中（它在etc/目录下）拷贝log4j.properties到你的src目录，与hibernate.cfg.xml.放在一起。看一下配置示例，如果你希望看到更加详细的输出信息，你可以修改配置。默认情况下，只有Hibernate的启动信息才会显示在标准输出上。

示例的基本框架完成了 － 现在我们可以用Hibernate来做些真正的工作。

我们终于可以使用Hibernate来加载和存储对象了，编写一个带有main()方法的EventManager类：

package events;
import org.hibernate.Session;

import java.util.Date;

import util.HibernateUtil;

public class EventManager {

    public static void main(String[] args) {
        EventManager mgr = new EventManager();

        if (args[0].equals("store")) {
            mgr.createAndStoreEvent("My Event", new Date());
        }

        HibernateUtil.getSessionFactory().close();
    }

    private void createAndStoreEvent(String title, Date theDate) {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();

        session.beginTransaction();

        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);

        session.save(theEvent);

        session.getTransaction().commit();
    }

}

我们创建了个新的Event对象并把它传递给Hibernate。现在Hibernate负责与SQL打交道，并把INSERT命令传给数据库。在运行之前，让我们看一下处理Session和Transaction的代码。

一个Session就是个单一的工作单元。我们暂时让事情简单一些，并假设HibernateSession和数据库事务是一一对应的。为了让我们的代码从底层的事务系统中脱离出来（此例中是JDBC，但也可能是JTA），我们使用Hibernate Session中的Transaction API。

sessionFactory.getCurrentSession()是干什么的呢？首先，只要你持有SessionFactory（幸亏我们有HibernateUtil，可以随时获得），大可在任何时候、任何地点调用这个方法。getCurrentSession()方法总会返回“当前的”工作单元。记得我们在hibernate.cfg.xml中把这一配置选项调整为"thread"了吗？因此，因此，当前工作单元被绑定到当前执行我们应用程序的Java线程。但是，这并非是完全准确的,你还得考虑工作单元的生命周期范围 (scope),它何时开始,又何时结束.

Session在第一次被使用的时候,即第一次调用getCurrentSession()的时候,其生命周期就开始。然后它被Hibernate绑定到当前线程。当事务结束的时候，不管是提交还是回滚，Hibernate会自动把Session从当前线程剥离，并且关闭它。假若你再次调用getCurrentSession()，你会得到一个新的Session，并且开始一个新的工作单元。这种线程绑定(thread-bound)的编程模型（model）是使用Hibernate的最广泛的方式,因为它支持对你的代码灵活分层(事务划分可以和你的数据访问代码分离开来,在本教程的后面部分就会这么做)。

和工作单元的生命周期这个话题相关，Hibernate Session是否被应该用来执行多次数据库操作？上面的例子对每一次操作使用了一个Session，这完全是巧合，这个例子不是很复杂，无法展示其他方式。Hibernate Session的生命周期可以很灵活，但是你绝不要把你的应用程序设计成为每一次数据库操作都用一个新的Hibernate Session。因此就算下面的例子（它们都很简单）中你可以看到这种用法，记住每次操作一个session是一个反模式。在本教程的后面会展示一个真正的(web)程序。

关于事务处理及事务边界界定的详细信息，请参看第 11 章 事务和并发。在上面的例子中，我们也忽略了所有的错误与回滚的处理。

为第一次运行我们的程序，我们得在Ant的build文件中增加一个可以调用得到的target。

<target name="run" depends="compile">
    <java fork="true" classname="events.EventManager" classpathref="libraries">
        <classpath path="${targetdir}"/>
        <arg value="${action}"/>
    </java>
</target>

action参数（argument）的值是通过命令行调用这个target的时候设置的：

C:\hibernateTutorial\>ant run -Daction=store

你应该会看到，编译以后，Hibernate根据你的配置启动，并产生一大堆的输出日志。在日志最后你会看到下面这行：

[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)

这是Hibernate执行的INSERT命令，问号代表JDBC的绑定参数。如果想要看到绑定参数的值或者减少日志的长度，就要调整你在log4j.properties文件里的设置。

我们想要列出所有已经被存储的events，就要增加一个条件分支选项到main方法中去。

if (args[0].equals("store")) {
    mgr.createAndStoreEvent("My Event", new Date());
}
else if (args[0].equals("list")) {
    List events = mgr.listEvents();
    for (int i = 0; i < events.size(); i++) {
        Event theEvent = (Event) events.get(i);
        System.out.println("Event: " + theEvent.getTitle() +
                           " Time: " + theEvent.getDate());
    }
}

我们也增加一个新的listEvents()方法:

private List listEvents() {

    Session session = HibernateUtil.getSessionFactory().getCurrentSession();

    session.beginTransaction();

    List result = session.createQuery("from Event").list();

    session.getTransaction().commit();

    return result;
}

我们在这里是用一个HQL（Hibernate Query Language－Hibernate查询语言）查询语句来从数据库中加载所有存在的Event对象。Hibernate会生成适当的SQL，把它发送到数据库，并操作从查询得到数据的Event对象。当然，你可以使用HQL来创建更加复杂的查询。

现在，根据以下步骤来执行并测试以上各项：

如果你现在使用命令行参数-Daction=list运行Ant，你会看到那些至今为止我们所储存的events。当然，你也可以多调用几次store以保存更多的envents。

注意，很多Hibernate新手在这一步会失败，我们不时看到关于Table not found错误信息的提问。但是，只要你根据上面描述的步骤来执行，就不会有这个问题，因为hbm2ddl会在第一次运行的时候创建数据库schema，后继的应用程序重起后还能继续使用这个schema。假若你修改了映射，或者修改了数据库schema，你必须把hbm2ddl重新打开一次。

最初简单的Person类：

package events;

public class Person {

    private Long id;
    private int age;
    private String firstname;
    private String lastname;

    public Person() {}

    // Accessor methods for all properties, private setter for 'id'

}

创建一个名为Person.hbm.xml的新映射文件（别忘了最上面的DTD引用）：

<hibernate-mapping>

    <class name="events.Person" table="PERSON">
        <id name="id" column="PERSON_ID">
            <generator class="native"/>
        </id>
        <property name="age"/>
        <property name="firstname"/>
        <property name="lastname"/>
    </class>

</hibernate-mapping>

最后，把新的映射加入到Hibernate的配置中：

<mapping resource="events/Event.hbm.xml"/>
<mapping resource="events/Person.hbm.xml"/>

现在我们在这两个实体之间创建一个关联。显然，persons可以参与一系列events，而events也有不同的参加者（persons）。我们需要处理的设计问题是关联方向（directionality），阶数（multiplicity）和集合（collection）的行为。

我们将向Person类增加一连串的events。那样，通过调用aPerson.getEvents()，就可以轻松地导航到特定person所参与的events，而不用去执行一个显式的查询。我们使用Java的集合类（collection）：Set，因为set 不包含重复的元素及与我们无关的排序。

我们需要用set 实现一个单向多值关联。让我们在Java类里为这个关联编码，接着映射它：

public class Person {

    private Set events = new HashSet();

    public Set getEvents() {
        return events;
    }

    public void setEvents(Set events) {
        this.events = events;
    }
}

在映射这个关联之前，先考虑一下此关联的另外一端。很显然，我们可以保持这个关联是单向的。或者，我们可以在Event里创建另外一个集合，如果希望能够双向地导航，如：anEvent.getParticipants()。从功能的角度来说，这并不是必须的。因为你总可以显式地执行一个查询，以获得某个特定event的所有参与者。这是个在设计时需要做出的选择，完全由你来决定，但此讨论中关于关联的阶数是清楚的：即两端都是“多”值的，我们把它叫做多对多(many-to-many)关联。因而，我们使用Hibernate的多对多映射：

<class name="events.Person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="native"/>
    </id>
    <property name="age"/>
    <property name="firstname"/>
    <property name="lastname"/>

    <set name="events" table="PERSON_EVENT">
        <key column="PERSON_ID"/>
        <many-to-many column="EVENT_ID" class="events.Event"/>
    </set>

</class>

Hibernate支持各种各样的集合映射，<set>使用的最为普遍。对于多对多关联（或叫n:m实体关系）, 需要一个关联表（association table）。表里面的每一行代表从person到event的一个关联。表名是由set元素的table属性配置的。关联里面的标识符字段名，对于person的一端，是由<key>元素定义，而event一端的字段名是由<many-to-many>元素的column属性定义。你也必须告诉Hibernate集合中对象的类（也就是位于这个集合所代表的关联另外一端的类）。

因而这个映射的数据库schema是：

    _____________        __________________
   |             |      |                  |       _____________
   |   EVENTS    |      |   PERSON_EVENT   |      |             |
   |_____________|      |__________________|      |    PERSON   |
   |             |      |                  |      |_____________|
   | *EVENT_ID   | <--> | *EVENT_ID        |      |             |
   |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  |
   |  TITLE      |      |__________________|      |  AGE        |
   |_____________|                                |  FIRSTNAME  |
                                                  |  LASTNAME   |
                                                  |_____________|
 

我们把一些people和events 一起放到EventManager的新方法中：

private void addPersonToEvent(Long personId, Long eventId) {

    Session session = HibernateUtil.getSessionFactory().getCurrentSession();
    session.beginTransaction();

    Person aPerson = (Person) session.load(Person.class, personId);
    Event anEvent = (Event) session.load(Event.class, eventId);

    aPerson.getEvents().add(anEvent);

    session.getTransaction().commit();
}

在加载一Person和Event后，使用普通的集合方法就可容易地修改我们定义的集合。如你所见，没有显式的update()或save()，Hibernate会自动检测到集合已经被修改并需要更新回数据库。这叫做自动脏检查（automatic dirty checking），你也可以尝试修改任何对象的name或者date属性，只要他们处于持久化状态，也就是被绑定到某个Hibernate 的Session上（如：他们刚刚在一个单元操作被加载或者保存），Hibernate监视任何改变并在后台隐式写的方式执行SQL。同步内存状态和数据库的过程，通常只在单元操作结束的时候发生，称此过程为清理缓存（flushing）。在我们的代码中，工作单元由数据库事务的提交（或者回滚）来结束——这是由CurrentSessionContext类的thread配置选项定义的。

当然，你也可以在不同的单元操作里面加载person和event。或在Session以外修改不是处在持久化（persistent）状态下的对象（如果该对象以前曾经被持久化，那么我们称这个状态为脱管（detached））。你甚至可以在一个集合被脱管时修改它：

private void addPersonToEvent(Long personId, Long eventId) {

    Session session = HibernateUtil.getSessionFactory().getCurrentSession();
    session.beginTransaction();

    Person aPerson = (Person) session
            .createQuery("select p from Person p left join fetch p.events where p.id = :pid")
            .setParameter("pid", personId)
            .uniqueResult(); // Eager fetch the collection so we can use it detached

    Event anEvent = (Event) session.load(Event.class, eventId);

    session.getTransaction().commit();

    // End of first unit of work

    aPerson.getEvents().add(anEvent); // aPerson (and its collection) is detached

    // Begin second unit of work

    Session session2 = HibernateUtil.getSessionFactory().getCurrentSession();
    session2.beginTransaction();

    session2.update(aPerson); // Reattachment of aPerson

    session2.getTransaction().commit();
}

对update的调用使一个脱管对象重新持久化，你可以说它被绑定到一个新的单元操作上，所以在脱管状态下对它所做的任何修改都会被保存到数据库里。这也包括你对这个实体对象的集合所作的任何改动（增加/删除）。

这对我们当前的情形不是很有用，但它是非常重要的概念，你可以把它融入到你自己的应用程序设计中。在EventManager的main方法中添加一个新的动作，并从命令行运行它来完成我们所做的练习。如果你需要person及event的标识符 — 那就用save()方法返回它（你可能需要修改前面的一些方法来返回那个标识符）：

else if (args[0].equals("addpersontoevent")) {
    Long eventId = mgr.createAndStoreEvent("My Event", new Date());
    Long personId = mgr.createAndStorePerson("Foo", "Bar");
    mgr.addPersonToEvent(personId, eventId);
    System.out.println("Added person " + personId + " to event " + eventId);
}

上面是个关于两个同等重要的实体类间关联的例子。像前面所提到的那样，在特定的模型中也存在其它的类和类型，这些类和类型通常是“次要的”。你已看到过其中的一些，像int或String。我们称这些类为值类型（value type），它们的实例依赖（depend）在某个特定的实体上。这些类型的实例没有它们自己的标识（identity），也不能在实体间被共享（比如，两个person不能引用同一个firstname对象，即使他们有相同的first name）。当然，值类型并不仅仅在JDK中存在（事实上，在一个Hibernate应用程序中，所有的JDK类都被视为值类型），而且你也可以编写你自己的依赖类，例如Address，MonetaryAmount。

你也可以设计一个值类型的集合，这在概念上与引用其它实体的集合有很大的不同，但是在Java里面看起来几乎是一样的。

我们把一个值类型对象的集合加入Person实体中。我们希望保存email地址，所以使用String类型，而且这次的集合类型又是Set：

private Set emailAddresses = new HashSet();

public Set getEmailAddresses() {
    return emailAddresses;
}

public void setEmailAddresses(Set emailAddresses) {
    this.emailAddresses = emailAddresses;
}

这个Set的映射

<set name="emailAddresses" table="PERSON_EMAIL_ADDR">
    <key column="PERSON_ID"/>
    <element type="string" column="EMAIL_ADDR"/>
</set>

比较这次和此前映射的差别，主要在于element部分，这次并没有包含对其它实体引用的集合，而是元素类型为String的集合（在映射中使用小写的名字”string“是向你表明它是一个Hibernate的映射类型或者类型转换器）。和之前一样，set元素的table属性决定了用于集合的表名。key元素定义了在集合表中外键的字段名。element元素的column属性定义用于实际保存String值的字段名。

看一下修改后的数据库schema。

  _____________        __________________
 |             |      |                  |       _____________
 |   EVENTS    |      |   PERSON_EVENT   |      |             |       ___________________
 |_____________|      |__________________|      |    PERSON   |      |                   |
 |             |      |                  |      |_____________|      | PERSON_EMAIL_ADDR |
 | *EVENT_ID   | <--> | *EVENT_ID        |      |             |      |___________________|
 |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  | <--> |  *PERSON_ID       |
 |  TITLE      |      |__________________|      |  AGE        |      |  *EMAIL_ADDR      |
 |_____________|                                |  FIRSTNAME  |      |___________________|
                                                |  LASTNAME   |
                                                |_____________|
 

你可以看到集合表的主键实际上是个复合主键，同时使用了2个字段。这也暗示了对于同一个person不能有重复的email地址，这正是Java里面使用Set时候所需要的语义（Set里元素不能重复）。

你现在可以试着把元素加入到这个集合，就像我们在之前关联person和event的那样。其实现的Java代码是相同的：

private void addEmailToPerson(Long personId, String emailAddress) {

    Session session = HibernateUtil.getSessionFactory().getCurrentSession();
    session.beginTransaction();

    Person aPerson = (Person) session.load(Person.class, personId);

    // The getEmailAddresses() might trigger a lazy load of the collection
    aPerson.getEmailAddresses().add(emailAddress);

    session.getTransaction().commit();
}

This time we didn't use a fetch query to initialize the collection. Hence, the call to its getter method will trigger an additional select to initialize it, so we can add an element to it. Monitor the SQL log and try to optimize this with an eager fetch.

接下来我们将映射双向关联（bi-directional association）－ 在Java里让person和event可以从关联的任何一端访问另一端。当然，数据库schema没有改变，我们仍然需要多对多的阶数。一个关系型数据库要比网络编程语言 更加灵活，所以它并不需要任何像导航方向（navigation direction）的东西 － 数据可以用任何可能的方式进行查看和获取。

首先，把一个参与者（person）的集合加入Event类中：

private Set participants = new HashSet();

public Set getParticipants() {
    return participants;
}

public void setParticipants(Set participants) {
    this.participants = participants;
}

在Event.hbm.xml里面也映射这个关联。

<set name="participants" table="PERSON_EVENT" inverse="true">
    <key column="EVENT_ID"/>
    <many-to-many column="PERSON_ID" class="events.Person"/>
</set>

如你所见，两个映射文件里都有普通的set映射。注意在两个映射文件中，互换了key和many-to-many的字段名。这里最重要的是Event映射文件里增加了set元素的inverse="true"属性。

这意味着在需要的时候，Hibernate能在关联的另一端 － Person类得到两个实体间关联的信息。这将会极大地帮助你理解双向关联是如何在两个实体间被创建的。

首先请记住，Hibernate并不影响通常的Java语义。 在单向关联的例子中，我们是怎样在Person和Event之间创建联系的？我们把Event实例添加到Person实例内的event引用集合里。因此很显然，如果我们要让这个关联可以双向地工作，我们需要在另外一端做同样的事情 － 把Person实例加入Event类内的Person引用集合。这“在关联的两端设置联系”是完全必要的而且你都得这么做。

Many developers program defensively and create link management methods to correctly set both sides, e.g. in Person:

protected Set getEvents() {
    return events;
}

protected void setEvents(Set events) {
    this.events = events;
}

public void addToEvent(Event event) {
    this.getEvents().add(event);
    event.getParticipants().add(this);
}

public void removeFromEvent(Event event) {
    this.getEvents().remove(event);
    event.getParticipants().remove(this);
}

注意现在对于集合的get和set方法的访问级别是protected - 这允许在位于同一个包（package）中的类以及继承自这个类的子类可以访问这些方法，但禁止其他任何人的直接访问，避免了集合内容的混乱。你应尽可能地在另一端也把集合的访问级别设成protected。

inverse映射属性究竟表示什么呢？对于你和Java来说，一个双向关联仅仅是在两端简单地正确设置引用。然而，Hibernate并没有足够的信息去正确地执行INSERT和UPDATE语句（以避免违反数据库约束），所以它需要一些帮助来正确的处理双向关联。把关联的一端设置为inverse将告诉Hibernate忽略关联的这一端，把这端看成是另外一端的一个镜象（mirror）。这就是所需的全部信息，Hibernate利用这些信息来处理把一个有向导航模型转移到数据库schema时的所有问题。你只需要记住这个直观的规则：所有的双向关联需要有一端被设置为inverse。在一对多关联中它必须是代表多（many）的那端。而在多对多（many-to-many）关联中，你可以任意选取一端，因为两端之间并没有差别。

在你的源代码目录的events包中创建一个新的类：

package events;

// Imports

public class EventManagerServlet extends HttpServlet {

    // Servlet code
}

我们后面会用到dateFormatter 的工具， 它把Date对象转换为字符串。只要一个formatter作为servlet的成员就可以了。

protected void doGet(HttpServletRequest request,
                     HttpServletResponse response)
        throws ServletException, IOException {

    SimpleDateFormat dateFormatter = new SimpleDateFormat("dd.MM.yyyy");

    try {
        // Begin unit of work
        HibernateUtil.getSessionFactory()
                .getCurrentSession().beginTransaction();

        // Process request and render page...

        // End unit of work
        HibernateUtil.getSessionFactory()
                .getCurrentSession().getTransaction().commit();

    } catch (Exception ex) {
        HibernateUtil.getSessionFactory()
                .getCurrentSession().getTransaction().rollback();
        throw new ServletException(ex);
    }

}

The pattern we are applying here is called session-per-request. When a request hits the servlet, a new Hibernate Session is opened through the first call to getCurrentSession() on the SessionFactory. Then a database transaction is started-all data access as to occur inside a transaction, no matter if data is read or written (we don't use the auto-commit mode in applications).

我们称这里应用的模式为每次请求一个session(session-per-request)。当有请求到达这个servlet的时候，通过对SessionFactory的第一次调用，打开一个新的Hibernate Session。然后启动一个数据库事务-所有的数据访问都是在事务中进行，不管是读还是写（我们在应用程序中不使用auto-commit模式）。

不要为每次数据库操作都使用一个新的Hibernate Session。将Hibernate Session的范围设置为整个请求。要用getCurrentSession()，这样它自动会绑定到当前Java线程。

Finally, the unit of work ends when processing and rendering is complete. If any problem occurred during processing or rendering, an exception will be thrown and the database transaction rolled back. This completes the session-per-request pattern. Instead of the transaction demarcation code in every servlet you could also write a servlet filter. See the Hibernate website and Wiki for more information about this pattern, called Open Session in View-you'll need it as soon as you consider rendering your view in JSP, not in a servlet.

处理与渲染

// Write HTML header
PrintWriter out = response.getWriter();
out.println("<html><head><title>Event Manager</title></head><body>");

// Handle actions
if ( "store".equals(request.getParameter("action")) ) {

    String eventTitle = request.getParameter("eventTitle");
    String eventDate = request.getParameter("eventDate");

    if ( "".equals(eventTitle) || "".equals(eventDate) ) {
        out.println("<b><i>Please enter event title and date.</i></b>");
    } else {
        createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate));
        out.println("<b><i>Added event.</i></b>");
    }
}

// Print page
printEventForm(out);
listEvents(out, dateFormatter);

// Write HTML footer
out.println("</body></html>");
out.flush();
out.close();

Granted, this coding style with a mix of Java and HTML would not scale in a more complex application-keep in mind that we are only illustrating basic Hibernate concepts in this tutorial. The code prints an HTML header and a footer. Inside this page, an HTML form for event entry and a list of all events in the database are printed. The first method is trivial and only outputs HTML:

private void printEventForm(PrintWriter out) {
    out.println("<h2>Add new event:</h2>");
    out.println("<form>");
    out.println("Title: <input name='eventTitle' length='50'/><br/>");
    out.println("Date (e.g. 24.12.2009): <input name='eventDate' length='10'/><br/>");
    out.println("<input type='submit' name='action' value='store'/>");
    out.println("</form>");
}

listEvents()方法使用绑定到当前线程的Hibernate Session来执行查询：

private void listEvents(PrintWriter out, SimpleDateFormat dateFormatter) {

    List result = HibernateUtil.getSessionFactory()
                    .getCurrentSession().createCriteria(Event.class).list();
    if (result.size() > 0) {
        out.println("<h2>Events in database:</h2>");
        out.println("<table border='1'>");
        out.println("<tr>");
        out.println("<th>Event title</th>");
        out.println("<th>Event date</th>");
        out.println("</tr>");
        for (Iterator it = result.iterator(); it.hasNext();) {
            Event event = (Event) it.next();
            out.println("<tr>");
            out.println("<td>" + event.getTitle() + "</td>");
            out.println("<td>" + dateFormatter.format(event.getDate()) + "</td>");
            out.println("</tr>");
        }
        out.println("</table>");
    }
}

最后，store动作会被导向到createAndStoreEvent()方法，它也使用当前线程的Session:

protected void createAndStoreEvent(String title, Date theDate) {
    Event theEvent = new Event();
    theEvent.setTitle(title);
    theEvent.setDate(theDate);

    HibernateUtil.getSessionFactory()
                    .getCurrentSession().save(theEvent);
}

That's it, the servlet is complete. A request to the servlet will be processed in a single Session and Transaction. As earlier in the standalone application, Hibernate can automatically bind these objects to the current thread of execution. This gives you the freedom to layer your code and access the SessionFactory in any way you like. Usually you'd use a more sophisticated design and move the data access code into data access objects (the DAO pattern). See the Hibernate Wiki for more examples.

要发布这个程序，你得把它打成web发布包：WAR文件。把下面的脚本加入到你的build.xml中：

<target name="war" depends="compile">
    <war destfile="hibernate-tutorial.war" webxml="web.xml">
        <lib dir="${librarydir}">
          <exclude name="jsdk*.jar"/>
        </lib>

        <classes dir="${targetdir}"/>
    </war>
</target>

这段代码在你的开发目录中创建一个hibernate-tutorial.war的文件。它把所有的类库和web.xml描述文件都打包进去，web.xml 文件应该位于你的开发根目录中：

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <servlet>
        <servlet-name>Event Manager</servlet-name>
        <servlet-class>events.EventManagerServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Event Manager</servlet-name>
        <url-pattern>/eventmanager</url-pattern>
    </servlet-mapping>
</web-app>

Before you compile and deploy the web application, note that an additional library is required: jsdk.jar. This is the Java servlet development kit, if you don't have this library already, get it from the Sun website and copy it to your library directory. However, it will be only used for compilation and excluded from the WAR package.

在你的开发目录中，调用ant war来构建、打包，然后把hibernate-tutorial.war文件拷贝到你的tomcat的webapps目录下。假若你还没安装Tomcat，就去下载一个，按照指南来安装。对此应用的发布，你不需要修改任何Tomcat的配置。

在部署完，启动Tomcat之后，通过http://localhost:8080/hibernate-tutorial/eventmanager进行访问你的应用，在第一次servlet 请求发生时，请在Tomcat log中确认你看到Hibernate被初始化了（HibernateUtil的静态初始化器被调用），假若有任何异常抛出，也可以看到详细的输出。

你应当总是为你的数据库将hibernate.dialect属性设置成正确的 org.hibernate.dialect.Dialect子类. 如果你指定一种方言, Hibernate将为上面列出的一些属性使用合理的默认值, 为你省去了手工指定它们的功夫.

如果你的数据库支持ANSI, Oracle或Sybase风格的外连接, 外连接抓取通常能通过限制往返数据库次数 (更多的工作交由数据库自己来完成)来提高效率. 外连接抓取允许在单个SELECTSQL语句中， 通过many-to-one, one-to-many, many-to-many和one-to-one关联获取连接对象的整个对象图.

将hibernate.max_fetch_depth设为0能在全局 范围内禁止外连接抓取. 设为1或更高值能启用one-to-one和many-to-oneouter关联的外连接抓取, 它们通过 fetch="join"来映射.

参见第 19.1 节 “抓取策略(Fetching strategies)”获得更多信息.

Oracle限制那些通过JDBC驱动传输的字节数组的数目. 如果你希望使用二进值 (binary)或 可序列化的 (serializable)类型的大对象, 你应该开启 hibernate.jdbc.use_streams_for_binary属性. 这是系统级属性.

以hibernate.cache为前缀的属性允许你在Hibernate中，使用进程或群集范围内的二级缓存系统. 参见第 19.2 节 “二级缓存（The Second Level Cache）”获取更多的详情.

你可以使用hibernate.query.substitutions在Hibernate中定义新的查询符号. 例如:

hibernate.query.substitutions true=1, false=0

将导致符号true和false在生成的SQL中被翻译成整数常量.

hibernate.query.substitutions toLowercase=LOWER

将允许你重命名SQL中的LOWER函数.

如果你开启hibernate.generate_statistics, 那么当你通过 SessionFactory.getStatistics()调整正在运行的系统时，Hibernate将导出大量有用的数据. Hibernate甚至能被配置成通过JMX导出这些统计信息. 参考org.hibernate.stats中接口的Javadoc，以获得更多信息.

在你的架构中，Hibernate的Session API是独立于任何事务分界系统的. 如果你让Hibernate通过连接池直接使用JDBC, 你需要调用JDBC API来打开和关闭你的事务. 如果你运行在J2EE应用程序服务器中, 你也许想用Bean管理的事务并在需要的时候调用JTA API和UserTransaction.

为了让你的代码在两种(或其他)环境中可以移植，我们建议使用可选的Hibernate Transaction API, 它包装并隐藏了底层系统. 你必须通过设置Hibernate配置属性hibernate.transaction.factory_class来指定 一个Transaction实例的工厂类.

有三个标准(内建)的选择:

你也可以定义属于你自己的事务策略 (如, 针对CORBA的事务服务)

Hibernate的一些特性 (比如二级缓存, Contextual Sessions with JTA等等)需要访问在托管环境中的JTA TransactionManager. 由于J2EE没有标准化一个单一的机制,Hibernate在应用程序服务器中，你必须指定Hibernate如何获得TransactionManager的引用:

与JNDI绑定的Hibernate的SessionFactory能简化工厂的查询，简化创建新的Session. 需要注意的是这与JNDI绑定Datasource没有关系, 它们只是恰巧用了相同的注册表!

如果你希望将SessionFactory绑定到一个JNDI的名字空间, 用属性hibernate.session_factory_name指定一个名字(如, java:hibernate/SessionFactory). 如果不设置这个属性, SessionFactory将不会被绑定到JNDI中. (在以只读JNDI为默认实现的环境中，这个设置尤其有用, 如Tomcat.)

在将SessionFactory绑定至JNDI时, Hibernate将使用hibernate.jndi.url, 和hibernate.jndi.class的值来实例化初始环境(initial context). 如果它们没有被指定, 将使用默认的InitialContext.

在你调用cfg.buildSessionFactory()后, Hibernate会自动将SessionFactory注册到JNDI. 这意味这你至少需要在你应用程序的启动代码(或工具类)中完成这个调用, 除非你使用HibernateService来做JMX部署 (见后面讨论).

假若你使用JNDI SessionFactory,EJB或者任何其它类都可以从JNDI中找到此SessionFactory。

我们建议，在受管理的环境中，把SessionFactory绑定到JNDI，在其它情况下，使用一个static(静态的)singleton。为了在你的应用程序代码中隐藏这些细节，我们还建议你用一个helper类把实际查找SessionFactory的代码隐藏起来,比如HibernateUtil.getSessionFactory()。注意，这个类也就可以方便地启动Hibernate，参见第一章。

The easiest way to handle Sessions and transactions is Hibernates automatic "current" Session management. See the discussion of current sessions. Using the "jta" session context, if there is no Hibernate Session associated with the current JTA transaction, one will be started and associated with that JTA transaction the first time you call sessionFactory.getCurrentSession(). The Sessions retrieved via getCurrentSession() in "jta" context will be set to automatically flush before the transaction completes, close after the transaction completes, and aggressively release JDBC connections after each statement. This allows the Sessions to be managed by the life cycle of the JTA transaction to which it is associated, keeping user code clean of such management concerns. Your code can either use JTA programmatically through UserTransaction, or (recommended for portable code) use the Hibernate Transaction API to set transaction boundaries. If you run in an EJB container, declarative transaction demarcation with CMT is preferred.

为了将SessionFactory注册到JNDI中，cfg.buildSessionFactory()这行代码仍需在某处被执行. 你可在一个static初始化块(像HibernateUtil中的那样)中执行它或将Hibernate部署为一个托管的服务.

为了部署在一个支持JMX的应用程序服务器上，Hibernate和 org.hibernate.jmx.HibernateService一同分发，如Jboss AS。 实际的部署和配置是由应用程序服务器提供者指定的. 这里是JBoss 4.0.x的jboss-service.xml样例:

<?xml version="1.0"?>
<server>

<mbean code="org.hibernate.jmx.HibernateService"
    name="jboss.jca:service=HibernateFactory,name=HibernateFactory">

    <!-- Required services -->
    <depends>jboss.jca:service=RARDeployer</depends>
    <depends>jboss.jca:service=LocalTxCM,name=HsqlDS</depends>

    <!-- Bind the Hibernate service to JNDI -->
    <attribute name="JndiName">java:/hibernate/SessionFactory</attribute>

    <!-- Datasource settings -->
    <attribute name="Datasource">java:HsqlDS</attribute>
    <attribute name="Dialect">org.hibernate.dialect.HSQLDialect</attribute>

    <!-- Transaction integration -->
    <attribute name="TransactionStrategy">
        org.hibernate.transaction.JTATransactionFactory</attribute>
    <attribute name="TransactionManagerLookupStrategy">
        org.hibernate.transaction.JBossTransactionManagerLookup</attribute>
    <attribute name="FlushBeforeCompletionEnabled">true</attribute>
    <attribute name="AutoCloseSessionEnabled">true</attribute>

    <!-- Fetching options -->
    <attribute name="MaximumFetchDepth">5</attribute>

    <!-- Second-level caching -->
    <attribute name="SecondLevelCacheEnabled">true</attribute>
    <attribute name="CacheProviderClass">org.hibernate.cache.EhCacheProvider</attribute>
    <attribute name="QueryCacheEnabled">true</attribute>

    <!-- Logging -->
    <attribute name="ShowSqlEnabled">true</attribute>

    <!-- Mapping files -->
    <attribute name="MapResources">auction/Item.hbm.xml,auction/Category.hbm.xml</attribute>

</mbean>

</server>

这个文件是部署在META-INF目录下的, 并会被打包到以.sar (service archive)为扩展名的JAR文件中. 同时，你需要将Hibernate、它所需要的第三方库、你编译好的持久化类以及你的映射定义文件打包进同一个文档. 你的企业Bean(一般为会话Bean)可能会被打包成它们自己的JAR文件, 但你也许会将EJB JAR文件一同包含进能独立(热)部署的主服务文档. 参考JBoss AS文档以了解更多的JMX服务与EJB部署的信息.

Cat有一个无参数的构造方法。所有的持久化类都必须有一个 默认的构造方法（可以不是public的），这样的话Hibernate就可以使用 Constructor.newInstance()来实例化它们。 我们强烈建议，在Hibernate中，为了运行期代理的生成，构造方法至少是 包(package)内可见的。

Cat有一个属性叫做id。这个属性映射数据库表的主 键字段。这个属性可以叫任何名字，其类型可以是任何的原始类型、原始类型的包装类型、 java.lang.String 或者是 java.util.Date。 （如果你的遗留数据库表有联合主键，你甚至可以用一个用户自定义的类，该类拥有这些类型 的属性。参见后面的关于联合标识符的章节。）

标识符属性是可选的。可以不用管它，让Hibernate内部来追踪对象的识别。 但是我们并不推荐这样做。

实际上，一些功能只对那些声明了标识符属性的类起作用：

我们建议你对持久化类声明命名一致的标识属性。我们还建议你使用一 个可以为空（也就是说，不是原始类型）的类型。

代理（proxies）是Hibernate的一个重要的功能，它依赖的条件是，持久 化类或者是非final的，或者是实现了一个所有方法都声明为public的接口。

你可以用Hibernate持久化一个没有实现任何接口的final类，但是你 不能使用代理来延迟关联加载，这会限制你进行性能优化的选择。

你也应该避免在非final类中声明 public final的方法。如果你想使用一 个有public final方法的类，你必须通过设置lazy="false" 来明确地禁用代理。

Cat为它的所有持久化字段声明了访问方法。很多其他ORM工具直接对 实例变量进行持久化。我们相信，在关系数据库schema和类的内部数据结构之间引入间接层(原文为"非直接"，indirection)会好一些。默认情况下Hibernate持久化JavaBeans风格的属性，认可 getFoo，isFoo 和 setFoo这种形式的方法名。 如果需要，你可以对某些特定属性实行直接字段访问。

属性不需要要声明为public的。Hibernate可以持久化一个有 default、protected或private的get/set方法对 的属性进行持久化。

所有的XML映射都需要定义如上所示的doctype。DTD可以从上述URL中获取， 也可以从hibernate-x.x.x/src/net/sf/hibernate目录中、 或hibernate.jar文件中找到。Hibernate总是会首先在它的classptah中搜索DTD文件。 如果你发现它是通过连接Internet查找DTD文件，就对照你的classpath目录检查XML文件里的DTD声明。

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd" [
    <!ENTITY types SYSTEM "classpath://your/domain/types.xml">
]>

<hibernate-mapping package="your.domain">
    <class name="MyEntity">
        <id name="id" type="my-custom-id-type">
            ...
        </id>
    <class>
    &types;
</hibernate-mapping>

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

<hibernate-mapping
         schema="schemaName"                          (1)
         catalog="catalogName"                        (2)
         default-cascade="cascade_style"              (3)
         default-access="field|property|ClassName"    (4)
         default-lazy="true|false"                    (5)
         auto-import="true|false"                     (6)
         package="package.name"                       (7)
 />

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

注意hibernate-mapping 元素允许你嵌套多个如上所示的 <class>映射。但是最好的做法（也许一些工具需要的）是一个 持久化类（或一个类的继承层次）对应一个映射文件，并以持久化的超类名称命名，例如： Cat.hbm.xml， Dog.hbm.xml，或者如果使用继承，Animal.hbm.xml。

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

<class
        name="ClassName"                              (1)
        table="tableName"                             (2)
        discriminator-value="discriminator_value"     (3)
        mutable="true|false"                          (4)
        schema="owner"                                (5)
        catalog="catalog"                             (6)
        proxy="ProxyInterface"                        (7)
        dynamic-update="true|false"                   (8)
        dynamic-insert="true|false"                   (9)
        select-before-update="true|false"             (10)
        polymorphism="implicit|explicit"              (11)
        where="arbitrary sql where condition"         (12)
        persister="PersisterClass"                    (13)
        batch-size="N"                                (14)
        optimistic-lock="none|version|dirty|all"      (15)
        lazy="true|false"                             (16)
        entity-name="EntityName"                      (17)
        check="arbitrary sql check condition"         (18)
        rowid="rowid"                                 (19)
        subselect="SQL expression"                    (20)
        abstract="true|false"                         (21)
        node="element-name"
/>

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

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

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

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

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

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

使用select-before-update通常会降低性能。如果你重新连接一个脱管（detache）对象实例 到一个Session中时，它可以防止数据库不必要的触发update。 这就很有用了。

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

我们非常强烈建议你在Hibernate中使用version/timestamp字段来进行乐观锁定。 对性能来说，这是最好的选择，并且这也是唯一能够处理在session外进行操作的策略（例如： 在使用Session.merge()的时候）。

对Hibernate映射来说视图和表是没有区别的，这是因为它们在数据层都是透明的（ 注意：一些数据库不支持视图属性，特别是更新的时候）。有时你想使用视图，但却不能在数据库 中创建它（例如：在遗留的schema中）。这样的话，你可以映射一个不可变的（immutable）并且是 只读的实体到一个给定的SQL子查询表达式：

<class name="Summary">
    <subselect>
        select item.name, max(bid.amount), count(*)
        from item
        join bid on bid.item_id = item.id
        group by item.name
    </subselect>
    <synchronize table="item"/>
    <synchronize table="bid"/>
    <id name="name"/>
    ...
</class>

定义这个实体用到的表为同步（synchronize），确保自动刷新（auto-flush）正确执行， 并且依赖原实体的查询不会返回过期数据。<subselect>在属性元素 和一个嵌套映射元素中都可见。

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

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

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

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

unsaved-value 属性在Hibernate3中几乎不再需要。

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

<id name="id" type="long" column="cat_id">
        <generator class="org.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="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>

<id name="id" type="long" column="person_id">
        <generator class="select">
                <param name="key">socialSecurityNumber</param>
        </generator>
</id>

Starting with release 3.2.3, there are 2 new generators which represent a re-thinking of 2 different aspects of identifier generation. The first aspect is database portability; the second is optimization (not having to query the database for every request for a new identifier value). These two new generators are intended to take the place of some of the named generators described above (starting in 3.3.x); however, they are included in the current releases and can be referenced by FQN.

The first of these new generators is org.hibernate.id.enhanced.SequenceStyleGenerator which is intended firstly as a replacement for the sequence generator and secondly as a better portability generator than native (because native (generally) chooses between identity and sequence which have largely different semantics which can cause subtle isssues in applications eyeing portability). org.hibernate.id.enhanced.SequenceStyleGenerator however achieves portability in a different manner. It chooses between using a table or a sequence in the database to store its incrementing values depending on the capabilities of the dialect being used. The difference between this and native is that table-based and sequence-based storage have the same exact semantic (in fact sequences are exactly what Hibernate tries to emmulate with its table-based generators). This generator has a number of configuration parameters:

The second of these new generators is org.hibernate.id.enhanced.TableGenerator which is intended firstly as a replacement for the table generator (although it actually functions much more like org.hibernate.id.MultipleHiLoPerTableGenerator) and secondly as a re-implementation of org.hibernate.id.MultipleHiLoPerTableGenerator utilizing the notion of pluggable optimiziers. Essentially this generator defines a table capable of holding a number of different increment values simultaneously by using multiple distinctly keyed rows. This generator has a number of configuration parameters:

For identifier generators which 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'd ideally want to 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.5 节 “Enhanced identifier generators” support this notion.

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

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

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

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

不幸的是，这种组合关键字的方法意味着一个持久化类是它自己的标识。除了对象自己之外， 没有什么方便的“把手”可用。你必须初始化持久化类的实例，填充它的标识符属性，再load() 组合关键字关联的持久状态。我们把这种方法称为embedded（嵌入式）的组合标识符，在重要的应用中不鼓励使用这种用法。

第二种方法我们称为mapped(映射式)组合标识符 (mapped composite identifier),<composite-id>元素中列出的标识属性不但在持久化类出现，还形成一个独立的标识符类。

<composite-id class="MedicareId" mapped="true">
        <key-property name="medicareNumber"/>
        <key-property name="dependent"/>
</composite-id>

在这个例子中，组合标识符类MedicareId和实体类都含有medicareNumber和dependent属性。标识符类必须重载equals()和hashCode()并且实现Serializable接口。这种方法的缺点是出现了明显的代码重复。

下面列出的属性是用来指定一个映射式组合标识符的：

在第 8.4 节 “组件作为联合标识符(Components as composite identifiers)”一节中,我们会描述第三种方式,那就是把组合标识符实现为一个组件(component)类,这是更方便的方法。下面的属性仅对第三种方法有效：

第三种方式，被称为identifier component(标识符组件)是我们对几乎所有应用都推荐使用的方式。

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

<discriminator
        column="discriminator_column"                      (1)
        type="discriminator_type"                          (2)
        force="true|false"                                 (3)
        insert="true|false"                                (4)
        formula="arbitrary sql expression"                 (5)
/>

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

force属性仅仅在这种情况下有用的：表中包含没有被映射到持久化类的附加辨别器值。 这种情况不会经常遇到。

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

<discriminator
    formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end"
    type="integer"/>

<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)
        generated="never|always"                                     (6)
        insert="true|false"                                          (7)
        node="element-name|@attribute-name|element/@attribute|."
/>

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

一个脱管（detached）实例的version或timestamp属性不能为空（null），因为Hibernate不管 unsaved-value被指定为何种策略，它将任何属性为空的version或timestamp 实例看作为瞬时（transient）实例。 避免Hibernate中的传递重附（transitive reattachment）问题的一个简单方法是 定义一个不能为空的version或timestamp属性，特别是在人们使用程序分配的标识符（assigned identifiers） 或复合主键时非常有用！

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

<timestamp
        column="timestamp_column"                                    (1)
        name="propertyName"                                          (2)
        access="field|property|ClassName"                            (3)
        unsaved-value="null|undefined"                               (4)
        source="vm|db"                                               (5)
        generated="never|always"                                     (6)
        node="element-name|@attribute-name|element/@attribute|."
/>

注意，<timestamp> 和<version type="timestamp">是等价的。并且<timestamp source="db">和<version type="dbtimestamp">是等价的。

<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)
        lazy="true|false"                                            (7)
        unique="true|false"                                          (8)
        not-null="true|false"                                        (9)
        optimistic-lock="true|false"                                 (10)
        generated="never|insert|always"                              (11)
        node="element-name|@attribute-name|element/@attribute|."
        index="index_name"
        unique_key="unique_key_id"
        length="L"
        precision="P"
        scale="S"
/>

typename可以是如下几种：

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

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

衍生属性（derive propertie）是一个特别强大的特征。这些属性应该定义为只读，属性值在装载时计算生成。 你用一个SQL表达式生成计算的结果，它会在这个实例转载时翻译成一个SQL查询的SELECT 子查询语句。

<property name="totalPrice"
    formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p
                WHERE li.productId = p.productId
                AND li.customerId = customerId
                AND li.orderNumber = orderNumber )"/>

注意，你可以使用实体自己的表，而不用为这个特别的列定义别名（ 上面例子中的customerId）。同时注意，如果你不喜欢使用属性， 你可以使用嵌套的<formula>映射元素。

通过many-to-one元素,可以定义一种常见的与另一个持久化类的关联。 这种关系模型是多对一关联（实际上是一个对象引用－译注）：这个表的一个外键引用目标表的 主键字段。

<many-to-one
        name="propertyName"                                          (1)
        column="column_name"                                         (2)
        class="ClassName"                                            (3)
        cascade="cascade_style"                                      (4)
        fetch="join|select"                                          (5)
        update="true|false"                                          (6)
        insert="true|false"                                          (6)
        property-ref="propertyNameFromAssociatedClass"               (7)
        access="field|property|ClassName"                            (8)
        unique="true|false"                                          (9)
        not-null="true|false"                                        (10)
        optimistic-lock="true|false"                                 (11)
        lazy="proxy|no-proxy|false"                                  (12)
        not-found="ignore|exception"                                 (13)
        entity-name="EntityName"                                     (14)
        formula="arbitrary SQL expression"                           (15)
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        index="index_name"
        unique_key="unique_key_id"
        foreign-key="foreign_key_name"
/>

cascade属性设置为除了none以外任何有意义的值， 它将把特定的操作传递到关联对象中。这个值就代表着Hibernate基本操作的名称， persist, merge, delete, save-update, evict, replicate, lock, refresh， 以及特别的值delete-orphan和all，并且可以用逗号分隔符 来组合这些操作，例如，cascade="persist,merge,evict"或 cascade="all,delete-orphan"。更全面的解释请参考第 10.11 节 “传播性持久化(transitive persistence)”. 注意，单值关联 (many-to-one 和 one-to-one 关联) 不支持删除孤儿（orphan delete，删除不再被引用的值）.

一个典型的简单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"/>

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

如果被引用的唯一主键由关联实体的多个属性组成，你应该在名称为<properties>的元素 里面映射所有关联的属性。

假若被引用的唯一主键是组件的属性，你可以指定属性路径：

<many-to-one name="owner" property-ref="identity.ssn" column="OWNER_SSN"/>

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

<one-to-one
        name="propertyName"                                          (1)
        class="ClassName"                                            (2)
        cascade="cascade_style"                                      (3)
        constrained="true|false"                                     (4)
        fetch="join|select"                                          (5)
        property-ref="propertyNameFromAssociatedClass"               (6)
        access="field|property|ClassName"                            (7)
        formula="any SQL expression"                                 (8)
        lazy="proxy|no-proxy|false"                                  (9)
        entity-name="EntityName"                                     (10)
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        foreign-key="foreign_key_name"
/>

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

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

比如说，对下面的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"/>

<natural-id mutable="true|false"/>
        <property ... />
        <many-to-one ... />
        ......
</natural-id>

我们建议使用代用键（键值不具备实际意义）作为主键，我们仍然应该尝试为所有的实体采用自然的键值作为（附加——译者注）标示。自然键（natural key）是单个或组合属性，他们必须唯一且非空。如果它还是不可变的那就更理想了。在<natural-id>元素中列出自然键的属性。Hibernate会帮你生成必须的唯一键值和非空约束，你的映射会更加的明显易懂（原文是self-documenting，自我注解）。

我们强烈建议你实现equals() 和hashCode()方法,来比较实体的自然键属性。

这一映射不是为了把自然键作为主键而准备的。

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

<component
        name="propertyName"                 (1)
        class="className"                   (2)
        insert="true|false"                 (3)
        update="true|false"                 (4)
        access="field|property|ClassName"   (5)
        lazy="true|false"                   (6)
        optimistic-lock="true|false"        (7)
        unique="true|false"                 (8)
        node="element-name|."
>

        <property ...../>
        <many-to-one .... />
        ........
</component>

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

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

<dynamic-component>元素允许把一个Map映射为组件，其属性名对应map的键值。 参见第 8.5 节 “动态组件 （Dynamic components）”.

<properties> 元素允许定义一个命名的逻辑分组(grouping)包含一个类中的多个属性。 这个元素最重要的用处是允许多个属性的组合作为property-ref的目标(target)。 这也是定义多字段唯一约束的一种方便途径。

<properties
        name="logicalName"                  (1)
        insert="true|false"                 (2)
        update="true|false"                 (3)
        optimistic-lock="true|false"        (4)
        unique="true|false"                 (5)
>

        <property ...../>
        <many-to-one .... />
        ........
</properties>

例如，如果我们有如下的<properties>映射:

<class name="Person">
    <id name="personNumber"/>
    ...
    <properties name="name"
            unique="true" update="false">
        <property name="firstName"/>
        <property name="initial"/>
        <property name="lastName"/>
    </properties>
</class>

然后，我们可能有一些遗留的数据关联，引用 Person表的这个唯一键，而不是主键。

<many-to-one name="person"
         class="Person" property-ref="name">
    <column name="firstName"/>
    <column name="initial"/>
    <column name="lastName"/>
</many-to-one>

我们并不推荐这样使用，除非在映射遗留数据的情况下。

最后，多态持久化需要为父类的每个子类都进行定义。对于“每一棵类继承树对应一个表”的策略来说，就需要使用<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"
        entity-name="EntityName"
        node="element-name"
        extends="SuperclassName">

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

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

For information about inheritance mappings, see 第 9 章 继承映射(Inheritance Mappings).

此外，每个子类可能被映射到他自己的表中(每个子类一个表的策略)。被继承的状态通过和超类的表关联得到。我们使用<joined-subclass>元素。

<joined-subclass
        name="ClassName"                    (1)
        table="tablename"                   (2)
        proxy="ProxyInterface"              (3)
        lazy="true|false"                   (4)
        dynamic-update="true|false"
        dynamic-insert="true|false"
        schema="schema"
        catalog="catalog"
        extends="SuperclassName"
        persister="ClassName"
        subselect="SQL expression"
        entity-name="EntityName"
        node="element-name">

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

For information about inheritance mappings, see 第 9 章 继承映射(Inheritance Mappings).

第三种选择是仅仅映射类继承树中具体类部分到表中(每个具体类一张表的策略)。其中，每张表定义了类的所有持久化状态，包括继承的状态。在 Hibernate 中，并不需要完全显式地映射这样的继承树。你可以简单地使用单独的<class>定义映射每个类。然而，如果你想使用多态关联(例如，一个对类继承树中超类的关联)，你需要使用<union-subclass>映射。

<union-subclass
        name="ClassName"                    (1)
        table="tablename"                   (2)
        proxy="ProxyInterface"              (3)
        lazy="true|false"                   (4)
        dynamic-update="true|false"
        dynamic-insert="true|false"
        schema="schema"
        catalog="catalog"
        extends="SuperclassName"
        abstract="true|false"
        persister="ClassName"
        subselect="SQL expression"
        entity-name="EntityName"
        node="element-name">

        <property .... />
        .....
</union-subclass>

这种映射策略不需要指定辨别标志(discriminator)字段。

For information about inheritance mappings, see 第 9 章 继承映射(Inheritance Mappings).

使用 <join> 元素，假若在表之间存在一对一关联,可以将一个类的属性映射到多张表中。

<join
        table="tablename"                        (1)
        schema="owner"                           (2)
        catalog="catalog"                        (3)
        fetch="join|select"                      (4)
        inverse="true|false"                     (5)
        optional="true|false">                   (6)

        <key ... />

        <property ... />
        ...
</join>

例如，一个人(person)的地址(address)信息可以被映射到单独的表中(并保留所有属性的值类型语义)：

<class name="Person"
    table="PERSON">

    <id name="id" column="PERSON_ID">...</id>

    <join table="ADDRESS">
        <key column="ADDRESS_ID"/>
        <property name="address"/>
        <property name="zip"/>
        <property name="country"/>
    </join>
    ...

此特性常常对遗留数据模型有用，我们推荐表个数比类个数少，以及细粒度的领域模型。然而，在单独的继承树上切换继承映射策略是有用的，后面会解释这点。

我们目前已经见到过<key>元素多次了。 这个元素在父映射元素定义了对新表的连接，并且在被连接表中定义了一个外键引用原表的主键的情况下经常使用。

<key
        column="columnname"                      (1)
        on-delete="noaction|cascade"             (2)
        property-ref="propertyName"              (3)
        not-null="true|false"                    (4)
        update="true|false"                      (5)
        unique="true|false"                      (6)
/>

对那些看重删除性能的系统，我们推荐所有的键都应该定义为on-delete="cascade"，这样 Hibernate 将使用数据库级的ON CASCADE DELETE约束，而不是多个DELETE语句。 注意，这个特性会绕过 Hibernate 通常对版本数据(versioned data)采用的乐观锁策略。

not-null 和 update 属性在映射单向一对多关联的时候有用。如果你映射一个单向一对多关联到非空的(non-nullable)外键，你必须 用<key not-null="true">定义此键字段。

任何接受column属性的映射元素都可以选择接受<column> 子元素。同样的，formula子元素也可以替换<formula>属性。

<column
        name="column_name"
        length="N"
        precision="N"
        scale="N"
        not-null="true|false"
        unique="true|false"
        unique-key="multicolumn_unique_key_name"
        index="index_name"
        sql-type="sql_type_name"
        check="SQL expression"
        default="SQL expression"/>

<formula>SQL expression</formula>

column 和 formula 属性甚至可以在同一个属性或关联映射中被合并来表达，例如，一些奇异的连接条件。

<many-to-one name="homeAddress" class="Address"
        insert="false" update="false">
    <column name="person_id" not-null="true" length="10"/>
    <formula>'MAILING'</formula>
</many-to-one>

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

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

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

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

meta-type 属性使得应用程序能指定一个将数据库字段的值映射到持久化类的自定义类型。这个持久化类包含有用id-type指定的标识符属性。 你必须指定从meta-type的值到类名的映射。

<any name="being" 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="cascade_style"                  (4)
        access="field|property|ClassName"        (5)
        optimistic-lock="true|false"             (6)
>
        <meta-value ... />
        <meta-value ... />
        .....
        <column .... />
        <column .... />
        .....
</any>

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

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

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

直到现在，我们都一直使用术语“持久类”(persistent class)来代表实体。我们仍然会这么做。 然而严格说来，不是所有的用户自定义的，带有持久化状态的类都是实体。组件就是用户自定义类，却是值语义的。java.lang.String类型的java属性也是值语义的。给了这个定义以后，我们可以说所有JDK提供的类型(类)都是值类型的语义，而用于自定义类型可能被映射为实体类型或值类型语义。采用哪种类型的语义取决于开发人员。在领域模型中，寻找实体类的一个好线索是共享引用指向这个类的单一实例，而组合或聚合通常被转化为值类型。

我们会在本文档中重复碰到这两个概念。

挑战在于将java类型系统(和开发者定义的实体和值类型)映射到 SQL/数据库类型系统。Hibernate提供了连接两个系统之间的桥梁：对于实体类型，我们使用<class>, <subclass> 等等。对于值类型，我们使用 <property>, <component> 及其他，通常跟随着type属性。这个属性的值是Hibernate 的映射类型的名字。Hibernate提供了许多现成的映射(标准的JDK值类型)。你也可以编写自己的映射类型并实现自定义的变换策略，随后我们会看到这点。

所有的Hibernate内建类型，除了collections以外，都支持空(null)语义。

The built-in basic mapping types may be roughly categorized into

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

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

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

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

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

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

CompositeUserType, EnhancedUserType, UserCollectionType, 和 UserVersionType 接口为更特殊的使用方式提供支持。

你甚至可以在一个映射文件中提供参数给一个UserType。 为了这样做，你的UserType必须实现org.hibernate.usertype.ParameterizedType接口。为了给自定义类型提供参数，你可以在映射文件中使用<type>元素。

<property name="priority">
    <type name="com.mycompany.usertypes.DefaultValueIntegerType">
        <param name="default">0</param>
    </type>
</property>

现在，UserType 可以从传入的Properties对象中得到default 参数的值。

如果你非常频繁地使用某一UserType，可以为他定义一个简称。这可以通过使用 <typedef>元素来实现。Typedefs为一自定义类型赋予一个名称，并且如果此类型是参数化的，还可以包含一系列默认的参数值。

<typedef class="com.mycompany.usertypes.DefaultValueIntegerType" name="default_zero">
    <param name="default">0</param>
</typedef>

<property name="priority" type="default_zero"/>

也可以根据具体案例通过属性映射中的类型参数覆盖在typedef中提供的参数。

尽管 Hibernate 内建的丰富的类型和对组件的支持意味着你可能很少 需要使用自定义类型。不过，为那些在你的应用中经常出现的(非实体)类使用自定义类型也是一个好方法。例如，一个MonetaryAmount类使用CompositeUserType来映射是不错的选择，虽然他可以很容易地被映射成组件。这样做的动机之一是抽象。使用自定义类型，以后假若你改变表示金额的方法时，它可以保证映射文件不需要修改。

很多Hibernate使用者更喜欢使用XDoclet@hibernate.tags将映射信息直接嵌入到源代码中。我们不会在本文档中涉及这个方法，因为严格说来，这属于XDoclet的一部分。然而，我们包含了如下使用XDoclet映射的Cat类的例子。

package eg;
import java.util.Set;
import java.util.Date;

/**
 * @hibernate.class
 *  table="CATS"
 */
public class Cat {
    private Long id; // identifier
    private Date birthdate;
    private Cat mother;
    private Set kittens
    private Color color;
    private char sex;
    private float weight;

    /*
     * @hibernate.id
     *  generator-class="native"
     *  column="CAT_ID"
     */
    public Long getId() {
        return id;
    }
    private void setId(Long id) {
        this.id=id;
    }

    /**
     * @hibernate.many-to-one
     *  column="PARENT_ID"
     */
    public Cat getMother() {
        return mother;
    }
    void setMother(Cat mother) {
        this.mother = mother;
    }

    /**
     * @hibernate.property
     *  column="BIRTH_DATE"
     */
    public Date getBirthdate() {
        return birthdate;
    }
    void setBirthdate(Date date) {
        birthdate = date;
    }
    /**
     * @hibernate.property
     *  column="WEIGHT"
     */
    public float getWeight() {
        return weight;
    }
    void setWeight(float weight) {
        this.weight = weight;
    }

    /**
     * @hibernate.property
     *  column="COLOR"
     *  not-null="true"
     */
    public Color getColor() {
        return color;
    }
    void setColor(Color color) {
        this.color = color;
    }
    /**
     * @hibernate.set
     *  inverse="true"
     *  order-by="BIRTH_DATE"
     * @hibernate.collection-key
     *  column="PARENT_ID"
     * @hibernate.collection-one-to-many
     */
    public Set getKittens() {
        return kittens;
    }
    void setKittens(Set kittens) {
        this.kittens = kittens;
    }
    // addKitten not needed by Hibernate
    public void addKitten(Cat kitten) {
        kittens.add(kitten);
    }

    /**
     * @hibernate.property
     *  column="SEX"
     *  not-null="true"
     *  update="false"
     */
    public char getSex() {
        return sex;
    }
    void setSex(char sex) {
        this.sex=sex;
    }
}

参考Hibernate网站更多的Xdoclet和Hibernate的例子

JDK 5.0 在语言级别引入了 XDoclet 风格的标注，并且是类型安全的，在编译期进行检查。这一机制比XDoclet的注解更为强大，有更好的工具和IDE支持。例如， IntelliJ IDEA，支持JDK 5.0注解的自动完成和语法高亮 。EJB规范的新修订版(JSR-220)使用 JDK 5.0的注解作为entity beans的主要元数据(metadata)机制。Hibernate 3 实现了JSR-220 (the persistence API)的EntityManager，支持通过Hibernate Annotations包定义映射元数据。这个包作为单独的部分下载，支持EJB3 (JSR-220)和Hibernate3的元数据。

这是一个被注解为EJB entity bean 的POJO类的例子

@Entity(access = AccessType.FIELD)
public class Customer implements Serializable {

    @Id;
    Long id;

    String firstName;
    String lastName;
    Date birthday;

    @Transient
    Integer age;

    @Embedded
    private Address homeAddress;

    @OneToMany(cascade=CascadeType.ALL)
    @JoinColumn(name="CUSTOMER_ID")
    Set<Order> orders;

    // Getter/setter and business methods
}

注意：对 JDK 5.0 注解 (和 JSR-220)支持的工作仍然在进行中,并未完成。更多细节请参阅Hibernate Annotations 模块。

集合实例在数据库中依靠持有集合的实体的外键加以辨别。此外键作为集合关键字段（collection key column）（或多个字段）加以引用。集合关键字段通过<key> 元素映射。

在外键字段上可能具有非空约束。对于大多数集合来说，这是隐含的。对单向一对多关联来说，外键字段默认是可以为空的，因此你可能需要指明 not-null="true"。

<key column="productSerialNumber" not-null="true"/>

外键约束可以使用ON DELETE CASCADE。

<key column="productSerialNumber" on-delete="cascade"/>

对<key> 元素的完整定义，请参阅前面的章节。

集合几乎可以包含任何其他的Hibernate类型，包括所有的基本类型、自定义类型、组件，当然还有对其他实体的引用。存在一个重要的区别：位于集合中的对象可能是根据“值”语义来操作（其声明周期完全依赖于集合持有者），或者它可能是指向另一个实体的引用，具有其自己的生命周期。在后者的情况下，被作为集合持有的状态考虑的，只有两个对象之间的“连接”。

被包容的类型被称为集合元素类型（collection element type）。集合元素通过<element>或<composite-element>映射，或在其是实体引用的时候，通过<one-to-many> 或<many-to-many>映射。前两种用于使用值语义映射元素，后两种用于映射实体关联。

所有的集合映射，除了set和bag语义的以外，都需要指定一个集合表的索引字段(index column)——用于对应到数组索引，或者List的索引，或者Map的关键字。通过<map-key>,Map 的索引可以是任何基础类型；若通过<map-key-many-to-many>，它也可以是一个实体引用；若通过<composite-map-key>，它还可以是一个组合类型。数组或列表的索引必须是integer类型，并且使用 <list-index>元素定义映射。被映射的字段包含有顺序排列的整数（默认从0开始）。

<list-index 
        column="column_name"                (1)
        base="0|1|..."/>

<map-key 
        column="column_name"                (1)
        formula="any SQL expression"        (2)
        type="type_name"                    (3)
        node="@attribute-name"
        length="N"/>

<map-key-many-to-many
        column="column_name"                (1)
        formula="any SQL expression"        (2)(3)
        class="ClassName"
/>

值集合于多对多关联(Collections of values and many-to-many associations)

column(可选):保存集合元素值的字段名。

formula (可选): 用于计算元素的SQL公式

<element
        column="column_name"                     (1)
        formula="any SQL expression"             (2)
        type="typename"                          (3)
        length="L"
        precision="P"
        scale="S"
        not-null="true|false"
        unique="true|false"
        node="element-name"
/>

A many-to-many association is specified using the <many-to-many> element.

<many-to-many
        column="column_name"                               (1)
        formula="any SQL expression"                       (2)
        class="ClassName"                                  (3)
        fetch="select|join"                                (4)
        unique="true|false"                                (5)
        not-found="ignore|exception"                       (6)
        entity-name="EntityName"                           (7)
        property-ref="propertyNameFromAssociatedClass"     (8)
        node="element-name"
        embed-xml="true|false"
    />

包含一组整数的bag(还设置了order-by参数指定了迭代的顺序)：

<set name="names" table="person_names">
    <key column="person_id"/>
    <element column="person_name" type="string"/>
</set>

一个实体数组,在这个案例中是一个多对多的关联(注意这里的实体是自动管理生命周期的对象（life cycle objects）,cascade="all"):

<bag name="sizes" 
        table="item_sizes" 
        order-by="size asc">
    <key column="item_id"/>
    <element column="size" type="integer"/>
</bag>

一个map,通过字符串的索引来指明日期：

<array name="addresses" 
        table="PersonAddress" 
        cascade="persist">
    <key column="personId"/>
    <list-index column="sortOrder"/>
    <many-to-many column="addressId" class="Address"/>
</array>

一个组件的列表：（下一章讨论）

<map name="holidays" 
        table="holidays" 
        schema="dbo" 
        order-by="hol_name asc">
    <key column="id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date" type="date"/>
</map>

一对多关联（One-to-many Associations）

<list name="carComponents" 
        table="CarComponents">
    <key column="carId"/>
    <list-index column="sortOrder"/>
    <composite-element class="CarComponent">
        <property name="price"/>
        <property name="type"/>
        <property name="serialNumber" column="serialNum"/>
    </composite-element>
</list>

一个被包含的实体的实例只能被包含在一个集合的实例中

class(必须):被关联类的名称。

<one-to-many 
        class="ClassName"                                  (1)
        not-found="ignore|exception"                       (2)
        entity-name="EntityName"                           (3)
        node="element-name"
        embed-xml="true|false"
    />

注意:<one-to-many>元素不需要定义任何字段。 也不需要指定表名。

重要提示:如果一对多关联中的外键字段定义成NOT NULL,你必须把<key>映射声明为not-null="true",或者使用双向关联，并且标明inverse="true"。参阅本章后面关于双向关联的讨论。

下面的例子展示一个Part实体的map,把name作为关键字。( partName 是Part的持久化属性)。注意其中的基于公式的索引的用法。

<map name="parts"
        cascade="all">
    <key column="productId" not-null="true"/>
    <map-key formula="partName"/>
    <one-to-many class="Part"/>
</map>

Hibernate支持实现java.util.SortedMap和java.util.SortedSet的集合。 你必须在映射文件中指定一个比较器：

<set name="aliases" 
            table="person_aliases" 
            sort="natural">
    <key column="person"/>
    <element column="name" type="string"/>
</set>

<map name="holidays" sort="my.custom.HolidayComparator">
    <key column="year_id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date" type="date"/>
</map>

sort属性中允许的值包括unsorted,natural和某个实现了java.util.Comparator的类的名称。

分类集合的行为事实上象java.util.TreeSet或者java.util.TreeMap。

如果你希望数据库自己对集合元素排序，可以利用set,bag或者map映射中的order-by属性。这个解决方案只能在jdk1.4或者更高的jdk版本中才可以实现(通过LinkedHashSet或者 LinkedHashMap实现)。 它是在SQL查询中完成排序，而不是在内存中。

<set name="aliases" table="person_aliases" order-by="lower(name) asc">
    <key column="person"/>
    <element column="name" type="string"/>
</set>

<map name="holidays" order-by="hol_date, hol_name">
    <key column="year_id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date type="date"/>
</map>

注意: 这个order-by属性的值是一个SQL排序子句而不是HQL的！

关联还可以在运行时使用集合filter()根据任意的条件来排序。

sortedUsers = s.createFilter( group.getUsers(), "order by this.name" ).list();

A bidirectional association allows navigation from both "ends" of the association. Two kinds of bidirectional association are supported:

要建立一个双向的多对多关联，只需要映射两个many-to-many关联到同一个数据库表中，并再定义其中的一端为inverse(使用哪一端要根据你的选择，但它不能是一个索引集合)。

这里有一个many-to-many的双向关联的例子;每一个category都可以有很多items,每一个items可以属于很多categories：

<class name="Category">
    <id name="id" column="CATEGORY_ID"/>
    ...
    <bag name="items" table="CATEGORY_ITEM">
        <key column="CATEGORY_ID"/>
        <many-to-many class="Item" column="ITEM_ID"/>
    </bag>
</class>

<class name="Item">
    <id name="id" column="ITEM_ID"/>
    ...

    <!-- inverse end -->
    <bag name="categories" table="CATEGORY_ITEM" inverse="true">
        <key column="ITEM_ID"/>
        <many-to-many class="Category" column="CATEGORY_ID"/>
    </bag>
</class>

如果只对关联的反向端进行了改变，这个改变不会被持久化。 这表示Hibernate为每个双向关联在内存中存在两次表现,一个从A连接到B,另一个从B连接到A。如果你回想一下Java对象模型，我们是如何在Java中创建多对多关系的，这可以让你更容易理解：

category.getItems().add(item);          // The category now "knows" about the relationship
item.getCategories().add(category);     // The item now "knows" about the relationship

session.persist(item);                   // The relationship won't be saved!
session.persist(category);               // The relationship will be saved

非反向端用于把内存中的表示保存到数据库中。

要建立一个一对多的双向关联，你可以通过把一个一对多关联，作为一个多对一关联映射到到同一张表的字段上，并且在"多"的那一端定义inverse="true"。

<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <set name="children" inverse="true">
        <key column="parent_id"/>
        <one-to-many class="Child"/>
    </set>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        not-null="true"/>
</class>

在“一”这一端定义inverse="true"不会影响级联操作，二者是正交的概念！

对于有一端是<list>或者<map>的双向关联，需要加以特别考虑。假若子类中的一个属性映射到索引字段，没问题，我们仍然可以在集合类映射上使用inverse="true"：

<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <map name="children" inverse="true">
        <key column="parent_id"/>
        <map-key column="name" 
            type="string"/>
        <one-to-many class="Child"/>
    </map>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <property name="name" 
        not-null="true"/>
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        not-null="true"/>
</class>

但是，假若子类中没有这样的属性存在，我们不能认为这个关联是真正的双向关联（信息不对称，在关联的一端有一些另外一端没有的信息）。在这种情况下，我们不能使用inverse="true"。我们需要这样用：

<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <map name="children">
        <key column="parent_id"
            not-null="true"/>
        <map-key column="name" 
            type="string"/>
        <one-to-many class="Child"/>
    </map>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        insert="false"
        update="false"
        not-null="true"/>
</class>

注意在这个映射中，关联中集合类"值"一端负责来更新外键.TODO: Does this really result in some unnecessary update statements?

有三种可能的途径来映射一个三重关联。第一种是使用一个Map，把一个关联作为其索引：

<map name="contracts">
    <key column="employer_id" not-null="true"/>
    <map-key-many-to-many column="employee_id" class="Employee"/>
    <one-to-many class="Contract"/>
</map>

<map name="connections">
    <key column="incoming_node_id"/>
    <map-key-many-to-many column="outgoing_node_id" class="Node"/>
    <many-to-many column="connection_id" class="Connection"/>
</map>

第二种方法是简单的把关联重新建模为一个实体类。这使我们最经常使用的方法。

最后一种选择是使用复合元素，我们会在后面讨论

如果你完全信奉我们对于“联合主键（composite keys）是个坏东西”，和“实体应该使用（无机的）自己生成的代用标识符（surrogate keys）”的观点，也许你会感到有一些奇怪，我们目前为止展示的多对多关联和值集合都是映射成为带有联合主键的表的！现在，这一点非常值得争辩；看上去一个单纯的关联表并不能从代用标识符中获得什么好处（虽然使用组合值的集合可能会获得一点好处）。不过，Hibernate提供了一个（一点点试验性质的）功能，让你把多对多关联和值集合应得到一个使用代用标识符的表去。

<idbag> 属性让你使用bag语义来映射一个List (或Collection)。

<idbag name="lovers" table="LOVERS">
    <collection-id column="ID" type="long">
        <generator class="sequence"/>
    </collection-id>
    <key column="PERSON1"/>
    <many-to-many column="PERSON2" class="Person" fetch="join"/>
</idbag>

你可以理解，<idbag>人工的id生成器，就好像是实体类一样！集合的每一行都有一个不同的人造关键字。但是，Hibernate没有提供任何机制来让你取得某个特定行的人造关键字。

注意<idbag>的更新性能要比普通的<bag>高得多！Hibernate可以有效的定位到不同的行，分别进行更新或删除工作，就如同处理一个list, map或者set一样。

在目前的实现中，还不支持使用identity标识符生成器策略来生成<idbag>集合的标识符。

单向many-to-one关联是最常见的单向关联关系。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>

create table Person ( personId bigint not null primary key, addressId bigint not null )
create table Address ( addressId bigint not null primary key )
        

基于外键关联的单向一对一关联和单向多对一关联几乎是一样的。唯一的不同就是单向一对一关联中的外键字段具有唯一性约束。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId" 
        unique="true"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>

create table Person ( personId bigint not null primary key, addressId bigint not null unique )
create table Address ( addressId bigint not null primary key )
        

基于主键关联的单向一对一关联通常使用一个特定的id生成器。（请注意，在这个例子中我们掉换了关联的方向。）

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
</class>

<class name="Address">
    <id name="id" column="personId">
        <generator class="foreign">
            <param name="property">person</param>
        </generator>
    </id>
    <one-to-one name="person" constrained="true"/>
</class>

create table Person ( personId bigint not null primary key )
create table Address ( personId bigint not null primary key )
        

基于外键关联的单向一对多关联是一种很少见的情况，并不推荐使用。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses">
        <key column="personId" 
            not-null="true"/>
        <one-to-many class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>

create table Person ( personId bigint not null primary key )
create table Address ( addressId bigint not null primary key, personId bigint not null )
        

我们认为对于这种关联关系最好使用连接表。

基于连接表的单向一对多关联 应该优先被采用。请注意，通过指定unique="true"，我们可以把多样性从多对多改变为一对多。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses" table="PersonAddress">
        <key column="personId"/>
        <many-to-many column="addressId"
            unique="true"
            class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>

create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId not null, addressId bigint not null primary key )
create table Address ( addressId bigint not null primary key )
        

基于连接表的单向多对一关联在关联关系可选的情况下应用也很普遍。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        optional="true">
        <key column="personId" unique="true"/>
        <many-to-one name="address"
            column="addressId" 
            not-null="true"/>
    </join>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>

create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null primary key, addressId bigint not null )
create table Address ( addressId bigint not null primary key )
        

基于连接表的单向一对一关联非常少见，但也是可行的。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        optional="true">
        <key column="personId" 
            unique="true"/>
        <many-to-one name="address"
            column="addressId" 
            not-null="true"
            unique="true"/>
    </join>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>

create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique )
create table Address ( addressId bigint not null primary key )
        

最后，还有 单向多对多关联.

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses" table="PersonAddress">
        <key column="personId"/>
        <many-to-many column="addressId"
            class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>

create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) )
create table Address ( addressId bigint not null primary key )
        

双向多对一关联 是最常见的关联关系。（这也是标准的父/子关联关系。）

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <set name="people" inverse="true">
        <key column="addressId"/>
        <one-to-many class="Person"/>
    </set>
</class>

create table Person ( personId bigint not null primary key, addressId bigint not null )
create table Address ( addressId bigint not null primary key )
        

如果你使用List(或者其他有序集合类)，你需要设置外键对应的key列为 not null,让Hibernate来从集合端管理关联，维护每个元素的索引（通过设置update="false" and insert="false"来对另一端反向操作）。

<class name="Person">
   <id name="id"/>
   ...
   <many-to-one name="address"
      column="addressId"
      not-null="true"
      insert="false"
      update="false"/>
</class>

<class name="Address">
   <id name="id"/>
   ...
   <list name="people">
      <key column="addressId" not-null="true"/>
      <list-index column="peopleIdx"/>
      <one-to-many class="Person"/>
   </list>
</class>

假若集合映射的<key>元素对应的底层外键字段是NOT NULL的，那么为这一key元素定义not-null="true"是很重要的。不要仅仅为可能的嵌套<column>元素定义not-null="true"，<key>元素也是需要的。

基于外键关联的双向一对一关联也很常见。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId" 
        unique="true"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
   <one-to-one name="person" 
        property-ref="address"/>
</class>

create table Person ( personId bigint not null primary key, addressId bigint not null unique )
create table Address ( addressId bigint not null primary key )
        

基于主键关联的一对一关联需要使用特定的id生成器。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <one-to-one name="address"/>
</class>

<class name="Address">
    <id name="id" column="personId">
        <generator class="foreign">
            <param name="property">person</param>
        </generator>
    </id>
    <one-to-one name="person" 
        constrained="true"/>
</class>

create table Person ( personId bigint not null primary key )
create table Address ( personId bigint not null primary key )
        

基于连接表的双向一对多关联。注意inverse="true"可以出现在关联的任意一端，即collection端或者join端。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses" 
        table="PersonAddress">
        <key column="personId"/>
        <many-to-many column="addressId"
            unique="true"
            class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        inverse="true" 
        optional="true">
        <key column="addressId"/>
        <many-to-one name="person"
            column="personId"
            not-null="true"/>
    </join>
</class>

create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null, addressId bigint not null primary key )
create table Address ( addressId bigint not null primary key )
        

基于连接表的双向一对一关联极为罕见，但也是可行的。

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        optional="true">
        <key column="personId" 
            unique="true"/>
        <many-to-one name="address"
            column="addressId" 
            not-null="true"
            unique="true"/>
    </join>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        optional="true"
        inverse="true">
        <key column="addressId" 
            unique="true"/>
        <many-to-one name="person"
            column="personId" 
            not-null="true"
            unique="true"/>
    </join>
</class>

create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique )
create table Address ( addressId bigint not null primary key )
        

最后，还有 双向多对多关联.

<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses" table="PersonAddress">
        <key column="personId"/>
        <many-to-many column="addressId"
            class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <set name="people" inverse="true" table="PersonAddress">
        <key column="addressId"/>
        <many-to-many column="personId"
            class="Person"/>
    </set>
</class>

create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) )
create table Address ( addressId bigint not null primary key )
        

假设我们有接口Payment和它的几个实现类： CreditCardPayment, CashPayment, 和ChequePayment。则“每个类分层结构一张表”(Table per class hierarchy)的映射代码如下所示：

<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="PAYMENT_TYPE" type="string"/>
    <property name="amount" column="AMOUNT"/>
    ...
    <subclass name="CreditCardPayment" discriminator-value="CREDIT">
        <property name="creditCardType" column="CCTYPE"/>
        ...
    </subclass>
    <subclass name="CashPayment" discriminator-value="CASH">
        ...
    </subclass>
    <subclass name="ChequePayment" discriminator-value="CHEQUE">
        ...
    </subclass>
</class>

采用这种策略只需要一张表即可。它有一个很大的限制：要求那些由子类定义的字段， 如CCTYPE，不能有非空(NOT NULL)约束。

对于上例中的几个类而言，采用“每个子类一张表”的映射策略，代码如下所示：

<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="AMOUNT"/>
    ...
    <joined-subclass name="CreditCardPayment" table="CREDIT_PAYMENT">
        <key column="PAYMENT_ID"/>
        <property name="creditCardType" column="CCTYPE"/>
        ...
    </joined-subclass>
    <joined-subclass name="CashPayment" table="CASH_PAYMENT">
        <key column="PAYMENT_ID"/>
        ...
    </joined-subclass>
    <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT">
        <key column="PAYMENT_ID"/>
        ...
    </joined-subclass>
</class>

需要四张表。三个子类表通过主键关联到超类表(因而关系模型实际上是一对一关联)。

注意，对“每个子类一张表”的映射策略，Hibernate的实现不需要辨别字段，而其他 的对象/关系映射工具使用了一种不同于Hibernate的实现方法，该方法要求在超类 表中有一个类型辨别字段(type discriminator column)。Hibernate采用的方法更 难实现，但从关系（数据库）的角度来看，按理说它更正确。若你愿意使用带有辨别字 段的“每个子类一张表”的策略，你可以结合使用<subclass> 与<join>，如下所示：

<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="PAYMENT_TYPE" type="string"/>
    <property name="amount" column="AMOUNT"/>
    ...
    <subclass name="CreditCardPayment" discriminator-value="CREDIT">
        <join table="CREDIT_PAYMENT">
            <key column="PAYMENT_ID"/>
            <property name="creditCardType" column="CCTYPE"/>
            ...
        </join>
    </subclass>
    <subclass name="CashPayment" discriminator-value="CASH">
        <join table="CASH_PAYMENT">
            <key column="PAYMENT_ID"/>
            ...
        </join>
    </subclass>
    <subclass name="ChequePayment" discriminator-value="CHEQUE">
        <join table="CHEQUE_PAYMENT" fetch="select">
            <key column="PAYMENT_ID"/>
            ...
        </join>
    </subclass>
</class>

可选的声明fetch="select"，是用来告诉Hibernate，在查询超类时， 不要使用外部连接(outer join)来抓取子类ChequePayment的数据。

你甚至可以采取如下方法混和使用“每个类分层结构一张表”和“每个子类一张表”这两种策略：

<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="PAYMENT_TYPE" type="string"/>
    <property name="amount" column="AMOUNT"/>
    ...
    <subclass name="CreditCardPayment" discriminator-value="CREDIT">
        <join table="CREDIT_PAYMENT">
            <property name="creditCardType" column="CCTYPE"/>
            ...
        </join>
    </subclass>
    <subclass name="CashPayment" discriminator-value="CASH">
        ...
    </subclass>
    <subclass name="ChequePayment" discriminator-value="CHEQUE">
        ...
    </subclass>
</class>

对上述任何一种映射策略而言，指向根类Payment的 关联是使用<many-to-one>进行映射的。

<many-to-one name="payment" column="PAYMENT_ID" class="Payment"/>

对于“每个具体类一张表”的映射策略，可以采用两种方法。第一种方法是使用 <union-subclass>。

<class name="Payment">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="sequence"/>
    </id>
    <property name="amount" column="AMOUNT"/>
    ...
    <union-subclass name="CreditCardPayment" table="CREDIT_PAYMENT">
        <property name="creditCardType" column="CCTYPE"/>
        ...
    </union-subclass>
    <union-subclass name="CashPayment" table="CASH_PAYMENT">
        ...
    </union-subclass>
    <union-subclass name="ChequePayment" table="CHEQUE_PAYMENT">
        ...
    </union-subclass>
</class>

这里涉及三张与子类相关的表。每张表为对应类的所有属性（包括从超类继承的属性）定义相应字段。

这种方式的局限在于，如果一个属性在超类中做了映射，其字段名必须与所有子类 表中定义的相同。(我们可能会在Hibernate的后续发布版本中放宽此限制。) 不允许在联合子类(union subclass)的继承层次中使用标识生成器策略(identity generator strategy), 实际上, 主键的种子(primary key seed)不得不为同一继承层次中的全部被联合子类所共用.

假若超类是抽象类，请使用abstract="true"。当然，假若它不是抽象的，需要一个额外的表（上面的例子中，默认是PAYMENT），来保存超类的实例。

另一种可供选择的方法是采用隐式多态：

<class name="CreditCardPayment" table="CREDIT_PAYMENT">
    <id name="id" type="long" column="CREDIT_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="CREDIT_AMOUNT"/>
    ...
</class>

<class name="CashPayment" table="CASH_PAYMENT">
    <id name="id" type="long" column="CASH_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="CASH_AMOUNT"/>
    ...
</class>

<class name="ChequePayment" table="CHEQUE_PAYMENT">
    <id name="id" type="long" column="CHEQUE_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="CHEQUE_AMOUNT"/>
    ...
</class>

注意，我们没有在任何地方明确的提及接口Payment。同时注意 Payment的属性在每个子类中都进行了映射。如果你想避免重复， 可以考虑使用XML实体(例如：位于DOCTYPE声明内的 [ <!ENTITY allproperties SYSTEM "allproperties.xml"> ] 和映射中的&allproperties;)。

这种方法的缺陷在于，在Hibernate执行多态查询时(polymorphic queries)无法生成带 UNION的SQL语句。

对于这种映射策略而言，通常用<any>来实现到 Payment的多态关联映射。

<any name="payment" meta-type="string" id-type="long">
    <meta-value value="CREDIT" class="CreditCardPayment"/>
    <meta-value value="CASH" class="CashPayment"/>
    <meta-value value="CHEQUE" class="ChequePayment"/>
    <column name="PAYMENT_CLASS"/>
    <column name="PAYMENT_ID"/>
</any>

对这一映射还有一点需要注意。因为每个子类都在各自独立的元素<class> 中映射(并且Payment只是一个接口)，每个子类可以很容易的成为另一 个继承体系中的一部分！(你仍然可以对接口Payment使用多态查询。)

<class name="CreditCardPayment" table="CREDIT_PAYMENT">
    <id name="id" type="long" column="CREDIT_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="CREDIT_CARD" type="string"/>
    <property name="amount" column="CREDIT_AMOUNT"/>
    ...
    <subclass name="MasterCardPayment" discriminator-value="MDC"/>
    <subclass name="VisaPayment" discriminator-value="VISA"/>
</class>

<class name="NonelectronicTransaction" table="NONELECTRONIC_TXN">
    <id name="id" type="long" column="TXN_ID">
        <generator class="native"/>
    </id>
    ...
    <joined-subclass name="CashPayment" table="CASH_PAYMENT">
        <key column="PAYMENT_ID"/>
        <property name="amount" column="CASH_AMOUNT"/>
        ...
    </joined-subclass>
    <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT">
        <key column="PAYMENT_ID"/>
        <property name="amount" column="CHEQUE_AMOUNT"/>
        ...
    </joined-subclass>
</class>

我们还是没有明确的提到Payment。 如果我们针对接口Payment执行查询 ——如from Payment—— Hibernate 自动返回CreditCardPayment(和它的子类，因为 它们也实现了接口Payment)、 CashPayment和Chequepayment的实例， 但不返回NonelectronicTransaction的实例。

HQL和原生SQL(native SQL)查询要通过为org.hibernate.Query的实例来表达。 这个接口提供了参数绑定、结果集处理以及运行实际查询的方法。 你总是可以通过当前Session获取一个Query对象：

List cats = session.createQuery(
    "from Cat as cat where cat.birthdate < ?")
    .setDate(0, date)
    .list();

List mothers = session.createQuery(
    "select mother from Cat as cat join cat.mother as mother where cat.name = ?")
    .setString(0, name)
    .list();

List kittens = session.createQuery(
    "from Cat as cat where cat.mother = ?")
    .setEntity(0, pk)
    .list();

Cat mother = (Cat) session.createQuery(
    "select cat.mother from Cat as cat where cat = ?")
    .setEntity(0, izi)
    .uniqueResult();]]

Query mothersWithKittens = (Cat) session.createQuery(
    "select mother from Cat as mother left join fetch mother.kittens");
Set uniqueMothers = new HashSet(mothersWithKittens.list());

一个查询通常在调用list()时被执行，执行结果会完全装载进内存中的一个集合(collection)。 查询返回的对象处于持久(persistent)状态。如果你知道的查询只会返回一个对象，可使用list()的快捷方式uniqueResult()。 注意，使用集合预先抓取的查询往往会返回多次根对象（他们的集合类都被初始化了）。你可以通过一个集合来过滤这些重复对象。

// fetch ids
Iterator iter = sess.createQuery("from eg.Qux q order by q.likeliness").iterate();
while ( iter.hasNext() ) {
    Qux qux = (Qux) iter.next();  // fetch the object
    // something we couldnt express in the query
    if ( qux.calculateComplicatedAlgorithm() ) {
        // delete the current instance
        iter.remove();
        // dont need to process the rest
        break;
    }
}

Iterator kittensAndMothers = sess.createQuery(
            "select kitten, mother from Cat kitten join kitten.mother mother")
            .list()
            .iterator();

while ( kittensAndMothers.hasNext() ) {
    Object[] tuple = (Object[]) kittensAndMothers.next();
    Cat kitten = (Cat) tuple[0];
    Cat mother = (Cat) tuple[1];
    ....
}

Iterator results = sess.createQuery(
        "select cat.color, min(cat.birthdate), count(cat) from Cat cat " +
        "group by cat.color")
        .list()
        .iterator();

while ( results.hasNext() ) {
    Object[] row = (Object[]) results.next();
    Color type = (Color) row[0];
    Date oldest = (Date) row[1];
    Integer count = (Integer) row[2];
    .....
}

//named parameter (preferred)
Query q = sess.createQuery("from DomesticCat cat where cat.name = :name");
q.setString("name", "Fritz");
Iterator cats = q.iterate();

//positional parameter
Query q = sess.createQuery("from DomesticCat cat where cat.name = ?");
q.setString(0, "Izi");
Iterator cats = q.iterate();

//named parameter list
List names = new ArrayList();
names.add("Izi");
names.add("Fritz");
Query q = sess.createQuery("from DomesticCat cat where cat.name in (:namesList)");
q.setParameterList("namesList", names);
List cats = q.list();

Query q = sess.createQuery("from DomesticCat cat");
q.setFirstResult(20);
q.setMaxResults(10);
List cats = q.list();

Query q = sess.createQuery("select cat.name, cat from DomesticCat cat " +
                            "order by cat.name");
ScrollableResults cats = q.scroll();
if ( cats.first() ) {

    // find the first name on each page of an alphabetical list of cats by name
    firstNamesOfPages = new ArrayList();
    do {
        String name = cats.getString(0);
        firstNamesOfPages.add(name);
    }
    while ( cats.scroll(PAGE_SIZE) );

    // Now get the first page of cats
    pageOfCats = new ArrayList();
    cats.beforeFirst();
    int i=0;
    while( ( PAGE_SIZE > i++ ) && cats.next() ) pageOfCats.add( cats.get(1) );

}
cats.close()

<query name="ByNameAndMaximumWeight"><![CDATA[
    from eg.DomesticCat as cat
        where cat.name = ?
        and cat.weight > ?
] ]></query>

Query q = sess.getNamedQuery("ByNameAndMaximumWeight");
q.setString(0, name);
q.setInt(1, minWeight);
List cats = q.list();

集合过滤器(filter)是一种用于一个持久化集合或者数组的特殊的查询。查询字符串中可以使用"this"来引用集合中的当前元素。

Collection blackKittens = session.createFilter(
    pk.getKittens(), 
    "where this.color = ?")
    .setParameter( Color.BLACK, Hibernate.custom(ColorUserType.class) )
    .list()
);

返回的集合可以被认为是一个包(bag, 无顺序可重复的集合(collection))，它是所给集合的副本。 原来的集合不会被改动（这与“过滤器(filter)”的隐含的含义不符，不过与我们期待的行为一致）。

请注意过滤器(filter)并不需要from子句（当然需要的话它们也可以加上）。过滤器(filter)不限定于只能返回集合元素本身。

Collection blackKittenMates = session.createFilter(
    pk.getKittens(), 
    "select this.mate where this.color = eg.Color.BLACK.intValue")
    .list();

即使无条件的过滤器(filter)也是有意义的。例如，用于加载一个大集合的子集：

Collection tenKittens = session.createFilter(
    mother.getKittens(), "")
    .setFirstResult(0).setMaxResults(10)
    .list();

HQL极为强大，但是有些人希望能够动态的使用一种面向对象API创建查询，而非在他们的Java代码中嵌入字符串。对于那部分人来说，Hibernate提供了直观的Criteria查询API。

Criteria crit = session.createCriteria(Cat.class);
crit.add( Restrictions.eq( "color", eg.Color.BLACK ) );
crit.setMaxResults(10);
List cats = crit.list();

Criteria以及相关的样例(Example)API将会再第 15 章 条件查询(Criteria Queries)中详细讨论。

你可以使用createSQLQuery()方法，用SQL来描述查询，并由Hibernate将结果集转换成对象。 请注意，你可以在任何时候调用session.connection()来获得并使用JDBC Connection对象。 如果你选择使用Hibernate的API, 你必须把SQL别名用大括号包围起来:

List cats = session.createSQLQuery("SELECT {cat.*} FROM CAT {cat} WHERE ROWNUM<10")
    .addEntity("cat", Cat.class)
.list();

List cats = session.createSQLQuery(
    "SELECT {cat}.ID AS {cat.id}, {cat}.SEX AS {cat.sex}, " +
           "{cat}.MATE AS {cat.mate}, {cat}.SUBCLASS AS {cat.class}, ... " +
    "FROM CAT {cat} WHERE ROWNUM<10")
    .addEntity("cat", Cat.class)
.list()

和Hibernate查询一样，SQL查询也可以包含命名参数和占位参数。 可以在第 16 章 Native SQL查询找到更多关于Hibernate中原生SQL(native SQL)的信息。

首先，别用session-per-operation这种反模式了，也就是说，在单个线程中， 不要因为一次简单的数据库调用，就打开和关闭一次Session！数据库事务也是如此。 应用程序中的数据库调用是按照计划好的次序，分组为原子的操作单元。（注意，这也意味着，应用程 序中，在单个的SQL语句发送之后，自动事务提交(auto-commit)模式失效了。这种模式专门为SQL控制台操作设计的。 Hibernate禁止立即自动事务提交模式，或者期望应用服务器禁止立即自动事务提交模式。）数据库事务绝不是可有可无的，任何与数据库之间的通讯都必须在某个事务中进行，不管你是在读还是在写数据。对读数据而言，应该避免auto-commit行为，因为很多小的事务比一个清晰定义的工作单元性能差。后者也更容易维护和扩展。

The most common pattern in a multi-user client/server application is session-per-request. In this model, a request from the client is sent to the server (where the Hibernate persistence layer runs), a new Hibernate Session is opened, and all database operations are executed in this unit of work. Once the work has been completed (and the response for the client has been prepared), the session is flushed and closed. You would also use a single database transaction to serve the clients request, starting and committing it when you open and close the Session. The relationship between the two is one-to-one and this model is a perfect fit for many applications.

The challenge lies in the implementation. Hibernate provides built-in management of the "current session" to simplify this pattern. All you have to do is start a transaction when a server request has to be processed, and end the transaction before the response is sent to the client. You can do this in any way you like, common solutions are ServletFilter, AOP interceptor with a pointcut on the service methods, or a proxy/interception container. An EJB container is a standardized way to implement cross-cutting aspects such as transaction demarcation on EJB session beans, declaratively with CMT. If you decide to use programmatic transaction demarcation, prefer the Hibernate Transaction API shown later in this chapter, for ease of use and code portability.

在任何时间，任何地方，你的应用代码可以通过简单的调用sessionFactory.getCurrentSession()来访问"当前session"，用于处理请求。你总是会得到当前数据库事务范围内的Session。在使用本地资源或JTA环境时，必须配置它，请参见第 2.5 节 “上下文相关的（Contextual）Session”。

有时，将Session和数据库事务的边界延伸到"展示层被渲染后"会带来便利。有些serlvet应用程序在对请求进行处理后，有个单独的渲染期，这种延伸对这种程序特别有用。假若你实现你自己的拦截器，把事务边界延伸到展示层渲染结束后非常容易。然而，假若你依赖有容器管理事务的EJB，这就不太容易了，因为事务会在EJB方法返回后结束，而那是在任何展示层渲染开始之前。请访问Hibernate网站和论坛，你可以找到Open Session in View这一模式的提示和示例。

session-per-request模式不仅仅是一个可以用来设计操作单元的有用概念。很多业务处理都需 要一系列完整的与用户之间的交互，而这些用户是指对数据库有交叉访问的用户。在基于web的应用和企业 应用中，跨用户交互的数据库事务是无法接受的。考虑下面的例子：

从用户的角度来看，我们把这个操作单元称为长时间运行的对话（conversation）,或者(or 应用事务,application transaction)。 在你的应用程序中，可以有很多种方法来实现它。

头一个幼稚的做法是，在用户思考的过程中，保持Session和数据库事务是打开的， 保持数据库锁定，以阻止并发修改，从而保证数据库事务隔离级别和原子操作。这种方式当然是一个反模式， 因为锁争用会导致应用程序无法扩展并发用户的数目。

Clearly, we have to use several database transactions to implement the conversation. In this case, maintaining isolation of business processes becomes the partial responsibility of the application tier. A single conversation usually spans several database transactions. It will be atomic if only one of these database transactions (the last one) stores the updated data, all others simply read data (e.g. in a wizard-style dialog spanning several request/response cycles). This is easier to implement than it might sound, especially if you use Hibernate's features:

session-per-request-with-detached-objects 和 session-per-conversation 各有优缺点，我们在本章后面乐观并发 控制那部分再进行讨论。

应用程序可能在两个不同的Session中并发访问同一持久化状态，但是， 一个持久化类的实例无法在两个 Session中共享。因此有两种不同的标识语义：

Then for objects attached to a particular Session (i.e. in the scope of a Session) the two notions are equivalent, and JVM identity for database identity is guaranteed by Hibernate. However, while the application might concurrently access the "same" (persistent identity) business object in two different sessions, the two instances will actually be "different" (JVM identity). Conflicts are resolved using (automatic versioning) at flush/commit time, using an optimistic approach.

这种方式把关于并发的头疼问题留给了Hibernate和数据库；由于在单个线程内，操作单元中的对象识别不 需要代价昂贵的锁定或其他意义上的同步，因此它同时可以提供最好的可伸缩性。只要在单个线程只持有一个 Session，应用程序就不需要同步任何业务对象。在Session 的范围内，应用程序可以放心的使用==进行对象比较。

不过，应用程序在Session的外面使用==进行对象比较可能会 导致无法预期的结果。在一些无法预料的场合，例如，如果你把两个脱管对象实例放进同一个 Set的时候，就可能发生。这两个对象实例可能有同一个数据库标识（也就是说， 他们代表了表的同一行数据），从JVM标识的定义上来说，对脱管的对象而言，Hibernate无法保证他们 的的JVM标识一致。开发人员必须覆盖持久化类的equals()方法和 hashCode() 方法，从而实现自定义的对象相等语义。警告：不要使用数据库标识 来实现对象相等，应该使用业务键值，由唯一的，通常不变的属性组成。当一个瞬时对象被持久化的时 候，它的数据库标识会发生改变。如果一个瞬时对象（通常也包括脱管对象实例）被放入一 个Set，改变它的hashcode会导致与这个Set的关系中断。虽 然业务键值的属性不象数据库主键那样稳定不变，但是你只需要保证在同一个Set 中的对象属性的稳定性就足够了。请到Hibernate网站去寻求这个问题更多的详细的讨论。请注意，这不是一 个有关Hibernate的问题，而仅仅是一个关于Java对象标识和判等行为如何实现的问题。

决不要使用反模式session-per-user-session或者 session-per-application（当然，这个规定几乎没有例外）。请注意， 下述一些问题可能也会出现在我们推荐的模式中，在你作出某个设计决定之前，请务必理解该模式的应用前提。

如果Hibernat持久层运行在一个非托管环境中，数据库连接通常由Hibernate的简单（即非DataSource)连接池机制 来处理。session/transaction处理方式如下所示：

// Non-managed environment idiom
Session sess = factory.openSession();
Transaction tx = null;
try {
    tx = sess.beginTransaction();

    // do some work
    ...

    tx.commit();
}
catch (RuntimeException e) {
    if (tx != null) tx.rollback();
    throw e; // or display error message
}
finally {
    sess.close();
}

You don't have to flush() the Session explicitly - the call to commit() automatically triggers the synchronization (depending upon the FlushMode for the session. A call to close() marks the end of a session. The main implication of close() is that the JDBC connection will be relinquished by the session. This Java code is portable and runs in both non-managed and JTA environments.

更加灵活的方案是Hibernate内置的"current session"上下文管理，前文已经讲过：

// Non-managed environment idiom with getCurrentSession()
try {
    factory.getCurrentSession().beginTransaction();

    // do some work
    ...

    factory.getCurrentSession().getTransaction().commit();
}
catch (RuntimeException e) {
    factory.getCurrentSession().getTransaction().rollback();
    throw e; // or display error message
}

你很可能从未在一个通常的应用程序的业务代码中见过这样的代码片断：致命的（系统）异常应该总是 在应用程序“顶层”被捕获。换句话说，执行Hibernate调用的代码（在持久层）和处理 RuntimeException异常的代码（通常只能清理和退出应用程序）应该在不同 的应用程序逻辑层。Hibernate的当前上下文管理可以极大地简化这一设计，你所有的一切就是SessionFactory。 异常处理将在本章稍后进行讨论。

请注意，你应该选择 org.hibernate.transaction.JDBCTransactionFactory (这是默认选项)，对第二个例子来说，hibernate.current_session_context_class应该是"thread"

如果你的持久层运行在一个应用服务器中（例如，在EJB session beans的后面），Hibernate获取 的每个数据源连接将自动成为全局JTA事务的一部分。 你可以安装一个独立的JTA实现，使用它而不使用EJB。Hibernate提供了两种策略进行JTA集成。

如果你使用bean管理事务（BMT），可以通过使用Hibernate的 Transaction API来告诉 应用服务器启动和结束BMT事务。因此，事务管理代码和在非托管环境下是一样的。

// BMT idiom
Session sess = factory.openSession();
Transaction tx = null;
try {
    tx = sess.beginTransaction();

    // do some work
    ...

    tx.commit();
}
catch (RuntimeException e) {
    if (tx != null) tx.rollback();
    throw e; // or display error message
}
finally {
    sess.close();
}

如果你希望使用与事务绑定的Session，也就是使用getCurrentSession()来简化上下文管理，你将不得不直接使用JTA UserTransactionAPI。

// BMT idiom with getCurrentSession()
try {
    UserTransaction tx = (UserTransaction)new InitialContext()
                            .lookup("java:comp/UserTransaction");

    tx.begin();

    // Do some work on Session bound to transaction
    factory.getCurrentSession().load(...);
    factory.getCurrentSession().persist(...);

    tx.commit();
}
catch (RuntimeException e) {
    tx.rollback();
    throw e; // or display error message
}

With CMT, transaction demarcation is done in session bean deployment descriptors, not programmatically, hence, the code is reduced to:

// CMT idiom
 Session sess = factory.getCurrentSession();

 // do some work
 ...

在CMT/EJB中甚至会自动rollback，因为假若有未捕获的RuntimeException从session bean方法中抛出，这就会通知容器把全局事务回滚。这就意味着，在BMT或者CMT中，你根本就不需要使用Hibernate Transaction API ，你自动得到了绑定到事务的“当前”Session。

Note that you should choose org.hibernate.transaction.JTATransactionFactory if you use JTA directly (BMT), and org.hibernate.transaction.CMTTransactionFactory in a CMT session bean, when you configure Hibernate's transaction factory. Remember to also set hibernate.transaction.manager_lookup_class. Furthermore, make sure that your hibernate.current_session_context_class is either unset (backwards compatibility), or set to "jta".

The getCurrentSession() operation has one downside in a JTA environment. There is one caveat to the use of after_statement connection release mode, which is then used by default. Due to a silly limitation of the JTA spec, it is not possible for Hibernate to automatically clean up any unclosed ScrollableResults or Iterator instances returned by scroll() or iterate(). You must release the underlying database cursor by calling ScrollableResults.close() or Hibernate.close(Iterator) explicitly from a finally block. (Of course, most applications can easily avoid using scroll() or iterate() at all from the JTA or CMT code.)

如果 Session 抛出异常 (包括任何SQLException), 你应该立即回滚数据库事务，调用 Session.close() ，丢弃该 Session实例。Session的某些方法可能会导致session 处于不一致的状态。所有由Hibernate抛出的异常都视为不可以恢复的。确保在 finally 代码块中调用close()方法，以关闭掉 Session。

HibernateException是一个非检查期异常（这不同于Hibernate老的版本）， 它封装了Hibernate持久层可能出现的大多数错误。我们的观点是，不应该强迫应用程序开发人员 在底层捕获无法恢复的异常。在大多数软件系统中，非检查期异常和致命异常都是在相应方法调用 的堆栈的顶层被处理的（也就是说，在软件上面的逻辑层），并且提供一个错误信息给应用软件的用户 （或者采取其他某些相应的操作）。请注意，Hibernate也有可能抛出其他并不属于 HibernateException的非检查期异常。这些异常同样也是无法恢复的，应该 采取某些相应的操作去处理。

Hibernate wraps SQLExceptions thrown while interacting with the database in a JDBCException. In fact, Hibernate will attempt to convert the exception into a more meaningful subclass of JDBCException. The underlying SQLException is always available via JDBCException.getCause(). Hibernate converts the SQLException into an appropriate JDBCException subclass using the SQLExceptionConverter attached to the SessionFactory. By default, the SQLExceptionConverter is defined by the configured dialect; however, it is also possible to plug in a custom implementation (see the javadocs for the SQLExceptionConverterFactory class for details). The standard JDBCException subtypes are:

One extremely important feature provided by a managed environment like EJB that is never provided for non-managed code is transaction timeout. Transaction timeouts ensure that no misbehaving transaction can indefinitely tie up resources while returning no response to the user. Outside a managed (JTA) environment, Hibernate cannot fully provide this functionality. However, Hibernate can at least control data access operations, ensuring that database level deadlocks and queries with huge result sets are limited by a defined timeout. In a managed environment, Hibernate can delegate transaction timeout to JTA. This functionality is abstracted by the Hibernate Transaction object.

Session sess = factory.openSession();
try {
    //set transaction timeout to 3 seconds
    sess.getTransaction().setTimeout(3);
    sess.getTransaction().begin();

    // do some work
    ...

    sess.getTransaction().commit()
}
catch (RuntimeException e) {
    sess.getTransaction().rollback();
    throw e; // or display error message
}
finally {
    sess.close();
}

注意setTimeout()不应该在CMT bean中调用，此时事务超时值应该是被声明式定义的。

未能充分利用Hibernate功能的实现代码中，每次和数据库交互都需要一个新的 Session，而且开发人员必须在显示数据之前从数据库中重 新载入所有的持久化对象实例。这种方式迫使应用程序自己实现版本检查来确保 对话事务的隔离，从数据访问的角度来说是最低效的。这种使用方式和 entity EJB最相似。

// foo is an instance loaded by a previous Session
session = factory.openSession();
Transaction t = session.beginTransaction();

int oldVersion = foo.getVersion();
session.load( foo, foo.getKey() ); // load the current state
if ( oldVersion != foo.getVersion() ) throw new StaleObjectStateException();
foo.setProperty("bar");

t.commit();
session.close();

version 属性使用 <version>来映射，如果对象 是脏数据，在同步的时候，Hibernate会自动增加版本号。

当然，如果你的应用是在一个低数据并发环境下，并不需要版本检查的话，你照样可以使用 这种方式，只不过跳过版本检查就是了。在这种情况下，最晚提交生效 （last commit wins）就是你的长对话的默认处理策略。 请记住这种策略可能会让应用软件的用户感到困惑，因为他们有可能会碰上更新丢失掉却没 有出错信息，或者需要合并更改冲突的情况。

Clearly, manual version checking is only feasible in very trivial circumstances and not practical for most applications. Often not only single instances, but complete graphs of modified objects have to be checked. Hibernate offers automatic version checking with either an extended Session or detached instances as the design paradigm.

单个 Session实例和它所关联的所有持久化对象实例都被用于整个 对话，这被称为session-per-conversation。Hibernate在同步的时候进行对象实例的版本检查，如果检测到并发修 改则抛出异常。由开发人员来决定是否需要捕获和处理这个异常（通常的抉择是给用户 提供一个合并更改，或者在无脏数据情况下重新进行业务对话的机会）。

在等待用户交互的时候， Session 断开底层的JDBC连接。这种方式 以数据库访问的角度来说是最高效的方式。应用程序不需要关心版本检查或脱管对象实例 的重新关联，在每个数据库事务中，应用程序也不需要载入读取对象实例。

// foo is an instance loaded earlier by the old session
Transaction t = session.beginTransaction(); // Obtain a new JDBC connection, start transaction

foo.setProperty("bar");

session.flush();    // Only for last transaction in conversation
t.commit();         // Also return JDBC connection
session.close();    // Only for last transaction in conversation

foo对象知道它是在哪个Session中被装入的。在一个旧session中开启一个新的数据库事务，会导致session获取一个新的连接，并恢复session的功能。将数据库事务提交，使得session从JDBC连接断开，并将此连接交还给连接池。在重新连接之后，要强制对你没有更新的数据进行一次版本检查，你可以对所有可能被其他事务修改过的对象，使用参数LockMode.READ来调用Session.lock()。你不用lock任何你正在更新的数据。一般你会在扩展的Session上设置FlushMode.MANUAL，因此只有最后一个数据库事务循环才会真正的吧整个对话中发生的修改发送到数据库。因此，只有这最后一次数据库事务才会包含flush()操作，然后在整个对话结束后，还要close()这个session。

如果在用户思考的过程中，Session因为太大了而不能保存，那么这种模式是有 问题的。举例来说，一个HttpSession应该尽可能的小。由于 Session是一级缓存，并且保持了所有被载入过的对象，因此 我们只应该在那些少量的request/response情况下使用这种策略。你应该只把一个Session用于单个对话，因为它很快就会出现脏数据。

（注意，早期的Hibernate版本需要明确的对Session进行disconnec和reconnect。这些方法现在已经过时了，打开事务和关闭事务会起到同样的效果。）

此外，也请注意，你应该让与数据库连接断开的Session对持久层保持 关闭状态。换句话说，在三层环境中，使用有状态的EJB session bean来持有Session， 而不要把它传递到web层（甚至把它序列化到一个单独的层），保存在HttpSession中。

扩展session模式，或者被称为每次对话一个session(session-per-conversation), 在与自动管理当前session上下文联用的时候会更困难。你需要提供你自己的CurrentSessionContext实现。请参阅Hibernate Wiki以获得示例。

这种方式下，与持久化存储的每次交互都发生在一个新的Session中。 然而，同一持久化对象实例可以在多次与数据库的交互中重用。应用程序操纵脱管对象实例 的状态，这个脱管对象实例最初是在另一个Session 中载入的，然后 调用 Session.update()，Session.saveOrUpdate(), 或者 Session.merge() 来重新关联该对象实例。

// foo is an instance loaded by a previous Session
foo.setProperty("bar");
session = factory.openSession();
Transaction t = session.beginTransaction();
session.saveOrUpdate(foo); // Use merge() if "foo" might have been loaded already
t.commit();
session.close();

Again, Hibernate will check instance versions during flush, throwing an exception if conflicting updates occurred.

如果你确信对象没有被修改过，你也可以调用lock() 来设置 LockMode.READ（绕过所有的缓存，执行版本检查），从而取 代 update()操作。

对于特定的属性和集合，通过为它们设置映射属性optimistic-lock的值 为false，来禁止Hibernate的版本自动增加。这样的话，如果该属性 脏数据，Hibernate将不再增加版本号。

Legacy database schemas are often static and can't be modified. Or, other applications might also access the same database and don't know how to handle version numbers or even timestamps. In both cases, versioning can't rely on a particular column in a table. To force a version check without a version or timestamp property mapping, with a comparison of the state of all fields in a row, turn on optimistic-lock="all" in the <class> mapping. Note that this conceptually only works if Hibernate can compare the old and new state, i.e. if you use a single long Session and not session-per-request-with-detached-objects.

有些情况下，只要更改不发生交错，并发修改也是允许的。当你在<class> 的映射中设置optimistic-lock="dirty"，Hibernate在同步的时候将只比较有脏 数据的字段。

In both cases, with dedicated version/timestamp columns or with full/dirty field comparison, Hibernate uses a single UPDATE statement (with an appropriate WHERE clause) per entity to execute the version check and update the information. If you use transitive persistence to cascade reattachment to associated entities, Hibernate might execute unnecessary updates. This is usually not a problem, but on update triggers in the database might be executed even when no changes have been made to detached instances. You can customize this behavior by setting select-before-update="true" in the <class> mapping, forcing Hibernate to SELECT the instance to ensure that changes did actually occur, before updating the row.