如何把Hibernate2.1升级到Hibernate3.0？

选自<<精通Hibernate：Java对象持久化技术详解>> 做者：孙卫琴 来源:[url]www.javathinker.org[/url]
 

1.1 Hibernate API 变化
1.1.1 包名
1.1.2 org.hibernate.classic包
1.1.3 Hibernate所依赖的第三方软件包
1.1.4 异常模型
1.1.5 Session接口
1.1.6 createSQLQuery()
1.1.7 Lifecycle 和 Validatable 接口
1.1.8 Interceptor接口
1.1.9 UserType和CompositeUserType接口
1.1.10 FetchMode类
1.1.11 PersistentEnum类
1.1.12 对Blob 和Clob的支持
1.1.13 Hibernate中供扩展的API的变化
1.2 元数据的变化
1.2.1 检索策略
1.2.2 对象标识符的映射
1.2.3 集合映射
1.2.4 DTD
1.3 查询语句的变化
1.3.1 indices()和elements()函数

尽管Hibernate 3.0 与Hibernate2.1的源代码是不兼容的，可是当Hibernate开发小组在设计Hibernate3.0时，为简化升级Hibernate版本做了周到的考虑。对于现有的基于Hibernate2.1的Java项目，能够很方便的把它升级到Hibernate3.0。

本文描述了Hibernate3.0版本的新变化，Hibernate3.0版本的变化包括三个方面：
（1）API的变化，它将影响到Java程序代码。
（2）元数据，它将影响到对象-关系映射文件。
（3）HQL查询语句。

值得注意的是， Hibernate3.0并不会彻底取代Hibernate2.1。在同一个应用程序中，容许Hibernate3.0和Hibernate2.1并存。

1.1 Hibernate API 变化

1.1.1 包名

Hibernate3.0的包的根路径为: “org.hibernate” ，而在Hibernate2.1中为“net.sf.hibernate”。这一命名变化使得Hibernate2.1和Hibernate3.0可以同时在同一个应用程序中运行。

若是但愿把已有的应用升级到Hibernate3.0，那么升级的第一步是把Java源程序中的全部“net.sf.hibernate”替换为“org.hibernate”。

Hibernate2.1中的“net.sf.hibernate.expression”包被更名为 “org.hibernate.criterion”。假如应用程序使用了Criteria API，那么在升级的过程当中，必须把Java源程序中的全部“net.sf.hibernate.expression”替换为 “org.hibernate.criterion”。

若是应用使用了除Hibernate之外的其余外部软件，而这个外部软件又引用了Hibernate的接口，那么在升级时必须十分当心。例如 EHCache拥有本身的CacheProvider： net.sf.ehcache.hibernate.Provider，在这个类中引用了Hibernate2.1中的接口，在升级应用时，能够采用如下办法之一来升级EHCache:

（1）手工修改net.sf.ehcache.hibernate.Provider类，使它引用Hibernate3.0中的接口。
（2）等到EHCache软件自己升级为使用Hibernate3.0后，使用新的EHCache软件。
（3）使用Hibernate3.0中内置的CacheProvider：org.hibernate.cache.EhCacheProvider。

1.1.2 org.hibernate.classic包

Hibernate3.0把一些被废弃的接口都转移到org.hibernate.classic中。

1.1.3 Hibernate所依赖的第三方软件包

在Hibernate3.0的软件包的lib目录下的README.txt文件中，描述了Hibernate3.0所依赖的第三方软件包的变化。

1.1.4 异常模型

在Hibernate3.0中，HibernateException异常以及它的全部子类都继承了java.lang.RuntimeException。所以在编译时，编译器不会再检查HibernateException。

1.1.5 Session接口

在Hibernate3.0中，原来Hibernate2.1的Session接口中的有些基本方法也被废弃，但为了简化升级，这些方法依然是可用的，能够经过org.hibernate.classic.Session子接口来访问它们，例如：

org.hibernate.classic.Session session=sessionFactory.openSession();
session.delete("delete from Customer ");

在Hibernate3.0中，org.hibernate.classic.Session接口继承了 org.hibernate.Session接口，在org.hibernate.classic.Session接口中包含了一系列被废弃的方法，如 find()、interate()等。SessionFactory接口的openSession()方法返回 org.hibernate.classic.Session类型的实例。若是但愿在程序中彻底使用Hibernate3.0，能够采用如下方式建立 Session实例：

org.hibernate.Session session=sessionFactory.openSession();

若是是对已有的程序进行简单的升级，而且但愿仍然调用Hibernate2.1中Session的一些接口，能够采用如下方式建立Session实例：

org.hibernate.classic.Session session=sessionFactory.openSession();

在Hibernate3.0中，Session接口中被废弃的方法包括：
* 执行查询的方法：find()、iterate()、filter()和delete(String hqlSelectQuery)
* saveOrUpdateCopy()

Hibernate3.0一概采用createQuery()方法来执行全部的查询语句，采用DELETE 查询语句来执行批量删除，采用merge()方法来替代 saveOrUpdateCopy()方法。

提示：在Hibernate2.1中，Session的delete()方法有几种重载形式，其中参数为HQL查询语句的delete() 方法在Hibernate3.0中被废弃，而参数为Ojbect类型的的delete()方法依然被支持。delete(Object o)方法用于删除参数指定的对象，该方法支持级联删除。

Hibernate2.1没有对批量更新和批量删除提供很好的支持，参见<<精通Hibernate>>一书的第13章的 13.1.1节（批量更新和批量删除），而Hibernate3.0对批量更新和批量删除提供了支持，可以直接执行批量更新或批量删除语句，无需把被更新或删除的对象先加载到内存中。如下是经过Hibernate3.0执行批量更新的程序代码：

Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();

