4.1. 一个简单的POJO例子

大多数Java程序需要用一个持久化类来表示猫科动物。

package eg;
import java.util.Set;
import java.util.Date;
public class Cat {
private Long id; // identifier
private Date birthdate;
private Color color;
private char sex;
private float weight;
private int litterId;
private Cat mother;
private Set kittens = new HashSet();
private void setId(Long id) {
this.id=id;
}
public Long getId() {
return id;
}
void setBirthdate(Date date) {
birthdate = date;
}
public Date getBirthdate() {
return birthdate;
}
void setWeight(float weight) {
this.weight = weight;
}
public float getWeight() {
return weight;
}
public Color getColor() {
return color;
}
void setColor(Color color) {
this.color = color;
}
void setSex(char sex) {
this.sex=sex;
}
public char getSex() {
return sex;
}
void setLitterId(int id) {
this.litterId = id;
}
public int getLitterId() {
return litterId;
}
void setMother(Cat mother) {
this.mother = mother;
}
public Cat getMother() {
return mother;
}
void setKittens(Set kittens) {
this.kittens = kittens;
}
public Set getKittens() {
return kittens;
}
// addKitten not needed by Hibernate
public void addKitten(Cat kitten) {
kitten.setMother(this);
kitten.setLitterId( kittens.size() );
kittens.add(kitten);
}
}

There are four main rules to follow here:

这里要遵循四条主要的规则：

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

Cat为它的所有持久化字段声明了访问方法。很多其他ORM工具直接对 实例变量进行持久化。我们相信从持久化机制中分离这种实现细节要好得多。 Hibernate持久化JavaBeans风格的属性，认可如下形式的方法名： getFoo, isFoo 和 setFoo。 如果需要，你总是可以切换特定的属性的指示字段的访问方法。

属性不需要要声明为public的。Hibernate默认使用 protected或private的get/set方法对， 对属性进行持久化。

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

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

4.1.3. 提供一个标识属性（identifier property）（可选）

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

标识符属性是可选的。可以不用管它，让Hibernate内部来追踪对象的识别。 不推荐使用这个属性。

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

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

4.1.4. 使用非final的类 (可选)

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

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

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

4.2. 实现继承（Inheritance）

子类也必须遵守第一条和第二条规则。它从超类Cat继承了标识属性。

package eg;
public class DomesticCat extends Cat {
private String name;
public String getName() {
return name;
}
protected void setName(String name) {
this.name=name;
}
}

4.3. 实现equals()和hashCode()

如果你有如下需求，你必须重载 equals() 和 hashCode()方法：

Hibernate保证，持久化标识（数据库的行）和仅在特定会话范围内的Java标识是等值的。因此，一旦 我们混合了从不同会话中获取的实例，如果我们希望Set有明确的语义，我们必 须实现equals() 和hashCode()。

实现equals()/hashCode()最显而易见的方法是比较两个对象 标识符的值。如果值相同，则两个对象对应于数据库的同一行，因此它们是相等的（如果都被添加到 Set，则在Set中只有一个元素）。不幸的是，对生成的标识不能 使用这种方法。Hibernate仅对那些持久化对象赋标识值，一个新创建的实例将不会有任何标识值。此外， 如果一个实例没有被保存(unsaved)，并且在一个Set中，保存它将会给这个对象 赋一个标识值。如果equals() 和 hashCode()是基于标识值 实现的，则其哈希码将会改变，违反Set的契约。建议去Hibernate的站点看关于这个 问题的全部讨论。注意，这不是一个Hibernate问题，而是一般的Java对象标识和相等的语义问题。

我们建议使用业务键值相等(Business key equality)来实现equals() 和 hashCode()。业务键值相等的意思是，equals()方法 仅仅比较来自业务键的属性，一个业务键将标识在真实世界里（一个天生的候选键） 的实例。

public class Cat {
...
public boolean equals(Object other) {
if (this == other) return true;
if ( !(other instanceof Cat) ) return false;
final Cat cat = (Cat) other;
if ( !cat.getLitterId().equals( getLitterId() ) ) return false;
if ( !cat.getMother().equals( getMother() ) ) return false;
return true;
}
public int hashCode() {
int result;
result = getMother().hashCode();
result = 29 * result + getLitterId();
return result;
}
}

