HIBERNATE - 符合Java习惯的关系数据库持久化

Hibernate参考文档

3.2


目录

前言
1. 翻译说明
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. 总结
2. 体系结构(Architecture)
2.1. 概况(Overview)
2.2. 实例状态
2.3. JMX整合
2.4. 对JCA的支持
2.5. 上下文相关的(Contextual)Session
3. 配置
3.1. 可编程的配置方式
3.2. 获得SessionFactory
3.3. JDBC连接
3.4. 可选的配置属性
3.4.1. SQL方言
3.4.2. 外连接抓取(Outer Join Fetching)
3.4.3. 二进制流 (Binary Streams)
3.4.4. 二级缓存与查询缓存
3.4.5. 查询语言中的替换
3.4.6. Hibernate的统计(statistics)机制
3.5. 日志
3.6. 实现NamingStrategy
3.7. XML配置文件
3.8. J2EE应用程序服务器的集成
3.8.1. 事务策略配置
3.8.2. JNDI绑定的SessionFactory
3.8.3. 在JTA环境下使用Current Session context (当前session上下文)管理
3.8.4. JMX部署
4. 持久化类(Persistent Classes)
4.1. 一个简单的POJO例子
4.1.1. 实现一个默认的(即无参数的)构造方法(constructor)
4.1.2. 提供一个标识属性(identifier property)(可选)
4.1.3. 使用非final的类 (可选)
4.1.4. 为持久化字段声明访问器(accessors)和是否可变的标志(mutators)(可选)
4.2. 实现继承(Inheritance)
4.3. 实现equals()和hashCode()
4.4. 动态模型(Dynamic models)
4.5. 元组片断映射(Tuplizers)
5. 对象/关系数据库映射基础(Basic O/R Mapping)
5.1. 映射定义(Mapping declaration)
5.1.1. Doctype
5.1.1.1. EntityResolver
5.1.2. hibernate-mapping
5.1.3. class
5.1.4. id
5.1.4.1. Generator
5.1.4.2. 高/低位算法(Hi/Lo Algorithm)
5.1.4.3. UUID算法(UUID Algorithm )
5.1.4.4. 标识字段和序列(Identity columns and Sequences)
5.1.4.5. 程序分配的标识符(Assigned Identifiers)
5.1.4.6. 触发器实现的主键生成器(Primary keys assigned by triggers)
5.1.5. composite-id
5.1.6. 鉴别器(discriminator)
5.1.7. 版本(version)(可选)
5.1.8. timestamp (可选)
5.1.9. property
5.1.10. 多对一(many-to-one)
5.1.11. 一对一
5.1.12. 自然ID(natural-id)
5.1.13. 组件(component), 动态组件(dynamic-component)
5.1.14. properties
5.1.15. 子类(subclass)
5.1.16. 连接的子类(joined-subclass)
5.1.17. 联合子类(union-subclass)
5.1.18. 连接(join)
5.1.19. 键(key)
5.1.20. 字段和规则元素(column and formula elements)
5.1.21. 引用(import)
5.1.22. any
5.2. Hibernate 的类型
5.2.1. 实体(Entities)和值(values)
5.2.2. 基本值类型
5.2.3. 自定义值类型
5.3. 多次映射同一个类
5.4. SQL中引号包围的标识符
5.5. 其他元数据(Metadata)
5.5.1. 使用 XDoclet 标记
5.5.2. 使用 JDK 5.0 的注解(Annotation)
5.6. 数据库生成属性(Generated Properties)
5.7. 辅助数据库对象(Auxiliary Database Objects)
6. 集合类(Collections)映射
6.1. 持久化集合类(Persistent collections)
6.2. 集合映射( Collection mappings )
6.2.1. 集合外键(Collection foreign keys)
6.2.2. 集合元素(Collection elements)
6.2.3. 索引集合类(Indexed collections)
6.2.4. 值集合于多对多关联(Collections of values and many-to-many associations)
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)
7.5.2. 一对一(one to one)
7.5.3. 多对多(many to many)
7.6. 更复杂的关联映射
8. 组件(Component)映射
8.1. 依赖对象(Dependent objects)
8.2. 在集合中出现的依赖对象 (Collections of dependent objects)
8.3. 组件作为Map的索引(Components as Map indices )
8.4. 组件作为联合标识符(Components as composite identifiers)
8.5. 动态组件 (Dynamic components)
9. 继承映射(Inheritance Mappings)
9.1. 三种策略
9.1.1. 每个类分层结构一张表(Table per class hierarchy)
9.1.2. 每个子类一张表(Table per subclass)
9.1.3. 每个子类一张表(Table per subclass),使用辨别标志(Discriminator)
9.1.4. 混合使用“每个类分层结构一张表”和“每个子类一张表”
9.1.5. 每个具体类一张表(Table per concrete class)
9.1.6. Table per concrete class, using implicit polymorphism
9.1.7. 隐式多态和其他继承映射混合使用
9.2. 限制
10. 与对象共事
10.1. Hibernate对象状态(object states)
10.2. 使对象持久化
10.3. 装载对象
10.4. 查询
10.4.1. 执行查询
10.4.1.1. 迭代式获取结果(Iterating results)
10.4.1.2. 返回元组(tuples)的查询
10.4.1.3. 标量(Scalar)结果
10.4.1.4. 绑定参数
10.4.1.5. 分页
10.4.1.6. 可滚动遍历(Scrollable iteration)
10.4.1.7. 外置命名查询(Externalizing named queries)
10.4.2. 过滤集合
10.4.3. 条件查询(Criteria queries)
10.4.4. 使用原生SQL的查询
10.5. 修改持久对象
10.6. 修改脱管(Detached)对象
10.7. 自动状态检测
10.8. 删除持久对象
10.9. 在两个不同数据库间复制对象
10.10. Session刷出(flush)
10.11. 传播性持久化(transitive persistence)
10.12. 使用元数据
11. 事务和并发
11.1. Session和事务范围(transaction scope)
11.1.1. 操作单元(Unit of work)
11.1.2. 长对话
11.1.3. 关注对象标识(Considering object identity)
11.1.4. 常见问题
11.2. 数据库事务声明
11.2.1. 非托管环境
11.2.2. 使用JTA
11.2.3. 异常处理
11.2.4. 事务超时
11.3. 乐观并发控制(Optimistic concurrency control)
11.3.1. 应用程序级别的版本检查(Application version checking)
11.3.2. 扩展周期的session和自动版本化
11.3.3. 脱管对象(deatched object)和自动版本化
11.3.4. 定制自动版本化行为
11.4. 悲观锁定(Pessimistic Locking)
11.5. 连接释放模式(Connection Release Modes)
12. 拦截器与事件(Interceptors and events)
12.1. 拦截器(Interceptors)
12.2. 事件系统(Event system)
12.3. Hibernate的声明式安全机制
13. 批量处理(Batch processing)
13.1. 批量插入(Batch inserts)
13.2. 批量更新(Batch updates)
13.3. StatelessSession (无状态session)接口
13.4. DML(数据操作语言)风格的操作(DML-style operations)
14. HQL: Hibernate查询语言
14.1. 大小写敏感性问题
14.2. from子句
14.3. 关联(Association)与连接(Join)
14.4. join 语法的形式
14.5. select子句
14.6. 聚集函数
14.7. 多态查询
14.8. where子句
14.9. 表达式
14.10. order by子句
14.11. group by子句
14.12. 子查询
14.13. HQL示例
14.14. 批量的UPDATE和DELETE
14.15. 小技巧 & 小窍门
15. 条件查询(Criteria Queries)
15.1. 创建一个Criteria 实例
15.2. 限制结果集内容
15.3. 结果集排序
15.4. 关联
15.5. 动态关联抓取
15.6. 查询示例
15.7. 投影(Projections)、聚合(aggregation)和分组(grouping)
15.8. 离线(detached)查询和子查询
15.9. 根据自然标识查询(Queries by natural identifier)
16. Native SQL查询
16.1. 使用SQLQuery
16.1.1. 标量查询(Scalar queries)
16.1.2. 实体查询(Entity queries)
16.1.3. 处理关联和集合类(Handling associations and collections)
16.1.4. 返回多个实体(Returning multiple entities)
16.1.4.1. 别名和属性引用(Alias and property references)
16.1.5. 返回非受管实体(Returning non-managed entities)
16.1.6. 处理继承(Handling inheritance)
16.1.7. 参数(Parameters)
16.2. 命名SQL查询
16.2.1. 使用return-property来明确地指定字段/别名
16.2.2. 使用存储过程来查询
16.2.2.1. 使用存储过程的规则和限制
16.3. 定制SQL用来create,update和delete
16.4. 定制装载SQL
17. 过滤数据
17.1. Hibernate 过滤器(filters)
18. XML映射
18.1. 用XML数据进行工作
18.1.1. 指定同时映射XML和类
18.1.2. 只定义XML映射
18.2. XML映射元数据
18.3. 操作XML数据
19. 提升性能
19.1. 抓取策略(Fetching strategies)
19.1.1. 操作延迟加载的关联
19.1.2. 调整抓取策略(Tuning fetch strategies)
19.1.3. 单端关联代理(Single-ended association proxies)
19.1.4. 实例化集合和代理(Initializing collections and proxies)
19.1.5. 使用批量抓取(Using batch fetching)
19.1.6. 使用子查询抓取(Using subselect fetching)
19.1.7. 使用延迟属性抓取(Using lazy property fetching)
19.2. 二级缓存(The Second Level Cache)
19.2.1. 缓存映射(Cache mappings)
19.2.2. 策略:只读缓存(Strategy: read only)
19.2.3. 策略:读/写缓存(Strategy: read/write)
19.2.4. 策略:非严格读/写缓存(Strategy: nonstrict read/write)
19.2.5. 策略:事务缓存(transactional)
19.3. 管理缓存(Managing the caches)
19.4. 查询缓存(The Query Cache)
19.5. 理解集合性能(Understanding Collection performance)
19.5.1. 分类(Taxonomy)
19.5.2. Lists, maps 和sets用于更新效率最高
19.5.3. Bag和list是反向集合类中效率最高的
19.5.4. 一次性删除(One shot delete)
19.6. 监测性能(Monitoring performance)
19.6.1. 监测SessionFactory
19.6.2. 数据记录(Metrics)
20. 工具箱指南
20.1. Schema自动生成(Automatic schema generation)
20.1.1. 对schema定制化(Customizing the schema)
20.1.2. 运行该工具
20.1.3. 属性(Properties)
20.1.4. 使用Ant(Using Ant)
20.1.5. 对schema的增量更新(Incremental schema updates)
20.1.6. 用Ant来增量更新schema(Using Ant for incremental schema updates)
20.1.7. Schema 校验
20.1.8. 使用Ant进行schema校验
21. 示例:父子关系(Parent Child Relationships)
21.1. 关于collections需要注意的一点
21.2. 双向的一对多关系(Bidirectional one-to-many)
21.3. 级联生命周期(Cascading lifecycle)
21.4. 级联与未保存值(Cascades and unsaved-value)
21.5. 结论
22. 示例:Weblog 应用程序
22.1. 持久化类
22.2. Hibernate 映射
22.3. Hibernate 代码
23. 示例:复杂映射实例
23.1. Employer(雇主)/Employee(雇员)
23.2. Author(作家)/Work(作品)
23.3. Customer(客户)/Order(订单)/Product(产品)
23.4. 杂例
23.4.1. "Typed" one-to-one association
23.4.2. Composite key example
23.4.3. 共有组合键属性的多对多(Many-to-many with shared composite key attribute)
23.4.4. Content based discrimination
23.4.5. Associations on alternate keys
24. 最佳实践(Best Practices)

