Hibernate3 Migration Guide (翻译)

:D 这是本人第一次发表文章，翻译水平有限，难免谬误重重，望各位读者不吝赐教。 
[e-mail]

源文：http://www.hibernate.org/Documentation/Hibernate3MigrationGuide#A7

Hibernate 3.0 不完全兼容 Hibernate 2.1, 并且不是各简单的替代2.1. 相反, 对于改进后的3.0是切切实实的把code 和 metadata 都大大的改变了，如果没有太多的经验的话，移植到3.0会遇到许多意想不到的结果与困难。
本文简单的说明了Hibernate 2.1 与 Hibernate 3.0的不同； Hibernate 3.0有一些新的改进细节对于现有程序的改进会有很大的帮助。
改进列表如下:（Hibernate 2.1 和 Hibernate 3.0在同一个程序中能共存）

• API Changes
o Package naming
o org.hibernate.classic package
o Dependencies
o Exception model
o Session interface
o createSQLQuery()
o Lifecycle and Validatable interfaces
o Interceptor interface
o UserType and CompositeUserType interfaces
o FetchMode
o PersistentEnum
o Blob and Clob support
o Changes to extension APIs
• Metadata Changes
o Association fetching strategies
o Identifier mappings
o Collection mappings
o DTD• Query Language Changes
o indices() and elements() functions
• BEA Weblogic issues（没使用过，所以没有发言权无后续部分）
 
API Changes

Package naming
对于 Hibernate3 包结构已由net.sf.hibernate变为  org.hibernate.在导入包中首先要改变这一处。
net.sf.hibernate.expression ----》org.hibernate.criterion.在程序中用Criteria queries需要一个further text/search来适应它。
在使用IDE时 对于EHCache你需要加倍注意（它在程序中的引用是否是Hibernate packages 下的org.hibernate.cache.EhCacheProvider）
org.hibernate.classic package在它下的一些接口已经提倡了，现已改到org.hibernate.classic包下了；

Dependencies
你需要查看第三方库文件在lib/README.txt，看看哪些是已更新，哪些是是必需的。
Session interface
在org.hibernate.Session interface中，一些多余的方法已经被抛弃了. 然而，为了移植方便，有些方法还是暂时保留了下来如:
• 查询: find(), iterate(), filter(), delete()
• saveOrUpdateCopy()
由些看来classic也不是长久之策,以Gavin的观点,所有的query操作都应该由createQuery()实现才是标准。

createSQLQuery()
重载后的createSQLQuery()已经移到org.hibernate.classic.Session. 新的 SQLQuery接口比以前的功能实现多一些。不过对于已存的程序代码可以继续用前一点所说的方法。

Lifecycle and Validatable interfaces

The Lifecycle and Validatable 接口已经不提倡，并且已经移到了 org.hibernate.classic 包下. Hibernate3开发团队认为域模型不应依靠 persistence-specific APIs. Hibernate3 程序应该用拦截器或者新建一个事件框架.对于已存程序代码可以继续使用之，暂时没有性命之忧。

Interceptor interface
新增了两个方法， 已有的 interceptors代码需要更新实现. instantiate()已经由类对象改为取一个字符值的实体名。 isUnsaved()方法已改为isTransient().
UserType and CompositeUserType interfaces
它们都增加了一些方法实现来支持Hibernate3. 它们移到org.hibernate.usertype包下.已存代码需要更新实现

Note: Hibernate3 提供了一个 ParameterizedType 接口允许更好的重用 user type 实现.

FetchMode

FetchMode.LAZY 和 FetchMode.EAGER 被 deprecated. 替代方法是 FetchMode.SELECT 和FetchMode

PersistentEnum
不提倡使用的PersistentEnum重获新生,已有程序可以用UserType 来处理persistent enumerated 类型了啦.
Blob and Clob support
Hibernate 包裹了它俩的实例，以便允许含有此类型的类可以被 detached, serialized, deserialized, and passed to merge(). 相反,它不能转换厂商指定的type (eg. oracle.sql.CLOB). 你需要用 getWrappedClob() 或者getWrappedBlob() 方法:
clob = (oracle.sql.CLOB) ( (org.hibernate.lob.SerializableClob) foo.getText() ).getWrappedClob();
我们期待Oracle整理JDBC driver， 可以不用以上方法。

