2

Hibernate 中文文档 3.2

4.1.1.实现一个默认的（即无参数的）构造方法（constructor）

4.1.2.提供一个标识属性（identifier property）（可选） 5.1.2 5.1.1

4.1.4.为持久化字段声明访问器(accessors)和是否可变的标志

3

Hibernate 中文文档 3.2

4

Hibernate 中文文档 3.2

6.2.5. 一对多关联（One-to-many Associations） 6.3. 高级集合映射（Advanced collection mappings）

6.3.1. 有序集合（Sorted collections）

6.3.2. 双向关联（Bidirectional associations）

6.3.3. 双向关联，涉及有序集合类

6.3.4. 三重关联（Ternary associations）

6.3.5. `使用<idbag>`

6.4. 集合例子（Collection example） 第 7 章 关联关系映射

7.1. 介绍

7.2. 单向关联（Unidirectional associations） 7.2.1. 多对一(many to one)

7.2.2. 一对一（one to one） 7.2.3. 一对多（one to many）

7.3. 使用连接表的单向关联（Unidirectional associations with join tables）

7.3.1. 一对多(one to many) 7.3.2. 多对一（many to one）

7.3.3. 一对一（one to one） 7.3.4. 多对多（many to many）

7.4. 双向关联（Bidirectional associations）

7.4.1. 一对多（one to many) / 多对一（many to one）

7.4.2. 一对一（one to one）

7.5. 使用连接表的双向关联（Bidirectional associations with join tables）

7.5.1. 一对多（one to many） /多对一（ many to one） 8.5.1 8.5

5

Hibernate 中文文档 3.2

9.1.4.混合使用“每个类分层结构一张表”和“每个子类一张表” 10.1.4

6

Hibernate 中文文档 3.2

7

Hibernate 中文文档 3.2

8

Hibernate 中文文档 3.2

20.1.5.对schema的增量更新(Incremental schema updates) 21.1.5