注意，业务键不必是象数据库的主键那样是固定不变的（参见第 11.1.3 节 “关注对象标识(Considering object identity)”）。 对业务键而言，不可变或唯一的属性是好的候选。

4.4. 动态模型(Dynamic models)

注意，以下特性在当前是基于实验考虑的，可能会在将来改变。

运行期的持久化实体没有必要象POJO类或JavaBean对象一样表示。Hibernate也支持动态模型 （在运行期使用Map的Map）和象DOM4J的树模型那 样的实体表示。使用这种方法，你不用写持久化类，只写映射文件就行了。

Hibernate默认工作在普通POJO模式。你可以使用配置选项default_entity_mode， 对特定的SessionFactory，设置一个默认的实体表示模式。 （参见表 3.3 “ Hibernate配置属性 ”。）

下面是用Map来表示的例子。首先，在映射文件中，要声明 entity-name来代替（或外加）一个类名。

<hibernate-mapping>
<class entity-name="Customer">
<id name="id"
type="long"
column="ID">
<generator class="sequence"/>
</id>
<property name="name"
column="NAME"
type="string"/>
<property name="address"
column="ADDRESS"
type="string"/>
<many-to-one name="organization"
column="ORGANIZATION_ID"
class="Organization"/>
<bag name="orders"
inverse="true"
lazy="false"
cascade="all">
<key column="CUSTOMER_ID"/>
<one-to-many class="Order"/>
</bag>
</class>
</hibernate-mapping>

注意，虽然是用目标类名来声明关联的，但是关联的目标类型除了是POJO之外，也可以 是一个动态的实体。

在使用dynamic-map为SessionFactory 设置了默认的实体模式之后，可以在运行期使用Map的 Map。

Session s = openSession();
Transaction tx = s.beginTransaction();
Session s = openSession();
// Create a customer
Map david = new HashMap();
david.put("name", "David");
// Create an organization
Map foobar = new HashMap();
foobar.put("name", "Foobar Inc.");
// Link both
david.put("organization", foobar);
// Save both
s.save("Customer", david);
s.save("Organization", foobar);
tx.commit();
s.close();

动态映射的好处是，使原型在不需要实体类实现的情况下，快速转变时间。然而，你无法进行 编译期的类型检查，并可能由此会处理很多的运行期异常。幸亏有了Hibernate映射，它使得数 据库的schema能容易的规格化和合理化，并允许稍后添加正确的领域模型的最新实现。

实体表示模式也能在每个Session的基础上设置：

Session dynamicSession = pojoSession.getSession(EntityMode.MAP);
// Create a customer
Map david = new HashMap();
david.put("name", "David");
dynamicSession.save("Customer", david);
...
dynamicSession.flush();
dynamicSession.close()
...
// Continue on pojoSession

请注意，用EntityMode调用getSession()是在 Session的API中，而不是SessionFactory。 这样，新的Session共享底层的JDBC连接，事务，和其他的上下文信 息。这意味着，你不需要在第二个Session中调用 flush()和close()，同样的，把事务和连接的处理 交给原来的工作单元。

关于XML表示能力的更多信息可以在第 18 章 XML映射中找到。

3.1.  可编程的配置方式

一个org.hibernate.cfg.Configuration实例代表了一个应用程序中Java类型 到SQL数据库映射的完整集合. Configuration被用来构建一个(不可变的 (immutable))SessionFactory. 映射定义则由不同的XML映射定义文件编译而来.

你可以直接实例化Configuration来获取一个实例，并为它指定XML映射定义 文件. 如果映射定 义文件在类路径(classpath)中, 请使用addResource():

Configuration cfg = new Configuration()
.addResource("Item.hbm.xml")
.addResource("Bid.hbm.xml");

一个替代方法（有时是更好的选择）是，指定被映射的类，让Hibernate帮你寻找映射定义文件:

Configuration cfg = new Configuration()
.addClass(org.hibernate.auction.Item.class)
.addClass(org.hibernate.auction.Bid.class);

Hibernate将会在类路径(classpath)中寻找名字为 /org/hibernate/auction/Item.hbm.xml和 /org/hibernate/auction/Bid.hbm.xml映射定义文件. 这种方式消除了任何对文件名的硬编码(hardcoded).

Configuration也允许你指定配置属性:

Configuration cfg = new Configuration()
.addClass(org.hibernate.auction.Item.class)
.addClass(org.hibernate.auction.Bid.class)
.setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect")
.setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
.setProperty("hibernate.order_updates", "true");

当然这不是唯一的传递Hibernate配置属性的方式, 其他可选方式还包括:

如果想尽快体验Hbernate, hibernate.properties是最简单的方式.

Configuration实例是一个启动期间（startup-time）的对象, 一旦SessionFactory创建完成它就被丢弃了.

3.2.  获得SessionFactory

当所有映射定义被Configuration解析后, 应用程序必须获得一个用于构造Session实例的工厂. 这个工厂将被应用程序的所有线程共享:

SessionFactory sessions = cfg.buildSessionFactory();

Hibernate允许你的应用程序创建多个SessionFactory实例. 这对 使用多个数据库的应用来说很有用.

3.3.  JDBC连接

通常你希望SessionFactory来为你创建和缓存(pool)JDBC连接. 如果你采用这种方式, 只需要如下例所示那样，打开一个Session:

Session session = sessions.openSession(); // open a new Session

一旦你需要进行数据访问时, 就会从连接池(connection pool)获得一个JDBC连接.

为了使这种方式工作起来, 我们需要向Hibernate传递一些JDBC连接的属性. 所有Hibernate属性的名字和语义都在org.hibernate.cfg.Environment中定义. 我们现在将描述JDBC连接配置中最重要的设置.

如果你设置如下属性，Hibernate将使用java.sql.DriverManager来获得(和缓存)JDBC连接 :

但Hibernate自带的连接池算法相当不成熟. 它只是为了让你快些上手，不适合用于产品系统或性能测试中。 出于最佳性能和稳定性考虑你应该使用第三方的连接池。只需要连接池的特定设置替换 hibernate.connection.pool_size。这将关闭Hibernate自带的连接池. 例如, 你可能会想用C3P0.

C3P0是一个随Hibernate一同分发的开源的JDBC连接池, 它位于lib目录下。 如果你设置了hibernate.c3p0.*相关的属性, Hibernate将使用 C3P0ConnectionProvider来缓存JDBC连接. 如果你更原意使用Proxool, 请参考发 行包中的hibernate.properties并到Hibernate网站获取更多的信息.

这是一个使用C3P0的hibernate.properties样例文件:

hibernate.connection.driver_class = org.postgresql.Driver
hibernate.connection.url = jdbc:postgresql://localhost/mydatabase
hibernate.connection.username = myuser
hibernate.connection.password = secret
hibernate.c3p0.min_size=5
hibernate.c3p0.max_size=20
hibernate.c3p0.timeout=1800
hibernate.c3p0.max_statements=50
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect

为了能在应用程序服务器(application server)中使用Hibernate, 你应当总是将Hibernate 配置成注册在JNDI中的Datasource处获得连接，你至少需要设置下列属性中的一个:

这里有一个使用应用程序服务器JNDI数据源的hibernate.properties样例文件:

hibernate.connection.datasource = java:/comp/env/jdbc/test
hibernate.transaction.factory_class = \
org.hibernate.transaction.JTATransactionFactory
hibernate.transaction.manager_lookup_class = \
org.hibernate.transaction.JBossTransactionManagerLookup
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect

从JNDI数据源获得的JDBC连接将自动参与应用程序服务器中容器管理的事务(container-managed transactions)中去.

任何连接(connection)配置属性的属性名要以"hibernate.connnection"前缀开头. 例如, 你可能会使用hibernate.connection.charSet来指定charSet.

通过实现org.hibernate.connection.ConnectionProvider接口，你可以定义属于 你自己的获得JDBC连接的插件策略。通过设置hibernate.connection.provider_class， 你可以选择一个自定义的实现.

3.4.  可选的配置属性

有大量属性能用来控制Hibernate在运行期的行为. 它们都是可选的, 并拥有适当的默认值.

警告: 其中一些属性是"系统级(system-level)的". 系统级属性可以通过java -Dproperty=value或 hibernate.properties来设置, 而不能用上面描述的其他方法来设置.

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

hibernate.query.substitutions toLowercase=LOWER

3.5.  日志

Hibernate使用Apache commons-logging来为各种事件记录日志.