前言

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 满江红翻译团队 <caoxg@yahoo.com>

在今日的企业环境中,把面向对象的软件和关系数据库一起使用可能是相当麻烦、浪费时间的。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)。

  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企业级中间件系统的一个核心组件。

1. 翻译说明

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

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

表 1.  Hibernate v3翻译团队

序号 标题 中文标题 v3翻译 v3审校 v3.1审校
--Quickstart with Tomcat在Tomcat中快速上手(3.1版本中取消)曹晓钢zoujm--
#1TurtotialHibernate入门Zheng Shuai-Sean Chan
#2Architecture体系结构Hilton(BJUG)厌倦发呆Sean Chan
#3Configuration配置Gonchamochowzcgly
#4Persistent Classes持久化类曹晓钢mochowDigitalSonic
#5Basic O/R Mapping对象/关系数据库映射基础(上)moxieKingfish张成钢
  对象/关系数据库映射基础(下)inter_dudu刘国雄(vincent)张成钢
#6Collection Mapping集合类映射曹晓钢robbin--
#7Association Mappings关联关系映射Robbindevils.advocate--
#8Component Mapping组件映射曹晓钢RobbinSong guo qiang
#9Inheritance Mappings继承映射morning(BJUG)mochowLiang cheng
#10Working with objects与对象共事程广楠厌倦发呆--
#11Transactions And Concurrency事务和并发Robbinmochow--
#12Interceptors and events继承映射七彩狼(BJUG)厌倦发呆--
#13Batch processing批量处理Kingfish(BJUG)厌倦发呆--
#14HQL: The Hibernate Query LanguageHQL: Hibernate查询语言郑浩(BJUG)Zheng Shuai--
#15Criteria Queries条件查询nemo(BJUG)Zheng Shuai--
#16Native SQLNative SQL查询似水流年zoujm--
#17Filters过滤数据冰云(BJUG)Goncha--
#18XML MappingXML映射edward(BJUG)Gonchahuxb
#19Improving performance性能提升WangjinfengRobbin--
#20Toolset Guide工具箱指南曹晓钢Robbin--
#21Example: Parent/Child示例:父子关系曹晓钢devils.advocate--
#22Example: Weblog Application示例:Weblog 应用程序曹晓钢devils.advocate--
#23Example: Various Mappings示例:多种映射shidu(BJUG)冰云--
#24Best Practices最佳实践曹晓钢冰云--

关于我们

满江红.开源, 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,李毅,李海林。

2. 版权声明

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

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

第 1 章  Hibernate入门

1.1.  前言

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

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

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

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。

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

对一特定的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。

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.dtd">

<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-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 类上使用反射机制)不会产生你所期待或需要的缺省值。date属性就是个很好的例子,Hibernate无法知道这个属性(java.util.Date类型的)应该被映射成:SQL date,或timestamp,还是time 字段。在此例中,把这个属性映射成timestamp 转换器,这样我们预留了日期和时间的全部信息。

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

.
+lib
  <Hibernate and third-party libraries>
+src
 +events
  Event.java
  Event.hbm.xml

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

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配置文件:

<?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">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选项将自动生成数据库模式(schema)- 直接加入数据库中。当然这个选项也可以被关闭(通过去除这个配置选项)或者通过Ant任务SchemaExport的帮助来把数据库schema重定向到文件中。最后,在配置中为持久化类加入映射文件。

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

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,会得到以下输出:

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 

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().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;
    }

}

这个类不但在它的静态初始化过程(仅当加载这个类的时候被JVM执行一次)中产生全局的SessionFactory,而且隐藏了它使用了静态singleton的事实。它也可能在应用程序服务器中的JNDI查找SessionFactory

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

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来做些真正的工作。

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().getCurrentSession();

        session.beginTransaction();

        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);

        session.save(theEvent);

        session.getTransaction().commit();
    }

}

我们创建了个新的Event对象并把它传递给Hibernate。现在Hibernate负责与SQL打交道,并把INSERT命令传给数据库。在运行之前,让我们看一下处理SessionTransaction的代码。

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

action参数(argument)的值是通过命令行调用这个target的时候设置的:

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

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

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

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

    session.beginTransaction();

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

    session.getTransaction().commit();

    return result;
}

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

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

  • 运行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重新打开一次。

1.3.  第二部分 - 关联映射

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

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)的行为。

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支持各种各样的集合映射,<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   |
                                                  |_____________|
 

1.3.3.  使关联工作

我们把一些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();
}

在加载一PersonEvent后,使用普通的集合方法就可容易地修改我们定义的集合。如你所见,没有显式的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);
}

上面是个关于两个同等重要的实体类间关联的例子。像前面所提到的那样,在特定的模型中也存在其它的类和类型,这些类和类型通常是“次要的”。你已看到过其中的一些,像intString。我们称这些类为值类型(value type),它们的实例依赖(depend)在某个特定的实体上。这些类型的实例没有它们自己的标识(identity),也不能在实体间被共享(比如,两个person不能引用同一个firstname对象,即使他们有相同的first name)。当然,值类型并不仅仅在JDK中存在(事实上,在一个Hibernate应用程序中,所有的JDK类都被视为值类型),而且你也可以编写你自己的依赖类,例如AddressMonetaryAmount

你也可以设计一个值类型的集合,这在概念上与引用其它实体的集合有很大的不同,但是在Java里面看起来几乎是一样的。

1.3.4.  值类型的集合

我们把一个值类型对象的集合加入Person实体中。我们希望保存email地址,所以使用String类型,而且这次的集合类型又是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   |
                                                |_____________|
 

你可以看到集合表的主键实际上是个复合主键,同时使用了2个字段。这也暗示了对于同一个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);

    // The getEmailAddresses() might trigger a lazy load of the collection
    aPerson.getEmailAddresses().add(emailAddress);

    session.getTransaction().commit();
}

这次我们没有使用fetch查询来初始化集合。因此,调用其getter方法会触发另一附加的select来初始化集合,这样我们才能把元素添加进去。检查SQL log,试着通过预先抓取来优化它。

1.3.5.  双向关联

接下来我们将映射双向关联(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映射。注意在两个映射文件中,互换了keymany-to-many的字段名。这里最重要的是Event映射文件里增加了set元素的inverse="true"属性。

这意味着在需要的时候,Hibernate能在关联的另一端 - Person类得到两个实体间关联的信息。这将会极大地帮助你理解双向关联是如何在两个实体间被创建的。

1.3.6.  使双向连起来

首先请记住,Hibernate并不影响通常的Java语义。 在单向关联的例子中,我们是怎样在PersonEvent之间创建联系的?我们把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并没有足够的信息去正确地执行INSERTUPDATE语句(以避免违反数据库约束),所以它需要一些帮助来正确的处理双向关联。把关联的一端设置为inverse将告诉Hibernate忽略关联的这一端,把这端看成是另外一端的一个镜象(mirror)。这就是所需的全部信息,Hibernate利用这些信息来处理把一个有向导航模型转移到数据库schema时的所有问题。你只需要记住这个直观的规则:所有的双向关联需要有一端被设置为inverse。在一对多关联中它必须是代表多(many)的那端。而在多对多(many-to-many)关联中,你可以任意选取一端,因为两端之间并没有差别。

让我们把进入一个小型的web应用程序。

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

Hibernate web应用程序使用SessionTransaction的方式几乎和独立应用程序是一样的。但是,有一些常见的模式(pattern)非常有用。现在我们编写一个EventManagerServlet。这个servlet可以列出数据库中保存的所有的events,还提供一个HTML表单来增加新的events。

1.4.1. 编写基本的servlet

在你的源代码目录的events包中创建一个新的类:

package events;

// Imports

public class EventManagerServlet extends HttpServlet {

    // Servlet code
}

我们后面会用到dateFormatter 的工具, 它把Date对象转换为字符串。只要一个formatter作为servlet的成员就可以了。

这个servlet只处理 HTTP GET 请求,因此,我们要实现的是doGet()方法:

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();
        throw new ServletException(ex);
    }

}