20.1.6.用Ant来增量更新schema(Using Ant for incremental schema

9

Hibernate 中文文档 3.2

10

Hibernate 中文文档 3.2

Hibernate 中文文档 3.2

Hibernate 中文文档 3.2

前言

目录

1. 翻译说明

2. 版权声明

WARNING! This is a translated version of the English Hibernate reference documentation. The translated version might not be up to date! However, the differences should only be very minor. Consult the English reference documentation if you are missing information or encounter a translation error. If you like to contribute to a particular translation, contact us on the Hibernate developer mailing list.

Translator(s): RedSaga Translate Team 满江红翻译团队 <[email protected]>

在今日的企业环境中，把面向对象的软件和关系数据库一起使用可能是相当麻烦、 浪费时间的。Hibernate是一个面向Java环境的对象/关系数据库映射工具。对象/关

系数据库映射(object/relational mapping (ORM))这个术语表示一种技术，用来把对 象模型表示的对象映射到基于SQL的关系模型数据结构中去。

Hibernate不仅仅管理Java类到数据库表的映射（包括Java数据类型到SQL数据类 型的映射），还提供数据查询和获取数据的方法，可以大幅度减少开发时人工使用 SQL和JDBC处理数据的时间。

Hibernate的目标是对于开发者通常的数据持久化相关的编程任务，解放其中的

95%。对于以数据为中心的程序来说,它们往往只在数据库中使用存储过程来实现商 业逻辑,Hibernate可能不是最好的解决方案;对于那些在基于Java的中间层应用中， 它们实现面向对象的业务模型和商业逻辑的应用，Hibernate是最有用的。不管怎 样，Hibernate一定可以帮助你消除或者包装那些针对特定厂商的SQL代码，并且帮 你把结果集从表格式的表示形式转换到一系列的对象去。

如果你对Hibernate和对象/关系数据库映射还是个新手，或者甚至对Java也不熟 悉，请按照下面的步骤来学习。

1.阅读第 1 章 Hibernate入门 ，这是一篇包含详细的逐步指导的指南。本指南的 源代码包含在发行包中，你可以在 doc/reference/tutorial/ 目录下找到。

2.阅读第 2 章 体系结构(Architecture)来理解Hibernate可以使用的环境。

3.查看Hibernate发行包中的 eg/ 目录，里面有一个简单的独立运行的程序。把 你的JDBC驱动拷贝到 lib/ 目录下，修改一

下 src/hibernate.properties ,指定其中你的数据库的信息。进入命令行，

切换到你的发行包的目录，输入 ant eg (使用了Ant），或者在Windows操作 系统中使用 build eg 。

4.把这份参考文档作为你学习的主要信息来源。

5.在Hibernate 的网站上可以找到经常提问的问题与解答(FAQ)。

Hibernate 中文文档 3.2

6.在Hibernate网站上还有第三方的演示、示例和教程的链接。

7.Hibernate网站的“社区(Community Area)”是讨论关于设计模式以及很多整合方 案(Tomcat, JBoss AS, Struts, EJB,等等)的好地方。

如果你有问题，请使用Hibernate网站上链接的用户论坛。我们也提供一个JIRA问 题追踪系统，来搜集bug报告和新功能请求。如果你对开发Hibernate有兴趣，请加 入开发者的邮件列表。（Hibernate网站上的用户论坛有一个中文版面，JavaEye也 有Hibernate中文版面,您可以在那里交流问题与经验。）

商业开发、产品支持和Hibernate培训可以通过JBoss Inc.获得。（请查阅： http://www.hibernate.org/SupportTraining/）。 Hibernate是一个专业的开放源代码

项目(Professional Open Source project)，也是JBoss Enterprise Middleware System(JEMS),JBoss企业级中间件系统的一个核心组件。

Hibernate 中文文档 3.2

1.翻译说明

本文档的翻译是在网络上协作进行的，也会不断根据Hibernate的升级进行更新。提 供此文档的目的是为了减缓学习Hibernate的坡度，而非代替原文档。我们建议所有 有能力的读者都直接阅读英文原文。若您对翻译有异议，或发现翻译错误，敬请不 吝赐教，报告到如下email地址：cao at redsaga.com

Hibernate版本3的翻译由满江红翻译团队(RedSaga Translate Team)集体进行，这 也是一次大规模网络翻译的试验。在不到20天的时间内，我们完成了两百多页文档 的翻译，这一成果是通过十几位网友集体努力完成的。通过这次翻译，我们也有了 一套完整的流程，从初译、技术审核一直到文字审核、发布。我们的翻译团队还会 继续完善我们的翻译流程，并翻译其他优秀的Java开源资料，敬请期待。

表1. Hibernate v3翻译团队

Hibernate 中文文档 3.2

Hibernate 中文文档 3.2

v3.2版本在2006年11月份由曹晓钢更新。

关于我们

满江红.开源, http://www.redsaga.com

从成立之初就致力于Java开放源代码在中国的传播与发展,与国内多个Java团体及 出版社有深入交流。坚持少说多做的原则，目前有两个团队，“OpenDoc团队”与“翻 译团队”，本翻译文档即为翻译团队作品。OpenDoc团队已经推出包括Hibernate、 iBatis、Spring、WebWork的多份开放文档，并于2005年5月在Hibernate开放文档 基础上扩充成书，出版了原创书籍：《深入浅出Hibernate》，本书400余页，适合

各个层次的Hibernate用户。(http://www.redsaga.com/hibernate_book.html)敬请支 持。

北京Java用户组, http://www.bjug.org

Beiing Java User Group，民间技术交流组织，成立于2004年6月。以交流与共享为 宗旨，每两周举行一次技术聚会活动。BJUG的目标是，通过小部分人的努力，形 成一个技术社群，创建良好的交流氛围，并将新的技术和思想推广到整个IT界，让 我们共同进步。

Java视线, http://www.javaeye.com

Java视线在是Hibernate中文论坛（ http://www.hibernate.org.cn ，Hibernate中文 论坛是中国最早的Hibernate专业用户论坛，为Hibernate在中国的推广做出了巨大 的贡献）基础上发展起来的Java深度技术网站，目标是成为一个高品质的，有思想 深度的、原创精神的Java技术交流网站，为软件从业人员提供一个自由的交流技 术，交流思想和交流信息的平台。

致谢

还有一些朋友给我们发来了勘误，在此致谢：Kurapica，李毅，李海林。

Hibernate 中文文档 3.2

2.版权声明

Hibernate英文文档属于Hibernate发行包的一部分，遵循LGPL协议。本翻译版本同 样遵循LGPL协议。参与翻译的译者一致同意放弃除署名权外对本翻译版本的其它 权利要求。

您可以自由链接、下载、传播此文档，或者放置在您的网站上，甚至作为产品的一 部分发行。但前提是必须保证全文完整转载，包括完整的版权信息和作译者声明， 并不能违反LGPL协议。这里“完整”的含义是，不能进行任何删除/增添/注解。若有 删除/增添/注解，必须逐段明确声明那些部分并非本文档的一部分。

Hibernate 中文文档 3.2

第1 章 Hibernate入门

目录

1.1. 前言

1.2. 第一部分 － 第一个Hibernate应用程序

1.2.1. 第一个class

1.2.2. 映射文件

1.2.3. Hibernate配置

1.2.4. 用Ant构建 1.2.5. 启动和辅助类

1.2.6. 加载并存储对象 1.3. 第二部分 － 关联映射

1.3.1. 映射Person类

1.3.2. 单向Set-based的关联

1.3.3. 使关联工作

1.3.4. 值类型的集合

1.3.5. 双向关联

1.3.6. 使双向连起来

1.4. 第三部分 - EventManager web应用程序

1.4.1. 编写基本的servlet

1.4.2. 处理与渲染 1.4.3. 部署与测试

1.5. 总结

Hibernate 中文文档 3.2

1.1.前言

本章是面向Hibernate初学者的一个入门教程。我们从一个使用驻留内存式(in- memory)数据库的简单命令行应用程序开始, 用易于理解的方式逐步开发。

本章面向Hibernate初学者，但需要Java和SQL知识。它是在Michael Goegl所写的 指南的基础上完成的。在这里，我们称第三方库文件是指JDK 1.4和5.0。若使用 JDK1.3，你可能需要其它的库文件。

本章的源代码已包含在发布包中，位于 doc/reference/tutorial/ 目录下。

Hibernate 中文文档 3.2

1.2.第一部分 － 第一个Hibernate应用程序

首先我们将创建一个简单的基于控制台的(console-based)Hibernate应用程序。由 于我们使用Java数据库(HSQL DB)，所以不必安装任何数据库服务器。

假设我们希望有一个小应用程序可以保存我们希望参加的活动（events）和这些活 动主办方的相关信息。 （译者注：在本教程的后面部分，我们将直接使用event而 不是它的中文翻译“活动”，以免混淆。）

我们所做的第一件事就是创建我们的开发目录，并且把所有需要用到的Java库文件 放进去。解压缩从Hibernate网站下载的Hibernate发布包，并把 /lib 目录下所有 需要的库文件拷到我们新建开发目录下的 /lib 目录下。看起来就像这样：

.

+lib

antlr.jar

cglib.jar

asm.jar asm-attrs.jars commons-collections.jar commons-logging.jar ehcache.jar hibernate3.jar jta.jar

dom4j.jar

log4j.jar

到编写本文时为止，这些是Hibernate运行所需要的最小库文件集合（注意我们也拷 贝了 Hibernate3.jar，这个是最主要的文件）。你正使用的Hibernate版本可能需要 比这更多或少一些的库文件。请参见发布包中的 lib/ 目录下的 README.txt ， 以获取更多关于所需和可选的第三方库文件信息（事实上，Log4j并不是必须的库 文件，但被许多开发者所喜欢）。

接下来我们创建一个类，用来代表那些我们希望储存在数据库里的event。

Hibernate 中文文档 3.2

1.2.1. 第一个class

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

package events;

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

Hibernate 中文文档 3.2

对一特定的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 中文文档 3.2

1.2.2.映射文件

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

<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 中文文档 3.2

<hibernate-mapping>

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

</id>

</class>

</hibernate-mapping>

id 元素是标识符属性的声明， name="id" 声明了Java属性的名字 － Hibernate 会使用 getId() 和 setId() 来访问它。 column 属性则告诉Hibernate, 我们使

用EVENTS 表的哪个字段作为主键。嵌套的 generator 元素指定了标识符生成策 略，在这里我们指定 native ，它根据已配置的数据库（方言）自动选择最佳的标 识符生成策略。Hibernate支持由数据库生成，全局唯一性（globally unique）和应 用程序指定（或者你自己为任何已有策略所写的扩展）这些策略来生成标识符。

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

<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 类上使用反射机制）不会产生你所

Hibernate 中文文档 3.2

期待或需要的缺省值。 date 属性就是个很好的例子，Hibernate无法知道这个属 性（ java.util.Date 类型的）应该被映射成：SQL date ，或 timestamp ， 还是 time 字段。在此例中，把这个属性映射成 timestamp 转换器，这样我们 预留了日期和时间的全部信息。

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

.

+lib

<Hibernate and third-party libraries> +src

+events

Event.java

Event.hbm.xml

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

Hibernate 中文文档 3.2

1.2.3. 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配置文件：

Hibernate 中文文档 3.2

<?xml version='1.0' encoding='utf-8'?> <!DOCTYPE hibernate-configuration PUBLIC

"-//Hibernate/Hibernate Configuration DTD 3.0//EN" "http://hibernate.sourceforge.net/hibernate-configuration-

<hibernate-configuration>

<session-factory>

<!-- Database connection settings -->

<property name="connection.driver_class">org.hsqldb.jdbcDr <property name="connection.url">jdbc:hsqldb:hsql://localho <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

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

<!-- Disable the second-level cache -->

<property name="cache.provider_class">org.hibernate.cache.

<!-- 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 选项将自

Hibernate 中文文档 3.2

动生成数据库模式（schema）－ 直接加入数据库中。当然这个选项也可以被关闭 （通过去除这个配置选项）或者通过Ant任务 SchemaExport 的帮助来把数据库 schema重定向到文件中。最后，在配置中为持久化类加入映射文件。

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

Hibernate 中文文档 3.2

1.2.4. 用Ant构建

现在我们用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，会得到以下输出：

Hibernate 中文文档 3.2

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

Hibernate 中文文档 3.2

1.2.5.启动和辅助类

是时候来加载和储存一些 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().build

}catch (Throwable ex) {

//Make sure you log the exception, as it might be swa System.err.println("Initial SessionFactory creation fa throw new ExceptionInInitializerError(ex);

}

}

public static SessionFactory getSessionFactory() { return sessionFactory;

}

}

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