commons-logging将直接输出到Apache Log4j(如果在类路径中包括log4j.jar)或 JDK1.4 logging (如果运行在JDK1.4或以上的环境下). 你可以从http://jakarta.apache.org 下载Log4j. 要使用Log4j，你需要将log4j.properties文件放置在类路径下, 随Hibernate 一同分发的样例属性文件在src/目录下.

我们强烈建议你熟悉一下Hibernate的日志消息. 在不失可读性的前提下， 我们做了很多工作，使Hibernate的日志可能地详细. 这是必要的查错利器. 最令人感兴趣的日志分类有如下这些:

在使用Hibernate开发应用程序时, 你应当总是为org.hibernate.SQL 开启debug级别的日志记录,或者开启hibernate.show_sql属性来代替它。.

3.6.  实现NamingStrategy

org.hibernate.cfg.NamingStrategy接口允许你为数据库中的对象和schema 元素指定一个“命名标准”.

你可能会提供一些通过Java标识生成数据库标识或将映射定义文件中"逻辑"表/列名处理成"物理"表/列名的规则. 这个特性有助于减少冗长的映射定义文件.

在加入映射定义前，你可以调用 Configuration.setNamingStrategy()指定一个不同的命名策略:

SessionFactory sf = new Configuration()
.setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
.addFile("Item.hbm.xml")
.addFile("Bid.hbm.xml")
.buildSessionFactory();

org.hibernate.cfg.ImprovedNamingStrategy是一个内建的命名策略, 对 一些应用程序而言，可能是非常有用的起点.

3.7.  XML配置文件

另一个配置方法是在hibernate.cfg.xml文件中指定一套完整的配置. 这个文件可以当成hibernate.properties的替代。 若两个文件同时存在，它将重载前者的属性.

XML配置文件被默认是放在CLASSPATH的根目录下. 这是一个例子:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
<!-- 以/jndi/name绑定到JNDI的SessionFactory实例 -->
<session-factory
name="java:hibernate/SessionFactory">
<!-- 属性 -->
<property name="connection.datasource">java:/comp/env/jdbc/MyDB</property>
<property name="dialect">org.hibernate.dialect.MySQLDialect</property>
<property name="show_sql">false</property>
<property name="transaction.factory_class">
org.hibernate.transaction.JTATransactionFactory
</property>
<property name="jta.UserTransaction">java:comp/UserTransaction</property>
<!-- 映射定义文件 -->
<mapping resource="org/hibernate/auction/Item.hbm.xml"/>
<mapping resource="org/hibernate/auction/Bid.hbm.xml"/>
<!-- 缓存设置 -->
<class-cache class="org.hibernate.auction.Item" usage="read-write"/>
<class-cache class="org.hibernate.auction.Bid" usage="read-only"/>
<collection-cache class="org.hibernate.auction.Item.bids" usage="read-write"/>
</session-factory>
</hibernate-configuration>

如你所见, 这个方法优势在于，在配置文件中指出了映射定义文件的名字. 一旦你需要调整Hibernate的缓存， hibernate.cfg.xml也是更方便. 注意，使用hibernate.properties还是 hibernate.cfg.xml完全是由你来决定, 除了上面提到的XML语法的优势之外, 两者是等价的.

使用XML配置，使得启动Hibernate变的异常简单, 如下所示，一行代码就可以搞定：

SessionFactory sf = new Configuration().configure().buildSessionFactory();

你可以使用如下代码来添加一个不同的XML配置文件

SessionFactory sf = new Configuration()
.configure("catdb.cfg.xml")
.buildSessionFactory();

3.8.  J2EE应用程序服务器的集成

针对J2EE体系,Hibernate有如下几个集成的方面:

如果应用程序服务器抛出"connection containment"异常, 根据你的环境，也许该将配置属性 hibernate.connection.release_mode设为after_statement.