我们称这里应用的模式为每次请求一个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中,你就会很快用到它。

1.4.2. 处理与渲染

我们来实现处理请求以及渲染页面的工作。

// 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();

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>");
        for (Iterator it = result.iterator(); 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会在单一的SessionTransaction中处理到达的servlet请求。如同在前面的独立应用程序中那样,Hibernate可以自动的把这些对象绑定到当前运行的线程中。这给了你用任何你喜欢的方式来对代码分层及访问SessionFactory的自由。通常,你会用更加完备的设计,把数据访问代码转移到数据访问对象中(DAO模式)。请参见Hibernate Wiki,那里有更多的例子。

1.4.3. 部署与测试

要发布这个程序,你得把它打成web发布包:WAR文件。把下面的脚本加入到你的build.xml中:

<target name="war" depends="compile">
    <war destfile="hibernate-tutorial.war" webxml="web.xml">
        <lib dir="${librarydir}">
          <exclude name="jsdk*.jar"/>
        </lib>

        <classes dir="${targetdir}"/>
    </war>
</target>

这段代码在你的开发目录中创建一个hibernate-tutorial.war的文件。它把所有的类库和web.xml描述文件都打包进去,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>events.EventManagerServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Event Manager</servlet-name>
        <url-pattern>/eventmanager</url-pattern>
    </servlet-mapping>
</web-app>

请注意在你编译和部署web应用程之前,需要一个附加的类库:jsdk.jar。这是Java Servlet开发包,假若你还没有,可以从Sun网站上下载,把它copy到你的lib目录。但是,它仅仅是在编译时需要,不会被打入WAR包。

在你的开发目录中,调用ant war来构建、打包,然后把hibernate-tutorial.war文件拷贝到你的tomcat的webapps目录下。假若你还没安装Tomcat,就去下载一个,按照指南来安装。对此应用的发布,你不需要修改任何Tomcat的配置。

在部署完,启动Tomcat之后,通过http://localhost:8080/hibernate-tutorial/eventmanager进行访问你的应用,在第一次servlet 请求发生时,请在Tomcat log中确认你看到Hibernate被初始化了(HibernateUtil的静态初始化器被调用),假若有任何异常抛出,也可以看到详细的输出。

1.5.  总结

本章覆盖了如何编写一个简单独立的Hibernate命令行应用程序及小型的Hibernate web应用程序的基本要素。

如果你已经对Hibernate感到自信,通过开发指南目录,继续浏览你感兴趣的内容-那些会被问到的问题大多是事务处理 (第 11 章 事务和并发),抓取(fetch)的效率 (第 19 章 提升性能 ),或者API的使用 (第 10 章 与对象共事)和查询的特性(第 10.4 节 “查询”)。

别忘了去Hibernate的网站查看更多(有针对性的)示例。

第 2 章 体系结构(Architecture)

2.1. 概况(Overview)

一个非常简要的Hibernate体系结构的概要图:

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

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

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

图中各个对象的定义如下:

SessionFactory (org.hibernate.SessionFactory)

针对单个数据库映射关系经过编译后的内存镜像,是线程安全的(不可变)。 它是生成Session的工厂,本身要用到ConnectionProvider。 该对象可以在进程或集群的级别上,为那些事务之间可以重用的数据提供可选的二级缓存。

Session (org.hibernate.Session)

表示应用程序与持久储存层之间交互操作的一个单线程对象,此对象生存期很短。 其隐藏了JDBC连接,也是Transaction的工厂。 其会持有一个针对持久化对象的必选(第一级)缓存,在遍历对象图或者根据持久化标识查找对象时会用到。

持久的对象及其集合

带有持久化状态的、具有业务功能的单线程对象,此对象生存期很短。 这些对象可能是普通的JavaBeans/POJO,唯一特殊的是他们正与(仅仅一个)Session相关联。 一旦这个Session被关闭,这些对象就会脱离持久化状态,这样就可被应用程序的任何层自由使用。 (例如,用作跟表示层打交道的数据传输对象。)

瞬态(transient)和脱管(detached)的对象及其集合

那些目前没有与session关联的持久化类实例。 他们可能是在被应用程序实例化后,尚未进行持久化的对象。 也可能是因为实例化他们的Session已经被关闭而脱离持久化的对象。

事务Transaction (org.hibernate.Transaction)

(可选的)应用程序用来指定原子操作单元范围的对象,它是单线程的,生命周期很短。 它通过抽象将应用从底层具体的JDBC、JTA以及CORBA事务隔离开。 某些情况下,一个Session之内可能包含多个Transaction对象。 尽管是否使用该对象是可选的,但无论是使用底层的API还是使用Transaction对象,事务边界的开启与关闭是必不可少的。

ConnectionProvider (org.hibernate.connection.ConnectionProvider)

(可选的)生成JDBC连接的工厂(同时也起到连接池的作用)。 它通过抽象将应用从底层的DatasourceDriverManager隔离开。 仅供开发者扩展/实现用,并不暴露给应用程序使用。

TransactionFactory (org.hibernate.TransactionFactory)

(可选的)生成Transaction对象实例的工厂。 仅供开发者扩展/实现用,并不暴露给应用程序使用。

扩展接口

Hibernate提供了很多可选的扩展接口,你可以通过实现它们来定制你的持久层的行为。 具体请参考API文档。

在特定“轻型”的体系结构中,应用程序可能绕过 Transaction/TransactionFactory 以及 ConnectionProvider 等API直接跟JTA或JDBC打交道。

2.2. 实例状态

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

瞬态(transient)

该实例从未与任何持久化上下文关联过。它没有持久化标识(相当于主键值)。

持久化(persistent)

实例目前与某个持久化上下文有关联。 它拥有持久化标识(相当于主键值),并且可能在数据库中有一个对应的行。 对于某一个特定的持久化上下文,Hibernate保证持久化标识与Java标识(其值代表对象在内存中的位置)等价。

脱管(detached)

实例曾经与某个持久化上下文发生过关联,不过那个上下文被关闭了, 或者这个实例是被序列化(serialize)到另外的进程。 它拥有持久化标识,并且在数据库中可能存在一个对应的行。 对于脱管状态的实例,Hibernate不保证任何持久化标识和Java标识的关系。

2.3. JMX整合

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

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

  • Session管理: Hibernate的Session对象的生命周期可以 自动跟一个JTA事务边界绑定。这意味着你无需手工开关Session了, 这项 工作会由JBoss EJB 拦截器来完成。你再也不用担心你的代码中的事务边界了(除非你想利用Hibernate提供可选 的Transaction API来自己写一个便于移植的的持久层)。 你通过调用HibernateContext来访问Session

  • HAR 部署: 通常情况下,你会使用JBoss的服务部署描述符(在EAR或/和SAR文件中)来部署Hibernate JMX服务。 这种部署方式支持所有常见的Hibernate SessionFactory的配置选项。 不过,你仍需在部署描述符中,列出你所有的映射文件的名字。如果你使用HAR部署方式, JBoss 会自动探测出你的HAR文件中所有的映射文件。

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

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

2.4. 对JCA的支持

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

2.5. 上下文相关的(Contextual)Session

使用Hibernate的大多数应用程序需要某种形式的“上下文相关的” session,特定的session在整个特定的上下文范围内始终有效。然而,对不同类型的应用程序而言,要为什么是组成这种“上下文”下一个定义通常是困难的;不同的上下文对“当前”这个概念定义了不同的范围。在3.0版本之前,使用Hibernate的程序要么采用自行编写的基于ThreadLocal的上下文session,要么采用HibernateUtil这样的辅助类,要么采用第三方框架(比如Spring或Pico),它们提供了基于代理(proxy)或者基于拦截器(interception)的上下文相关session。

从3.0.1版本开始,Hibernate增加了SessionFactory.getCurrentSession()方法。一开始,它假定了采用JTA事务,JTA事务定义了当前session的范围和上下文(scope and context)。Hibernate开发团队坚信,因为有好几个独立的JTA TransactionManager实现稳定可用,不论是否被部署到一个J2EE容器中,大多数(假若不是所有的)应用程序都应该采用JTA事务管理。基于这一点,采用JTA的上下文相关session可以满足你一切需要。

更好的是,从3.1开始,SessionFactory.getCurrentSession()的后台实现是可拔插的。因此,我们引入了新的扩展接口(org.hibernate.context.CurrentSessionContext)和新的配置参数(hibernate.current_session_context_class),以便对什么是“当前session”的范围和上下文(scope and context)的定义进行拔插。

请参阅org.hibernate.context.CurrentSessionContext接口的Javadoc,那里有关于它的契约的详细讨论。它定义了单一的方法,currentSession(),特定的实现用它来负责跟踪当前的上下文session。Hibernate内置了此接口的三种实现。

  • org.hibernate.context.JTASessionContext - 当前session根据JTA来跟踪和界定。这和以前的仅支持JTA的方法是完全一样的。详情请参阅Javadoc。

  • org.hibernate.context.ThreadLocalSessionContext - 当前session通过当前执行的线程来跟踪和界定。详情也请参阅Javadoc。

  • org.hibernate.context.ManagedSessionContext - 当前session通过当前执行的线程来跟踪和界定。但是,你需要负责使用这个类的静态方法将Session实例绑定、或者取消绑定,它并不会打开(open)、flush或者关闭(close)任何Session

前两种实现都提供了“每数据库事务对应一个session”的编程模型,也称作每次请求一个session。Hibernate session的起始和终结由数据库事务的生存来控制。假若你在纯粹的 Java SE之上采用自行编写代码来管理事务,而不使用JTA,建议你使用Hibernate Transaction API来把底层事务实现从你的代码中隐藏掉。如果你使用JTA,请使用JTA借口来管理Transaction。如果你在支持CMT的EJB容器中执行代码,事务边界是声明式定义的,你不需要在代码中进行任何事务或session管理操作。请参阅第 11 章 事务和并发一节来阅读更多的内容和示例代码。

hibernate.current_session_context_class配置参数定义了应该采用哪个org.hibernate.context.CurrentSessionContext实现。注意,为了向下兼容,如果未配置此参数,但是存在org.hibernate.transaction.TransactionManagerLookup的配置,Hibernate会采用org.hibernate.context.JTASessionContext。一般而言,此参数的值指明了要使用的实现类的全名,但那三种内置的实现可以使用简写,即"jta"、"thread"和"managed"。

第 3 章  配置

由于Hibernate是为了能在各种不同环境下工作而设计的, 因此存在着大量的配置参数. 幸运的是多数配置参数都 有比较直观的默认值, 并有随Hibernate一同分发的配置样例hibernate.properties (位于etc/)来展示各种配置选项. 所需做的仅仅是将这个样例文件复制到类路径 (classpath)下并做一些自定义的修改.

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配置属性的方式, 其他可选方式还包括:

  1. 传一个java.util.Properties实例给 Configuration.setProperties().

  2. hibernate.properties放置在类路径(classpath)的根目录下 (root directory).

  3. 通过java -Dproperty=value来设置系统 (System)属性.

  4. hibernate.cfg.xml中加入元素 <property> (稍后讨论).

如果想尽快体验Hibernate, 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连接 :

表 3.1.  Hibernate JDBC属性

属性名 用途
hibernate.connection.driver_classjdbc驱动类
hibernate.connection.urljdbc URL
hibernate.connection.username数据库用户
hibernate.connection.password数据库用户密码
hibernate.connection.pool_size连接池容量上限数目

但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处获得连接,你至少需要设置下列属性中的一个:

表 3.2.  Hibernate数据源属性

属性名 用途
hibernate.connection.datasource数据源JNDI名字
hibernate.jndi.urlJNDI提供者的URL (可选)
hibernate.jndi.classJNDI InitialContextFactory (可选)
hibernate.connection.username数据库用户 (可选)
hibernate.connection.password数据库用户密码 (可选)

这是一个使用应用程序服务器提供的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=valuehibernate.properties来设置, 而不能用上面描述的其他方法来设置.

表 3.3.  Hibernate配置属性

属性名 用途
hibernate.dialect 一个Hibernate Dialect类名允许Hibernate针对特定的关系数据库生成优化的SQL.

取值 full.classname.of.Dialect

hibernate.show_sql 输出所有SQL语句到控制台. 有一个另外的选择是把org.hibernate.SQL这个log category设为debug

eg. true | false

hibernate.format_sql 在log和console中打印出更漂亮的SQL。

取值 true | false

hibernate.default_schema 在生成的SQL中, 将给定的schema/tablespace附加于非全限定名的表名上.

取值 SCHEMA_NAME

hibernate.default_catalog 在生成的SQL中, 将给定的catalog附加于非全限定名的表名上.

取值 CATALOG_NAME

hibernate.session_factory_nameSessionFactory创建后,将自动使用这个名字绑定到JNDI中.

取值 jndi/composite/name

hibernate.max_fetch_depth 为单向关联(一对一, 多对一)的外连接抓取(outer join fetch)树设置最大深度. 值为0意味着将关闭默认的外连接抓取.

取值 建议在03之间取值

hibernate.default_batch_fetch_size 为Hibernate关联的批量抓取设置默认数量.

取值 建议的取值为4, 8, 和16

hibernate.default_entity_mode 为由这个SessionFactory打开的所有Session指定默认的实体表现模式.

取值 dynamic-map, dom4j, pojo

hibernate.order_updates 强制Hibernate按照被更新数据的主键,为SQL更新排序。这么做将减少在高并发系统中事务的死锁。

取值 true | false

hibernate.generate_statistics 如果开启, Hibernate将收集有助于性能调节的统计数据.

取值 true | false

hibernate.use_identifer_rollback 如果开启, 在对象被删除时生成的标识属性将被重设为默认值.

取值 true | false

hibernate.use_sql_comments 如果开启, Hibernate将在SQL中生成有助于调试的注释信息, 默认值为false.

取值 true | false

表 3.4.  Hibernate JDBC和连接(connection)属性

属性名 用途
hibernate.jdbc.fetch_size 非零值,指定JDBC抓取数量的大小 (调用Statement.setFetchSize()).
hibernate.jdbc.batch_size 非零值,允许Hibernate使用JDBC2的批量更新.

取值 建议取530之间的值

hibernate.jdbc.batch_versioned_data 如果你想让你的JDBC驱动从executeBatch()返回正确的行计数 , 那么将此属性设为true(开启这个选项通常是安全的). 同时,Hibernate将为自动版本化的数据使用批量DML. 默认值为false.

eg. true | false

hibernate.jdbc.factory_class 选择一个自定义的Batcher. 多数应用程序不需要这个配置属性.

eg. classname.of.Batcher

hibernate.jdbc.use_scrollable_resultset 允许Hibernate使用JDBC2的可滚动结果集. 只有在使用用户提供的JDBC连接时,这个选项才是必要的, 否则Hibernate会使用连接的元数据.

取值 true | false

hibernate.jdbc.use_streams_for_binary 在JDBC读写binary (二进制)serializable (可序列化) 的类型时使用流(stream)(系统级属性).

取值 true | false

hibernate.jdbc.use_get_generated_keys 在数据插入数据库之后,允许使用JDBC3 PreparedStatement.getGeneratedKeys() 来获取数据库生成的key(键)。需要JDBC3+驱动和JRE1.4+, 如果你的数据库驱动在使用Hibernate的标 识生成器时遇到问题,请将此值设为false. 默认情况下将使用连接的元数据来判定驱动的能力.

取值 true|false

hibernate.connection.provider_class 自定义ConnectionProvider的类名, 此类用来向Hibernate提供JDBC连接.

取值 classname.of.ConnectionProvider

hibernate.connection.isolation 设置JDBC事务隔离级别. 查看java.sql.Connection来了解各个值的具体意义, 但请注意多数数据库都不支持所有的隔离级别.

取值 1, 2, 4, 8

hibernate.connection.autocommit 允许被缓存的JDBC连接开启自动提交(autocommit) (不建议).

取值 true | false

hibernate.connection.release_mode 指定Hibernate在何时释放JDBC连接. 默认情况下,直到Session被显式关闭或被断开连接时,才会释放JDBC连接. 对于应用程序服务器的JTA数据源, 你应当使用after_statement, 这样在每次JDBC调用后,都会主动的释放连接. 对于非JTA的连接, 使用after_transaction在每个事务结束时释放连接是合理的. auto将为JTA和CMT事务策略选择after_statement, 为JDBC事务策略选择after_transaction.

取值 auto (默认) | on_close | after_transaction | after_statement

注意,这些设置仅对通过SessionFactory.openSession得到的Session起作用。对于通过SessionFactory.getCurrentSession得到的Session,所配置的CurrentSessionContext实现控制这些Session的连接释放模式。请参阅第 2.5 节 “上下文相关的(Contextual)Session”

hibernate.connection.<propertyName> 将JDBC属性propertyName传递到DriverManager.getConnection()中去.
hibernate.jndi.<propertyName> 将属性propertyName传递到JNDI InitialContextFactory中去.

表 3.5.  Hibernate缓存属性

属性名 用途
hibernate.cache.provider_class 自定义的CacheProvider的类名.

取值 classname.of.CacheProvider

hibernate.cache.use_minimal_puts 以频繁的读操作为代价, 优化二级缓存来最小化写操作. 在Hibernate3中,这个设置对的集群缓存非常有用, 对集群缓存的实现而言,默认是开启的.

取值 true|false

hibernate.cache.use_query_cache 允许查询缓存, 个别查询仍然需要被设置为可缓存的.

取值 true|false

hibernate.cache.use_second_level_cache 能用来完全禁止使用二级缓存. 对那些在类的映射定义中指定<cache>的类,会默认开启二级缓存.

取值 true|false

hibernate.cache.query_cache_factory 自定义实现QueryCache接口的类名, 默认为内建的StandardQueryCache.

取值 classname.of.QueryCache

hibernate.cache.region_prefix 二级缓存区域名的前缀.

取值 prefix

hibernate.cache.use_structured_entries 强制Hibernate以更人性化的格式将数据存入二级缓存.

取值 true|false

表 3.6.  Hibernate事务属性

属性名 用途
hibernate.transaction.factory_class 一个TransactionFactory的类名, 用于Hibernate Transaction API (默认为JDBCTransactionFactory).

取值 classname.of.TransactionFactory

jta.UserTransaction 一个JNDI名字,被JTATransactionFactory用来从应用服务器获取JTA UserTransaction.

取值 jndi/composite/name

hibernate.transaction.manager_lookup_class 一个TransactionManagerLookup的类名 - 当使用JVM级缓存,或在JTA环境中使用hilo生成器的时候需要该类.

取值 classname.of.TransactionManagerLookup

hibernate.transaction.flush_before_completion 如果开启, session在事务完成后将被自动清洗(flush)。 现在更好的方法是使用自动session上下文管理。请参见第 2.5 节 “上下文相关的(Contextual)Session”

取值 true | false

hibernate.transaction.auto_close_session 如果开启, session在事务完成后将被自动关闭。 现在更好的方法是使用自动session上下文管理。请参见第 2.5 节 “上下文相关的(Contextual)Session”

取值 true | false

表 3.7.  其他属性

属性名 用途
hibernate.current_session_context_class 为"当前" Session指定一个(自定义的)策略。关于内置策略的详情,请参见第 2.5 节 “上下文相关的(Contextual)Session”

eg. jta | thread | managed | custom.Class

hibernate.query.factory_class 选择HQL解析器的实现.

取值 org.hibernate.hql.ast.ASTQueryTranslatorFactory or org.hibernate.hql.classic.ClassicQueryTranslatorFactory

hibernate.query.substitutions 将Hibernate查询中的符号映射到SQL查询中的符号 (符号可能是函数名或常量名字).

取值 hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC

hibernate.hbm2ddl.autoSessionFactory创建时,自动检查数据库结构,或者将数据库schema的DDL导出到数据库. 使用 create-drop时,在显式关闭SessionFactory时,将drop掉数据库schema.

取值 validate | update | create | create-drop

hibernate.cglib.use_reflection_optimizer 开启CGLIB来替代运行时反射机制(系统级属性). 反射机制有时在除错时比较有用. 注意即使关闭这个优化, Hibernate还是需要CGLIB. 你不能在hibernate.cfg.xml中设置此属性.

取值 true | false

3.4.1.  SQL方言

你应当总是为你的数据库将hibernate.dialect属性设置成正确的 org.hibernate.dialect.Dialect子类. 如果你指定一种方言, Hibernate将为上面列出的一些属性使用合理的默认值, 为你省去了手工指定它们的功夫.

表 3.8.  Hibernate SQL方言 (hibernate.dialect)

RDBMS 方言
DB2org.hibernate.dialect.DB2Dialect
DB2 AS/400org.hibernate.dialect.DB2400Dialect
DB2 OS390org.hibernate.dialect.DB2390Dialect
PostgreSQLorg.hibernate.dialect.PostgreSQLDialect
MySQLorg.hibernate.dialect.MySQLDialect
MySQL with InnoDBorg.hibernate.dialect.MySQLInnoDBDialect
MySQL with MyISAMorg.hibernate.dialect.MySQLMyISAMDialect
Oracle (any version)org.hibernate.dialect.OracleDialect
Oracle 9i/10gorg.hibernate.dialect.Oracle9Dialect
Sybaseorg.hibernate.dialect.SybaseDialect
Sybase Anywhereorg.hibernate.dialect.SybaseAnywhereDialect
Microsoft SQL Serverorg.hibernate.dialect.SQLServerDialect
SAP DBorg.hibernate.dialect.SAPDBDialect
Informixorg.hibernate.dialect.InformixDialect
HypersonicSQLorg.hibernate.dialect.HSQLDialect
Ingresorg.hibernate.dialect.IngresDialect
Progressorg.hibernate.dialect.ProgressDialect
Mckoi SQLorg.hibernate.dialect.MckoiDialect
Interbaseorg.hibernate.dialect.InterbaseDialect
Pointbaseorg.hibernate.dialect.PointbaseDialect
FrontBaseorg.hibernate.dialect.FrontbaseDialect
Firebirdorg.hibernate.dialect.FirebirdDialect

3.4.2.  外连接抓取(Outer Join Fetching)

如果你的数据库支持ANSI, Oracle或Sybase风格的外连接, 外连接抓取通常能通过限制往返数据库次数 (更多的工作交由数据库自己来完成)来提高效率. 外连接抓取允许在单个SELECTSQL语句中, 通过many-to-one, one-to-many, many-to-many和one-to-one关联获取连接对象的整个对象图.

hibernate.max_fetch_depth设为0能在全局 范围内禁止外连接抓取. 设为1或更高值能启用one-to-one和many-to-oneouter关联的外连接抓取, 它们通过 fetch="join"来映射.

参见第 19.1 节 “ 抓取策略(Fetching strategies) ”获得更多信息.

3.4.3.  二进制流 (Binary Streams)

Oracle限制那些通过JDBC驱动传输的字节数组的数目. 如果你希望使用二进值 (binary)可序列化的 (serializable)类型的大对象, 你应该开启 hibernate.jdbc.use_streams_for_binary属性. 这是系统级属性.

3.4.4.  二级缓存与查询缓存

hibernate.cache为前缀的属性允许你在Hibernate中,使用进程或群集范围内的二级缓存系统. 参见第 19.2 节 “二级缓存(The Second Level Cache) ”获取更多的详情.

3.4.5.  查询语言中的替换

你可以使用hibernate.query.substitutions在Hibernate中定义新的查询符号. 例如:

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

将导致符号truefalse在生成的SQL中被翻译成整数常量.

hibernate.query.substitutions toLowercase=LOWER

将允许你重命名SQL中的LOWER函数.

3.4.6.  Hibernate的统计(statistics)机制

如果你开启hibernate.generate_statistics, 那么当你通过 SessionFactory.getStatistics()调整正在运行的系统时,Hibernate将导出大量有用的数据. Hibernate甚至能被配置成通过JMX导出这些统计信息. 参考org.hibernate.stats中接口的Javadoc,以获得更多信息.

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的日志可能地详细. 这是必要的查错利器. 最令人感兴趣的日志分类有如下这些:

表 3.9.  Hibernate日志类别

类别 功能
org.hibernate.SQL 在所有SQL DML语句被执行时为它们记录日志
org.hibernate.type 为所有JDBC参数记录日志
org.hibernate.tool.hbm2ddl 在所有SQL DDL语句执行时为它们记录日志
org.hibernate.pretty 在session清洗(flush)时,为所有与其关联的实体(最多20个)的状态记录日志
org.hibernate.cache 为所有二级缓存的活动记录日志
org.hibernate.transaction 为事务相关的活动记录日志
org.hibernate.jdbc 为所有JDBC资源的获取记录日志
org.hibernate.hql.AST 在解析查询的时候,记录HQL和SQL的AST分析日志
org.hibernate.secure 为JAAS认证请求做日志
org.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 collection="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有如下几个集成的方面:

  • 容器管理的数据源(Container-managed datasources): Hibernate能使用通过容器管理,并由JNDI提供的JDBC连接. 通常, 特别是当处理多个数据源的分布式事务的时候, 由一个JTA兼容的TransactionManager和一个 ResourceManager来处理事务管理(CMT, 容器管理的事务). 当然你可以通过 编程方式来划分事务边界(BMT, Bean管理的事务). 或者为了代码的可移植性,你也也许会想使用可选的 Hibernate Transaction API.

  • 自动JNDI绑定: Hibernate可以在启动后将 SessionFactory绑定到JNDI.

  • JTA Session绑定: Hibernate Session 可以自动绑定到JTA事务作用的范围. 只需简单地从JNDI查找SessionFactory并获得当前的 Session. 当JTA事务完成时, 让Hibernate来处理 Session的清洗(flush)与关闭. 事务的划分可以是声明式的(CMT),也可以是编程式的(BMT/UserTransaction).

  • JMX部署: 如果你使用支持JMX应用程序服务器(如, JBoss AS), 那么你可以选择将Hibernate部署成托管MBean. 这将为你省去一行从Configuration构建SessionFactory的启动代码. 容器将启动你的HibernateService, 并完美地处理好服务间的依赖关系 (在Hibernate启动前,数据源必须是可用的,等等).

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

3.8.1.  事务策略配置

在你的架构中,Hibernate的Session API是独立于任何事务分界系统的. 如果你让Hibernate通过连接池直接使用JDBC, 你需要调用JDBC API来打开和关闭你的事务. 如果你运行在J2EE应用程序服务器中, 你也许想用Bean管理的事务并在需要的时候调用JTA API和UserTransaction.

为了让你的代码在两种(或其他)环境中可以移植,我们建议使用可选的Hibernate Transaction API, 它包装并隐藏了底层系统. 你必须通过设置Hibernate配置属性hibernate.transaction.factory_class来指定 一个Transaction实例的工厂类.

有三个标准(内建)的选择:

org.hibernate.transaction.JDBCTransactionFactory

委托给数据库(JDBC)事务(默认)

org.hibernate.transaction.JTATransactionFactory

如果在上下文环境中存在运行着的事务(如, EJB会话Bean的方法), 则委托给容器管 理的事务, 否则,将启动一个新的事务,并使用Bean管理的事务.

org.hibernate.transaction.CMTTransactionFactory

委托给容器管理的JTA事务

你也可以定义属于你自己的事务策略 (如, 针对CORBA的事务服务)

Hibernate的一些特性 (比如二级缓存, Contextual Sessions with JTA等等)需要访问在托管环境中的JTA TransactionManager. 由于J2EE没有标准化一个单一的机制,Hibernate在应用程序服务器中,你必须指定Hibernate如何获得TransactionManager的引用:

表 3.10. JTA TransactionManagers

Transaction工厂类 应用程序服务器
org.hibernate.transaction.JBossTransactionManagerLookupJBoss
org.hibernate.transaction.WeblogicTransactionManagerLookupWeblogic
org.hibernate.transaction.WebSphereTransactionManagerLookupWebSphere
org.hibernate.transaction.WebSphereExtendedJTATransactionLookupWebSphere 6
org.hibernate.transaction.OrionTransactionManagerLookupOrion
org.hibernate.transaction.ResinTransactionManagerLookupResin
org.hibernate.transaction.JOTMTransactionManagerLookupJOTM
org.hibernate.transaction.JOnASTransactionManagerLookupJOnAS
org.hibernate.transaction.JRun4TransactionManagerLookupJRun4
org.hibernate.transaction.BESTransactionManagerLookupBorland ES

3.8.2.  JNDI绑定的SessionFactory

与JNDI绑定的Hibernate的SessionFactory能简化工厂的查询,简化创建新的Session. 需要注意的是这与JNDI绑定Datasource没有关系, 它们只是恰巧用了相同的注册表!

如果你希望将SessionFactory绑定到一个JNDI的名字空间, 用属性hibernate.session_factory_name指定一个名字(如, java:hibernate/SessionFactory). 如果不设置这个属性, SessionFactory将不会被绑定到JNDI中. (在以只读JNDI为默认实现的环境中,这个设置尤其有用, 如Tomcat.)

在将SessionFactory绑定至JNDI时, Hibernate将使用hibernate.jndi.url, 和hibernate.jndi.class的值来实例化初始环境(initial context). 如果它们没有被指定, 将使用默认的InitialContext.

在你调用cfg.buildSessionFactory()后, Hibernate会自动将SessionFactory注册到JNDI. 这意味这你至少需要在你应用程序的启动代码(或工具类)中完成这个调用, 除非你使用HibernateService来做JMX部署 (见后面讨论).

假若你使用JNDI SessionFactory,EJB或者任何其它类都可以从JNDI中找到此SessionFactory

我们建议,在受管理的环境中,把SessionFactory绑定到JNDI,在其它情况下,使用一个static(静态的)singleton。为了在你的应用程序代码中隐藏这些细节,我们还建议你用一个helper类把实际查找SessionFactory的代码隐藏起来,比如HibernateUtil.getSessionFactory()。注意,这个类也就可以方便地启动Hibernate,参见第一章。

3.8.3. 在JTA环境下使用Current Session context (当前session上下文)管理

在Hibernate中,管理Session和transaction最好的方法是自动的"当前"Session管理。请参见第 2.5 节 “上下文相关的(Contextual)Session”一节的讨论。使用"jta"session上下文,假若在当前JTA事务中还没有HibernateSession关联,第一次sessionFactory.getCurrentSession()调用会启动一个Session,并关联到当前的JTA事务。在"jta"上下文中调用getCurrentSession()获得的Session,会被设置为在transaction关闭的时候自动flush(清洗)、在transaction关闭之后自动关闭,每句语句之后主动释放JDBC连接。这就可以根据JTA事务的生命周期来管理与之关联的Session,用户代码中就可以不再考虑这些管理。你的代码也可以通过UserTransaction用编程方式使用JTA,或者(我们建议,为了便于移植代码)使用Hibernate的Transaction API来设置transaction边界。如果你的代码运行在EJB容器中,建议对CMT使用声明式事务声明。

3.8.4.  JMX部署

为了将SessionFactory注册到JNDI中,cfg.buildSessionFactory()这行代码仍需在某处被执行. 你可在一个static初始化块(像HibernateUtil中的那样)中执行它或将Hibernate部署为一个托管的服务.

为了部署在一个支持JMX的应用程序服务器上,Hibernate和 org.hibernate.jmx.HibernateService一同分发,如Jboss AS。 实际的部署和配置是由应用程序服务器提供者指定的. 这里是JBoss 4.0.x的jboss-service.xml样例:

<?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>

这个文件是部署在META-INF目录下的, 并会被打包到以.sar (service archive)为扩展名的JAR文件中. 同时,你需要将Hibernate、它所需要的第三方库、你编译好的持久化类以及你的映射定义文件打包进同一个文档. 你的企业Bean(一般为会话Bean)可能会被打包成它们自己的JAR文件, 但你也许会将EJB JAR文件一同包含进能独立(热)部署的主服务文档. 参考JBoss AS文档以了解更多的JMX服务与EJB部署的信息.

第 4 章 持久化类(Persistent Classes)

在应用程序中,用来实现业务问题实体的(如,在电子商务应用程序中的Customer和Order) 类就是持久化类。不能认为所有的持久化类的实例都是持久的状态——一个实例的状态也可能 是瞬时的或脱管的。

如果这些持久化类遵循一些简单的规则,Hibernate能够工作得更好,这些规则也被称作 简单传统Java对象(POJO:Plain Old Java Object)编程模型。但是这些规则并不是必需的。 实际上,Hibernate3对于你的持久化类几乎不做任何设想。你可以用其他的方法来表达领域模型: 比如,使用Map实例的树型结构。

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);
    }
}

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

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

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