能在应用程序服务器中的JNDI查找 SessionFactory 。

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

Hibernate 中文文档 3.2

把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 中文文档 3.2

1.2.6.加载并存储对象

我们终于可以使用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().getCur

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 的代码。

Hibernate 中文文档 3.2

一个 Session 就是个单一的工作单元。我们暂时让事情简单一些，并假设 Hibernate Session 和数据库事务是一一对应的。为了让我们的代码从底层的事务 系统中脱离出来（此例中是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 <classpath path="${targetdir}"/>

<arg value="${action}"/> </java>

</target>

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

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

Hibernate 中文文档 3.2

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

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

这是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().getCurrent

session.beginTransaction();

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

session.getTransaction().commit();

return result;

}

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

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

Hibernate 中文文档 3.2

运行 ant run -Daction=store 来保存一些内容到数据库。当然，先得用 hbm2ddl来生成数据库schema。

现在把 hibernate.cfg.xml 文件中hbm2ddl属性注释掉，这样我们就取消了 在启动时用hbm2ddl来生成数据库schema。通常只有在不断重复进行单元测试 的时候才需要打开它，但再次运行hbm2ddl会把你保存的一切都删掉（drop）

——create 配置的真实含义是：“在创建SessionFactory的时候，从schema

中drop 掉所有的表，再重新创建它们”。

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

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