<?xml version="1.0"?>
<server>
<mbean code="org.hibernate.jmx.HibernateService"
name="jboss.jca:service=HibernateFactory,name=HibernateFactory">
<!-- 必须的服务 -->
<depends>jboss.jca:service=RARDeployer</depends>
<depends>jboss.jca:service=LocalTxCM,name=HsqlDS</depends>
<!-- 将Hibernate服务绑定到JNDI -->
<attribute name="JndiName">java:/hibernate/SessionFactory</attribute>
<!-- 数据源设置 -->
<attribute name="Datasource">java:HsqlDS</attribute>
<attribute name="Dialect">org.hibernate.dialect.HSQLDialect</attribute>
<!-- 事务集成 -->
<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>
<!-- 抓取选项 -->
<attribute name="MaximumFetchDepth">5</attribute>
<!-- 二级缓存 -->
<attribute name="SecondLevelCacheEnabled">true</attribute>
<attribute name="CacheProviderClass">org.hibernate.cache.EhCacheProvider</attribute>
<attribute name="QueryCacheEnabled">true</attribute>
<!-- 日志 -->
<attribute name="ShowSqlEnabled">true</attribute>
<!-- 映射定义文件 -->
<attribute name="MapResources">auction/Item.hbm.xml,auction/Category.hbm.xml</attribute>
</mbean>
</server>

2.1. 概况(Overview)

一个非常简要的Hibernate架构的概要图：

从这个图可以看出，Hibernater使用数据库和配置信息来为应用程序提供持久化服务（以及持久的对象）。

我们来更详细地看一下Hibernate运行时架构。由于Hibernate非常灵活，且支持数种应用方案， 所以我们这只描述一下两种极端的情况。“轻型”的架构方案，要求应用程序提供自己的JDBC 连接并管理自己的事务。这种方案使用了Hibernate API的最小子集：

“全面解决”的架构方案，将应用层从底层的JDBC/JTA API中抽象出来，而让Hibernate来处理这些细节。

Heres some definitions of the objects in the diagrams: 图中各个对象的定义如下：

在一个“轻型”的架构中，应用程序可能绕过 Transaction/TransactionFactory 以及 ConnectionProvider 等API直接跟JTA或JDBC打交道。

2.2. 实例状态

一个持久化类的实例可能处于三种不同状态中的某一种。 这三种状态的定义则与所谓的持久化上下文(persistence context)有关。 Hibernate的Session对象就是这个所谓的持久化上下文：

2.3. JMX整合

JMX是管理Java组件(Java components)的J2EE规范。 Hibernate 可以通过一个JMX标准服务来管理。 在这个发行版本中，我们提供了一个MBean接口的实现,即 org.hibernate.jmx.HibernateService。

想要看如何在JBoss应用服务器上将Hibernate部署为一个JMX服务的例子，您可以参考JBoss用户指南。 我们现在说一下在Jboss应用服务器上，使用JMX来部署Hibernate的好处：

这些选项更多的描述，请参考JBoss 应用程序用户指南。

将Hibernate以部署为JMX服务的另一个好处，是可以查看Hibernate的运行时统计信息。参看 第 3.4.6 节 “ Hibernate的统计(statistics)机制 ”.

2.4. 对JCA的支持

Hibernate也可以被配置为一个JCA连接器（JCA connector）。更多信息请参看网站。 请注意，Hibernate对JCA的支持，仍处于实验性质。

1.1. 开始Hibernate之旅

这份教程描述如何在Apache Tomcat servlet容器中为web应用程序配置Hibernate 3.0(我们使用Tomcat 4.1版本，与5.0版本差别很小)。Hibernate在大多数主流J2EE应用服务器 的运行环境中都可以工作良好，甚至也可以在独立Java应用程序中使用。在本教程中使用的示例数据库系统是PostgreSQL 7.4,只需要修改Hibernate SQL语言配置与连接属性，就可以 很容易的支持其他数据库了。

第一步，我们必须拷贝所有需要的库文件到Tomcat安装目录中。在这篇教程中，我们使用一个独立的web Context配置（webapps/quickstart）。我们确认全局库文件（TOMCAT/common/lib）和本web应用程序上下文的路径（对于jar来说是webapps/quickstart/WEB-INF/lib，对于class文件来说是webapps/quickstart/WEB-INF/classes）能够被类装载器classloder检索到。我们把这两个类装载器级别分别称做全局类路径(global classpath)和上下文类路径(context classpath)。

现在，把这些库文件copy到两个类路径去:

接下来我们来配置在Tomcat和Hibernate中共用的数据库连接池。也就是说Tomcat会提供经过池处理的JDBC连接（用它内置的DBCP连接池），Hibernate通过JNDI方式来请求获得JDBC连接。作为替代方案，你也可以让Hibernate自行管理连接池。Tomcat把连接池绑定到JNDI,我们要在Tomcat的主配置文件（TOMCAT/conf/server.xml）中加一个资源声明:

<Context path="/quickstart" docBase="quickstart">
<Resource name="jdbc/quickstart" scope="Shareable" type="javax.sql.DataSource"/>
<ResourceParams name="jdbc/quickstart">
<parameter>
<name>factory</name>
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
</parameter>
<!-- DBCP database connection settings -->
<parameter>
<name>url</name>
<value>jdbc:postgresql://localhost/quickstart</value>
</parameter>
<parameter>
<name>driverClassName</name><value>org.postgresql.Driver</value>
</parameter>
<parameter>
<name>username</name>
<value>quickstart</value>
</parameter>
<parameter>
<name>password</name>
<value>secret</value>
</parameter>
<!-- DBCP connection pooling options -->
<parameter>
<name>maxWait</name>
<value>3000</value>
</parameter>
<parameter>
<name>maxIdle</name>
<value>100</value>
</parameter>
<parameter>
<name>maxActive</name>
<value>10</value>
</parameter>
</ResourceParams>
</Context>

我们在这个例子中要配置的上下文叫做quickstart，它位于TOMCAT/webapp/quickstart目录下。如果要访问这个应用程序,在你的浏览器中输入http://localhost:8080/quickstart就可以了(当然，在后面加上在你的web.xml文件中配置好你的servlet)。你现在可以创建一个只含有空process()的简单servlet了。

Tomcat现在通过JNDI的方式：java:comp/env/jdbc/quickstart来提供连接。如果你在配置连接池遇到问题，请查阅Tomcat文档。如果你遇到了JDBC驱动所报的exception出错信息，请在没有Hibernate的环境下，先测试JDBC连接池本身是否配置正确。Tomcat和JDBC的配置教程可以在Web上查到。

下一步就是配置Hibernate。首先Hibernate必须知道它如何获得JDBC连接，在这里我们使用基于XML格式的Hibernate配置文件。当然使用properties文件的进行配置，但缺少一些XML语法的特性。这个XML配置文件必须放在上下文类路径(WEB-INF/classes)下面，命名为hibernate.cfg.xml:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration
PUBLIC "-//Hibernate/Hibernate Configuration DTD//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
<session-factory>
<property name="connection.datasource">java:comp/env/jdbc/quickstart</property>
<property name="show_sql">false</property>
<property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>
<!-- Mapping files -->
<mapping resource="Cat.hbm.xml"/>
</session-factory>
</hibernate-configuration>

在这里我们关闭了SQL命令的log，同时告诉Hibernate使用哪种SQL数据库用语(Dialet)，以及如何得到JDBC连接（通过 Tomcat声明绑定的JNDI地址）。Dialet是必需配置的，因为不同的数据库都和"SQL标准"有一些出入。不用担心，Hibernate会替你处理这些差异，Hibernate支持所有主流的商业和开放源代码数据库。

SessionFactory是Hibernate的的一个概念，表示对应一个数据存储源。通过创建多个XML配置文件并也在你的程序中创建多个Configuration和SessionFactory对象，就可以支持多个数据库了。

在hibernate.cfg.xml中的最后一个元素声明了Cat.hbm.xml，这是一个Hibernate XML映射文件，对应于持久化类Cat。这个文件包含了把Cat POJO类映射到数据库表（或多个数据库表）的元数据。我们稍后就回来看这个文件。下一步让我们先编写这个POJO类，然后在声明它的映射元数据。

1.2. 第一个持久化类

Hibernate使用简单的Java对象(Plain Old Java Objects ,就是POJOs,有时候也称作Plain Ordinary Java Objects）这种编程模型来进行持久化。一个POJO很像JavaBean,通过getter和setter方法访问其属性，对外则隐藏了内部实现的细节(假若需要的话,Hibernate也可以直接访问其属性字段)。

package org.hibernate.examples.quickstart;
public class Cat {
private String id;
private String name;
private char sex;
private float weight;
public Cat() {
}
public String getId() {
return id;
}
private void setId(String id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public char getSex() {
return sex;
}
public void setSex(char sex) {
this.sex = sex;
}
public float getWeight() {
return weight;
}
public void setWeight(float weight) {
this.weight = weight;
}
}

Hibernate对属性使用的类型不加任何限制。所有的Java JDK类型和原始类型（比如String,char和Date)都可以被映射，也包括Java 集合（Java collections framework)中的类。你可以把它们映射成为值，值集合，或者与其他实体类相关联。id是一个特殊的属性，代表了这个类的数据库标识符(主键)，对于类似于Cat这样的实体类我们强烈建议使用。Hibernate也可以使用内部标识符，但这样我们会失去一些程序架构方面的灵活性。