Changes to extension APIs
对于org.hibernate.criterion, org.hibernate.mapping, org.hibernate.persister， org.hibernate.collection 需要大量的重构工作. 大多数的 Hibernate 2.1 程序没有使用以上的这些包，将来也不会用（最好），如果你的程序中含有此类引用，那你就死定了，你可能要小心再小心地移植。

Metadata Changes

Association fetching strategies以前实现映射所需的类和集合用lazy="true", 现在它的默认值是"lazy="true"".如果你还是怀念H2中的一次性load出PO而不是proxy,那么在hbm文件中的class 中声明lazy="false"即可.
对于 outer-join attribute 已经 deprecated.用 fetch="join" 和 fetch="select" 替代 outer-join="true" 和outer-join="false". 现有程序可以继续用以前的方法。

*****[swf width= height=]关于Lazy问题在Hibernate官方论坛的帖子[/swf] *****
http://forum.hibernate.org/viewtopic.php?t=939532&postdays=0&postorder=asc&start=0

Identifier mappings

对于unsaved-value attribute 现在是可选的了,大多数情况下Hibernate会用它的默认值是unsaved-value="0"； 是合情合理的。
Note: In Hibernate3, 不需要继承Interceptor.isUnsaved()当detached对象或用普通键；当对象是新的或detached的情况下Hibernate会终止查询数据库. 然而, 用Interceptor.isUnsaved() 会引起高开销，直到避免数据库查询。
Collection mappings
对于 <index>元素已是半deprecated, <list-index> 和 <map-key> 为首选. <map-key-many-to-many> 优于<key-many-to-many>. <composite-map-key> 优于<composite-index>.

DTD

更新你的 hbm XML files. http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd to http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd 在 DOCTYPE中.
Query Language Changes
Hibernate3 已经是一个全新的基于ANTLR（ANother Tool for Language Recognition(它让你能够用一个文本文件来描述自己的语言。如果你把ANTLR指向这个文件，那么它将生成一个能够处理你新语言的词法分析器（Lexer）和解释器。词法分析器会把字符翻译成为语言符号，而解释器则利用这些符号来完成任务。一旦ANTLR为你的微型语言生成了这些类，你就可以把它们用在自己的应用程序里来操控系统了)) HQL/SQL query translator了. 但是, Hibernate 2.1 query parser 还可以继续使用，在Hibernate属性设置hibernate.query.factory_classk中是可选的。可能的值： org.hibernate.hql.ast.ASTQueryTranslatorFactory, 对于新的query parser,然而对于先前的则使用 org.hibernate.hql.classic.ClassicQueryTranslatorFactory.但是，现有的程序只能用先前的query parser在移植过来时.而不能用新的query parser。

在Hibernate 1.x 中语法 "from f in class bar.Foo" 是不允许的,用 "from bar.Foo as f" 或"from bar.Foo f".
注意: 有一个已知的bug 波及了dialects with theta-style outer joins (eg. OracleDialect for Oracle 8i, TimesTen dialect, Sybase11Dialect).试图使dialect 支持 ANSI-style joins (eg. Oracle9Dialect),（如果你经历过这个问题的话）会退到先前的query parser
indices() and elements() functions
对于indices()和elements()它们以后会很少再出现了（因为语义关系会引起用户的歧义，越来越糊涂）,但是它们还会用在where()这种地方. （Use an explicit join instead of select elements(...)）。
总体过程如下：
1． 在项目的conf中修改两个文件hibernate.cfg.xml，hibernate.properties（最重要了，结合上文所说的修改，是一个反复运行的过程）
2． 在项目的lib中增加H3包下的几个Jar,如cglib、asm等，我做的是替换了Hibernate3.0其它的jar和上一个版本的jar共存。（如果去掉旧jar,程序会报导入出错，原因是两个版本之间的类path不一致）
3． 程序LIB包需要重导
4． 程序中的hbm.xml文件的DTD需要全部修改，否则程序会运行的像上了年纪的586 。