4.1.2. 提供一个标识属性(identifier property)(可选)

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

标识符属性是可选的。可以不用管它,让Hibernate内部来追踪对象的识别。 但是我们并不推荐这样做。

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

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

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

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

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

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

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

Cat为它的所有持久化字段声明了访问方法。很多其他ORM工具直接对 实例变量进行持久化。我们相信,在关系数据库schema和类的内部数据结构之间引入间接层(原文为"非直接",indirection)会好一些。默认情况下Hibernate持久化JavaBeans风格的属性,认可 getFooisFoosetFoo这种形式的方法名。 如果需要,你可以对某些特定属性实行直接字段访问。

属性不需要要声明为public的。Hibernate可以持久化一个有 defaultprotectedprivate的get/set方法对 的属性进行持久化。

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()方法:

  • 想把持久类的实例放入Set中(当表示多值关联时,推荐这么做)

  • 想重用脱管实例

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

实现equals()/hashCode()最显而易见的方法是比较两个对象 标识符的值。如果值相同,则两个对象对应于数据库的同一行,因此它们是相等的(如果都被添加到 Set,则在Set中只有一个元素)。不幸的是,对生成的标识不能 使用这种方法。Hibernate仅对那些持久化对象赋标识值,一个新创建的实例将不会有任何标识值。此外, 如果一个实例没有被保存(unsaved),并且它当前正在一个Set中,保存它将会给这个对象 赋一个标识值。如果equals()hashCode()是基于标识值 实现的,则其哈希码将会改变,这违反了Set的契约。建议去Hibernate的站点阅读关于这个 问题的全部讨论。注意,这不是Hibernate的问题,而是一般的Java对象标识和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也支持动态模型 (在运行期使用MapMap)和象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-mapSessionFactory 设置了默认的实体模式之后,可以在运行期使用MapMap

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映射中找到。