持久化类不需要实现什么特别的接口，也不需要从一个特别的持久化根类继承下来。Hibernate也不需要使用任何编译期处理，比如字节码增强操作，它独立的使用Java反射机制和运行时类增强（通过CGLIB）。所以不依赖于Hibernate，我们就可以把POJO的类映射成为数据库表。

1.3. 映射cat

Cat.hbm.xml映射文件包含了对象/关系映射（O/R Mapping）所需的元数据。元数据包含持久化类的声明和属性到数据库的映射（指向字段和其他实体的外键关联）。

<?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>
<class name="org.hibernate.examples.quickstart.Cat" table="CAT">
<!-- A 32 hex character is our surrogate key. It's automatically
generated by Hibernate with the UUID pattern. -->
<id name="id" type="string" unsaved-value="null" >
<column name="CAT_ID" sql-type="char(32)" not-null="true"/>
<generator class="uuid.hex"/>
</id>
<!-- A cat has to have a name, but it shouldn' be too long. -->
<property name="name">
<column name="NAME" length="16" not-null="true"/>
</property>
<property name="sex"/>
<property name="weight"/>
</class>
</hibernate-mapping>

每个持久化类都应该有一个标识属性（实际上，这个类只代表实体，而不是独立的值类型类，后者会被映射称为实体对象中的一个组件）。这个属性用来区分持久化对象：如果catA.getId().equals(catB.getId())结果是true的话，这两个Cat就是相同的。这个概念称为数据库标识。Hiernate 附带了几种不同的标识符生成器，用于不同的场合（包括数据库本地的顺序(sequence)生成器、hi/lo高低位标识模式、和程序自己定义的标识符）。我们在这里使用UUID生成器（只在测试时建议使用，如果使用数据库自己生成的整数类型的键值更好），并指定CAT表中的CAT_ID字段（作为表的主键）存放生成的标识值。

Cat的其他属性都映射到同一个表的字段。对name属性来说，我们把它显式地声明映射到一个数据库字段。如果数据库schema是通过由映射声明使用Hibernate的SchemaExport工具自动生成的（作为SQL DDL指令）的话，这就特别有用。所有其它的属性都用Hibernate的默认值映射，大多数情况你都会这样做。数据库中的CAT表看起来是这样的：

 Column |         Type          | Modifiers
--------+-----------------------+-----------
cat_id | character(32)         | not null
name   | character varying(16) | not null
sex    | character(1)          |
weight | real                  |
Indexes: cat_pkey primary key btree (cat_id)

你现在可以在你的数据库中手工创建这个表了，如果你需要使用hbm2ddl工具把这个步骤自动化，请参阅第 20 章 工具箱指南。这个工具能够创建完整的SQL DDL，包括表定义，自定义的字段类型约束，惟一约束和索引。

1.4. 与Cat同乐

我们现在可以开始Hibernate的Session了。它是一个持久化管理器，我们通过它来从数据库中存取Cat。首先，我们要从SessionFactory中获取一个Session（Hibernate的工作单元）。

SessionFactory sessionFactory =
new Configuration().configure().buildSessionFactory();

通过对configure()的调用来装载hibernate.cfg.xml配置文件,并初始化成一个Configuration实例。 在创建 SessionFactory之前（它是不可变的），你可以访问Configuration来设置其他属性（甚至修改映射的元数据）。我们应该在哪儿创建SessionFactory，在我们的程序中又如何访问它呢？ SessionFactory通常只是被初始化一次，比如说通过一个load-on-startup servlet的来初始化。这意味着你不应该在serlvet中把它作为一个实例变量来持有，而应该放在其他地方。进一步的说，我们需要使用单例（Singleton）模式，我们才能更容易的在程序中访问SessionFactory。下面的方法就同时解决了两个问题：对SessionFactory的初始配置与便捷使用。