Hibernate 中文文档 3.2

1.3.第二部分 － 关联映射

我们已经映射了一个持久化实体类到表上。让我们在这个基础上增加一些类之间的 关联。首先我们往应用程序里增加人（people）的概念，并存储他们所参与的一个 Event列表。（译者注：与Event一样，我们在后面将直接使用person来表示“人”而 不是它的中文翻译）

Hibernate 中文文档 3.2

1.3.1. 映射Person类

最初简单的 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）的行为。

Hibernate 中文文档 3.2

1.3.2. 单向Set-based的关联

我们将向 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 中文文档 3.2

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

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

Hibernate 中文文档 3.2

1.3.3.使关联工作

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

private void addPersonToEvent(Long personId, Long eventId) {

Session session = HibernateUtil.getSessionFactory().getCurrent 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））。你甚至可以在一个集合被脱管时修改 它：

Hibernate 中文文档 3.2

private void addPersonToEvent(Long personId, Long eventId) {

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

Person aPerson = (Person) session

.createQuery("select p from Person p left join fetch p

.setParameter("pid", personId)

.uniqueResult(); // Eager fetch the collection so we c

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

session.getTransaction().commit();

// End of first unit of work

aPerson.getEvents().add(anEvent); // aPerson (and its collecti

// Begin second unit of work

Session session2 = HibernateUtil.getSessionFactory().getCurren 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 " +

}

上面是个关于两个同等重要的实体类间关联的例子。像前面所提到的那样，在特定 的模型中也存在其它的类和类型，这些类和类型通常是“次要的”。你已看到过其中 的一些，像 int 或 String 。我们称这些类为值类型（value type），它们的实