4.5. 元组片断映射(Tuplizers)

org.hibernate.tuple.Tuplizer,以及其子接口,负责根据给定的org.hibernate.EntityMode,来复现片断数据。如果给定的片断数据被认为其是一种数据结构,"tuplizer"就是一个知道如何创建这样的数据结构,以及如何给这个数据结构赋值的东西。比如说,对于POJO这种Entity Mode,对应的tuplizer知道通过其构造方法来创建一个POJO,再通过其属性访问器来访问POJO属性。有两大类高层Tuplizer,分别是org.hibernate.tuple.entity.EntityTuplizerorg.hibernate.tuple.entity.ComponentTuplizer接口。EntityTuplizer负责管理上面提到的实体的契约,而ComponentTuplizer则是针对组件的。

用户也可以插入其自定义的tuplizer。或许您需要一种不同于dynamic-map entity-mode中使用的java.util.HashMapjava.util.Map实现;或许您需要与默认策略不同的代理生成策略(proxy generation strategy)。通过自定义tuplizer实现,这两个目标您都可以达到。Tuplizer定义被附加到它们期望管理的entity或者component映射中。回到我们的customer entity例子:

<hibernate-mapping>
    <class entity-name="Customer">
        <!--
            Override the dynamic-map entity-mode
            tuplizer for the customer entity
        -->
        <tuplizer entity-mode="dynamic-map"
                class="CustomMapTuplizerImpl"/>

        <id name="id" type="long" column="ID">
            <generator class="sequence"/>
        </id>

        <!-- other properties -->
        ...
    </class>