我们实现一个HibernateUtil辅助类：

import org.hibernate.*;
import org.hibernate.cfg.*;
public class HibernateUtil {
private static Log log = LogFactory.getLog(HibernateUtil.class);
private static final SessionFactory sessionFactory;
static {
try {
// Create the SessionFactory
sessionFactory = new Configuration().configure().buildSessionFactory();
} catch (Throwable ex) {
// Make sure you log the exception, as it might be swallowed
log.error("Initial SessionFactory creation failed.", ex);
throw new ExceptionInInitializerError(ex);
}
}
public static final ThreadLocal session = new ThreadLocal();
public static Session currentSession()  {
Session s = (Session) session.get();
// Open a new Session, if this Thread has none yet
if (s == null) {
s = sessionFactory.openSession();
session.set(s);
}
return s;
}
public static void closeSession() {
Session s = (Session) session.get();
if (s != null)
s.close();
session.set(null);
}
}

这个类不但在它的静态初始器中使用了SessionFactory，还使用了一个ThreadLocal变量来保存Session做为当前工作线程。在你使用这个辅助类之前，请确保你理解了thread-local变量这个Java概念。你可以在CaveatEmptor(http://caveatemptor.hibernate.org/)上找到一个更加复杂和强大的 HibernateUtil。

SessionFactory是安全线程，可以由很多线程并发访问并获取到Sessions。单个Session不是安全线程对象，它只代表与数据库之间的一次操作。Session通过SessionFactory获得并在所有的工作完成后关闭。在你servlet的process()中可以象是这么写的(省略了异常情况处理):

Session session = HibernateUtil.currentSession();
Transaction tx= session.beginTransaction();
Cat princess = new Cat();
princess.setName("Princess");
princess.setSex('F');
princess.setWeight(7.4f);
session.save(princess);
tx.commit();
HibernateUtil.closeSession();

在一个Session中，每个数据库操作都是在一个事务(transaction)中进行的，这样就可以隔离开不同的操作（甚至包括只读操作）。我们使用Hibernate的Transaction API来从底层的事务策略中（本例中是JDBC事务）脱身出来。这样，我们就不需要更改任何源代码，就可以把我们的程序部署到一个由容器管理事务的环境中去（使用JTA）。

这样你就可以随心所欲的多次调用HibernateUtil.currentSession();，你每次都会得到同一个当前线程的Session。不管是在你的servlet代码中，或者在servlet filter中还是在HTTP结果返回之前，你都必须确保这个Session在你的数据库访问工作完成后关闭。这样做还有一个好处就是可以容易的使用延迟装载（lazy initialization）：Session在渲染view层的时候仍然打开着的，所以你在遍历当前对象图的时候可以装载所需的对象。

Hibernate有不同的方法用来从数据库中取回对象。最灵活的方式就是使用Hibernate查询语言(HQL),这是一种容易学习的语言，是对SQL的面向对象的强大扩展。

Transaction tx= session.beginTransaction();
Query query = session.createQuery("select c from Cat as c where c.sex = :sex");
query.setCharacter("sex", 'F');
for (Iterator it = query.iterate(); it.hasNext();) {
Cat cat = (Cat) it.next();
out.println("Female Cat: " + cat.getName() );
}
tx.commit();

Hibernate也提供一种面向对象的按条件查询API，可以执行简洁安全类型的查询。当然，Hibernate在所有与数据库的交互中都使用PrepatedStatement和参数绑定。你也可以使用Hibernate的直接SQL查询特性，或者在特殊情况下从Session获取一个原始的JDBC连接。

1.5. 结语

在这个短小的教程中，我们对Hibernate的浅尝即止。请注意我们没有在例子中包含任何servlet相关代码。你必须自行编写servlet，并插入合适你的Hibernate代码。

请记住Hibernate作为一个数据库访问层，是与你的程序紧密相关的。通常情况下，所有其他层次都依赖持久机制。请确信你理解了这种设计的内涵。

若希望学习更复杂的例子,请参阅http://caveatemptor.hibernate.org/ 。在 http://www.hibernate.org/Documentation 也可以得到其他教程的链接。

1. 翻译说明

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

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

参与二审的人员有:Robbin,linxin.

关于我们

2. 版权声明

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

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