Hibernate.orgCommunity Documentation
面向新用户，从一个简单的使用内存数据库的例子开始，本章提供对 Hibernate 的逐步介绍。本教程基于 Michael Gloegl 早期编写的手册。所有代码都包含在 tutorials/web 目录下。
本教程期望用户具备 Java 和 SQL 知识。如果你这方面的知识有限，我们建议你在学习 Hibernate 之前先好好了解这些技术。
本版本在源代码目录 tutorial/eg 下还包含另外一个例程。
在这个例子里，我们将设立一个小应用程序可以保存我们希望参加的活动（events）和这些活动主办方的相关信息。（译者注：在本教程的后面部分，我们将直接使用 event 而不是它的中文翻译“活动”，以免混淆。）
虽然你可以使用任何数据库，我们还是用 HSQLDB（一个用 Java 编写的内存数据库）来避免花费篇章对数据库服务器的安装/配置进行解释。
我们需要做的第一件事情是设置开发环境。我们将使用许多构建工具如 Maven 所鼓吹的“标准格式”。特别是 Maven，它的资源对这个格式（layout）有着很好的描述。因为本教程使用的是 web 应用程序，我么将创建和使用 src/main/java、src/main/resources 和 src/main/webapp 目录。
在本教程里我们将使用 Maven，利用其 transitive dependency 管理以及根据 Maven 描述符用 IDE 自动设置项目的能力。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion
>4.0.0</modelVersion>
<groupId
>org.hibernate.tutorials</groupId>
<artifactId
>hibernate-tutorial</artifactId>
<version
>1.0.0-SNAPSHOT</version>
<name
>First Hibernate Tutorial</name>
<build>
<!-- we dont want the version to be part of the generated war file name -->
<finalName
>${artifactId}</finalName>
</build>
<dependencies>
<dependency>
<groupId
>org.hibernate</groupId>
<artifactId
>hibernate-core</artifactId>
</dependency>
<!-- Because this is a web app, we also have a dependency on the servlet api. -->
<dependency>
<groupId
>javax.servlet</groupId>
<artifactId
>servlet-api</artifactId>
</dependency>
<!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend -->
<dependency>
<groupId
>org.slf4j</groupId>
<artifactId
>slf4j-simple</artifactId>
</dependency>
<!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
<dependency>
<groupId
>javassist</groupId>
<artifactId
>javassist</artifactId>
</dependency>
</dependencies>
</project
>
It is not a requirement to use Maven. If you wish to use something else to build this tutorial (such as Ant), the layout will remain the same. The only change is that you will need to manually account for all the needed dependencies. If you use something like Ivy providing transitive dependency management you would still use the dependencies mentioned below. Otherwise, you'd need to grab all dependencies, both explicit and transitive, and add them to the project's classpath. If working from the Hibernate distribution bundle, this would mean hibernate3.jar, all artifacts in the lib/required directory and all files from either the lib/bytecode/cglib or lib/bytecode/javassist directory; additionally you will need both the servlet-api jar and one of the slf4j logging backends.
把这个文件保存为项目根目录下的 pom.xml。
接下来我们创建一个类，用来代表那些我们希望储存在数据库里的 event，这是一个具有一些属性的简单 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）。
对一特定的 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）的情况下，从持久化类里获取数据会更有效率。
把这个文件保存到 src/main/java/org/hibernate/tutorial/domain 目录下。
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 package="org.hibernate.tutorial.domain">
[...]
</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 package="org.hibernate.tutorial.domain">
<class name="Event" table="EVENTS">
</class>
</hibernate-mapping
>
到目前为止，我们告诉了 Hibernate 怎样把 Events 类的对象持久化到数据库的 EVENTS 表里，以及怎样从 EVENTS 表加载到 Events 类的对象。每个实例对应着数据库表中的一行。现在我们将继续讨论有关唯一标识符属性到数据库表的映射。另外，由于我们不关心怎样处理这个标识符，我们就配置由 Hibernate 的标识符生成策略来产生代理主键字段：
<hibernate-mapping package="org.hibernate.tutorial.domain">
<class name="Event" table="EVENTS">
<id name="id" column="EVENT_ID">
<generator class="native"/>
</id>
</class>
</hibernate-mapping
>
id 元素是对 identifier 属性的声明。name="id" 映射属性声明了 JavaBean 属性的名称并告诉 Hibernate 使用 getId() 和 setId() 方法来访问这个属性。column 属性告诉 Hibernate EVENTS 表的哪个字段持有主键值。
嵌套的 generator 元素指定标识符的生成策略（也就是标识符值是怎么产生的）。在这个例子里，我们选择 native，它提供了取决于数据库方言的可移植性。Hibernate 数据库生成的、全局性唯一的以及应用程序分配的标识符。标识符值的生成也是 Hibernate 的扩展功能之一，你可以插入自己的策略。
native is no longer consider the best strategy in terms of portability. for further discussion, see 第 26.4 节 “标识符的生成”
最后我们在映射文件里面包含需要持久化属性的声明。默认情况下，类里面的属性都被视为非持久化的：
<hibernate-mapping package="org.hibernate.tutorial.domain">
<class name="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 转换器，这样我们预留了日期和时间的全部信息。
当处理映射文件时，Hibernate 用反射（reflection）来决定这个映射类型。这需要时间和资源，所以如果你注重启动性能，你应该考虑显性地定义所用的类型。
把这个映射文件保存为 src/main/resources/org/hibernate/tutorial/domain/Event.hbm.xml。
此时，你应该有了持久化类和它的映射文件。现在是配置 Hibernate 的时候了。首先让我们设立 HSQLDB 使其运行在“服务器模式”。
数据在程序运行期间需要保持有效。
在开发的根目录下创建一个 data 目录 － 这是 HSQL DB 存储数据文件的地方。此时在 data 目录中运行 java -classpath ../lib/hsqldb.jar org.hsqldb.Server 就可启动数据库。你可以在 log 中看到它的启动，及绑定到 TCP/IP 套接字，这正是我们的应用程序稍后会连接的地方。如果你希望在本例中运行一个全新的数据库，就在窗口中按下 CTRL + C 来关闭 HSQL 数据库，并删除 data/ 目录下的所有文件，再重新启动 HSQL 数据库。
Hibernate 将为你的应用程序连接到数据库，所以它需要知道如何获取连接。在这个教程里，我们使用一个独立连接池（和 javax.sql.DataSource 相反）。Hibernate 支持两个第三方的开源 JDBC 连接池：c3p0 和 proxool。然而，在本教程里我们将使用 Hibernate 内置的连接池。
嵌入的 Hibernate 连接池不用于产品环境。它缺乏连接池里的几个功能。
为了保存 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"
>update</property>
<mapping resource="org/hibernate/tutorial/domain/Event.hbm.xml"/>
</session-factory>
</hibernate-configuration
>
请注意，这个配置文件指定了一个不同的 DTD。
注意这个 XML 配置使用了一个不同的 DTD。在这里，我们配置了 Hibernate 的SessionFactory — 一个关联于特定数据库全局的工厂（factory）。如果你要使用多个数据库，就要用多个的 <session-factory>，通常把它们放在多个配置文件中（为了更容易启动）。
签名 4 个 property 元素包含了 JDBC 连接所必需的配置。方言 property 元素指定了 Hibernate 生成的特定 SQL 语句。
In most cases, Hibernate is able to properly determine which dialect to use. See 第 26.3 节 “方言的使用” for more information.
最开始的 4 个 property 元素包含必要的 JDBC 连接信息。方言（dialect）的 property 元素指明 Hibernate 生成的特定 SQL 变量。你很快会看到，Hibernate 对持久化上下文的自动 session 管理就会派上用场。 打开 hbm2ddl.auto 选项将自动生成数据库模式（schema）－ 直接加入数据库中。当然这个选项也可以被关闭（通过去除这个配置选项）或者通过 Ant 任务 SchemaExport 的帮助来把数据库 schema 重定向到文件中。最后，在配置中为持久化类加入映射文件。
把这个文件保存为 src/main/resources 目录下的 hibernate.cfg.xml。
我们将用 Maven 构建这个教程。你将需要安装 Maven；你可以从 Maven 下载页面获得 Maven。Maen 将读取我们先前创建的 /pom.xml 并知道执行基本的项目任务。首先，让我们运行 compile 目标来确保我们可以编译到目前为止的所有程序：
[hibernateTutorial]$ mvn compile [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Building First Hibernate Tutorial [INFO] task-segment: [compile] [INFO] ------------------------------------------------------------------------ [INFO] [resources:resources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:compile] [INFO] Compiling 1 source file to /home/steve/projects/sandbox/hibernateTutorial/target/classes [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2 seconds [INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009 [INFO] Final Memory: 5M/547M [INFO] ------------------------------------------------------------------------
是时候来加载和储存一些 Event 对象了，但首先我们得编写一些基础的代码以完成设置。我们必须启动 Hibernate，此过程包括创建一个全局的 SessoinFactory，并把它储存在应用程序代码容易访问的地方。SessionFactory 可以创建并打开新的 Session。一个 Session 代表一个单线程的单元操作，org.hibernate.SessionFactory 则是个线程安全的全局对象，只需要被实例化一次。
我们将创建一个 HibernateUtil 辅助类（helper class）来负责启动 Hibernate 和更方便地操作 org.hibernate.SessionFactory。让我们来看一下它的实现：
package org.hibernate.tutorial.util;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;
public class HibernateUtil {
private static final SessionFactory sessionFactory = buildSessionFactory();
private static SessionFactory buildSessionFactory() {
try {
// Create the SessionFactory from hibernate.cfg.xml
return 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;
}
}
把这段代码保存为 src/main/java/org/hibernate/tutorial/util/HibernateUtil.java。
这个类不但在它的静态初始化过程（仅当加载这个类的时候被 JVM 执行一次）中产生全局的 org.hibernate.SessionFactory，而且隐藏了它使用了静态 singleton 的事实。它也可能在应用程序服务器中的 JNDI 查找 org.hibernate.SessionFactory。
如果你在配置文件中给 org.hibernate.SessionFactory 一个名字，在 它创建后，Hibernate 会试着把它绑定到 JNDI。要完全避免这样的代码，你也可以使用 JMX 部署，让具有 JMX 能力的容器来实例化 HibernateService 并把它绑定到 JNDI。这些高级可选项在后面的章节中会讨论到。
再次编译这个应用程序应该不会有问题。最后我们需要配置一个日志（logging)系统 — Hibernate 使用通用日志接口，允许你在 Log4j 和 JDK 1.4 日志之间进行选择。多数开发者更喜欢 Log4j：从 Hibernate 的发布包中（它在 etc/ 目录下）拷贝 log4j.properties 到你的 src 目录，与 hibernate.cfg.xml 放在一起。看一下配置示例，如果你希望看到更加详细的输出信息，你可以修改配置。默认情况下，只有 Hibernate 的启动信息才会显示在标准输出上。
示例的基本框架完成了 — 现在我们可以用 Hibernate 来做些真正的工作。
We are now ready to start doing some real work with Hibernate. Let's start by writing an EventManager class with a main() method:
package org.hibernate.tutorial;
import org.hibernate.Session;
import java.util.*;
import org.hibernate.tutorial.domain.Event;
import org.hibernate.tutorial.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();
}
}
在 createAndStoreEvent() 来里我们创建了一个新的 Event 对象并把它传递给 Hibernate。现在 Hibernate 负责与 SQL 打交道，并把 INSERT 命令传给数据库。
A org.hibernate.Session is designed to represent a single unit of work (a single atomic piece of work to be performed). For now we will keep things simple and assume a one-to-one granularity between a Hibernate org.hibernate.Session and a database transaction. To shield our code from the actual underlying transaction system we use the Hibernate org.hibernate.Transaction API. In this particular case we are using JDBC-based transactional semantics, but it could also run with JTA.
sessionFactory.getCurrentSession() 是干什么的呢？首先，只要你持有 org.hibernate.SessionFactory，大可在任何时候、任何地点调用这个方法。getCurrentSession() 方法总会返回“当前的”工作单元。记得我们在 src/main/resources/hibernate.cfg.xml 中把这一配置选项调整为 "thread" 了吗？因此，因此，当前工作单元被绑定到当前执行我们应用程序的 Java 线程。但是，这并非是完全准确的,你还得考虑工作单元的生命周期范围（scope），它何时开始,又何时结束。
Hibernate 提供三种跟踪当前会话的方法。基于“线程”的方法不适合于产品环境，它仅用于 prototyping 和教学用途。后面将更详细地讨论会话跟踪。
org.hibernate.Session 在第一次被使用的时候，即第一次调用 getCurrentSession() 的时候,其生命周期就开始。然后它被 Hibernate 绑定到当前线程。当事务结束的时候，不管是提交还是回滚，Hibernate 会自动把 org.hibernate.Session 从当前线程剥离，并且关闭它。假若你再次调用 getCurrentSession()，你会得到一个新的 org.hibernate.Session，并且开始一个新的工作单元。
和工作单元的生命周期这个话题相关，Hibernate org.hibernate.Session 是否被应该用来执行多次数据库操作？上面的例子对每一次操作使用了一个 org.hibernate.Session，这完全是巧合，这个例子不是很复杂，无法展示其他方式。Hibernate org.hibernate.Session 的生命周期可以很灵活，但是你绝不要把你的应用程序设计成为每一次数据库操作都用一个新的 Hibernate org.hibernate.Session。因此就算下面的例子（它们都很简单）中你可以看到这种用法，记住每次操作一个 session 是一个反模式。在本教程的后面会展示一个真正的（web）程序。
See 第 12 章 事务和并发 for more information about transaction handling and demarcation. The previous example also skipped any error handling and rollback.
要运行它，我们将使用 Maven exec 插件以及必要的 classpath 设置来进行调用：mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="store"。
你可能需要先执行 mvn compile。
你应该会看到，编译以后，Hibernate 根据你的配置启动，并产生一大堆的输出日志。在日志最后你会看到下面这行：
[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)
执行 HQL INSERT 语句的例子如下：
我们想要列出所有已经被存储的 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;
}
Here, we are using a Hibernate Query Language (HQL) query to load all existing Event objects from the database. Hibernate will generate the appropriate SQL, send it to the database and populate Event objects with the data. You can create more complex queries with HQL. See 第 15 章 HQL: Hibernate 查询语言 for more information.
现在我们可以再次用 Maven exec plugin - mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="list" 调用新的功能了。
我们已经映射了一个持久化实体类到表上。让我们在这个基础上增加一些类之间的关联。首先我们往应用程序里增加人（people）的概念，并存储他们所参与的一个 Event 列表。（译者注：与 Event 一样，我们在后面将直接使用 person 来表示“人”而不是它的中文翻译）
最初简单的 Person 类：
package org.hibernate.tutorial.domain;
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'
}
把它保存为文件 src/main/java/org/hibernate/tutorial/domain/Person.java。
然后，创建新的映射文件 src/main/resources/org/hibernate/tutorial/domain/Person.hbm.xml。
<hibernate-mapping package="org.hibernate.tutorial.domain">
<class name="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 不包含重复的元素及与我们无关的排序。
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="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="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 实体里添加一个电子邮件的集合。这将以 java.lang.String 实例的 java.util.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 |
|_____________|
你可以看到集合表的主键实际上是个复合主键，同时使用了两个字段。这也暗示了对于同一个 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);
// adding to the emailAddress collection might trigger a lazy load of the collection
aPerson.getEmailAddresses().add(emailAddress);
session.getTransaction().commit();
}
这次我们没有使用 fetch 查询来初始化集合。因此，调用其 getter 方法会触发另一附加的 select 来初始化集合，这样我们才能把元素添加进去。检查 SQL log，试着通过预先抓取来优化它。
接下来我们将映射双向关联（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 引用集合。这“在关联的两端设置联系”是完全必要的而且你都得这么做。
许多开发人员防御式地编程，创建管理关联的方法来保证正确的设置了关联的两端，比如在 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）关联中，你可以任意选取一端，因为两端之间并没有差别。
Hibernate web 应用程序使用 Session 和 Transaction 的方式几乎和独立应用程序是一样的。但是，有一些常见的模式（pattern）非常有用。现在我们编写一个 EventManagerServlet。这个 servlet 可以列出数据库中保存的所有的 events，还提供一个 HTML 表单来增加新的 events。
这个 servlet 只处理 HTTP GET 请求，因此，我们要实现的是 doGet() 方法：
package org.hibernate.tutorial.web;
// Imports
public class EventManagerServlet extends HttpServlet {
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();
if ( ServletException.class.isInstance( ex ) ) {
throw ( ServletException ) ex;
}
else {
throw new ServletException( ex );
}
}
}
}
把这个 servlet 保存为 src/main/java/org/hibernate/tutorial/web/EventManagerServlet.java。
我们称这里应用的模式为每次请求一个 session(session-per-request)。当有请求到达这个 servlet 的时候，通过对 SessionFactory 的第一次调用，打开一个新的 Hibernate Session。然后启动一个数据库事务 — 所有的数据访问都是在事务中进行，不管是读还是写（我们在应用程序中不使用 auto-commit 模式）。
不要为每次数据库操作都使用一个新的 Hibernate Session。将 Hibernate Session 的范围设置为整个请求。要用 getCurrentSession()，这样它自动会绑定到当前 Java 线程。
下一步，对请求的可能动作进行处理，渲染出反馈的 HTML。我们很快就会涉及到那部分。
最后，当处理与渲染都结束的时候，这个工作单元就结束了。假若在处理或渲染的时候有任何错误发生，会抛出一个异常，回滚数据库事务。这样，session-per-request 模式就完成了。为了避免在每个 servlet 中都编写事务边界界定的代码，可以考虑写一个 servlet 过滤器（filter）来更好地解决。关于这一模式的更多信息，请参阅 Hibernate 网站和 Wiki，这一模式叫做 Open Session in View — 只要你考虑用JSP来渲染你的视图（view），而不是在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();
必须承认，这种编码风格把 Java 和 HTML 混在一起，在更复杂的应用程序里不应该大量使用 — 记住，在本章里我们仅仅是展示了 Hibernate 的基本概念。这段代码打印出了 HTML 页眉和页脚，在这个页面里，还打印了一个输入 events 条目的表单单并列出了数据库里的有的 events。第一个方法微不足道，仅仅是输出 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
>");
Iterator it = result.iterator();
while (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);
}
大功告成，这个 servlet 写完了。Hibernate 会在单一的 Session 和 Transaction 中处理到达的 servlet 请求。如同在前面的独立应用程序中那样，Hibernate 可以自动的把这些对象绑定到当前运行的线程中。这给了你用任何你喜欢的方式来对代码分层及访问 SessionFactory 的自由。通常，你会用更加完备的设计，把数据访问代码转移到数据访问对象中（DAO 模式）。请参见 Hibernate Wiki，那里有更多的例子。
要部署这个应用程序以进行测试，我们必须出具一个 Web ARchive (WAR)。首先我们必须定义 WAR 描述符为 src/main/webapp/WEB-INF/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
>org.hibernate.tutorial.web.EventManagerServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name
>Event Manager</servlet-name>
<url-pattern
>/eventmanager</url-pattern>
</servlet-mapping>
</web-app
>
在你的开发目录中，调用 ant war 来构建、打包，然后把 hibernate-tutorial.war 文件拷贝到你的 tomcat 的 webapps 目录下。假若你还没安装 Tomcat，就去下载一个，按照指南来安装。对此应用的发布，你不需要修改任何 Tomcat 的配置。
If you do not have Tomcat installed, download it from http://tomcat.apache.org/ and follow the installation instructions. Our application requires no changes to the standard Tomcat configuration.
在部署完，启动 Tomcat 之后，通过 http://localhost:8080/hibernate-tutorial/eventmanager 进行访问你的应用，在第一次 servlet 请求发生时，请在 Tomcat log 中确认你看到 Hibernate 被初始化了（HibernateUtil 的静态初始化器被调用），假若有任何异常抛出，也可以看到详细的输出。
本章覆盖了如何编写一个简单独立的 Hibernate 命令行应用程序及小型的 Hibernate web 应用程序的基本要素。更多的教程可以在 website 上找到。
版权 © 2004 Red Hat, Inc.