</hibernate-mapping>


public class CustomMapTuplizerImpl
        extends org.hibernate.tuple.entity.DynamicMapEntityTuplizer {
    // override the buildInstantiator() method to plug in our custom map...
    protected final Instantiator buildInstantiator(
            org.hibernate.mapping.PersistentClass mappingInfo) {
        return new CustomMapInstantiator( mappingInfo );
    }

    private static final class CustomMapInstantiator
            extends org.hibernate.tuple.DynamicMapInstantitor {
        // override the generateMap() method to return our custom map...
	    protected final Map generateMap() {
		    return new CustomMap();
	    }
    }
}

TODO:property和proxy包里的用户扩展框架文档。

第 5 章 对象/关系数据库映射基础(Basic O/R Mapping)

5.1. 映射定义(Mapping declaration)

对象和关系数据库之间的映射通常是用一个XML文档(XML document)来定义的。这个映射文档被设计为易读的, 并且可以手工修改。映射语言是以Java为中心,这意味着映射文档是按照持久化类的定义来创建的, 而非表的定义。

请注意,虽然很多Hibernate用户选择手写XML映射文档,但也有一些工具可以用来生成映射文档, 包括XDoclet,Middlegen和AndroMDA。

让我们从一个映射的例子开始:

<?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="eg">

        <class name="Cat" 
            table="cats"
            discriminator-value="C">
                
                <id name="id">
                        <generator class="native"/>
                </id>

                <discriminator column="subclass" 
                     type="character"/>

                <property name="weight"/>

                <property name="birthdate"
                    type="date" 
                    not-null="true" 
                    update="false"/>

                <property name="color"
                    type="eg.types.ColorUserType"
                    not-null="true"
                    update="false"/>

                <property name="sex"
                    not-null="true" 
                    update="false"/>

                <property name="litterId"
                    column="litterId"
                    update="false"/>

                <many-to-one name="mother"
                    column="mother_id"
                    update="false"/>

                <set name="kittens"
                    inverse="true"
                    order-by="litter_id">
                        <key column="mother_id"/>
                        <one-to-many class="Cat"/>
                </set>

                <subclass name="DomesticCat"
                    discriminator-value="D">

                        <property name="name" 
                            type="string"/>

                </subclass>

        </class>

        <class name="Dog">
                <!-- mapping for Dog could go here -->
        </class>