String hqlUpdate = "update Customer set name = :newName where name = :oldName";
int updatedEntities = s.createQuery( hqlUpdate )
.setString( "newName", newName )
.setString( "oldName", oldName )
.executeUpdate();
tx.commit();
session.close();

如下是经过Hibernate3.0执行批量删除的程序代码：

Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();

String hqlDelete = "delete Customer where name = :oldName";
int deletedEntities = s.createQuery( hqlDelete )
.setString( "oldName", oldName )
.executeUpdate();
tx.commit();
session.close();

1.1.6 createSQLQuery()

在Hibernate3.0中，Session接口的createSQLQuery()方法被废弃，被移到org.hibernate.classic.Session接口中。Hibernate3.0采用新的SQLQuery接口来完成相同的功能。

1.1.7 Lifecycle 和 Validatable 接口

Lifecycle和Validatable 接口被废弃，而且被移到org.hibernate.classic包中。

1.1.8 Interceptor接口

在Interceptor 接口中加入了两个新的方法。用户建立的Interceptor实现类在升级的过程当中，须要为这两个新方法提供方法体为空的实现。此外，instantiate()方法的参数做了修改，isUnsaved()方法被更名为isTransient()。

1.1.9 UserType和CompositeUserType接口

在UserType和CompositeUserType接口中都加入了一些新的方法，这两个接口被移到org.hibernate.usertype包中，用户定义的UserType和CompositeUserType实现类必须实现这些新方法。

Hibernate3.0提供了ParameterizedType接口，用于更好的重用用户自定义的类型。

1.1.10 FetchMode类

FetchMode.LAZY 和 FetchMode.EAGER被废弃。取而代之的分别为FetchMode.SELECT 和FetchMode.JOIN。

1.1.11 PersistentEnum类

PersistentEnum被废弃并删除。已经存在的应用应该采用UserType来处理枚举类型。

1.1.12 对Blob 和Clob的支持

Hibernate对Blob和Clob实例进行了包装，使得那些拥有Blob或Clob类型的属性的类的实例能够被游离、序列化或反序列化，以及传递到merge()方法中。

1.1.13 Hibernate中供扩展的API的变化

org.hibernate.criterion、 org.hibernate.mapping、 org.hibernate.persister和org.hibernate.collection 包的结构和实现发生了重大的变化。多数基于Hibernate
2.1 的应用不依赖于这些包，所以不会被影响。若是你的应用扩展了这些包中的类，那么必须很是当心的对受影响的程序代码进行升级。

1.2 元数据的变化

1.2.1 检索策略

在Hibernate2.1中，lazy属性的默认值为“false”，而在Hibernate3.0中，lazy属性的默认值为“true”。在升级映射文件时，若是原来的映射文件中的有关元素，如<set>、<class>等没有显式设置lazy属性，那么必须把它们都显式的设置为lazy=“true”。若是以为这种升级方式很麻烦，能够采起另外一简单的升级方式：在<hibernate-mapping> 元素中设置: default-lazy=“false”。

1.2.2 对象标识符的映射

unsaved-value属性是可选的，在多数状况下，Hibernate3.0将把unsaved-value="0" 做为默认值。

在Hibernate3.0中，当使用天然主键和游离对象时，再也不强迫实现Interceptor.isUnsaved()方法。若是没有设置这个方法，当Hibernate3.0没法区分对象的状态时，会查询数据库，来判断这个对象究竟是临时对象，仍是游离对象。不过，显式的使用 Interceptor.isUnsaved()方法会得到更好的性能，由于这能够减小Hibernate直接访问数据库的次数。

1.2.3 集合映射

<index>元素在某些状况下被<list-index>和<map-key>元素替代。此外， Hibernate3.0用<map-key-many-to-many> 元素来替代原来的<key-many-to-many>.元素，用<composite-map-key>元素来替代原来的 <composite-index>元素。

1.2.4 DTD

对象-关系映射文件中的DTD文档，由原来的：
[url]http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd[/url]
改成：
[url]http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd[/url]

1.3 查询语句的变化

Hibernate3.0 采用新的基于ANTLR的HQL/SQL查询翻译器，不过，Hibernate2.1的查询翻译器也依然存在。在Hibernate的配置文件中，hibernate.query.factory_class属性用来选择查询翻译器。例如：
（1）选择Hibernate3.0的查询翻译器：
hibernate.query.factory_class= org.hibernate.hql.ast.ASTQueryTranslatorFactory
（2）选择Hibernate2.1的查询翻译器
hibernate.query.factory_class= org.hibernate.hql.classic.ClassicQueryTranslatorFactory

提示：ANTLR是用纯Java语言编写出来的一个编译工具，它可生成Java语言或者是C++的词法和语法分析器，并可产生语法分析树并对该树进行遍历。ANTLR因为是纯Java的，所以能够安装在任意平台上，可是须要JDK的支持。

Hibernate开发小组尽力保证Hibernate3.0的查询翻译器可以支持Hibernate2.1的全部查询语句。不过，对于许多已经存在的应用，在升级过程当中，也不妨仍然使用Hibernate2.1的查询翻译器。
值得注意的是， Hibernate3.0的查询翻译器存在一个Bug：不支持某些theta-style连结查询方言：如Oracle8i的OracleDialect 方言、Sybase11Dialect。解决这一问题的办法有两种：（1）改成使用支持ANSI-style连结查询的方言，如 Oracle9Dialect,（2）若是升级的时候遇到这一问题，那么仍是改成使用Hibernate2.1的查询翻译器。

1.3.1 indices()和elements()函数

在HQL的select子句中废弃了indices()和elements()函数，由于这两个函数的语法很让用户费解，能够用显式的链接查询语句来替代 select elements(...) 。而在HQL的where子句中，仍然可使用elements()函数。