</hibernate-mapping>

我们现在开始讨论映射文档的内容。我们只描述Hibernate在运行时用到的文档元素和属性。 映射文档还包括一些额外的可选属性和元素,它们在使用schema导出工具的时候会影响导出的数据库schema结果。 (比如, not-null 属性。)

5.1.1. Doctype

所有的XML映射都需要定义如上所示的doctype。DTD可以从上述URL中获取, 也可以从hibernate-x.x.x/src/net/sf/hibernate目录中、 或hibernate.jar文件中找到。Hibernate总是会首先在它的classptah中搜索DTD文件。 如果你发现它是通过连接Internet查找DTD文件,就对照你的classpath目录检查XML文件里的DTD声明。

5.1.1.1. EntityResolver

As mentioned previously, Hibernate will first attempt to resolve DTDs in its classpath. The manner in which it does this is by registering a custom org.xml.sax.EntityResolver implementation with the SAXReader it uses to read in the xml files. This custom EntityResolver recognizes two different systemId namespaces. 如前所述,Hibernate首先在其classpath中查找DTD。其行为是依靠在系统中注册的org.xml.sax.EntityResolver的一个具体实现,SAXReader依靠它来读取xml文件。这一 EntityResolver 实现能辨认两种不同的 systenId命名空间。

  • 若resolver遇到了一个以http://hibernate.sourceforge.net/为开头的systemId,它会辨认出是hibernate namespace,resolver就试图通过加载Hibernate类的classloader来查找这些实体。

  • 若resolver遇到了一个使用classpath://URL协议的systemId,它会辨认出这是user namespace,resolver试图通过(1)当前线程上下文的classloader和(2)加载Hibernate class的classloader来查找这些实体。

使用user namespace(用户命名空间)的例子:

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd" [
    <!ENTITY types SYSTEM "classpath://your/domain/types.xml">
]>

<hibernate-mapping package="your.domain">
    <class name="MyEntity">
        <id name="id" type="my-custom-id-type">
            ...
        </id>
    <class>
    &types;
</hibernate-mapping>

types.xmlyour.domain包中的一个资源,它包含了一个定制的第 5.2.3 节 “自定义值类型”

5.1.2. hibernate-mapping

这个元素包括一些可选的属性。schemacatalog属性, 指明了这个映射所连接(refer)的表所在的schema和/或catalog名称。 假若指定了这个属性,表名会加上所指定的schema和catalog的名字扩展为全限定名。假若没有指定,表名就不会使用全限定名。 default-cascade指定了未明确注明cascade属性的Java属性和 集合类Hibernate会采取什么样的默认级联风格。auto-import属性默认让我们在查询语言中可以使用 非全限定名的类名。

<hibernate-mapping
         schema="schemaName"                          (1)
         catalog="catalogName"                        (2)
         default-cascade="cascade_style"              (3)
         default-access="field|property|ClassName"    (4)
         default-lazy="true|false"                    (5)
         auto-import="true|false"                     (6)
         package="package.name"                       (7)
 />
(1)

schema (可选): 数据库schema的名称。

(2)

catalog (可选): 数据库catalog的名称。

(3)

default-cascade (可选 - 默认为 none): 默认的级联风格。

(4)

default-access (可选 - 默认为 property): Hibernate用来访问所有属性的策略。可以通过实现PropertyAccessor接口 自定义。

(5)

default-lazy (可选 - 默认为 true): 指定了未明确注明lazy属性的Java属性和集合类, Hibernate会采取什么样的默认加载风格。

(6)

auto-import (可选 - 默认为 true): 指定我们是否可以在查询语言中使用非全限定的类名(仅限于本映射文件中的类)。

(7)

package (可选): 指定一个包前缀,如果在映射文档中没有指定全限定的类名, 就使用这个作为包名。

假若你有两个持久化类,它们的非全限定名是一样的(就是两个类的名字一样,所在的包不一样--译者注), 你应该设置auto-import="false"。如果你把一个“import过”的名字同时对应两个类, Hibernate会抛出一个异常。

注意hibernate-mapping 元素允许你嵌套多个如上所示的 <class>映射。但是最好的做法(也许一些工具需要的)是一个 持久化类(或一个类的继承层次)对应一个映射文件,并以持久化的超类名称命名,例如: Cat.hbm.xmlDog.hbm.xml,或者如果使用继承,Animal.hbm.xml

5.1.3. class

你可以使用class元素来定义一个持久化类:

<class
        name="ClassName"                              (1)
        table="tableName"                             (2)
        discriminator-value="discriminator_value"     (3)
        mutable="true|false"                          (4)
        schema="owner"                                (5)
        catalog="catalog"                             (6)
        proxy="ProxyInterface"                        (7)
        dynamic-update="true|false"                   (8)
        dynamic-insert="true|false"                   (9)
        select-before-update="true|false"             (10)
        polymorphism="implicit|explicit"              (11)
        where="arbitrary sql where condition"         (12)
        persister="PersisterClass"                    (13)
        batch-size="N"                                (14)
        optimistic-lock="none|version|dirty|all"      (15)
        lazy="true|false"                             (16)
        entity-name="EntityName"                      (17)
        check="arbitrary sql check condition"         (18)
        rowid="rowid"                                 (19)
        subselect="SQL expression"                    (20)
        abstract="true|false"                         (21)
        node="element-name"
/>
(1)

name (可选): 持久化类(或者接口)的Java全限定名。 如果这个属性不存在,Hibernate将假定这是一个非POJO的实体映射。

(2)

table (可选 - 默认是类的非全限定名): 对应的数据库表名。

(3)

discriminator-value (可选 - 默认和类名一样): 一个用于区分不同的子类的值,在多态行为时使用。它可以接受的值包括 nullnot null

(4)

mutable (可选,默认值为true): 表明该类的实例是可变的或者不可变的。

(5)

schema (可选): 覆盖在根<hibernate-mapping>元素中指定的schema名字。

(6)

catalog (可选): 覆盖在根<hibernate-mapping>元素中指定的catalog名字。

(7)

proxy (可选): 指定一个接口,在延迟装载时作为代理使用。 你可以在这里使用该类自己的名字。

(8)

dynamic-update (可选, 默认为 false): 指定用于UPDATE 的SQL将会在运行时动态生成,并且只更新那些改变过的字段。

(9)

dynamic-insert (可选, 默认为 false): 指定用于INSERT的 SQL 将会在运行时动态生成,并且只包含那些非空值字段。

(10)

select-before-update (可选, 默认为 false): 指定Hibernate除非确定对象真正被修改了(如果该值为true-译注),否则不会执行SQL UPDATE操作。在特定场合(实际上,它只在一个瞬时对象(transient object)关联到一个 新的session中时执行的update()中生效),这说明Hibernate会在UPDATE 之前执行一次额外的SQL SELECT操作,来决定是否应该执行 UPDATE

(11)

polymorphism(多态) (可选, 默认值为 implicit (隐式) ): 界定是隐式还是显式的使用多态查询(这只在Hibernate的具体表继承策略中用到-译注)。

(12)

where (可选) 指定一个附加的SQLWHERE 条件, 在抓取这个类的对象时会一直增加这个条件。

(13)

persister (可选): 指定一个定制的ClassPersister

(14)

batch-size (可选,默认是1) 指定一个用于 根据标识符(identifier)抓取实例时使用的"batch size"(批次抓取数量)。

(15)

optimistic-lock(乐观锁定) (可选,默认是version): 决定乐观锁定的策略。

(16)

lazy (可选): 通过设置lazy="false", 所有的延迟加载(Lazy fetching)功能将被全部禁用(disabled)。

(17)

entity-name (可选,默认为类名): Hibernate3允许一个类进行多次映射( 前提是映射到不同的表),并且允许使用Maps或XML代替Java层次的实体映射 (也就是实现动态领域模型,不用写持久化类-译注)。 更多信息请看第 4.4 节 “动态模型(Dynamic models)” and 第 18 章 XML映射

(18)

check (可选): 这是一个SQL表达式, 用于为自动生成的schema添加多行(multi-row)约束检查

(19)

rowid (可选): Hibernate可以使用数据库支持的所谓的ROWIDs,例如: Oracle数据库,如果你设置这个可选的rowid, Hibernate可以使用额外的字段rowid实现快速更新。ROWID是这个功能实现的重点, 它代表了一个存储元组(tuple)的物理位置。

(20)

subselect (可选): 它将一个不可变(immutable)并且只读的实体映射到一个数据库的 子查询中。当你想用视图代替一张基本表的时候,这是有用的,但最好不要这样做。更多的介绍请看下面内容。

(21)

abstract (可选): 用于在<union-subclass>的继承结构 (hierarchies)中标识抽象超类。

若指明的持久化类实际上是一个接口,这也是完全可以接受的。 之后你可以用元素<subclass>来指定该接口的实际实现类。 你可以持久化任何static(静态的)内部类。 你应该使用标准的类名格式来指定类名,比如:Foo$Bar

不可变类,mutable="false"不可以被应用程序更新或者删除。 这可以让Hibernate做一些小小的性能优化。

可选的proxy属性允许延迟加载类的持久化实例。 Hibernate开始会返回实现了这个命名接口的CGLIB代理。当代理的某个方法被实际调用的时候, 真实的持久化对象才会被装载。参见下面的“用于延迟装载的代理”。

Implicit (隐式)的多态是指,如果查询时给出的是任何超类、该类实现的接口或者该类的 名字,都会返回这个类的实例;如果查询中给出的是子类的名字,则会返回子类的实例。 Explicit (显式)的多态是指,只有在查询时给出明确的该类名字时才会返回这个类的实例; 同时只有在这个<class>的定义中作为<subclass> 或者<joined-subclass>出现的子类,才会可能返回。 在大多数情况下,默认的polymorphism="implicit"都是合适的。 显式的多态在有两个不同的类映射到同一个表的时候很有用。(允许一个“轻型”的类,只包含部分表字段)。

persister属性可以让你定制这个类使用的持久化策略。 你可以指定你自己实现 org.hibernate.persister.EntityPersister的子类,你甚至可以完全从头开始编写一个 org.hibernate.persister.ClassPersister接口的实现, 比如是用储存过程调用、序列化到文件或者LDAP数据库来实现。 参阅org.hibernate.test.CustomPersister,这是一个简单的例子 (“持久化”到一个Hashtable)。

请注意dynamic-updatedynamic-insert的设置并不会继承到子类, 所以在<subclass>或者<joined-subclass>元素中可能 需要再次设置。这些设置是否能够提高效率要视情形而定。请用你的智慧决定是否使用。

使用select-before-update通常会降低性能。如果你重新连接一个脱管(detache)对象实例 到一个Session中时,它可以防止数据库不必要的触发update。 这就很有用了。

如果你打开了dynamic-update,你可以选择几种乐观锁定的策略:

  • version(版本检查) 检查version/timestamp字段

  • all(全部) 检查全部字段

  • dirty(脏检查)只检察修改过的字段

  • none(不检查)不使用乐观锁定

我们非常强烈建议你在Hibernate中使用version/timestamp字段来进行乐观锁定。 对性能来说,这是最好的选择,并且这也是唯一能够处理在session外进行操作的策略(例如: 在使用Session.merge()的时候)。

对Hibernate映射来说视图和表是没有区别的,这是因为它们在数据层都是透明的( 注意:一些数据库不支持视图属性,特别是更新的时候)。有时你想使用视图,但却不能在数据库 中创建它(例如:在遗留的schema中)。这样的话,你可以映射一个不可变的(immutable)并且是 只读的实体到一个给定的SQL子查询表达式:

<class name="Summary">
    <subselect>
        select item.name, max(bid.amount), count(*)
        from item
        join bid on bid.item_id = item.id
        group by item.name
    </subselect>
    <synchronize table="item"/>
    <synchronize table="bid"/>
    <id name="name"/>
    ...
</class>

定义这个实体用到的表为同步(synchronize),确保自动刷新(auto-flush)正确执行, 并且依赖原实体的查询不会返回过期数据。<subselect>在属性元素 和一个嵌套映射元素中都可见。

5.1.4. id

被映射的类必须定义对应数据库表主键字段。大多数类有一个JavaBeans风格的属性, 为每一个实例包含唯一的标识。<id> 元素定义了该属性到数据库表主键字段的映射。

<id
        name="propertyName"                                          (1)
        type="typename"                                              (2)
        column="column_name"                                         (3)
        unsaved-value="null|any|none|undefined|id_value"             (4)
        access="field|property|ClassName"                            (5)
        node="element-name|@attribute-name|element/@attribute|.">

        <generator class="generatorClass"/>
</id>
(1)

name (可选): 标识属性的名字。

(2)

type (可选): 标识Hibernate类型的名字。

(3)

column (可选 - 默认为属性名): 主键字段的名字。

(4)

unsaved-value (可选 - 默认为一个切合实际(sensible)的值): 一个特定的标识属性值,用来标志该实例是刚刚创建的,尚未保存。 这可以把这种实例和从以前的session中装载过(可能又做过修改--译者注) 但未再次持久化的实例区分开来。

(5)

access (可选 - 默认为property): Hibernate用来访问属性值的策略。

如果 name属性不存在,会认为这个类没有标识属性。

unsaved-value 属性在Hibernate3中几乎不再需要。

还有一个另外的<composite-id>定义可以访问旧式的多主键数据。 我们强烈不建议使用这种方式。

5.1.4.1. Generator

可选的<generator>子元素是一个Java类的名字, 用来为该持久化类的实例生成唯一的标识。如果这个生成器实例需要某些配置值或者初始化参数, 用<param>元素来传递。

<id name="id" type="long" column="cat_id">
        <generator class="org.hibernate.id.TableHiLoGenerator">
                <param name="table">uid_table</param>
                <param name="column">next_hi_value_column</param>
        </generator>
</id>

所有的生成器都实现org.hibernate.id.IdentifierGenerator接口。 这是一个非常简单的接口;某些应用程序可以选择提供他们自己特定的实现。当然, Hibernate提供了很多内置的实现。下面是一些内置生成器的快捷名字:

increment

用于为long, short或者int类型生成 唯一标识。只有在没有其他进程往同一张表中插入数据时才能使用。 在集群下不要使用。

identity

对DB2,MySQL, MS SQL Server, Sybase和HypersonicSQL的内置标识字段提供支持。 返回的标识符是long, short 或者int类型的。

sequence

在DB2,PostgreSQL, Oracle, SAP DB, McKoi中使用序列(sequence), 而在Interbase中使用生成器(generator)。返回的标识符是long, short或者 int类型的。

hilo

使用一个高/低位算法高效的生成long, short 或者 int类型的标识符。给定一个表和字段(默认分别是 hibernate_unique_keynext_hi)作为高位值的来源。 高/低位算法生成的标识符只在一个特定的数据库中是唯一的。

seqhilo

使用一个高/低位算法来高效的生成long, short 或者 int类型的标识符,给定一个数据库序列(sequence)的名字。

uuid

用一个128-bit的UUID算法生成字符串类型的标识符, 这在一个网络中是唯一的(使用了IP地址)。UUID被编码为一个32位16进制数字的字符串。

guid

在MS SQL Server 和 MySQL 中使用数据库生成的GUID字符串。

native

根据底层数据库的能力选择identity, sequence 或者hilo中的一个。

assigned

让应用程序在save()之前为对象分配一个标示符。这是 <generator>元素没有指定时的默认生成策略。

select

通过数据库触发器选择一些唯一主键的行并返回主键值来分配一个主键。

foreign

使用另外一个相关联的对象的标识符。通常和<one-to-one>联合起来使用。

sequence-identity

一种特别的序列生成策略,使用数据库序列来生成实际值,但将它和JDBC3的getGeneratedKeys结合在一起,使得在插入语句执行的时候就返回生成的值。目前为止只有面向JDK 1.4的Oracle 10g驱动支持这一策略。注意,因为Oracle驱动程序的一个bug,这些插入语句的注释被关闭了。(原文:Note comments on these insert statements are disabled due to a bug in the Oracle drivers.)

5.1.4.2. 高/低位算法(Hi/Lo Algorithm)

hiloseqhilo生成器给出了两种hi/lo算法的实现, 这是一种很令人满意的标识符生成算法。第一种实现需要一个“特殊”的数据库表来保存下一个可用的“hi”值。 第二种实现使用一个Oracle风格的序列(在被支持的情况下)。

<id name="id" type="long" column="cat_id">
        <generator class="hilo">
                <param name="table">hi_value</param>
                <param name="column">next_value</param>
                <param name="max_lo">100</param>
        </generator>
</id>
<id name="id" type="long" column="cat_id">
        <generator class="seqhilo">
                <param name="sequence">hi_value</param>
                <param name="max_lo">100</param>
        </generator>
</id>

很不幸,你在为Hibernate自行提供Connection时无法使用hilo。 当Hibernate使用JTA获取应用服务器的数据源连接时,你必须正确地配置 hibernate.transaction.manager_lookup_class

5.1.4.3. UUID算法(UUID Algorithm )

UUID包含:IP地址,JVM的启动时间(精确到1/4秒),系统时间和一个计数器值(在JVM中唯一)。 在Java代码中不可能获得MAC地址或者内存地址,所以这已经是我们在不使用JNI的前提下的能做的最好实现了。

5.1.4.4. 标识字段和序列(Identity columns and Sequences)

对于内部支持标识字段的数据库(DB2,MySQL,Sybase,MS SQL),你可以使用identity关键字生成。 对于内部支持序列的数据库(DB2,Oracle, PostgreSQL, Interbase, McKoi,SAP DB), 你可以使用sequence风格的关键字生成。 这两种方式对于插入一个新的对象都需要两次SQL查询。

<id name="id" type="long" column="person_id">
        <generator class="sequence">
                <param name="sequence">person_id_sequence</param>
        </generator>
</id>
<id name="id" type="long" column="person_id" unsaved-value="0">
        <generator class="identity"/>
</id>

对于跨平台开发,native策略会从identity, sequencehilo中进行选择,选择哪一个,这取决于底层数据库的支持能力。

5.1.4.5. 程序分配的标识符(Assigned Identifiers)

如果你需要应用程序分配一个标示符(而非Hibernate来生成),你可以使用assigned 生成器。这种特殊的生成器会使用已经分配给对象的标识符属性的标识符值。 这个生成器使用一个自然键(natural key,有商业意义的列-译注)作为主键,而不是使用一个代理键( surrogate key,没有商业意义的列-译注)。这是没有指定<generator>元素时的默认行为

当选择assigned生成器时,除非有一个version或timestamp属性,或者你定义了 Interceptor.isUnsaved(),否则需要让Hiberante使用 unsaved-value="undefined",强制Hibernatet查询数据库来确定一个实例是瞬时的(transient) 还是脱管的(detached)。

5.1.4.6. 触发器实现的主键生成器(Primary keys assigned by triggers)

仅仅用于遗留的schema中 (Hibernate不能使用触发器生成DDL)。

<id name="id" type="long" column="person_id">
        <generator class="select">
                <param name="key">socialSecurityNumber</param>
        </generator>
</id>

&