Hibernate.orgCommunity Documentation

HIBERNATE - Relational Persistence for Idiomatic Java

Hibernate Reference Documentation

3.6.10.Final

Legal Notice

February 8, 2012


前言
1. 教程
1.1. 第一部分 - 第一个 Hibernate 应用程序
1.1.1. 设置
1.1.2. 第一个 class
1.1.3. 映射文件
1.1.4. Hibernate 配置
1.1.5. 用 Maven 构建
1.1.6. 启动和辅助类
1.1.7. 加载并存储对象
1.2. 第二部分 - 关联映射
1.2.1. 映射 Person 类
1.2.2. 单向 Set-based 的关联
1.2.3. 使关联工作
1.2.4. 值类型的集合
1.2.5. 双向关联
1.2.6. 使双向连起来
1.3. 第三部分 - EventManager web 应用程序
1.3.1. 编写基本的 servlet
1.3.2. 处理与渲染
1.3.3. 部署与测试
1.4. 总结
2. 体系结构(Architecture)
2.1. 概况(Overview)
2.1.1. Minimal architecture
2.1.2. Comprehensive architecture
2.1.3. Basic APIs
2.2. JMX 整合
2.3. 上下文相关的会话(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. Implementing a PersisterClassProvider
3.8. XML 配置文件
3.9. Java EE Application Server integration
3.9.1. 事务策略配置
3.9.2. JNDI 绑定的 SessionFactory
3.9.3. 在 JTA 环境下使用 Current Session context(当前 session 上下文)管理
3.9.4. JMX 部署
4. 持久化类(Persistent Classes)
4.1. 一个简单的 POJO 例子
4.1.1. 实现一个默认的(即无参数的)构造方法(constructor)
4.1.2. Provide an identifier property
4.1.3. Prefer non-final classes (semi-optional)
4.1.4. 为持久化字段声明访问器(accessors)和是否可变的标志(mutators)(可选)
4.2. 实现继承(Inheritance)
4.3. 实现 equals() 和 hashCode() 方法:
4.4. 动态模型(Dynamic models)
4.5. 元组片断映射(Tuplizers)
4.6. EntityNameResolvers
5. 对象/关系数据库映射基础(Basic O/R Mapping)
5.1. 映射定义(Mapping declaration)
5.1.1. Entity
5.1.2. Identifiers
5.1.3. Optimistic locking properties (optional)
5.1.4. Property
5.1.5. Embedded objects (aka components)
5.1.6. Inheritance strategy
5.1.7. Mapping one to one and one to many associations
5.1.8. 自然 ID(natural-id)
5.1.9. Any
5.1.10. 属性(Properties)
5.1.11. Some hbm.xml specificities
5.2. Hibernate 的类型
5.2.1. 实体(Entities)和值(values)
5.2.2. 基本值类型
5.2.3. 自定义值类型
5.3. 多次映射同一个类
5.4. SQL 中引号包围的标识符
5.5. 数据库生成属性(Generated Properties)
5.6. Column transformers: read and write expressions
5.7. 辅助数据库对象(Auxiliary Database Objects)
6. Types
6.1. Value types
6.1.1. Basic value types
6.1.2. Composite types
6.1.3. Collection types
6.2. Entity types
6.3. Significance of type categories
6.4. Custom types
6.4.1. Custom types using org.hibernate.type.Type
6.4.2. Custom types using org.hibernate.usertype.UserType
6.4.3. Custom types using org.hibernate.usertype.CompositeUserType
6.5. Type registry
7. 集合映射(Collection mappings)
7.1. 持久化集合类(Persistent collections)
7.2. How to map collections
7.2.1. 集合外键(Collection foreign keys)
7.2.2. 索引集合类(Indexed collections)
7.2.3. Collections of basic types and embeddable objects
7.3. 高级集合映射(Advanced collection mappings)
7.3.1. 有序集合(Sorted collections)
7.3.2. 双向关联(Bidirectional associations)
7.3.3. 双向关联,涉及有序集合类
7.3.4. 三重关联(Ternary associations)
7.3.5. Using an <idbag>
7.4. 集合例子(Collection example)
8. 关联关系映射
8.1. 介绍
8.2. 单向关联(Unidirectional associations)
8.2.1. 多对一(many-to-one)
8.2.2. 一对一(One-to-one)
8.2.3. 一对多(one-to-many)
8.3. 使用连接表的单向关联(Unidirectional associations with join tables)
8.3.1. 一对多(one-to-many)
8.3.2. 多对一(many-to-one)
8.3.3. 一对一(One-to-one)
8.3.4. 多对多(many-to-many)
8.4. 双向关联(Bidirectional associations)
8.4.1. 一对多(one to many)/多对一(many to one)
8.4.2. 一对一(One-to-one)
8.5. 使用连接表的双向关联(Bidirectional associations with join tables)
8.5.1. 一对多(one to many)/多对一(many to one)
8.5.2. 一对一(one to one)
8.5.3. 多对多(many-to-many)
8.6. 更复杂的关联映射
9. 组件(Component)映射
9.1. 依赖对象(Dependent objects)
9.2. 在集合中出现的依赖对象(Collections of dependent objects)
9.3. 组件作为 Map 的索引(Components as Map indices )
9.4. 组件作为联合标识符(Components as composite identifiers)
9.5. 动态组件(Dynamic components)
10. 继承映射(Inheritance Mapping)
10.1. 三种策略
10.1.1. 每个类分层结构一张表(Table per class hierarchy)
10.1.2. 每个子类一张表(Table per subclass)
10.1.3. 每个子类一张表(Table per subclass),使用辨别标志(Discriminator)
10.1.4. 混合使用“每个类分层结构一张表”和“每个子类一张表”
10.1.5. 每个具体类一张表(Table per concrete class)
10.1.6. 每个具体类一张表,使用隐式多态
10.1.7. 隐式多态和其他继承映射混合使用
10.2. 限制
11. 与对象共事
11.1. Hibernate 对象状态(object states)
11.2. 使对象持久化
11.3. 装载对象
11.4. 查询
11.4.1. 执行查询
11.4.2. 过滤集合
11.4.3. 条件查询(Criteria queries)
11.4.4. 使用原生 SQL 的查询
11.5. 修改持久对象
11.6. 修改脱管(Detached)对象
11.7. 自动状态检测
11.8. 删除持久对象
11.9. 在两个不同数据库间复制对象
11.10. Session 刷出(flush)
11.11. 传播性持久化(transitive persistence)
11.12. 使用元数据
12. Read-only entities
12.1. Making persistent entities read-only
12.1.1. Entities of immutable classes
12.1.2. Loading persistent entities as read-only
12.1.3. Loading read-only entities from an HQL query/criteria
12.1.4. Making a persistent entity read-only
12.2. Read-only affect on property type
12.2.1. Simple properties
12.2.2. Unidirectional associations
12.2.3. Bidirectional associations
13. 事务和并发
13.1. Session 和事务范围(transaction scope)
13.1.1. 操作单元(Unit of work)
13.1.2. 长对话
13.1.3. 关注对象标识(Considering object identity)
13.1.4. 常见问题
13.2. 数据库事务声明
13.2.1. 非托管环境
13.2.2. 使用 JTA
13.2.3. 异常处理
13.2.4. 事务超时
13.3. 乐观并发控制(Optimistic concurrency control)
13.3.1. 应用程序级别的版本检查(Application version checking)
13.3.2. 扩展周期的 session 和自动版本化
13.3.3. 脱管对象(deatched object)和自动版本化
13.3.4. 定制自动版本化行为
13.4. 悲观锁定(Pessimistic Locking)
13.5. 连接释放模式(Connection Release Modes)
14. 拦截器与事件(Interceptors and events)
14.1. 拦截器(Interceptors)
14.2. 事件系统(Event system)
14.3. Hibernate 的声明式安全机制
15. 批量处理(Batch processing)
15.1. 批量插入(Batch inserts)
15.2. 批量更新(Batch updates)
15.3. StatelessSession(无状态 session)接口
15.4. DML(数据操作语言)风格的操作(DML-style operations)
16. HQL: Hibernate 查询语言
16.1. 大小写敏感性问题
16.2. from 子句
16.3. 关联(Association)与连接(Join)
16.4. join 语法的形式
16.5. 引用 identifier 属性
16.6. select 子句
16.7. 聚集函数
16.8. 多态查询
16.9. where 子句
16.10. 表达式
16.11. order by 子句
16.12. group by 子句
16.13. 子查询
16.14. HQL 示例
16.15. 批量的 UPDATE 和 DELETE
16.16. 小技巧 & 小窍门
16.17. 组件
16.18. Row value 构造函数语法
17. 条件查询(Criteria Queries)
17.1. 创建一个 Criteria 实例
17.2. 限制结果集内容
17.3. 结果集排序
17.4. 关联
17.5. 动态关联抓取
17.6. 查询示例
17.7. 投影(Projections)、聚合(aggregation)和分组(grouping)
17.8. 离线(detached)查询和子查询
17.9. 根据自然标识查询(Queries by natural identifier)
18. Native SQL 查询
18.1. 使用 SQLQuery
18.1.1. 标量查询(Scalar queries)
18.1.2. 实体查询(Entity queries)
18.1.3. 处理关联和集合类(Handling associations and collections)
18.1.4. 返回多个实体(Returning multiple entities)
18.1.5. 返回非受管实体(Returning non-managed entities)
18.1.6. 处理继承(Handling inheritance)
18.1.7. 参数(Parameters)
18.2. 命名 SQL 查询
18.2.1. 使用 return-property 来明确地指定字段/别名
18.2.2. 使用存储过程来查询
18.3. 定制 SQL 用来 create,update 和 delete
18.4. 定制装载 SQL
19. 过滤数据
19.1. Hibernate 过滤器(filters)
20. XML 映射
20.1. 用 XML 数据进行工作
20.1.1. 指定同时映射 XML 和类
20.1.2. 只定义 XML 映射
20.2. XML 映射元数据
20.3. 操作 XML 数据
21. 提升性能
21.1. 抓取策略(Fetching strategies)
21.1.1. 操作延迟加载的关联
21.1.2. 调整抓取策略(Tuning fetch strategies)
21.1.3. 单端关联代理(Single-ended association proxies)
21.1.4. 实例化集合和代理(Initializing collections and proxies)
21.1.5. 使用批量抓取(Using batch fetching)
21.1.6. 使用子查询抓取(Using subselect fetching)
21.1.7. Fetch profile(抓取策略)
21.1.8. 使用延迟属性抓取(Using lazy property fetching)
21.2. 二级缓存(The Second Level Cache)
21.2.1. 缓存映射(Cache mappings)
21.2.2. 策略:只读缓存(Strategy:read only)
21.2.3. 策略:读写/缓存(Strategy:read/write)
21.2.4. 策略:非严格读/写缓存(Strategy:nonstrict read/write)
21.2.5. 策略:事务缓存(transactional)
21.2.6. 各种缓存提供商/缓存并发策略的兼容性
21.3. 管理缓存(Managing the caches)
21.4. 查询缓存(The Query Cache)
21.4.1. 启用查询缓存
21.4.2. 查询缓存区
21.5. 理解集合性能(Understanding Collection performance)
21.5.1. 分类(Taxonomy)
21.5.2. Lists,maps 和 sets 用于更新效率最高
21.5.3. Bag 和 list 是反向集合类中效率最高的
21.5.4. 一次性删除(One shot delete)
21.6. 监测性能(Monitoring performance)
21.6.1. 监测 SessionFactory
21.6.2. 数据记录(Metrics)
22. 工具箱指南
22.1. Schema 自动生成(Automatic schema generation)
22.1.1. 对 schema 定制化(Customizing the schema)
22.1.2. 运行该工具
22.1.3. 属性(Properties)
22.1.4. 使用 Ant(Using Ant)
22.1.5. 对 schema 的增量更新(Incremental schema updates)
22.1.6. 用 Ant 来增量更新 schema(Using Ant for incremental schema updates)
22.1.7. Schema 校验
22.1.8. 使用 Ant 进行 schema 校验
23. Additional modules
23.1. Bean Validation
23.1.1. Adding Bean Validation
23.1.2. Configuration
23.1.3. Catching violations
23.1.4. Database schema
23.2. Hibernate Search
23.2.1. Description
23.2.2. Integration with Hibernate Annotations
24. 示例:父子关系(Parent/Child)
24.1. 关于 collections 需要注意的一点
24.2. 双向的一对多关系(Bidirectional one-to-many)
24.3. 级联生命周期(Cascading lifecycle)
24.4. 级联与未保存值(unsaved-value)
24.5. 结论
25. 示例:Weblog 应用程序
25.1. 持久化类(Persistent Classes)
25.2. Hibernate 映射
25.3. Hibernate 代码
26. 示例:复杂映射实例
26.1. Employer(雇主)/Employee(雇员)
26.2. Author(作家)/Work(作品)
26.3. Customer(客户)/Order(订单)/Product(产品)
26.4. 杂例
26.4.1. "Typed" 一对一关联
26.4.2. 组合键示例
26.4.3. 共有组合键属性的多对多(Many-to-many with shared composite key attribute)
26.4.4. 基于内容的识别
26.4.5. 备用键的联合
27. 最佳实践(Best Practices)
28. 数据库移植性考量
28.1. 移植性基础
28.2. Dialect
28.3. 方言的使用
28.4. 标识符的生成
28.5. 数据库函数
28.6. 类型映射
参考资料

Working with both Object-Oriented software and Relational Databases can be cumbersome and time consuming. Development costs are significantly higher due to a paradigm mismatch between how data is represented in objects versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments. The term Object/Relational Mapping refers to the technique of mapping data from an object model representation to a relational data model representation (and visa versa). See http://en.wikipedia.org/wiki/Object-relational_mapping for a good high-level discussion.

注意

While having a strong background in SQL is not required to use Hibernate, having a basic understanding of the concepts can greatly help you understand Hibernate more fully and quickly. Probably the single best background is an understanding of data modeling principles. You might want to consider these resources as a good starting point:

Hibernate not only takes care of the mapping from Java classes to database tables (and from Java data types to SQL data types), but also provides data query and retrieval facilities. It can significantly reduce development time otherwise spent with manual data handling in SQL and JDBC. Hibernate’s design goal is to relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for manual, hand-crafted data processing using SQL and JDBC. However, unlike many other persistence solutions, Hibernate does not hide the power of SQL from you and guarantees that your investment in relational technology and knowledge is as valid as always.

Hibernate may not be the best solution for data-centric applications that only use stored-procedures to implement the business logic in the database, it is most useful with object-oriented domain models and business logic in the Java-based middle-tier. However, Hibernate can certainly help you to remove or encapsulate vendor-specific SQL code and will help with the common task of result set translation from a tabular representation to a graph of objects.

如果你对 Hibernate 和对象/关系型数据库映射还是个新手,甚至对 Java 也不熟悉,请按照下面的步骤来学习。

  1. Read 第 1 章 教程 for a tutorial with step-by-step instructions. The source code for the tutorial is included in the distribution in the doc/reference/tutorial/ directory.

  2. Read 第 2 章 体系结构(Architecture) to understand the environments where Hibernate can be used.

  3. 查看 Hibernate 发行包中的 eg/ 目录,里面有个一简单的独立运行的程序。把你的 JDBC 驱动复制到 lib/ 目录并修改一下 etc/hibernate.properties,指定数据库的信息。然后进入命令行,切换到发行包的目录,输入 ant eg(使用 Ant),或者在 Windows 系统下使用 build eg

  4. Use this reference documentation as your primary source of information. Consider reading [JPwH] if you need more help with application design, or if you prefer a step-by-step tutorial. Also visit http://caveatemptor.hibernate.org and download the example application from [JPwH].

  5. 在 Hibernate 网站上可以找到问题和解答(FAQ)。

  6. 在 Hibernate 网站上还有第三方的演示、示例和教程的链接。

  7. Hibernate 网站的社区是讨论关于设计模式以及很多整合方案(Tomcat、JBoss AS、Struts、EJB 等)的好地方。

There are a number of ways to become involved in the Hibernate community, including

  • Trying stuff out and reporting bugs. See http://hibernate.org/issuetracker.html details.

  • Trying your hand at fixing some bugs or implementing enhancements. Again, see http://hibernate.org/issuetracker.html details.

  • http://hibernate.org/community.html list a few ways to engage in the community.

    • There are forums for users to ask questions and receive help from the community.

    • There are also IRC channels for both user and developer discussions.

  • Helping improve or translate this documentation. Contact us on the developer mailing list if you have interest.

  • Evangelizing Hibernate within your organization.

面向新用户,从一个简单的使用内存数据库的例子开始,本章提供对 Hibernate 的逐步介绍。本教程基于 Michael Gloegl 早期编写的手册。所有代码都包含在 tutorials/web 目录下。

重要

本教程期望用户具备 Java 和 SQL 知识。如果你这方面的知识有限,我们建议你在学习 Hibernate 之前先好好了解这些技术。

注意

本版本在源代码目录 tutorial/eg 下还包含另外一个例程。

在这个例子里,我们将设立一个小应用程序可以保存我们希望参加的活动(events)和这些活动主办方的相关信息。(译者注:在本教程的后面部分,我们将直接使用 event 而不是它的中文翻译“活动”,以免混淆。)

注意

虽然你可以使用任何数据库,我们还是用 HSQLDB(一个用 Java 编写的内存数据库)来避免花费篇章对数据库服务器的安装/配置进行解释。

我们需要做的第一件事情是设置开发环境。我们将使用许多构建工具如 Maven 所鼓吹的“标准格式”。特别是 Maven,它的资源对这个格式(layout)有着很好的描述。因为本教程使用的是 web 应用程序,我么将创建和使用 src/main/javasrc/main/resourcessrc/main/webapp 目录。

在本教程里我们将使用 Maven,利用其 transitive dependency 管理以及根据 Maven 描述符用 IDE 自动设置项目的能力。


<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion
>4.0.0</modelVersion>

    <groupId
>org.hibernate.tutorials</groupId>
    <artifactId
>hibernate-tutorial</artifactId>
    <version
>1.0.0-SNAPSHOT</version>
    <name
>First Hibernate Tutorial</name>

    <build>
         <!-- we dont want the version to be part of the generated war file name -->
         <finalName
>${artifactId}</finalName>
    </build>

    <dependencies>
        <dependency>
            <groupId
>org.hibernate</groupId>
            <artifactId
>hibernate-core</artifactId>
        </dependency>

        <!-- Because this is a web app, we also have a dependency on the servlet api. -->
        <dependency>
            <groupId
>javax.servlet</groupId>
            <artifactId
>servlet-api</artifactId>
        </dependency>

        <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend -->
        <dependency>
            <groupId
>org.slf4j</groupId>
            <artifactId
>slf4j-simple</artifactId>
        </dependency>

        <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
        <dependency>
            <groupId
>javassist</groupId>
            <artifactId
>javassist</artifactId>
        </dependency>
    </dependencies>

</project
>

提示

It is not a requirement to use Maven. If you wish to use something else to build this tutorial (such as Ant), the layout will remain the same. The only change is that you will need to manually account for all the needed dependencies. If you use something like Ivy providing transitive dependency management you would still use the dependencies mentioned below. Otherwise, you'd need to grab all dependencies, both explicit and transitive, and add them to the project's classpath. If working from the Hibernate distribution bundle, this would mean hibernate3.jar, all artifacts in the lib/required directory and all files from either the lib/bytecode/cglib or lib/bytecode/javassist directory; additionally you will need both the servlet-api jar and one of the slf4j logging backends.

把这个文件保存为项目根目录下的 pom.xml

接下来我们创建一个类,用来代表那些我们希望储存在数据库里的 event,这是一个具有一些属性的简单 JavaBean 类:

package org.hibernate.tutorial.domain;


import java.util.Date;
public class Event {
    private Long id;
    private String title;
    private Date date;
    public Event() {}
    public Long getId() {
        return id;
    }
    private void setId(Long id) {
        this.id = id;
    }
    public Date getDate() {
        return date;
    }
    public void setDate(Date date) {
        this.date = date;
    }
    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }
}

你可以看到这个类对属性的存取方法(getter and setter method)使用了标准 JavaBean 命名约定,同时把类属性(field)的访问级别设成私有的(private)。这是推荐的设计,但并不是必须的。Hibernate 也可以直接访问这些 field,而使用访问方法(accessor method)的好处是提供了重构时的健壮性(robustness)。

对一特定的 event, id 属性持有唯一的标识符(identifier)的值。如果我们希望使用 Hibernate 提供的所有特性,那么所有的持久化实体(persistent entity)类(这里也包括一些次要依赖类)都需要一个这样的标识符属性。而事实上,大多数应用程序(特别是 web 应用程序)都需要通过标识符来区别对象,所以你应该考虑使用标识符属性而不是把它当作一种限制。然而,我们通常不会操作对象的标识(identity),因此它的 setter 方法的访问级别应该声明 private。这样当对象被保存的时候,只有 Hibernate 可以为它分配标识符值。你可看到Hibernate可以直接访问 public,private 和 protected 的访问方法和 field。所以选择哪种方式完全取决于你,你可以使你的选择与你的应用程序设计相吻合。

所有的持久化类(persistent classes)都要求有无参的构造器,因为 Hibernate 必须使用 Java 反射机制来为你创建对象。构造器(constructor)的访问级别可以是 private,然而当生成运行时代理(runtime proxy)的时候则要求使用至少是 package 级别的访问控制,这样在没有字节码指令(bytecode instrumentation)的情况下,从持久化类里获取数据会更有效率。

把这个文件保存到 src/main/java/org/hibernate/tutorial/domain 目录下。

Hibernate 需要知道怎样去加载(load)和存储(store)持久化类的对象。这正是 Hibernate 映射文件发挥作用的地方。映射文件告诉 Hibernate 它应该访问数据库(database)里面的哪个表(table)及应该使用表里面的哪些字段(column)。

一个映射文件的基本结构看起来像这样:


<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
        "http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="org.hibernate.tutorial.domain">
[...]
</hibernate-mapping
>

注意 Hibernate 的 DTD 是非常复杂的。你的编辑器或者 IDE 里使用它来自动完成那些用来映射的 XML 元素(element)和属性(attribute)。你也可以在文本编辑器里打开 DTD — 这是最简单的方式来概览所有的元素和 attribute,并查看它们的缺省值以及注释。注意 Hibernate 不会从 web 加载 DTD 文件,但它会首先在应用程序的 classpath 中查找。DTD 文件已包括在 hibernate3.jar 里,同时也在 Hibernate 发布包的 src/ 目录下。

hibernate-mapping 标签(tag)之间, 含有一个 class 元素。所有的持久化实体类(再次声明,或许接下来会有依赖类,就是那些次要的实体)都需要一个这样的映射,来把类对象映射到 SQL 数据库里的表:


<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">

    </class>

</hibernate-mapping
>

到目前为止,我们告诉了 Hibernate 怎样把 Events 类的对象持久化到数据库的 EVENTS 表里,以及怎样从 EVENTS 表加载到 Events 类的对象。每个实例对应着数据库表中的一行。现在我们将继续讨论有关唯一标识符属性到数据库表的映射。另外,由于我们不关心怎样处理这个标识符,我们就配置由 Hibernate 的标识符生成策略来产生代理主键字段:


<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
    </class>

</hibernate-mapping
>

id 元素是对 identifier 属性的声明。name="id" 映射属性声明了 JavaBean 属性的名称并告诉 Hibernate 使用 getId()setId() 方法来访问这个属性。column 属性告诉 Hibernate EVENTS 表的哪个字段持有主键值。

嵌套的 generator 元素指定标识符的生成策略(也就是标识符值是怎么产生的)。在这个例子里,我们选择 native,它提供了取决于数据库方言的可移植性。Hibernate 数据库生成的、全局性唯一的以及应用程序分配的标识符。标识符值的生成也是 Hibernate 的扩展功能之一,你可以插入自己的策略。

最后我们在映射文件里面包含需要持久化属性的声明。默认情况下,类里面的属性都被视为非持久化的:



<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
        <property name="date" type="timestamp" column="EVENT_DATE"/>
        <property name="title"/>
    </class>

</hibernate-mapping
>

id 元素一样,property 元素的 name 属性告诉 Hibernate 使用哪个 getter 和 setter 方法。在此例中,Hibernate 会寻找 getDate()setDate()getTitle()setTitle() 方法。

注意

为什么 date 属性的映射含有 column attribute,而 title 却没有?当没有设定 column attribute 的时候,Hibernate 缺省地使用 JavaBean 的属性名作为字段名。对于 title,这样工作得很好。然而,date 在多数的数据库里,是一个保留关键字,所以我们最好把它映射成一个不同的名字。

另一有趣的事情是 title 属性缺少一个 type attribute。我们在映射文件里声明并使用的类型,却不是我们期望的那样,是 Java 数据类型,同时也不是 SQL 数据库的数据类型。这些类型就是所谓的 Hibernate 映射类型(mapping types),它们能把 Java 数据类型转换到 SQL 数据类型,反之亦然。再次重申,如果在映射文件中没有设置 type 属性的话,Hibernate 会自己试着去确定正确的转换类型和它的映射类型。在某些情况下这个自动检测机制(在 Java 类上使用反射机制)不会产生你所期待或需要的缺省值。date 属性就是个很好的例子,Hibernate 无法知道这个属性(java.util.Date 类型的)应该被映射成:SQL date,或 timestamp,还是 time 字段。在此例中,把这个属性映射成 timestamp 转换器,这样我们预留了日期和时间的全部信息。

提示

当处理映射文件时,Hibernate 用反射(reflection)来决定这个映射类型。这需要时间和资源,所以如果你注重启动性能,你应该考虑显性地定义所用的类型。

把这个映射文件保存为 src/main/resources/org/hibernate/tutorial/domain/Event.hbm.xml

此时,你应该有了持久化类和它的映射文件。现在是配置 Hibernate 的时候了。首先让我们设立 HSQLDB 使其运行在“服务器模式”。

在开发的根目录下创建一个 data 目录 - 这是 HSQL DB 存储数据文件的地方。此时在 data 目录中运行 java -classpath ../lib/hsqldb.jar org.hsqldb.Server 就可启动数据库。你可以在 log 中看到它的启动,及绑定到 TCP/IP 套接字,这正是我们的应用程序稍后会连接的地方。如果你希望在本例中运行一个全新的数据库,就在窗口中按下 CTRL + C 来关闭 HSQL 数据库,并删除 data/ 目录下的所有文件,再重新启动 HSQL 数据库。

Hibernate 将为你的应用程序连接到数据库,所以它需要知道如何获取连接。在这个教程里,我们使用一个独立连接池(和 javax.sql.DataSource 相反)。Hibernate 支持两个第三方的开源 JDBC 连接池:c3p0proxool。然而,在本教程里我们将使用 Hibernate 内置的连接池。

小心

嵌入的 Hibernate 连接池不用于产品环境。它缺乏连接池里的几个功能。

为了保存 Hibernate 的配置,我们可以使用一个简单的 hibernate.properties 文件,或者一个稍微复杂的 hibernate.cfg.xml,甚至可以完全使用程序来配置 Hibernate。多数用户更喜欢使用 XML 配置文件:


<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <session-factory>

        <!-- Database connection settings -->
        <property name="connection.driver_class"
>org.hsqldb.jdbcDriver</property>
        <property name="connection.url"
>jdbc:hsqldb:hsql://localhost</property>
        <property name="connection.username"
>sa</property>
        <property name="connection.password"
></property>

        <!-- JDBC connection pool (use the built-in) -->
        <property name="connection.pool_size"
>1</property>

        <!-- SQL dialect -->
        <property name="dialect"
>org.hibernate.dialect.HSQLDialect</property>

        <!-- Enable Hibernate's automatic session context management -->
        <property name="current_session_context_class"
>thread</property>

        <!-- Disable the second-level cache  -->
        <property name="cache.provider_class"
>org.hibernate.cache.NoCacheProvider</property>

        <!-- Echo all executed SQL to stdout -->
        <property name="show_sql"
>true</property>

        <!-- Drop and re-create the database schema on startup -->
        <property name="hbm2ddl.auto"
>update</property>

        <mapping resource="org/hibernate/tutorial/domain/Event.hbm.xml"/>

    </session-factory>

</hibernate-configuration
>

注意

请注意,这个配置文件指定了一个不同的 DTD。

注意这个 XML 配置使用了一个不同的 DTD。在这里,我们配置了 Hibernate 的SessionFactory — 一个关联于特定数据库全局的工厂(factory)。如果你要使用多个数据库,就要用多个的 <session-factory>,通常把它们放在多个配置文件中(为了更容易启动)。

签名 4 个 property 元素包含了 JDBC 连接所必需的配置。方言 property 元素指定了 Hibernate 生成的特定 SQL 语句。

提示

In most cases, Hibernate is able to properly determine which dialect to use. See 第 28.3 节 “方言的使用” for more information.

最开始的 4 个 property 元素包含必要的 JDBC 连接信息。方言(dialect)的 property 元素指明 Hibernate 生成的特定 SQL 变量。你很快会看到,Hibernate 对持久化上下文的自动 session 管理就会派上用场。 打开 hbm2ddl.auto 选项将自动生成数据库模式(schema)- 直接加入数据库中。当然这个选项也可以被关闭(通过去除这个配置选项)或者通过 Ant 任务 SchemaExport 的帮助来把数据库 schema 重定向到文件中。最后,在配置中为持久化类加入映射文件。

把这个文件保存为 src/main/resources 目录下的 hibernate.cfg.xml

我们将用 Maven 构建这个教程。你将需要安装 Maven;你可以从 Maven 下载页面获得 Maven。Maen 将读取我们先前创建的 /pom.xml 并知道执行基本的项目任务。首先,让我们运行 compile 目标来确保我们可以编译到目前为止的所有程序:

[hibernateTutorial]$ mvn compile
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building First Hibernate Tutorial
[INFO]    task-segment: [compile]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 1 source file to /home/steve/projects/sandbox/hibernateTutorial/target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009
[INFO] Final Memory: 5M/547M
[INFO] ------------------------------------------------------------------------

是时候来加载和储存一些 Event 对象了,但首先我们得编写一些基础的代码以完成设置。我们必须启动 Hibernate,此过程包括创建一个全局的 SessoinFactory,并把它储存在应用程序代码容易访问的地方。SessionFactory 可以创建并打开新的 Session。一个 Session 代表一个单线程的单元操作,org.hibernate.SessionFactory 则是个线程安全的全局对象,只需要被实例化一次。

我们将创建一个 HibernateUtil 辅助类(helper class)来负责启动 Hibernate 和更方便地操作 org.hibernate.SessionFactory。让我们来看一下它的实现:

package org.hibernate.tutorial.util;


import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;
public class HibernateUtil {
    private static final SessionFactory sessionFactory = buildSessionFactory();
    private static SessionFactory buildSessionFactory() {
        try {
            // Create the SessionFactory from hibernate.cfg.xml
            return new Configuration().configure().buildSessionFactory();
        }
        catch (Throwable ex) {
            // Make sure you log the exception, as it might be swallowed
            System.err.println("Initial SessionFactory creation failed." + ex);
            throw new ExceptionInInitializerError(ex);
        }
    }
    public static SessionFactory getSessionFactory() {
        return sessionFactory;
    }
}

把这段代码保存为 src/main/java/org/hibernate/tutorial/util/HibernateUtil.java

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

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

再次编译这个应用程序应该不会有问题。最后我们需要配置一个日志(logging)系统 — Hibernate 使用通用日志接口,允许你在 Log4j 和 JDK 1.4 日志之间进行选择。多数开发者更喜欢 Log4j:从 Hibernate 的发布包中(它在 etc/ 目录下)拷贝 log4j.properties 到你的 src 目录,与 hibernate.cfg.xml 放在一起。看一下配置示例,如果你希望看到更加详细的输出信息,你可以修改配置。默认情况下,只有 Hibernate 的启动信息才会显示在标准输出上。

示例的基本框架完成了 — 现在我们可以用 Hibernate 来做些真正的工作。

We are now ready to start doing some real work with Hibernate. Let's start by writing an EventManager class with a main() method:

package org.hibernate.tutorial;


import org.hibernate.Session;
import java.util.*;
import org.hibernate.tutorial.domain.Event;
import org.hibernate.tutorial.util.HibernateUtil;
public class EventManager {
    public static void main(String[] args) {
        EventManager mgr = new EventManager();
        if (args[0].equals("store")) {
            mgr.createAndStoreEvent("My Event", new Date());
        }
        HibernateUtil.getSessionFactory().close();
    }
    private void createAndStoreEvent(String title, Date theDate) {
        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);
        session.save(theEvent);
        session.getTransaction().commit();
    }
}

createAndStoreEvent() 来里我们创建了一个新的 Event 对象并把它传递给 Hibernate。现在 Hibernate 负责与 SQL 打交道,并把 INSERT 命令传给数据库。

A org.hibernate.Session is designed to represent a single unit of work (a single atomic piece of work to be performed). For now we will keep things simple and assume a one-to-one granularity between a Hibernate org.hibernate.Session and a database transaction. To shield our code from the actual underlying transaction system we use the Hibernate org.hibernate.Transaction API. In this particular case we are using JDBC-based transactional semantics, but it could also run with JTA.

sessionFactory.getCurrentSession() 是干什么的呢?首先,只要你持有 org.hibernate.SessionFactory,大可在任何时候、任何地点调用这个方法。getCurrentSession() 方法总会返回“当前的”工作单元。记得我们在 src/main/resources/hibernate.cfg.xml 中把这一配置选项调整为 "thread" 了吗?因此,因此,当前工作单元被绑定到当前执行我们应用程序的 Java 线程。但是,这并非是完全准确的,你还得考虑工作单元的生命周期范围(scope),它何时开始,又何时结束。

org.hibernate.Session 在第一次被使用的时候,即第一次调用 getCurrentSession() 的时候,其生命周期就开始。然后它被 Hibernate 绑定到当前线程。当事务结束的时候,不管是提交还是回滚,Hibernate 会自动把 org.hibernate.Session 从当前线程剥离,并且关闭它。假若你再次调用 getCurrentSession(),你会得到一个新的 org.hibernate.Session,并且开始一个新的工作单元。

和工作单元的生命周期这个话题相关,Hibernate org.hibernate.Session 是否被应该用来执行多次数据库操作?上面的例子对每一次操作使用了一个 org.hibernate.Session,这完全是巧合,这个例子不是很复杂,无法展示其他方式。Hibernate org.hibernate.Session 的生命周期可以很灵活,但是你绝不要把你的应用程序设计成为每一次数据库操作都用一个新的 Hibernate org.hibernate.Session。因此就算下面的例子(它们都很简单)中你可以看到这种用法,记住每次操作一个 session 是一个反模式。在本教程的后面会展示一个真正的(web)程序。

See 第 13 章 事务和并发 for more information about transaction handling and demarcation. The previous example also skipped any error handling and rollback.

要运行它,我们将使用 Maven exec 插件以及必要的 classpath 设置来进行调用:mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="store"

注意

你可能需要先执行 mvn compile

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

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

执行 HQL INSERT 语句的例子如下:

我们想要列出所有已经被存储的 events,就要增加一个条件分支选项到 main 方法中:

        if (args[0].equals("store")) {

            mgr.createAndStoreEvent("My Event", new Date());
        }
        else if (args[0].equals("list")) {
            List events = mgr.listEvents();
            for (int i = 0; i < events.size(); i++) {
                Event theEvent = (Event) events.get(i);
                System.out.println(
                        "Event: " + theEvent.getTitle() + " Time: " + theEvent.getDate()
                );
            }
        }

我们也增加一个新的 listEvents() 方法:

    private List listEvents() {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        List result = session.createQuery("from Event").list();
        session.getTransaction().commit();
        return result;
    }

Here, we are using a Hibernate Query Language (HQL) query to load all existing Event objects from the database. Hibernate will generate the appropriate SQL, send it to the database and populate Event objects with the data. You can create more complex queries with HQL. See 第 16 章 HQL: Hibernate 查询语言 for more information.

现在我们可以再次用 Maven exec plugin - mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="list" 调用新的功能了。

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

我们将向 Person 类增加一连串的 events。那样,通过调用 aPerson.getEvents(),就可以轻松地导航到特定 person 所参与的 events,而不用去执行一个显式的查询。我们使用 Java 的集合类(collection):Set,因为 set 不包含重复的元素及与我们无关的排序。

public class Person {


    private Set events = new HashSet();
    public Set getEvents() {
        return events;
    }
    public void setEvents(Set events) {
        this.events = events;
    }
}

在映射这个关联之前,先考虑一下此关联的另外一端。很显然,我们可以保持这个关联是单向的。或者,我们可以在 Event 里创建另外一个集合,如果希望能够双向地导航,如:anEvent.getParticipants()。从功能的角度来说,这并不是必须的。因为你总可以显式地执行一个查询,以获得某个特定 event 的所有参与者。这是个在设计时需要做出的选择,完全由你来决定,但此讨论中关于关联的阶数是清楚的:即两端都是“多”值的,我们把它叫做多对多(many-to-many)关联。因而,我们使用 Hibernate 的多对多映射:


<class name="Person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="native"/>
    </id>
    <property name="age"/>
    <property name="firstname"/>
    <property name="lastname"/>

    <set name="events" table="PERSON_EVENT">
        <key column="PERSON_ID"/>
        <many-to-many column="EVENT_ID" class="Event"/>
    </set>

</class>

Hibernate 支持各种各样的集合映射,<set> 使用的最为普遍。对于多对多关联(或叫 n:m 实体关系), 需要一个关联表(association table)。里面的每一行代表从 person 到 event 的一个关联。表名是由 set 元素的 table 属性配置的。关联里面的标识符字段名,对于 person 的一端,是由 <key> 元素定义,而 event 一端的字段名是由 <many-to-many> 元素的 column 属性定义。你也必须告诉 Hibernate 集合中对象的类(也就是位于这个集合所代表的关联另外一端的类)。

因而这个映射的数据库 schema 是:

    _____________        __________________
   |             |      |                  |       _____________
   |   EVENTS    |      |   PERSON_EVENT   |      |             |
   |_____________|      |__________________|      |    PERSON   |
   |             |      |                  |      |_____________|
   | *EVENT_ID   | <--> | *EVENT_ID        |      |             |
   |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  |
   |  TITLE      |      |__________________|      |  AGE        |
   |_____________|                                |  FIRSTNAME  |
                                                  |  LASTNAME   |
                                                  |_____________|
 

我们把一些 people 和 events 一起放到 EventManager 的新方法中:

    private void addPersonToEvent(Long personId, Long eventId) {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Person aPerson = (Person) session.load(Person.class, personId);
        Event anEvent = (Event) session.load(Event.class, eventId);
        aPerson.getEvents().add(anEvent);
        session.getTransaction().commit();
    }

在加载一 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 里面看起来几乎是一样的。

让我们在 Person 实体里添加一个电子邮件的集合。这将以 java.lang.String 实例的 java.util.Set 出现:

    private Set emailAddresses = new HashSet();


    public Set getEmailAddresses() {
        return emailAddresses;
    }
    public void setEmailAddresses(Set emailAddresses) {
        this.emailAddresses = emailAddresses;
    }

这个 Set 的映射如下:


        <set name="emailAddresses" table="PERSON_EMAIL_ADDR">
            <key column="PERSON_ID"/>
            <element type="string" column="EMAIL_ADDR"/>
        </set>

比较这次和此前映射的差别,主要在于 element 部分,这次并没有包含对其它实体引用的集合,而是元素类型为 String 的集合(在映射中使用小写的名字”string“是向你表明它是一个 Hibernate 的映射类型或者类型转换器)。和之前一样,set 元素的 table 属性决定了用于集合的表名。key 元素定义了在集合表中外键的字段名。element 元素的 column 属性定义用于实际保存 String 值的字段名。

看一下修改后的数据库 schema。

  _____________        __________________
 |             |      |                  |       _____________
 |   EVENTS    |      |   PERSON_EVENT   |      |             |       ___________________
 |_____________|      |__________________|      |    PERSON   |      |                   |
 |             |      |                  |      |_____________|      | PERSON_EMAIL_ADDR |
 | *EVENT_ID   | <--> | *EVENT_ID        |      |             |      |___________________|
 |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  | <--> |  *PERSON_ID       |
 |  TITLE      |      |__________________|      |  AGE        |      |  *EMAIL_ADDR      |
 |_____________|                                |  FIRSTNAME  |      |___________________|
                                                |  LASTNAME   |
                                                |_____________|
 

你可以看到集合表的主键实际上是个复合主键,同时使用了两个字段。这也暗示了对于同一个 person 不能有重复的 email 地址,这正是 Java 里面使用 Set 时候所需要的语义(Set 里元素不能重复)。

你现在可以试着把元素加入到这个集合,就像我们在之前关联 person 和 event 的那样。其实现的 Java 代码是相同的:

    private void addEmailToPerson(Long personId, String emailAddress) {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Person aPerson = (Person) session.load(Person.class, personId);
        // adding to the emailAddress collection might trigger a lazy load of the collection
        aPerson.getEmailAddresses().add(emailAddress);
        session.getTransaction().commit();
    }

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

接下来我们将映射双向关联(bi-directional association)— 在 Java 里让 person 和 event 可以从关联的任何一端访问另一端。当然,数据库 schema 没有改变,我们仍然需要多对多的阶数。一个关系型数据库要比网络编程语言更加灵活,所以它并不需要任何像导航方向(navigation direction)的东西 — 数据可以用任何可能的方式进行查看和获取。

首先,把一个参与者(person)的集合加入 Event 类中:

    private Set participants = new HashSet();


    public Set getParticipants() {
        return participants;
    }
    public void setParticipants(Set participants) {
        this.participants = participants;
    }

Event.hbm.xml 里面也映射这个关联。


        <set name="participants" table="PERSON_EVENT" inverse="true">
            <key column="EVENT_ID"/>
            <many-to-many column="PERSON_ID" class="Person"/>
        </set
>

如你所见,两个映射文件里都有普通的 set 映射。注意在两个映射文件中,互换了 keymany-to-many 的字段名。这里最重要的是 Event 映射文件里增加了 set 元素的 inverse="true" 属性。

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

首先请记住,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)关联中,你可以任意选取一端,因为两端之间并没有差别。

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

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

package org.hibernate.tutorial.web;


// Imports
public class EventManagerServlet extends HttpServlet {
    protected void doGet(
            HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException {
        SimpleDateFormat dateFormatter = new SimpleDateFormat( "dd.MM.yyyy" );
        try {
            // Begin unit of work
            HibernateUtil.getSessionFactory().getCurrentSession().beginTransaction();
            // Process request and render page...
            // End unit of work
            HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().commit();
        }
        catch (Exception ex) {
            HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().rollback();
            if ( ServletException.class.isInstance( ex ) ) {
                throw ( ServletException ) ex;
            }
            else {
                throw new ServletException( ex );
            }
        }
    }
}

把这个 servlet 保存为 src/main/java/org/hibernate/tutorial/web/EventManagerServlet.java

我们称这里应用的模式为每次请求一个 session(session-per-request)。当有请求到达这个 servlet 的时候,通过对 SessionFactory 的第一次调用,打开一个新的 Hibernate Session。然后启动一个数据库事务 — 所有的数据访问都是在事务中进行,不管是读还是写(我们在应用程序中不使用 auto-commit 模式)。

不要为每次数据库操作都使用一个新的 Hibernate Session。将 Hibernate Session 的范围设置为整个请求。要用 getCurrentSession(),这样它自动会绑定到当前 Java 线程。

下一步,对请求的可能动作进行处理,渲染出反馈的 HTML。我们很快就会涉及到那部分。

最后,当处理与渲染都结束的时候,这个工作单元就结束了。假若在处理或渲染的时候有任何错误发生,会抛出一个异常,回滚数据库事务。这样,session-per-request 模式就完成了。为了避免在每个 servlet 中都编写事务边界界定的代码,可以考虑写一个 servlet 过滤器(filter)来更好地解决。关于这一模式的更多信息,请参阅 Hibernate 网站和 Wiki,这一模式叫做 Open Session in View — 只要你考虑用JSP来渲染你的视图(view),而不是在servlet中,你就会很快用到它。

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

        // Write HTML header

        PrintWriter out = response.getWriter();
        out.println("<html><head><title>Event Manager</title></head><body>");
        // Handle actions
        if ( "store".equals(request.getParameter("action")) ) {
            String eventTitle = request.getParameter("eventTitle");
            String eventDate = request.getParameter("eventDate");
            if ( "".equals(eventTitle) || "".equals(eventDate) ) {
                out.println("<b><i>Please enter event title and date.</i></b>");
            }
            else {
                createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate));
                out.println("<b><i>Added event.</i></b>");
            }
        }
        // Print page
       printEventForm(out);
       listEvents(out, dateFormatter);
       // Write HTML footer
       out.println("</body></html>");
       out.flush();
       out.close();

必须承认,这种编码风格把 Java 和 HTML 混在一起,在更复杂的应用程序里不应该大量使用 — 记住,在本章里我们仅仅是展示了 Hibernate 的基本概念。这段代码打印出了 HTML 页眉和页脚,在这个页面里,还打印了一个输入 events 条目的表单单并列出了数据库里的有的 events。第一个方法微不足道,仅仅是输出 HTML:

    private void printEventForm(PrintWriter out) {

        out.println("<h2>Add new event:</h2>");
        out.println("<form>");
        out.println("Title: <input name='eventTitle' length='50'/><br/>");
        out.println("Date (e.g. 24.12.2009): <input name='eventDate' length='10'/><br/>");
        out.println("<input type='submit' name='action' value='store'/>");
        out.println("</form>");
    }

listEvents() 方法使用绑定到当前线程的 Hibernate Session 来执行查询:

    private void listEvents(PrintWriter out, SimpleDateFormat dateFormatter) {


        List result = HibernateUtil.getSessionFactory()
                .getCurrentSession().createCriteria(Event.class).list();
        if (result.size() > 0) {
            out.println("<h2>Events in database:</h2>");
            out.println("<table border='1'>");
            out.println("<tr>");
            out.println("<th>Event title</th>");
            out.println("<th>Event date</th>");
            out.println("</tr>");
            Iterator it = result.iterator();
            while (it.hasNext()) {
                Event event = (Event) it.next();
                out.println("<tr>");
                out.println("<td>" + event.getTitle() + "</td>");
                out.println("<td>" + dateFormatter.format(event.getDate()) + "</td>");
                out.println("</tr>");
            }
            out.println("</table>");
        }
    }

最后,store 动作会被导向到 createAndStoreEvent() 方法,它也使用当前线程的 Session

    protected void createAndStoreEvent(String title, Date theDate) {

        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);
        HibernateUtil.getSessionFactory()
                .getCurrentSession().save(theEvent);
    }

大功告成,这个 servlet 写完了。Hibernate 会在单一的 SessionTransaction 中处理到达的 servlet 请求。如同在前面的独立应用程序中那样,Hibernate 可以自动的把这些对象绑定到当前运行的线程中。这给了你用任何你喜欢的方式来对代码分层及访问 SessionFactory 的自由。通常,你会用更加完备的设计,把数据访问代码转移到数据访问对象中(DAO 模式)。请参见 Hibernate Wiki,那里有更多的例子。

要部署这个应用程序以进行测试,我们必须出具一个 Web ARchive (WAR)。首先我们必须定义 WAR 描述符为 src/main/webapp/WEB-INF/web.xml


<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <servlet>
        <servlet-name>Event Manager</servlet-name>
        <servlet-class>org.hibernate.tutorial.web.EventManagerServlet</servlet-class>
    </servlet>

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

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

注意

If you do not have Tomcat installed, download it from http://tomcat.apache.org/ and follow the installation instructions. Our application requires no changes to the standard Tomcat configuration.

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

下面的图表提供了 Hibernate 体系结构的高层视图:

Unfortunately we cannot provide a detailed view of all possible runtime architectures. Hibernate is sufficiently flexible to be used in a number of ways in many, many architectures. We will, however, illustrate 2 specifically since they are extremes.

Here are quick discussions about some of the API objects depicted in the preceding diagrams (you will see them again in more detail in later chapters).

SessionFactory (org.hibernate.SessionFactory)

A thread-safe, immutable cache of compiled mappings for a single database. A factory for org.hibernate.Session instances. A client of org.hibernate.connection.ConnectionProvider. Optionally maintains a second level cache of data that is reusable between transactions at a process or cluster level.

Session (org.hibernate.Session)

A single-threaded, short-lived object representing a conversation between the application and the persistent store. Wraps a JDBC java.sql.Connection. Factory for org.hibernate.Transaction. Maintains a first level cache of persistent the application's persistent objects and collections; this cache is used when navigating the object graph or looking up objects by identifier.

持久的对象及其集合

Short-lived, single threaded objects containing persistent state and business function. These can be ordinary JavaBeans/POJOs. They are associated with exactly one org.hibernate.Session. Once the org.hibernate.Session is closed, they will be detached and free to use in any application layer (for example, directly as data transfer objects to and from presentation). 第 11 章 与对象共事 discusses transient, persistent and detached object states.

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

Instances of persistent classes that are not currently associated with a org.hibernate.Session. They may have been instantiated by the application and not yet persisted, or they may have been instantiated by a closed org.hibernate.Session. 第 11 章 与对象共事 discusses transient, persistent and detached object states.

Transaction (org.hibernate.Transaction)

(Optional) A single-threaded, short-lived object used by the application to specify atomic units of work. It abstracts the application from the underlying JDBC, JTA or CORBA transaction. A org.hibernate.Session might span several org.hibernate.Transactions in some cases. However, transaction demarcation, either using the underlying API or org.hibernate.Transaction, is never optional.

ConnectionProvider (org.hibernate.connection.ConnectionProvider)

(Optional) A factory for, and pool of, JDBC connections. It abstracts the application from underlying javax.sql.DataSource or java.sql.DriverManager. It is not exposed to application, but it can be extended and/or implemented by the developer.

TransactionFactory (org.hibernate.TransactionFactory)

(Optional) A factory for org.hibernate.Transaction instances. It is not exposed to the application, but it can be extended and/or implemented by the developer.

Extension Interfaces

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

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

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

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

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

The first two implementations provide a "one session - one database transaction" programming model. This is also known and used as session-per-request. The beginning and end of a Hibernate session is defined by the duration of a database transaction. If you use programmatic transaction demarcation in plain JSE without JTA, you are advised to use the Hibernate Transaction API to hide the underlying transaction system from your code. If you use JTA, you can utilize the JTA interfaces to demarcate transactions. If you execute in an EJB container that supports CMT, transaction boundaries are defined declaratively and you do not need any transaction or session demarcation operations in your code. Refer to 第 13 章 事务和并发 for more information and code examples.

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

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

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

你可以直接实例化 org.hibernate.cfg.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)。

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

如果你想快速上路,hibernate.properties 就是最容易的途径。

org.hibernate.cfg.Configuration 实例被设计成启动期间(startup-time)对象,一旦 SessionFactory 创建完成它就被丢弃了。

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

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

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

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

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


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

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

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

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

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


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

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

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

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

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

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

表 3.3. Hibernate 配置属性

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

例如:full.classname.of.Dialect

在大多数情况下,Hibernate 可以根据 JDBC 驱动返回的 JDBC metadata 选择正确的 org.hibernate.dialect.Dialect 实现。

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

例如: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_nameorg.hibernate.SessionFactory 创建后,将自动使用这个名字绑定到 JNDI 中。

例如:jndi/composite/name

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

例如: 建议在 03 之间取值

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

例如:建议的取值为 48,和 16

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

取值dynamic-mapdom4jpojo

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

例如:true | false

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

例如:true | false

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

例如:true | false

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

例如:true | false

hibernate.id.new_generator_mappingsSetting is relevant when using @GeneratedValue. It indicates whether or not the new IdentifierGenerator implementations are used for javax.persistence.GenerationType.AUTO, javax.persistence.GenerationType.TABLE and javax.persistence.GenerationType.SEQUENCE. Default to false to keep backward compatibility.

例如:true | false


注意

We recommend all new projects which make use of to use @GeneratedValue to also set hibernate.id.new_generator_mappings=true as the new generators are more efficient and closer to the JPA 2 specification semantic. However they are not backward compatible with existing databases (if a sequence or a table is used for id generation).

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

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

例如:建议取 530 之间的值

hibernate.jdbc.batch_versioned_dataSet this property to true if your JDBC driver returns correct row counts from executeBatch(). It is usually safe to turn this option on. Hibernate will then use batched DML for automatically versioned data. Defaults to false.

例如:true | false

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

例如:classname.of.Batcher

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

例如:true | false

hibernate.jdbc.use_streams_for_binary在 JDBC 读写 binaryserializable 的类型时使用流(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

This setting only affects Sessions returned from SessionFactory.openSession. For Sessions obtained through SessionFactory.getCurrentSession, the CurrentSessionContext implementation configured for use controls the connection release mode for those Sessions. See 第 2.3 节 “上下文相关的会话(Contextual Session)”

hibernate.connection.<propertyName>把 JDBC 属性 <propertyName> 传递给 DriverManager.getConnection()
hibernate.jndi.<propertyName><propertyName> 属性传递给 JNDI InitialContextFactory



表 3.7. 其他属性

属性名用途
hibernate.current_session_context_classSupply a custom strategy for the scoping of the "current" Session. See 第 2.3 节 “上下文相关的会话(Contextual Session)” for more information about the built-in strategies.

例如:jta | thread | managed | custom.Class

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

例如:org.hibernate.hql.ast.ASTQueryTranslatorFactoryorg.hibernate.hql.classic.ClassicQueryTranslatorFactory

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

例如:hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC

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

例如:validate | update | create | create-drop

hibernate.hbm2ddl.import_files

Comma-separated names of the optional files containing SQL DML statements executed during the SessionFactory creation. This is useful for testing or demoing: by adding INSERT statements for example you can populate your database with a minimal set of data when it is deployed.

File order matters, the statements of a give file are executed before the statements of the following files. These statements are only executed if the schema is created ie if hibernate.hbm2ddl.auto is set to create or create-drop.

e.g. /humans.sql,/dogs.sql

hibernate.bytecode.use_reflection_optimizer

Enables the use of bytecode manipulation instead of runtime reflection. This is a System-level property and cannot be set in hibernate.cfg.xml. Reflection can sometimes be useful when troubleshooting. Hibernate always requires either CGLIB or javassist even if you turn off the optimizer.

例如:true | false

hibernate.bytecode.provider

Both javassist or cglib can be used as byte manipulation engines; the default is javassist.

e.g. javassist | cglib


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


Hibernate 利用 Simple Logging Facade for Java (SLF4J) 来记录不同系统事件的日志。SLF4J 可以根据你选择的绑定把日志输出到几个日志框架(NOP、Simple、log4j version 1.2、JDK 1.4 logging、JCL 或 logback)上。为了设置日志,你需要在 classpath 里加入 slf4j-api.jar 和你选择的绑定的 JAR 文件(使用 Log4J 时加入 slf4j-log4j12.jar)。更多的细节请参考 SLF4J 文档。要使用 Log4j,你也需要在 classpath 里加入 log4j.properties 文件。Hibernate 里的 src/ 目录里带有一个属性文件的例子。

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


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

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

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


<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD//EN"
    "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <!-- a SessionFactory instance listed as /jndi/name -->
    <session-factory
        name="java:hibernate/SessionFactory">

        <!-- properties -->
        <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 files -->
        <mapping resource="org/hibernate/auction/Item.hbm.xml"/>
        <mapping resource="org/hibernate/auction/Bid.hbm.xml"/>

        <!-- cache settings -->
        <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();

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

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

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

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

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

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

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


与 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

It is recommended that you bind the SessionFactory to JNDI in a managed environment and use a static singleton otherwise. To shield your application code from these details, we also recommend to hide the actual lookup code for a SessionFactory in a helper class, such as HibernateUtil.getSessionFactory(). Note that such a class is also a convenient way to startup Hibernate—see chapter 1.

The easiest way to handle Sessions and transactions is Hibernate's automatic "current" Session management. For a discussion of contextual sessions see 第 2.3 节 “上下文相关的会话(Contextual Session)”. Using the "jta" session context, if there is no Hibernate Session associated with the current JTA transaction, one will be started and associated with that JTA transaction the first time you call sessionFactory.getCurrentSession(). The Sessions retrieved via getCurrentSession() in the "jta" context are set to automatically flush before the transaction completes, close after the transaction completes, and aggressively release JDBC connections after each statement. This allows the Sessions to be managed by the life cycle of the JTA transaction to which it is associated, keeping user code clean of such management concerns. Your code can either use JTA programmatically through UserTransaction, or (recommended for portable code) use the Hibernate Transaction API to set transaction boundaries. If you run in an EJB container, declarative transaction demarcation with CMT is preferred.

为了将 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">

    <!-- Required services -->
    <depends>jboss.jca:service=RARDeployer</depends>
    <depends>jboss.jca:service=LocalTxCM,name=HsqlDS</depends>

    <!-- Bind the Hibernate service to JNDI -->
    <attribute name="JndiName">java:/hibernate/SessionFactory</attribute>

    <!-- Datasource settings -->
    <attribute name="Datasource">java:HsqlDS</attribute>
    <attribute name="Dialect">org.hibernate.dialect.HSQLDialect</attribute>

    <!-- Transaction integration -->
    <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>

    <!-- Fetching options -->
    <attribute name="MaximumFetchDepth">5</attribute>

    <!-- Second-level caching -->
    <attribute name="SecondLevelCacheEnabled">true</attribute>
    <attribute name="CacheProviderClass">org.hibernate.cache.EhCacheProvider</attribute>
    <attribute name="QueryCacheEnabled">true</attribute>

    <!-- Logging -->
    <attribute name="ShowSqlEnabled">true</attribute>

    <!-- Mapping files -->
    <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 部署的信息。

Persistent classes are classes in an application that implement the entities of the business problem (e.g. Customer and Order in an E-commerce application). The term "persistent" here means that the classes are able to be persisted, not that they are in the persistent state (see 第 11.1 节 “Hibernate 对象状态(object states)” for discussion).

Hibernate works best if these classes follow some simple rules, also known as the Plain Old Java Object (POJO) programming model. However, none of these rules are hard requirements. Indeed, Hibernate assumes very little about the nature of your persistent objects. You can express a domain model in other ways (using trees of java.util.Map instances, for example).

例 4.1. Simple POJO representing a cat

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 个主要规则的更多细节。

Cat has a property named id. This property maps to the primary key column(s) of the underlying database table. The type of the identifier property can be any "basic" type (see ???). See 第 9.4 节 “组件作为联合标识符(Components as composite identifiers)” for information on mapping composite (multi-column) identifiers.

注意

Identifiers do not necessarily need to identify column(s) in the database physically defined as a primary key. They should just identify columns that can be used to uniquely identify rows in the underlying table.

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

A central feature of Hibernate, proxies (lazy loading), depends upon the persistent class being either non-final, or the implementation of an interface that declares all public methods. You can persist final classes that do not implement an interface with Hibernate; you will not, however, be able to use proxies for lazy association fetching which will ultimately limit your options for performance tuning. To persist a final class which does not implement a "full" interface you must disable proxy generation. See 例 4.2 “Disabling proxies in hbm.xml” and 例 4.3 “Disabling proxies in annotations”.



If the final class does implement a proper interface, you could alternatively tell Hibernate to use the interface instead when generating the proxies. See 例 4.4 “Proxying an interface in hbm.xml” and 例 4.5 “Proxying an interface in annotations”.



You should also avoid declaring public final methods as this will again limit the ability to generate proxies from this class. If you want to use a class with public final methods, you must explicitly disable proxying. Again, see 例 4.2 “Disabling proxies in hbm.xml” and 例 4.3 “Disabling proxies in annotations”.

如果你有如下需求,你必须重载 equals()hashCode() 方法:

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

A business key does not have to be as solid as a database primary key candidate (see 第 13.1.3 节 “关注对象标识(Considering object identity)”). Immutable or unique properties are usually good candidates for a business key.

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

By default, Hibernate works in normal POJO mode. You can set a default entity representation mode for a particular SessionFactory using the default_entity_mode configuration option (see 表 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();
// 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(),同样的,把事务和连接的处理交给原来的工作单元。

More information about the XML representation capabilities can be found in 第 20 章 XML 映射.

org.hibernate.tuple.Tuplizer and its sub-interfaces are responsible for managing a particular representation of a piece of data given that representation's org.hibernate.EntityMode. If a given piece of data is thought of as a data structure, then a tuplizer is the thing that knows how to create such a data structure, how to extract values from such a data structure and how to inject values into such a data structure. For example, for the POJO entity mode, the corresponding tuplizer knows how create the POJO through its constructor. It also knows how to access the POJO properties using the defined property accessors.

There are two (high-level) types of Tuplizers:

Users can also plug in their own tuplizers. Perhaps you require that java.util.Map implementation other than java.util.HashMap be used while in the dynamic-map entity-mode. Or perhaps you need to define a different proxy generation strategy than the one used by default. Both would be achieved by defining a custom tuplizer implementation. Tuplizer definitions are attached to the entity or component mapping they are meant to manage. Going back to the example of our Customer entity, 例 4.6 “Specify custom tuplizers in annotations” shows how to specify a custom org.hibernate.tuple.entity.EntityTuplizer using annotations while 例 4.7 “Specify custom tuplizers in hbm.xml” shows how to do the same in hbm.xml



org.hibernate.EntityNameResolver is a contract for resolving the entity name of a given entity instance. The interface defines a single method resolveEntityName which is passed the entity instance and is expected to return the appropriate entity name (null is allowed and would indicate that the resolver does not know how to resolve the entity name of the given entity instance). Generally speaking, an org.hibernate.EntityNameResolver is going to be most useful in the case of dynamic models. One example might be using proxied interfaces as your domain model. The hibernate test suite has an example of this exact style of usage under the org.hibernate.test.dynamicentity.tuplizer2. Here is some of the code from that package for illustration.

/**

 * A very trivial JDK Proxy InvocationHandler implementation where we proxy an
 * interface as the domain model and simply store persistent state in an internal
 * Map.  This is an extremely trivial example meant only for illustration.
 */
public final class DataProxyHandler implements InvocationHandler {
        private String entityName;
        private HashMap data = new HashMap();
        public DataProxyHandler(String entityName, Serializable id) {
                this.entityName = entityName;
                data.put( "Id", id );
        }
        public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
                String methodName = method.getName();
                if ( methodName.startsWith( "set" ) ) {
                        String propertyName = methodName.substring( 3 );
                        data.put( propertyName, args[0] );
                }
                else if ( methodName.startsWith( "get" ) ) {
                        String propertyName = methodName.substring( 3 );
                        return data.get( propertyName );
                }
                else if ( "toString".equals( methodName ) ) {
                        return entityName + "#" + data.get( "Id" );
                }
                else if ( "hashCode".equals( methodName ) ) {
                        return new Integer( this.hashCode() );
                }
                return null;
        }
        public String getEntityName() {
                return entityName;
        }
        public HashMap getData() {
                return data;
        }
}
public class ProxyHelper {
    public static String extractEntityName(Object object) {
        // Our custom java.lang.reflect.Proxy instances actually bundle
        // their appropriate entity name, so we simply extract it from there
        // if this represents one of our proxies; otherwise, we return null
        if ( Proxy.isProxyClass( object.getClass() ) ) {
            InvocationHandler handler = Proxy.getInvocationHandler( object );
            if ( DataProxyHandler.class.isAssignableFrom( handler.getClass() ) ) {
                DataProxyHandler myHandler = ( DataProxyHandler ) handler;
                return myHandler.getEntityName();
            }
        }
        return null;
    }
    // various other utility methods ....
}
/**
 * The EntityNameResolver implementation.
 *
 * IMPL NOTE : An EntityNameResolver really defines a strategy for how entity names
 * should be resolved.  Since this particular impl can handle resolution for all of our
 * entities we want to take advantage of the fact that SessionFactoryImpl keeps these
 * in a Set so that we only ever have one instance registered.  Why?  Well, when it
 * comes time to resolve an entity name, Hibernate must iterate over all the registered
 * resolvers.  So keeping that number down helps that process be as speedy as possible.
 * Hence the equals and hashCode implementations as is
 */
public class MyEntityNameResolver implements EntityNameResolver {
    public static final MyEntityNameResolver INSTANCE = new MyEntityNameResolver();
    public String resolveEntityName(Object entity) {
        return ProxyHelper.extractEntityName( entity );
    }
    public boolean equals(Object obj) {
        return getClass().equals( obj.getClass() );
    }
    public int hashCode() {
        return getClass().hashCode();
    }
}
public class MyEntityTuplizer extends PojoEntityTuplizer {
        public MyEntityTuplizer(EntityMetamodel entityMetamodel, PersistentClass mappedEntity) {
                super( entityMetamodel, mappedEntity );
        }
        public EntityNameResolver[] getEntityNameResolvers() {
                return new EntityNameResolver[] { MyEntityNameResolver.INSTANCE };
        }
    public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory) {
        String entityName = ProxyHelper.extractEntityName( entityInstance );
        if ( entityName == null ) {
            entityName = super.determineConcreteSubclassEntityName( entityInstance, factory );
        }
        return entityName;
    }
    ...

为了注册 org.hibernate.EntityNameResolver,用户必须:

  1. Implement a custom tuplizer (see 第 4.5 节 “元组片断映射(Tuplizers)”), implementing the getEntityNameResolvers method

  2. registerEntityNameResolver 方法注册到 org.hibernate.impl.SessionFactoryImpl(它是 org.hibernate.SessionFactory 的实现类)。

Object/relational mappings can be defined in three approaches:

Annotations are split in two categories, the logical mapping annotations (describing the object model, the association between two entities etc.) and the physical mapping annotations (describing the physical schema, tables, columns, indexes, etc). We will mix annotations from both categories in the following code examples.

JPA annotations are in the javax.persistence.* package. Hibernate specific extensions are in org.hibernate.annotations.*. You favorite IDE can auto-complete annotations and their attributes for you (even without a specific "JPA" plugin, since JPA annotations are plain Java 5 annotations).

Here is an example of mapping

package eg;


@Entity 
@Table(name="cats") @Inheritance(strategy=SINGLE_TABLE)
@DiscriminatorValue("C") @DiscriminatorColumn(name="subclass", discriminatorType=CHAR)
public class Cat {
   
   @Id @GeneratedValue
   public Integer getId() { return id; }
   public void setId(Integer id) { this.id = id; }
   private Integer id;
   public BigDecimal getWeight() { return weight; }
   public void setWeight(BigDecimal weight) { this.weight = weight; }
   private BigDecimal weight;
   @Temporal(DATE) @NotNull @Column(updatable=false)
   public Date getBirthdate() { return birthdate; }
   public void setBirthdate(Date birthdate) { this.birthdate = birthdate; }
   private Date birthdate;
   @org.hibernate.annotations.Type(type="eg.types.ColorUserType")
   @NotNull @Column(updatable=false)
   public ColorType getColor() { return color; }
   public void setColor(ColorType color) { this.color = color; }
   private ColorType color;
   @NotNull @Column(updatable=false)
   public String getSex() { return sex; }
   public void setSex(String sex) { this.sex = sex; }
   private String sex;
   @NotNull @Column(updatable=false)
   public Integer getLitterId() { return litterId; }
   public void setLitterId(Integer litterId) { this.litterId = litterId; }
   private Integer litterId;
   @ManyToOne @JoinColumn(name="mother_id", updatable=false)
   public Cat getMother() { return mother; }
   public void setMother(Cat mother) { this.mother = mother; }
   private Cat mother;
   @OneToMany(mappedBy="mother") @OrderBy("litterId")
   public Set<Cat> getKittens() { return kittens; }
   public void setKittens(Set<Cat> kittens) { this.kittens = kittens; }
   private Set<Cat> kittens = new HashSet<Cat>();
}
@Entity @DiscriminatorValue("D")
public class DomesticCat extends Cat {
   public String getName() { return name; }
   public void setName(String name) { this.name = name }
   private String name;
}
@Entity
public class Dog { ... }

The legacy hbm.xml approach uses an XML schema designed to be readable and hand-editable. The mapping language is Java-centric, meaning that mappings are constructed around persistent class declarations and not table declarations.

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

下面是一个映射的例子:


<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
      "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
          "http://www.hibernate.org/dtd/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>

We will now discuss the concepts of the mapping documents (both annotations and XML). We will only describe, however, the document elements and attributes that are used by Hibernate at runtime. The mapping document also contains some extra optional attributes and elements that affect the database schemas exported by the schema export tool (for example, the not-null attribute).

An entity is a regular Java object (aka POJO) which will be persisted by Hibernate.

To mark an object as an entity in annotations, use the @Entity annotation.

@Entity

public class Flight implements Serializable {
    Long id;
    @Id
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
}         

That's pretty much it, the rest is optional. There are however any options to tweak your entity mapping, let's explore them.

@Table lets you define the table the entity will be persisted into. If undefined, the table name is the unqualified class name of the entity. You can also optionally define the catalog, the schema as well as unique constraints on the table.

@Entity

@Table(name="TBL_FLIGHT", 
       schema="AIR_COMMAND", 
       uniqueConstraints=
           @UniqueConstraint(
               name="flight_number", 
               columnNames={"comp_prefix", "flight_number"} ) )
public class Flight implements Serializable {
    @Column(name="comp_prefix")
    public String getCompagnyPrefix() { return companyPrefix; }
    @Column(name="flight_number")
    public String getNumber() { return number; }
}

The constraint name is optional (generated if left undefined). The column names composing the constraint correspond to the column names as defined before the Hibernate NamingStrategy is applied.

@Entity.name lets you define the shortcut name of the entity you can used in JP-QL and HQL queries. It defaults to the unqualified class name of the class.

Hibernate goes beyond the JPA specification and provide additional configurations. Some of them are hosted on @org.hibernate.annotations.Entity:

Some entities are not mutable. They cannot be updated or deleted by the application. This allows Hibernate to make some minor performance optimizations.. Use the @Immutable annotation.

You can also alter how Hibernate deals with lazy initialization for this class. On @Proxy, use lazy=false to disable lazy fetching (not recommended). You can also specify an interface to use for lazy initializing proxies (defaults to the class itself): use proxyClass on @Proxy. Hibernate will initially return proxies (Javassist or CGLIB) that implement the named interface. The persistent object will load when a method of the proxy is invoked. See "Initializing collections and proxies" below.

@BatchSize specifies a "batch size" for fetching instances of this class by identifier. Not yet loaded instances are loaded batch-size at a time (default 1).

You can specific an arbitrary SQL WHERE condition to be used when retrieving objects of this class. Use @Where for that.

In the same vein, @Check lets you define an SQL expression used to generate a multi-row check constraint for automatic schema generation.

There is no difference between a view and a base table for a Hibernate mapping. This is transparent at the database level, although some DBMS do not support views properly, especially with updates. Sometimes you want to use a view, but you cannot create one in the database (i.e. with a legacy schema). In this case, you can map an immutable and read-only entity to a given SQL subselect expression using @org.hibernate.annotations.Subselect:

@Entity

@Subselect("select item.name, max(bid.amount), count(*) "
        + "from item "
        + "join bid on bid.item_id = item.id "
        + "group by item.name")
@Synchronize( {"item", "bid"} ) //tables impacted
public class Summary {
    @Id
    public String getId() { return id; }
    ...
}

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

We will now explore the same options using the hbm.xml structure. You can declare a persistent class using the class element. For example:

<class
        name="(1)ClassName"
        table=(2)"tableName"
        discri(3)minator-value="discriminator_value"
        mutabl(4)e="true|false"
        schema(5)="owner"
        catalo(6)g="catalog"
        proxy=(7)"ProxyInterface"
        dynami(8)c-update="true|false"
        dynami(9)c-insert="true|false"
        select(10)-before-update="true|false"
        polymo(11)rphism="implicit|explicit"
        where=(12)"arbitrary sql where condition"
        persis(13)ter="PersisterClass"
        batch-(14)size="N"
        optimi(15)stic-lock="none|version|dirty|all"
        lazy="(16)true|false"
        entity(17)-name="EntityName"
        check=(18)"arbitrary sql check condition"
        rowid=(19)"rowid"
        subsel(20)ect="SQL expression"
        abstra(21)ct="true|false"
        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

polymorphisms (optional - defaults to implicit): determines whether implicit or explicit query polymorphisms is used.

12

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

13

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

14

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

15

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

(16)

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

(17)

entity-name (optional - defaults to the class name): Hibernate3 allows a class to be mapped multiple times, potentially to different tables. It also allows entity mappings that are represented by Maps or XML at the Java level. In these cases, you should provide an explicit arbitrary name for the entity. See 第 4.4 节 “动态模型(Dynamic models)” and 第 20 章 XML 映射 for more information.

(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

Here is how to do a virtual view (subselect) in XML:


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

The <subselect> is available both as an attribute and a nested mapping element.

Mapped classes must declare the primary key column of the database table. Most classes will also have a JavaBeans-style property holding the unique identifier of an instance.

Mark the identifier property with @Id.

@Entity

public class Person {
   @Id Integer getId() { ... }
   ...
}

In hbm.xml, use the <id> element which defines the mapping from that property to the primary key column.

<id
        name="(1)propertyName"
        type="(2)typename"
        column(3)="column_name"
        unsave(4)d-value="null|any|none|undefined|id_value"
        access(5)="field|property|ClassName">
        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 属性不存在,会认为这个类没有标识属性。

The unsaved-value attribute is almost never needed in Hibernate3 and indeed has no corresponding element in annotations.

You can also declare the identifier as a composite identifier. This allows access to legacy data with composite keys. Its use is strongly discouraged for anything else.

You can define a composite primary key through several syntaxes:

As you can see the last case is far from obvious. It has been inherited from the dark ages of EJB 2 for backward compatibilities and we recommend you not to use it (for simplicity sake).

Let's explore all three cases using examples.

Here is a simple example of @EmbeddedId.

@Entity

class User {
   @EmbeddedId
   @AttributeOverride(name="firstName", column=@Column(name="fld_firstname")
   UserId id;
   Integer age;
}
@Embeddable
class UserId implements Serializable {
   String firstName;
   String lastName;
}

You can notice that the UserId class is serializable. To override the column mapping, use @AttributeOverride.

An embedded id can itself contains the primary key of an associated entity.

@Entity

class Customer {
   @EmbeddedId CustomerId id;
   boolean preferredCustomer;
   @MapsId("userId")
   @JoinColumns({
      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),
      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")
   })
   @OneToOne User user;
}
@Embeddable
class CustomerId implements Serializable {
   UserId userId;
   String customerNumber;
   //implements equals and hashCode
}
@Entity 
class User {
   @EmbeddedId UserId id;
   Integer age;
}
@Embeddable
class UserId implements Serializable {
   String firstName;
   String lastName;
   //implements equals and hashCode
}

In the embedded id object, the association is represented as the identifier of the associated entity. But you can link its value to a regular association in the entity via the @MapsId annotation. The @MapsId value correspond to the property name of the embedded id object containing the associated entity's identifier. In the database, it means that the Customer.user and the CustomerId.userId properties share the same underlying column (user_fk in this case).

In practice, your code only sets the Customer.user property and the user id value is copied by Hibernate into the CustomerId.userId property.

While not supported in JPA, Hibernate lets you place your association directly in the embedded id component (instead of having to use the @MapsId annotation).

@Entity

class Customer {
   @EmbeddedId CustomerId id;
   boolean preferredCustomer;
}
@Embeddable
class CustomerId implements Serializable {
   @OneToOne
   @JoinColumns({
      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),
      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")
   }) 
   User user;
   String customerNumber;
   //implements equals and hashCode
}
@Entity 
class User {
   @EmbeddedId UserId id;
   Integer age;
}
@Embeddable
class UserId implements Serializable {
   String firstName;
   String lastName;
   //implements equals and hashCode
}

Let's now rewrite these examples using the hbm.xml syntax.


<composite-id
        name="propertyName"
        class="ClassName"
        mapped="true|false"
        access="field|property|ClassName"
        node="element-name|.">

        <key-property name="propertyName" type="typename" column="column_name"/>
        <key-many-to-one name="propertyName" class="ClassName" column="column_name"/>
        ......
</composite-id>

First a simple example:


<class name="User">
   <composite-id name="id" class="UserId">
      <key-property name="firstName" column="fld_firstname"/>
      <key-property name="lastName"/>
   </composite-id>
</class>

Then an example showing how an association can be mapped.


<class name="Customer">
   <composite-id name="id" class="CustomerId">
      <key-property name="firstName" column="userfirstname_fk"/>
      <key-property name="lastName" column="userfirstname_fk"/>
      <key-property name="customerNumber"/>
   </composite-id>

   <property name="preferredCustomer"/>

   <many-to-one name="user">
      <column name="userfirstname_fk" updatable="false" insertable="false"/>
      <column name="userlastname_fk" updatable="false" insertable="false"/>
   </many-to-one>
</class>

<class name="User">
   <composite-id name="id" class="UserId">
      <key-property name="firstName"/>
      <key-property name="lastName"/>
   </composite-id>

   <property name="age"/>
</class>

Notice a few things in the previous example:

The last example shows how to map association directly in the embedded id component.


<class name="Customer">
   <composite-id name="id" class="CustomerId">
      <key-many-to-one name="user">
         <column name="userfirstname_fk"/>
         <column name="userlastname_fk"/>
      </key-many-to-one>
      <key-property name="customerNumber"/>
   </composite-id>

   <property name="preferredCustomer"/>
</class>

<class name="User">
   <composite-id name="id" class="UserId">
      <key-property name="firstName"/>
      <key-property name="lastName"/>
   </composite-id>

   <property name="age"/>
</class>

This is the recommended approach to map composite identifier. The following options should not be considered unless some constraint are present.

Another, arguably more natural, approach is to place @Id on multiple properties of your entity. This approach is only supported by Hibernate (not JPA compliant) but does not require an extra embeddable component.

@Entity

class Customer implements Serializable {
   @Id @OneToOne
   @JoinColumns({
      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),
      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")
   })
   User user;
  
   @Id String customerNumber;
   boolean preferredCustomer;
   //implements equals and hashCode
}
@Entity 
class User {
   @EmbeddedId UserId id;
   Integer age;
}
@Embeddable
class UserId implements Serializable {
   String firstName;
   String lastName;
   //implements equals and hashCode
}

In this case Customer is its own identifier representation: it must implement Serializable and must implement equals() and hashCode().

In hbm.xml, the same mapping is:


<class name="Customer">
   <composite-id>
      <key-many-to-one name="user">
         <column name="userfirstname_fk"/>
         <column name="userlastname_fk"/>
      </key-many-to-one>
      <key-property name="customerNumber"/>
   </composite-id>

   <property name="preferredCustomer"/>
</class>

<class name="User">
   <composite-id name="id" class="UserId">
      <key-property name="firstName"/>
      <key-property name="lastName"/>
   </composite-id>

   <property name="age"/>
</class>

@IdClass on an entity points to the class (component) representing the identifier of the class. The properties marked @Id on the entity must have their corresponding property on the @IdClass. The return type of search twin property must be either identical for basic properties or must correspond to the identifier class of the associated entity for an association.

@Entity

@IdClass(CustomerId.class)
class Customer implements Serializable {
   @Id @OneToOne
   @JoinColumns({
      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),
      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")
   }) 
   User user;
  
   @Id String customerNumber;
   boolean preferredCustomer;
}
class CustomerId implements Serializable {
   UserId user;
   String customerNumber;
   //implements equals and hashCode
}
@Entity 
class User {
   @EmbeddedId UserId id;
   Integer age;
   //implements equals and hashCode
}
@Embeddable
class UserId implements Serializable {
   String firstName;
   String lastName;
   //implements equals and hashCode
}

Customer and CustomerId do have the same properties customerNumber as well as user. CustomerId must be Serializable and implement equals() and hashCode().

While not JPA standard, Hibernate let's you declare the vanilla associated property in the @IdClass.

@Entity

@IdClass(CustomerId.class)
class Customer implements Serializable {
   @Id @OneToOne
   @JoinColumns({
      @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),
      @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")
   }) 
   User user;
  
   @Id String customerNumber;
   boolean preferredCustomer;
}
class CustomerId implements Serializable {
   @OneToOne User user;
   String customerNumber;
   //implements equals and hashCode
}
@Entity 
class User {
   @EmbeddedId UserId id;
   Integer age;
   //implements equals and hashCode
}
@Embeddable
class UserId implements Serializable {
  String firstName;
  String lastName;
}

This feature is of limited interest though as you are likely to have chosen the @IdClass approach to stay JPA compliant or you have a quite twisted mind.

Here are the equivalent on hbm.xml files:


<class name="Customer">
   <composite-id class="CustomerId" mapped="true">
      <key-many-to-one name="user">
         <column name="userfirstname_fk"/>
         <column name="userlastname_fk"/>
      </key-many-to-one>
      <key-property name="customerNumber"/>
   </composite-id>

   <property name="preferredCustomer"/>
</class>

<class name="User">
   <composite-id name="id" class="UserId">
      <key-property name="firstName"/>
      <key-property name="lastName"/>
   </composite-id>

   <property name="age"/>
</class>

Hibernate can generate and populate identifier values for you automatically. This is the recommended approach over "business" or "natural" id (especially composite ids).

Hibernate offers various generation strategies, let's explore the most common ones first that happens to be standardized by JPA:

To mark an id property as generated, use the @GeneratedValue annotation. You can specify the strategy used (default to AUTO) by setting strategy.

@Entity

public class Customer {
   @Id @GeneratedValue
   Integer getId() { ... };
}
@Entity 
public class Invoice {
   @Id @GeneratedValue(strategy=GenerationType.IDENTITY)
   Integer getId() { ... };
}

SEQUENCE and TABLE require additional configurations that you can set using @SequenceGenerator and @TableGenerator:

  • name: name of the generator

  • table / sequenceName: name of the table or the sequence (defaulting respectively to hibernate_sequences and hibernate_sequence)

  • catalog / schema:

  • initialValue: the value from which the id is to start generating

  • allocationSize: the amount to increment by when allocating id numbers from the generator

In addition, the TABLE strategy also let you customize:

  • pkColumnName: the column name containing the entity identifier

  • valueColumnName: the column name containing the identifier value

  • pkColumnValue: the entity identifier

  • uniqueConstraints: any potential column constraint on the table containing the ids

To link a table or sequence generator definition with an actual generated property, use the same name in both the definition name and the generator value generator as shown below.

@Id 

@GeneratedValue(
    strategy=GenerationType.SEQUENCE, 
    generator="SEQ_GEN")
@javax.persistence.SequenceGenerator(
    name="SEQ_GEN",
    sequenceName="my_sequence",
    allocationSize=20
)
public Integer getId() { ... }        

The scope of a generator definition can be the application or the class. Class-defined generators are not visible outside the class and can override application level generators. Application level generators are defined in JPA's XML deployment descriptors (see XXXXXX ???):

<table-generator name="EMP_GEN"

            table="GENERATOR_TABLE"
            pk-column-name="key"
            value-column-name="hi"
            pk-column-value="EMP"
            allocation-size="20"/>
//and the annotation equivalent
@javax.persistence.TableGenerator(
    name="EMP_GEN",
    table="GENERATOR_TABLE",
    pkColumnName = "key",
    valueColumnName = "hi"
    pkColumnValue="EMP",
    allocationSize=20
)
<sequence-generator name="SEQ_GEN" 
    sequence-name="my_sequence"
    allocation-size="20"/>
//and the annotation equivalent
@javax.persistence.SequenceGenerator(
    name="SEQ_GEN",
    sequenceName="my_sequence",
    allocationSize=20
)
         

If a JPA XML descriptor (like META-INF/orm.xml) is used to define the generators, EMP_GEN and SEQ_GEN are application level generators.

注意

Package level definition is not supported by the JPA specification. However, you can use the @GenericGenerator at the package level (see ???).

These are the four standard JPA generators. Hibernate goes beyond that and provide additional generators or additional options as we will see below. You can also write your own custom identifier generator by implementing org.hibernate.id.IdentifierGenerator.

To define a custom generator, use the @GenericGenerator annotation (and its plural counter part @GenericGenerators) that describes the class of the identifier generator or its short cut name (as described below) and a list of key/value parameters. When using @GenericGenerator and assigning it via @GeneratedValue.generator, the @GeneratedValue.strategy is ignored: leave it blank.

@Id @GeneratedValue(generator="system-uuid")

@GenericGenerator(name="system-uuid", strategy = "uuid")
public String getId() {
@Id @GeneratedValue(generator="trigger-generated")
@GenericGenerator(
    name="trigger-generated", 
    strategy = "select",
    parameters = @Parameter(name="key", value = "socialSecurityNumber")
)
public String getId() {

The hbm.xml approach uses the optional <generator> child element inside <id>. If any parameters are required to configure or initialize the generator instance, they are passed using the <param> element.


<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 的内置标识字段提供支持。返回的标识符是 longshort 或者 int 类型的。

sequence

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

hilo

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

seqhilo

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

uuid

Generates a 128-bit UUID based on a custom algorithm. The value generated is represented as a string of 32 hexidecimal digits. Users can also configure it to use a separator (config parameter "separator") which separates the hexidecimal digits into 8{sep}8{sep}4{sep}8{sep}4. Note specifically that this is different than the IETF RFC 4122 representation of 8-4-4-4-12. If you need RFC 4122 compliant UUIDs, consider using "uuid2" generator discussed below.

uuid2

Generates a IETF RFC 4122 compliant (variant 2) 128-bit UUID. The exact "version" (the RFC term) generated depends on the pluggable "generation strategy" used (see below). Capable of generating values as java.util.UUID, java.lang.String or as a byte array of length 16 (byte[16]). The "generation strategy" is defined by the interface org.hibernate.id.UUIDGenerationStrategy. The generator defines 2 configuration parameters for defining which generation strategy to use:

Out of the box, comes with the following strategies:

guid

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

native

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

assigned

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

select

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

foreign

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

sequence-identity

一种特别的序列生成策略,它使用数据库序列来生成实际值,但将它和 JDBC3 的 getGeneratedKeys 结合在一起,使得在插入语句执行的时候就返回生成的值。目前为止只有面向 JDK 1.4 的 Oracle 10g 驱动支持这一策略。由于 Oracle 驱动程序的一个 bug,这些插入语句的注释被关闭了。

从 3.2.3 版本开始,有两个代表不同标识符生成概念的新的生成器。第一个概念是数据库移植性;第二个是优化。优化表示你不需对每个新标识符的请求都查询数据库。从 3.3.x 开始,这两个新的生成器都是用来取代上面所述的生成器的。然而,它们也包括在当前版本里且可以由 FQN 进行引用。

这些生成器的第一个是 org.hibernate.id.enhanced.SequenceStyleGenerator,首先,它是作为 sequence 生成器的替代物,其次,它是比 native 具有更好移植性的生成器。这是因为 native 通常在 identitysequence 之间选择,它有差别很大的 semantic,在移植时会导致潜在的问题。然而,org.hibernate.id.enhanced.SequenceStyleGenerator 以不同的方式实现移植性。它根据所使用的方言的能力,在数据库表或序列之间选择以存储其增量。这和 native 的区别是基于表或序列的存储具有恰好相同的 semantic。实际上,序列就是 Hibernate 试图用基于表的生成器来模拟的。这个生成器有如下的配置参数:

新生成器的第二个是 org.hibernate.id.enhanced.TableGenerator,它的目的首先是替代 table 生成器,即使它实际上比 org.hibernate.id.MultipleHiLoPerTableGenerator 功能要强得多;其次,作为利用可插拔 optimizer 的 org.hibernate.id.MultipleHiLoPerTableGenerator 的替代品。基本上这个生成器定义了一个可以利用多个不同的键值记录存储大量不同增量值的表。这个生成器有如下的配置参数:

  • table_name(可选 — 默认是 hibernate_sequences):所用的表的名称。

  • value_column_name(可选 — 默认为 next_val):用于存储这些值的表的字段的名字。

  • segment_column_name(可选,默认为 sequence_name):用于保存 "segment key" 的字段的名称。这是标识使用哪个增量值的值。

  • segment_value(可选,默认为 default):我们为这个生成器获取增量值的 segment 的 "segment key"。

  • segment_value_length(可选 — 默认为 255):用于 schema 生成;创建 Segment Key 字段的字段大小。

  • initial_value(可选 — 默认是 1):从表里获取的初始值。

  • increment_size(可选 — 默认是 1):对表随后的调用应该区分的值。

  • optimizer (optional - defaults to ??): See 第 5.1.2.3.1 节 “标识符生成器的优化”.

For identifier generators that store values in the database, it is inefficient for them to hit the database on each and every call to generate a new identifier value. Instead, you can group a bunch of them in memory and only hit the database when you have exhausted your in-memory value group. This is the role of the pluggable optimizers. Currently only the two enhanced generators (第 5.1.2.3 节 “增强的标识符生成器” support this operation.

  • none(如果没有指定 optimizer,通常这是缺省配置):这不会执行任何优化,在每次请求时都访问数据库。

  • hilo:对从数据库获取的值应用 hi/lo 算法。用于这个 optimizer 的从数据库获取的值应该是有序的。它们表明“组编号”。increment_size 将乘以内存里的值来定义组的“hi 值”。

  • pooled:和 hilo 一样,这个 optimizer 试图最小化对数据库的访问。然而,我们只是简单地把“下一组”的起始值而不是把序列值和分组算法的组合存入到数据库结构里。在这里,increment_size 表示数据库里的值。

When using long transactions or conversations that span several database transactions, it is useful to store versioning data to ensure that if the same entity is updated by two conversations, the last to commit changes will be informed and not override the other conversation's work. It guarantees some isolation while still allowing for good scalability and works particularly well in read-often write-sometimes situations.

You can use two approaches: a dedicated version number or a timestamp.

一个脱管(detached)实例的 version 或 timestamp 属性不能为空(null),因为 Hibernate 不管 unsaved-value 被指定为何种策略,它将任何属性为空的 version 或 timestamp 实例看作为瞬时(transient)实例。 避免 Hibernate 中的传递重附(transitive reattachment)问题的一个简单方法是 定义一个不能为空的 version 或 timestamp 属性,特别是在人们使用程序分配的标识符(assigned identifiers) 或复合主键时非常有用

You can add optimistic locking capability to an entity using the @Version annotation:

@Entity

public class Flight implements Serializable {
...
    @Version
    @Column(name="OPTLOCK")
    public Integer getVersion() { ... }
}           

The version property will be mapped to the OPTLOCK column, and the entity manager will use it to detect conflicting updates (preventing lost updates you might otherwise see with the last-commit-wins strategy).

The version column may be a numeric. Hibernate supports any kind of type provided that you define and implement the appropriate UserVersionType.

The application must not alter the version number set up by Hibernate in any way. To artificially increase the version number, check in Hibernate Entity Manager's reference documentation LockModeType.OPTIMISTIC_FORCE_INCREMENT or LockModeType.PESSIMISTIC_FORCE_INCREMENT.

If the version number is generated by the database (via a trigger for example), make sure to use @org.hibernate.annotations.Generated(GenerationTime.ALWAYS).

To declare a version property in hbm.xml, use:

<version
        column(1)="version_column"
        name="(2)propertyName"
        type="(3)typename"
        access(4)="field|property|ClassName"
        unsave(5)d-value="null|negative|undefined"
        genera(6)ted="never|always"
        insert(7)="true|false"
        node="element-name|@attribute-name|element/@attribute|."
/>

1

column(可选 — 默认为属性名):指定持有版本号的字段名。

2

name:持久化类的属性名。

3

type(可选 — 默认是 integer):版本号的类型。

4

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

5

unsaved-value(可选 — 默认是 undefined):用于标明某个实例时刚刚被实例化的(尚未保存)版本属性值,依靠这个值就可以把这种情况 和已经在先前的 session 中保存或装载的脱管(detached)实例区分开来。(undefined 指明应被使用的标识属性值。)

6

generated(可选 — 默认是 never):表明此版本属性值是否实际上是由数据库生成的。请参阅 generated properties 部分的讨论。

7

insert(可选 — 默认是 true):表明此版本列应该包含在 SQL 插入语句中。只有当数据库字段有默认值 0 的时候,才可以设置为 false

Alternatively, you can use a timestamp. Timestamps are a less safe implementation of optimistic locking. However, sometimes an application might use the timestamps in other ways as well.

Simply mark a property of type Date or Calendar as @Version.

@Entity

public class Flight implements Serializable {
...
    @Version
    public Date getLastUpdate() { ... }
}           

When using timestamp versioning you can tell Hibernate where to retrieve the timestamp value from - database or JVM - by optionally adding the @org.hibernate.annotations.Source annotation to the property. Possible values for the value attribute of the annotation are org.hibernate.annotations.SourceType.VM and org.hibernate.annotations.SourceType.DB. The default is SourceType.DB which is also used in case there is no @Source annotation at all.

Like in the case of version numbers, the timestamp can also be generated by the database instead of Hibernate. To do that, use @org.hibernate.annotations.Generated(GenerationTime.ALWAYS).

In hbm.xml, use the <timestamp> element:

<timestamp
        column(1)="timestamp_column"
        name="(2)propertyName"
        access(3)="field|property|ClassName"
        unsave(4)d-value="null|undefined"
        source(5)="vm|db"
        genera(6)ted="never|always"
        node="element-name|@attribute-name|element/@attribute|."
/>

1

column(可选 — 默认为属性名):存有时间戳的字段名。

2

name:在持久化类中的 JavaBeans 风格的属性名,其 Java 类型是 Date 或者 Timestamp 的。

3

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

4

unsaved-value(可选 — 默认是 null):用于标明某个实例时刚刚被实例化的(尚未保存)版本属性值,依靠这个值就可以把这种情况和已经在先前的 session 中保存或装载的脱管(detached)实例区分开来。(undefined 指明使用标识属性值进行这种判断。)

5

source(可选 — 默认是 vm):Hibernate 如何才能获取到时间戳的值呢?从数据库,还是当前 JVM?从数据库获取会带来一些负担,因为 Hibernate 必须访问数据库来获得“下一个值”,但是在集群环境中会更安全些。还要注意,并不是所有的 Dialect(方言)都支持获得数据库的当前时间戳的,而支持的数据库中又有一部分因为精度不足,用于锁定是不安全的(例如 Oracle 8)。

6

generated(可选 - 默认是 never):指出时间戳值是否实际上是由数据库生成的。请参阅 generated properties 的讨论。

You need to decide which property needs to be made persistent in a given entity. This differs slightly between the annotation driven metadata and the hbm.xml files.

In the annotations world, every non static non transient property (field or method depending on the access type) of an entity is considered persistent, unless you annotate it as @Transient. Not having an annotation for your property is equivalent to the appropriate @Basic annotation.

The @Basic annotation allows you to declare the fetching strategy for a property. If set to LAZY, specifies that this property should be fetched lazily when the instance variable is first accessed. It requires build-time bytecode instrumentation, if your classes are not instrumented, property level lazy loading is silently ignored. The default is EAGER. You can also mark a property as not optional thanks to the @Basic.optional attribute. This will ensure that the underlying column are not nullable (if possible). Note that a better approach is to use the @NotNull annotation of the Bean Validation specification.

Let's look at a few examples:

public transient int counter; //transient property


private String firstname; //persistent property
@Transient
String getLengthInMeter() { ... } //transient property
String getName() {... } // persistent property
@Basic
int getLength() { ... } // persistent property
@Basic(fetch = FetchType.LAZY)
String getDetailedComment() { ... } // persistent property
@Temporal(TemporalType.TIME)
java.util.Date getDepartureTime() { ... } // persistent property           
@Enumerated(EnumType.STRING)
Starred getNote() { ... } //enum persisted as String in database

counter, a transient field, and lengthInMeter, a method annotated as @Transient, and will be ignored by the Hibernate. name, length, and firstname properties are mapped persistent and eagerly fetched (the default for simple properties). The detailedComment property value will be lazily fetched from the database once a lazy property of the entity is accessed for the first time. Usually you don't need to lazy simple properties (not to be confused with lazy association fetching). The recommended alternative is to use the projection capability of JP-QL (Java Persistence Query Language) or Criteria queries.

JPA support property mapping of all basic types supported by Hibernate (all basic Java types , their respective wrappers and serializable classes). Hibernate Annotations supports out of the box enum type mapping either into a ordinal column (saving the enum ordinal) or a string based column (saving the enum string representation): the persistence representation, defaulted to ordinal, can be overridden through the @Enumerated annotation as shown in the note property example.

In plain Java APIs, the temporal precision of time is not defined. When dealing with temporal data you might want to describe the expected precision in database. Temporal data can have DATE, TIME, or TIMESTAMP precision (ie the actual date, only the time, or both). Use the @Temporal annotation to fine tune that.

@Lob indicates that the property should be persisted in a Blob or a Clob depending on the property type: java.sql.Clob, Character[], char[] and java.lang.String will be persisted in a Clob. java.sql.Blob, Byte[], byte[] and Serializable type will be persisted in a Blob.

@Lob

public String getFullText() {
    return fullText;
}
@Lob
public byte[] getFullCode() {
    return fullCode;
}

If the property type implements java.io.Serializable and is not a basic type, and if the property is not annotated with @Lob, then the Hibernate serializable type is used.

You can also manually specify a type using the @org.hibernate.annotations.Type and some parameters if needed. @Type.type could be:

If you do not specify a type, Hibernate will use reflection upon the named property and guess the correct Hibernate type. Hibernate will attempt to interpret the name of the return class of the property getter using, in order, rules 2, 3, and 4.

@org.hibernate.annotations.TypeDef and @org.hibernate.annotations.TypeDefs allows you to declare type definitions. These annotations can be placed at the class or package level. Note that these definitions are global for the session factory (even when defined at the class level). If the type is used on a single entity, you can place the definition on the entity itself. Otherwise, it is recommended to place the definition at the package level. In the example below, when Hibernate encounters a property of class PhoneNumer, it delegates the persistence strategy to the custom mapping type PhoneNumberType. However, properties belonging to other classes, too, can delegate their persistence strategy to PhoneNumberType, by explicitly using the @Type annotation.

@TypeDef(

   name = "phoneNumber",
   defaultForType = PhoneNumber.class,
   typeClass = PhoneNumberType.class
)
@Entity
public class ContactDetails {
   [...]
   private PhoneNumber localPhoneNumber;
   @Type(type="phoneNumber")
   private OverseasPhoneNumber overseasPhoneNumber;
   [...]
}

The following example shows the usage of the parameters attribute to customize the TypeDef.

//in org/hibernate/test/annotations/entity/package-info.java

@TypeDefs(
    {
    @TypeDef(
        name="caster",
        typeClass = CasterStringType.class,
        parameters = {
            @Parameter(name="cast", value="lower")
        }
    )
    }
)
package org.hibernate.test.annotations.entity;
//in org/hibernate/test/annotations/entity/Forest.java
public class Forest {
    @Type(type="caster")
    public String getSmallText() {
    ...
}      

When using composite user type, you will have to express column definitions. The @Columns has been introduced for that purpose.

@Type(type="org.hibernate.test.annotations.entity.MonetaryAmountUserType")

@Columns(columns = {
    @Column(name="r_amount"),
    @Column(name="r_currency")
})
public MonetaryAmount getAmount() {
    return amount;
}
public class MonetaryAmount implements Serializable {
    private BigDecimal amount;
    private Currency currency;
    ...
}

By default the access type of a class hierarchy is defined by the position of the @Id or @EmbeddedId annotations. If these annotations are on a field, then only fields are considered for persistence and the state is accessed via the field. If there annotations are on a getter, then only the getters are considered for persistence and the state is accessed via the getter/setter. That works well in practice and is the recommended approach.

However in some situations, you need to:

The best use case is an embeddable class used by several entities that might not use the same access type. In this case it is better to force the access type at the embeddable class level.

To force the access type on a given class, use the @Access annotation as showed below:

@Entity

public class Order {
   @Id private Long id;
   public Long getId() { return id; }
   public void setId(Long id) { this.id = id; }
   @Embedded private Address address;
   public Address getAddress() { return address; }
   public void setAddress() { this.address = address; }
}
@Entity
public class User {
   private Long id;
   @Id public Long getId() { return id; }
   public void setId(Long id) { this.id = id; }
   private Address address;
   @Embedded public Address getAddress() { return address; }
   public void setAddress() { this.address = address; }
}
@Embeddable
@Access(AcessType.PROPERTY)
public class Address {
   private String street1;
   public String getStreet1() { return street1; }
   public void setStreet1() { this.street1 = street1; }
   private hashCode; //not persistent
}

You can also override the access type of a single property while keeping the other properties standard.

@Entity

public class Order {
   @Id private Long id;
   public Long getId() { return id; }
   public void setId(Long id) { this.id = id; }
   @Transient private String userId;
   @Transient private String orderId;
   @Access(AccessType.PROPERTY)
   public String getOrderNumber() { return userId + ":" + orderId; }
   public void setOrderNumber() { this.userId = ...; this.orderId = ...; }
}

In this example, the default access type is FIELD except for the orderNumber property. Note that the corresponding field, if any must be marked as @Transient or transient.

The column(s) used for a property mapping can be defined using the @Column annotation. Use it to override default values (see the JPA specification for more information on the defaults). You can use this annotation at the property level for properties that are:

@Entity

public class Flight implements Serializable {
...
@Column(updatable = false, name = "flight_name", nullable = false, length=50)
public String getName() { ... }
            

The name property is mapped to the flight_name column, which is not nullable, has a length of 50 and is not updatable (making the property immutable).

This annotation can be applied to regular properties as well as @Id or @Version properties.

@Column(
    name="colu(1)mnName";
    boolean un(2)ique() default false;
    boolean nu(3)llable() default true;
    boolean in(4)sertable() default true;
    boolean up(5)datable() default true;
    String col(6)umnDefinition() default "";
    String tab(7)le() default "";
    int length(8)() default 255;
    int precis(9)ion() default 0; // decimal precision
    int scale((10)) default 0; // decimal scale

1

name (optional): the column name (default to the property name)

2

unique (optional): set a unique constraint on this column or not (default false)

3

nullable (optional): set the column as nullable (default true).

4

insertable (optional): whether or not the column will be part of the insert statement (default true)

5

updatable (optional): whether or not the column will be part of the update statement (default true)

6

columnDefinition (optional): override the sql DDL fragment for this particular column (non portable)

7

table (optional): define the targeted table (default primary table)

8

length (optional): column length (default 255)

8

precision (optional): column decimal precision (default 0)

10

scale (optional): column decimal scale if useful (default 0)

<property> 元素为类定义了一个持久化的、JavaBean 风格的属性。

<property
        name="(1)propertyName"
        column(2)="column_name"
        type="(3)typename"
        update(4)="true|false"
        insert(4)="true|false"
        formul(5)a="arbitrary SQL expression"
        access(6)="field|property|ClassName"
        lazy="(7)true|false"
        unique(8)="true|false"
        not-nu(9)ll="true|false"
        optimi(10)stic-lock="true|false"
        genera(11)ted="never|insert|always"
        node="element-name|@attribute-name|element/@attribute|."
        index="index_name"
        unique_key="unique_key_id"
        length="L"
        precision="P"
        scale="S"
/>

1

name:属性的名字,以小写字母开头。

2

column(可选 — 默认为属性名字):对应的数据库字段名。 也可以通过嵌套的 <column> 元素指定。

3

type(可选):一个 Hibernate 类型的名字。

4

update, insert(可选 — 默认为 true): 表明用于 UPDATE 和/或 INSERT 的 SQL 语句中是否包含这个被映射了的字段。这二者如果都设置为 false 则表明这是一个“外源性(derived)”的属性,它的值来源于映射到同一个(或多个) 字段的某些其他属性,或者通过一个 trigger(触发器)或其他程序生成。

5

formula(可选):一个 SQL 表达式,定义了这个计算 (computed) 属性的值。计算属性没有和它对应的数据库字段。

6

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

7

lazy(可选 — 默认为 false):指定 指定实例变量第一次被访问时,这个属性是否延迟抓取(fetched lazily)( 需要运行时字节码增强)。

8

unique(可选):使用 DDL 为该字段添加唯一的约束。同样,允许它作为 property-ref 引用的目标。

9

not-null(可选):使用 DDL 为该字段添加可否为空(nullability)的约束。

10

optimistic-lock(可选 — 默认为 true):指定这个属性在做更新时是否需要获得乐观锁定(optimistic lock)。换句话说,它决定这个属性发生脏数据时版本(version)的值是否增长。

11

generated(可选 — 默认为 never):表明此属性值是否实际上是由数据库生成的。请参阅 generated properties 的讨论。

typename 可以是如下几种:

如果你没有指定类型,Hibernarte 会使用反射来得到这个名字的属性,以此来猜测正确的 Hibernate 类型。Hibernate 会按照规则 2,3,4 的顺序对属性读取器(getter方法)的返回类进行解释。然而,这还不够。 在某些情况下你仍然需要 type 属性。(比如,为了区别Hibernate.DATEHibernate.TIMESTAMP,或者为了指定一个自定义类型。)

access 属性用来让你控制 Hibernate 如何在运行时访问属性。在默认情况下,Hibernate 会使用属性的 get/set 方法对(pair)。如果你指明 access="field",Hibernate 会忽略 get/set 方法对,直接使用反射来访问成员变量。你也可以指定你自己的策略,这就需要你自己实现 org.hibernate.property.PropertyAccessor 接口,再在 access 中设置你自定义策略类的名字。

衍生属性(derive propertie)是一个特别强大的特征。这些属性应该定义为只读,属性值在装载时计算生成。 你用一个 SQL 表达式生成计算的结果,它会在这个实例转载时翻译成一个 SQL 查询的 SELECT 子查询语句。


<property name="totalPrice"
    formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p
                WHERE li.productId = p.productId
                AND li.customerId = customerId
                AND li.orderNumber = orderNumber )"/>

注意,你可以使用实体自己的表,而不用为这个特别的列定义别名(上面例子中的 customerId)。同时注意,如果你不喜欢使用属性, 你可以使用嵌套的 <formula> 映射元素。

Embeddable objects (or components) are objects whose properties are mapped to the same table as the owning entity's table. Components can, in turn, declare their own properties, components or collections

It is possible to declare an embedded component inside an entity and even override its column mapping. Component classes have to be annotated at the class level with the @Embeddable annotation. It is possible to override the column mapping of an embedded object for a particular entity using the @Embedded and @AttributeOverride annotation in the associated property:

@Entity

public class Person implements Serializable {
    // Persistent component using defaults
    Address homeAddress;
    @Embedded
    @AttributeOverrides( {
            @AttributeOverride(name="iso2", column = @Column(name="bornIso2") ),
            @AttributeOverride(name="name", column = @Column(name="bornCountryName") )
    } )
    Country bornIn;
    ...
}          
@Embeddable

public class Address implements Serializable {
    String city;
    Country nationality; //no overriding here
}            
@Embeddable

public class Country implements Serializable {
    private String iso2;
    @Column(name="countryName") private String name;
    public String getIso2() { return iso2; }
    public void setIso2(String iso2) { this.iso2 = iso2; }
    
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    ...
}            

An embeddable object inherits the access type of its owning entity (note that you can override that using the @Access annotation).

The Person entity has two component properties, homeAddress and bornIn. homeAddress property has not been annotated, but Hibernate will guess that it is a persistent component by looking for the @Embeddable annotation in the Address class. We also override the mapping of a column name (to bornCountryName) with the @Embedded and @AttributeOverride annotations for each mapped attribute of Country. As you can see, Country is also a nested component of Address, again using auto-detection by Hibernate and JPA defaults. Overriding columns of embedded objects of embedded objects is through dotted expressions.

@Embedded

    @AttributeOverrides( {
            @AttributeOverride(name="city", column = @Column(name="fld_city") ),
            @AttributeOverride(name="nationality.iso2", column = @Column(name="nat_Iso2") ),
            @AttributeOverride(name="nationality.name", column = @Column(name="nat_CountryName") )
            //nationality columns in homeAddress are overridden
    } )
    Address homeAddress;

Hibernate Annotations supports something that is not explicitly supported by the JPA specification. You can annotate a embedded object with the @MappedSuperclass annotation to make the superclass properties persistent (see @MappedSuperclass for more informations).

You can also use association annotations in an embeddable object (ie @OneToOne, @ManyToOne, @OneToMany or @ManyToMany). To override the association columns you can use @AssociationOverride.

If you want to have the same embeddable object type twice in the same entity, the column name defaulting will not work as several embedded objects would share the same set of columns. In plain JPA, you need to override at least one set of columns. Hibernate, however, allows you to enhance the default naming mechanism through the NamingStrategy interface. You can write a strategy that prevent name clashing in such a situation. DefaultComponentSafeNamingStrategy is an example of this.

If a property of the embedded object points back to the owning entity, annotate it with the @Parent annotation. Hibernate will make sure this property is properly loaded with the entity reference.

In XML, use the <component> element.

<component
        name="(1)propertyName"
        class=(2)"className"
        insert(3)="true|false"
        update(4)="true|false"
        access(5)="field|property|ClassName"
        lazy="(6)true|false"
        optimi(7)stic-lock="true|false"
        unique(8)="true|false"
        node="element-name|."
>

        <property ...../>
        <many-to-one .... />
        ........
</component>

1

name:属性名。

2

class(可选 — 默认为通过反射得到的属性类型):组件(子)类的名字。

3

insert:被映射的字段是否出现在 SQL 的 INSERT 语句中?

4

update:被映射的字段是否出现在 SQL 的 UPDATE 语句中?

5

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

6

lazy(可选 — 默认是 false):表明此组件应在实例变量第一次被访问的时候延迟加载(需要编译时字节码装置器)。

7

optimistic-lock(可选 — 默认是 true):表明更新此组件是否需要获取乐观锁。换句话说,当这个属性变脏时,是否增加版本号(Version)。

8

unique(可选 — 默认是 false):表明组件映射的所有字段上都有唯一性约束。

<property> 子标签为子类的一些属性与表字段之间建立映射。

<component> 元素允许加入一个 <parent> 子元素,在组件类内部就可以有一个指向其容器的实体的反向引用。

The <dynamic-component> element allows a Map to be mapped as a component, where the property names refer to keys of the map. See 第 9.5 节 “动态组件(Dynamic components)” for more information. This feature is not supported in annotations.

Java is a language supporting polymorphism: a class can inherit from another. Several strategies are possible to persist a class hierarchy:

With this approach the properties of all the subclasses in a given mapped class hierarchy are stored in a single table.

Each subclass declares its own persistent properties and subclasses. Version and id properties are assumed to be inherited from the root class. Each subclass in a hierarchy must define a unique discriminator value. If this is not specified, the fully qualified Java class name is used.

@Entity

@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(
    name="planetype",
    discriminatorType=DiscriminatorType.STRING
)
@DiscriminatorValue("Plane")
public class Plane { ... }
@Entity
@DiscriminatorValue("A320")
public class A320 extends Plane { ... }          

In hbm.xml, for the table-per-class-hierarchy mapping strategy, the <subclass> declaration is used. For example:

<subclass
        name="(1)ClassName"
        discri(2)minator-value="discriminator_value"
        proxy=(3)"ProxyInterface"
        lazy="(4)true|false"
        dynamic-update="true|false"
        dynamic-insert="true|false"
        entity-name="EntityName"
        node="element-name"
        extends="SuperclassName">

        <property .... />
        .....
</subclass>

1

name:子类的全限定名。

2

discriminator-value(辨别标志)(可选 — 默认为类名):一个用于区分每个独立的子类的值。

3

proxy(可选):指定一个类或者接口,在延迟装载时作为代理使用。

4

lazy(可选,默认是 true):设置为 lazy="false" 禁止使用延迟装载。

For information about inheritance mappings see 第 10 章 继承映射(Inheritance Mapping) .

Discriminators are required for polymorphic persistence using the table-per-class-hierarchy mapping strategy. It declares a discriminator column of the table. The discriminator column contains marker values that tell the persistence layer what subclass to instantiate for a particular row. Hibernate Core supports the follwoing restricted set of types as discriminator column: string, character, integer, byte, short, boolean, yes_no, true_false.

Use the @DiscriminatorColumn to define the discriminator column as well as the discriminator type.

You can also use @DiscriminatorFormula to express in SQL a virtual discriminator column. This is particularly useful when the discriminator value can be extracted from one or more columns of the table. Both @DiscriminatorColumn and @DiscriminatorFormula are to be set on the root entity (once per persisted hierarchy).

@org.hibernate.annotations.DiscriminatorOptions allows to optionally specify Hibernate specific discriminator options which are not standardized in JPA. The available options are force and insert. The force attribute is useful if the table contains rows with "extra" discriminator values that are not mapped to a persistent class. This could for example occur when working with a legacy database. If force is set to true Hibernate will specify the allowed discriminator values in the SELECT query, even when retrieving all instances of the root class. The second option - insert - tells Hibernate whether or not to include the discriminator column in SQL INSERTs. Usually the column should be part of the INSERT statement, but if your discriminator column is also part of a mapped composite identifier you have to set this option to false.

Finally, use @DiscriminatorValue on each class of the hierarchy to specify the value stored in the discriminator column for a given entity. If you do not set @DiscriminatorValue on a class, the fully qualified class name is used.

@Entity

@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(
    name="planetype",
    discriminatorType=DiscriminatorType.STRING
)
@DiscriminatorValue("Plane")
public class Plane { ... }
@Entity
@DiscriminatorValue("A320")
public class A320 extends Plane { ... }          

In hbm.xml, the <discriminator> element is used to define the discriminator column or formula:

<discriminator
        column(1)="discriminator_column"
        type="(2)discriminator_type"
        force=(3)"true|false"
        insert(4)="true|false"
        formul(5)a="arbitrary sql expression"
/>

1

column(可选 — 默认为 class)discriminator 器字段的名字。

2

type(可选 — 默认为 string)一个 Hibernate 字段类型的名字

3

force(强制)(可选 — 默认为 false)"强制" Hibernate 指定允许的鉴别器值,即使当取得的所有实例都是根类的。

4

insert(可选 - 默认为true)如果你的鉴别器字段也是映射为复合标识(composite identifier)的一部分,则需将这个值设为 false。(告诉 Hibernate 在做 SQL INSERT 时不包含该列)

5

formula(可选)一个 SQL 表达式,在类型判断(判断是父类还是具体子类 — 译注)时执行。可用于基于内容的鉴别器。

鉴别器字段的实际值是根据 <class><subclass> 元素中的 discriminator-value 属性得来的。

使用 formula 属性你可以定义一个 SQL 表达式,用来判断一行数据的类型。


<discriminator
    formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end"
    type="integer"/>

Each subclass can also be mapped to its own table. This is called the table-per-subclass mapping strategy. An inherited state is retrieved by joining with the table of the superclass. A discriminator column is not required for this mapping strategy. Each subclass must, however, declare a table column holding the object identifier. The primary key of this table is also a foreign key to the superclass table and described by the @PrimaryKeyJoinColumns or the <key> element.

@Entity @Table(name="CATS")

@Inheritance(strategy=InheritanceType.JOINED)
public class Cat implements Serializable { 
    @Id @GeneratedValue(generator="cat-uuid") 
    @GenericGenerator(name="cat-uuid", strategy="uuid")
    String getId() { return id; }
    ...
}
@Entity @Table(name="DOMESTIC_CATS")
@PrimaryKeyJoinColumn(name="CAT")
public class DomesticCat extends Cat { 
    public String getName() { return name; }
}            

In hbm.xml, use the <joined-subclass> element. For example:

Use the <key> element to declare the primary key / foreign key column. The mapping at the start of the chapter would then be re-written as:


<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD//EN"
        "http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="eg">

        <class name="Cat" table="CATS">
                <id name="id" column="uid" type="long">
                        <generator class="hilo"/>
                </id>
                <property name="birthdate" type="date"/>
                <property name="color" not-null="true"/>
                <property name="sex" not-null="true"/>
                <property name="weight"/>
                <many-to-one name="mate"/>
                <set name="kittens">
                        <key column="MOTHER"/>
                        <one-to-many class="Cat"/>
                </set>
                <joined-subclass name="DomesticCat" table="DOMESTIC_CATS">
                    <key column="CAT"/>
                    <property name="name" type="string"/>
                </joined-subclass>
        </class>

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

</hibernate-mapping>

For information about inheritance mappings see 第 10 章 继承映射(Inheritance Mapping) .

This is sometimes useful to share common properties through a technical or a business superclass without including it as a regular mapped entity (ie no specific table for this entity). For that purpose you can map them as @MappedSuperclass.

@MappedSuperclass

public class BaseEntity {
    @Basic
    @Temporal(TemporalType.TIMESTAMP)
    public Date getLastUpdate() { ... }
    public String getLastUpdater() { ... }
    ...
}
@Entity class Order extends BaseEntity {
    @Id public Integer getId() { ... }
    ...
}

In database, this hierarchy will be represented as an Order table having the id, lastUpdate and lastUpdater columns. The embedded superclass property mappings are copied into their entity subclasses. Remember that the embeddable superclass is not the root of the hierarchy though.

You can override columns defined in entity superclasses at the root entity level using the @AttributeOverride annotation.

@MappedSuperclass

public class FlyingObject implements Serializable {
    public int getAltitude() {
        return altitude;
    }
    @Transient
    public int getMetricAltitude() {
        return metricAltitude;
    }
    @ManyToOne
    public PropulsionType getPropulsion() {
        return metricAltitude;
    }
    ...
}
@Entity
@AttributeOverride( name="altitude", column = @Column(name="fld_altitude") )
@AssociationOverride( 
   name="propulsion", 
   joinColumns = @JoinColumn(name="fld_propulsion_fk") 
)
public class Plane extends FlyingObject {
    ...
}

The altitude property will be persisted in an fld_altitude column of table Plane and the propulsion association will be materialized in a fld_propulsion_fk foreign key column.

You can define @AttributeOverride(s) and @AssociationOverride(s) on @Entity classes, @MappedSuperclass classes and properties pointing to an @Embeddable object.

In hbm.xml, simply map the properties of the superclass in the <class> element of the entity that needs to inherit them.

While not recommended for a fresh schema, some legacy databases force your to map a single entity on several tables.

Using the @SecondaryTable or @SecondaryTables class level annotations. To express that a column is in a particular table, use the table parameter of @Column or @JoinColumn.

@Entity

@Table(name="MainCat")
@SecondaryTables({
    @SecondaryTable(name="Cat1", pkJoinColumns={
        @PrimaryKeyJoinColumn(name="cat_id", referencedColumnName="id")
    ),
    @SecondaryTable(name="Cat2", uniqueConstraints={@UniqueConstraint(columnNames={"storyPart2"})})
})
public class Cat implements Serializable {
    private Integer id;
    private String name;
    private String storyPart1;
    private String storyPart2;
    @Id @GeneratedValue
    public Integer getId() {
        return id;
    }
    public String getName() {
        return name;
    }
    
    @Column(table="Cat1")
    public String getStoryPart1() {
        return storyPart1;
    }
    @Column(table="Cat2")
    public String getStoryPart2() {
        return storyPart2;
    }
}

In this example, name will be in MainCat. storyPart1 will be in Cat1 and storyPart2 will be in Cat2. Cat1 will be joined to MainCat using the cat_id as a foreign key, and Cat2 using id (ie the same column name, the MainCat id column has). Plus a unique constraint on storyPart2 has been set.

There is also additional tuning accessible via the @org.hibernate.annotations.Table annotation:

Make sure to use the secondary table name in the appliesto property

@Entity

@Table(name="MainCat")
@SecondaryTable(name="Cat1")
@org.hibernate.annotations.Table(
   appliesTo="Cat1",
   fetch=FetchMode.SELECT,
   optional=true)
public class Cat implements Serializable {
    private Integer id;
    private String name;
    private String storyPart1;
    private String storyPart2;
    @Id @GeneratedValue
    public Integer getId() {
        return id;
    }
    public String getName() {
        return name;
    }
    
    @Column(table="Cat1")
    public String getStoryPart1() {
        return storyPart1;
    }
    @Column(table="Cat2")
    public String getStoryPart2() {
        return storyPart2;
    }
}

In hbm.xml, use the <join> element.

<join
        table=(1)"tablename"
        schema(2)="owner"
        catalo(3)g="catalog"
        fetch=(4)"join|select"
        invers(5)e="true|false"
        option(6)al="true|false">

        <key ... />

        <property ... />
        ...
</join>

1

table:被连接表的名称。

2

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

3

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

4

fetch(可选 — 默认是 join):如果设置为默认值 join,Hibernate 将使用一个内连接来得到这个类或其超类定义的 <join>,而使用一个外连接来得到其子类定义的 <join>。如果设置为 select,则 Hibernate 将为子类定义的 <join> 使用顺序选择。这仅在一行数据表示一个子类的对象的时候才会发生。对这个类和其超类定义的 <join>,依然会使用内连接得到。

5

inverse(可选 — 默认是 false):如果打开,Hibernate 不会插入或者更新此连接定义的属性。

6

optional(可选 — 默认是 false):如果打开,Hibernate 只会在此连接定义的属性非空时插入一行数据,并且总是使用一个外连接来得到这些属性。

例如,一个人(person)的地址(address)信息可以被映射到单独的表中(并保留所有属性的值类型语义):


<class name="Person"
    table="PERSON">

    <id name="id" column="PERSON_ID">...</id>

    <join table="ADDRESS">
        <key column="ADDRESS_ID"/>
        <property name="address"/>
        <property name="zip"/>
        <property name="country"/>
    </join>
    ...

此特性常常对遗留数据模型有用,我们推荐表个数比类个数少,以及细粒度的领域模型。然而,在单独的继承树上切换继承映射策略是有用的,后面会解释这点。

To link one entity to an other, you need to map the association property as a to one association. In the relational model, you can either use a foreign key or an association table, or (a bit less common) share the same primary key value between the two entities.

To mark an association, use either @ManyToOne or @OnetoOne.

@ManyToOne and @OneToOne have a parameter named targetEntity which describes the target entity name. You usually don't need this parameter since the default value (the type of the property that stores the association) is good in almost all cases. However this is useful when you want to use interfaces as the return type instead of the regular entity.

Setting a value of the cascade attribute to any meaningful value other than nothing will propagate certain operations to the associated object. The meaningful values are divided into three categories.

By default, single point associations are eagerly fetched in JPA 2. You can mark it as lazily fetched by using @ManyToOne(fetch=FetchType.LAZY) in which case Hibernate will proxy the association and load it when the state of the associated entity is reached. You can force Hibernate not to use a proxy by using @LazyToOne(NO_PROXY). In this case, the property is fetched lazily when the instance variable is first accessed. This requires build-time bytecode instrumentation. lazy="false" specifies that the association will always be eagerly fetched.

With the default JPA options, single-ended associations are loaded with a subsequent select if set to LAZY, or a SQL JOIN is used for EAGER associations. You can however adjust the fetching strategy, ie how data is fetched by using @Fetch. FetchMode can be SELECT (a select is triggered when the association needs to be loaded) or JOIN (use a SQL JOIN to load the association while loading the owner entity). JOIN overrides any lazy attribute (an association loaded through a JOIN strategy cannot be lazy).

An ordinary association to another persistent class is declared using a

and a foreign key in one table is referencing the primary key column(s) of the target table.

@Entity

public class Flight implements Serializable {
    @ManyToOne( cascade = {CascadeType.PERSIST, CascadeType.MERGE} )
    @JoinColumn(name="COMP_ID")
    public Company getCompany() {
        return company;
    }
    ...
}            

The @JoinColumn attribute is optional, the default value(s) is the concatenation of the name of the relationship in the owner side, _ (underscore), and the name of the primary key column in the owned side. In this example company_id because the property name is company and the column id of Company is id.

@Entity

public class Flight implements Serializable {
    @ManyToOne( cascade = {CascadeType.PERSIST, CascadeType.MERGE}, targetEntity=CompanyImpl.class )
    @JoinColumn(name="COMP_ID")
    public Company getCompany() {
        return company;
    }
    ...
}
public interface Company {
    ...
}

You can also map a to one association through an association table. This association table described by the @JoinTable annotation will contains a foreign key referencing back the entity table (through @JoinTable.joinColumns) and a a foreign key referencing the target entity table (through @JoinTable.inverseJoinColumns).

@Entity

public class Flight implements Serializable {
    @ManyToOne( cascade = {CascadeType.PERSIST, CascadeType.MERGE} )
    @JoinTable(name="Flight_Company",
        joinColumns = @JoinColumn(name="FLIGHT_ID"),
        inverseJoinColumns = @JoinColumn(name="COMP_ID")
    )
    public Company getCompany() {
        return company;
    }
    ...
}       

You can mark an association as mandatory by using the optional=false attribute. We recommend to use Bean Validation's @NotNull annotation as a better alternative however. As a consequence, the foreign key column(s) will be marked as not nullable (if possible).

When Hibernate cannot resolve the association because the expected associated element is not in database (wrong id on the association column), an exception is raised. This might be inconvenient for legacy and badly maintained schemas. You can ask Hibernate to ignore such elements instead of raising an exception using the @NotFound annotation.


Sometimes you want to delegate to your database the deletion of cascade when a given entity is deleted. In this case Hibernate generates a cascade delete constraint at the database level.


Foreign key constraints, while generated by Hibernate, have a fairly unreadable name. You can override the constraint name using @ForeignKey.


Sometimes, you want to link one entity to an other not by the target entity primary key but by a different unique key. You can achieve that by referencing the unique key column(s) in @JoinColumn.referenceColumnName.

@Entity

class Person {
   @Id Integer personNumber;
   String firstName;
   @Column(name="I")
   String initial;
   String lastName;
}
@Entity
class Home {
   @ManyToOne
   @JoinColumns({
      @JoinColumn(name="first_name", referencedColumnName="firstName"),
      @JoinColumn(name="init", referencedColumnName="I"),
      @JoinColumn(name="last_name", referencedColumnName="lastName"),
   })
   Person owner
}

This is not encouraged however and should be reserved to legacy mappings.

In hbm.xml, mapping an association is similar. The main difference is that a @OneToOne is mapped as <many-to-one unique="true"/>, let's dive into the subject.

<many-to-one
        name="(1)propertyName"
        column(2)="column_name"
        class=(3)"ClassName"
        cascad(4)e="cascade_style"
        fetch=(5)"join|select"
        update(6)="true|false"
        insert(6)="true|false"
        proper(7)ty-ref="propertyNameFromAssociatedClass"
        access(8)="field|property|ClassName"
        unique(9)="true|false"
        not-nu(10)ll="true|false"
        optimi(11)stic-lock="true|false"
        lazy="(12)proxy|no-proxy|false"
        not-fo(13)und="ignore|exception"
        entity(14)-name="EntityName"
        formul(15)a="arbitrary SQL expression"
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        index="index_name"
        unique_key="unique_key_id"
        foreign-key="foreign_key_name"
/>

1

name:属性名。

2

column(可选):外键字段的名称。也可以通过嵌套的 <column> 指定。

3

class(可选 — 默认是通过反射得到的属性类型):被关联的类的名字。

4

cascade(级联)(可选)表明操作是否从父对象级联到被关联的对象。

5

fetch(可选 — 默认为 select):在外连接抓取(outer-join fetching)和序列选择抓取(sequential select fetching)两者中选择其一。

6

update, insert(可选 — 默认为 true)指定对应的字段是否包含在用于 UPDATE 和/或 INSERT 的 SQL 语句中。如果二者都是false,则这是一个纯粹的 “外源性(derived)”关联,它的值是通过映射到同一个(或多个)字段的某些其他属性得到 或者通过 trigger(触发器)、或其他程序生成。

7

property-ref:(可选)被关联到此外键的类中的对应属性的名字。如果没有指定,被关联类的主键将被使用。

8

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

9

unique(可选):使用 DDL 为外键字段生成一个唯一约束。此外, 这也可以用作 property-ref 的目标属性。这使关联同时具有一对一的效果。

10

not-null(可选):使用 DDL 为外键字段生成一个非空约束。

11

optimistic-lock(可选 — 默认为 true):指定这个属性在做更新时是否需要获得乐观锁定(optimistic lock)。换句话说,它决定这个属性发生脏数据时版本(version)的值是否增长。

12

lazy(可选 — 默认为 proxy):默认情况下,单点关联是经过代理的。lazy="no-proxy" 指定此属性应该在实例变量第一次被访问时应该延迟抓取(fetche lazily)(需要运行时字节码的增强)。lazy="false" 指定此关联总是被预先抓取。

13

not-found(可选 - 默认为exception):指定如何处理引用缺失行的外键:ignore 会把缺失的行作为一个空关联处理。

14

entity-name(可选):被关联的类的实体名。

15

formula(可选):SQL 表达式,用于定义 computed(计算出的)外键值。

Setting a value of the cascade attribute to any meaningful value other than none will propagate certain operations to the associated object. The meaningful values are divided into three categories. First, basic operations, which include: persist, merge, delete, save-update, evict, replicate, lock and refresh; second, special values: delete-orphan; and third,all comma-separated combinations of operation names: cascade="persist,merge,evict" or cascade="all,delete-orphan". See 第 11.11 节 “传播性持久化(transitive persistence)” for a full explanation. Note that single valued, many-to-one and one-to-one, associations do not support orphan delete.

一个典型的简单 many-to-one 定义例子:


<many-to-one name="product" class="Product" column="PRODUCT_ID"/>

property-ref 属性只应该用来对付遗留下来的数据库系统,可能有外键指向对方关联表的是个非主键字段(但是应该是一个惟一关键字)的情况下。这是一种十分丑陋的关系模型。比如说,假设 Product 类有一个惟一的序列号,它并不是主键。(unique 属性控制 Hibernate 通过 SchemaExport 工具进行的 DDL 生成。)


<property name="serialNumber" unique="true" type="string" column="SERIAL_NUMBER"/>

那么关于 OrderItem 的映射可能是:


<many-to-one name="product" property-ref="serialNumber" column="PRODUCT_SERIAL_NUMBER"/>

当然,我们决不鼓励这种用法。

如果被引用的唯一主键由关联实体的多个属性组成,你应该在名称为 <properties> 的元素 里面映射所有关联的属性。

假若被引用的唯一主键是组件的属性,你可以指定属性路径:


<many-to-one name="owner" property-ref="identity.ssn" column="OWNER_SSN"/>

The second approach is to ensure an entity and its associated entity share the same primary key. In this case the primary key column is also a foreign key and there is no extra column. These associations are always one to one.


注意

Many people got confused by these primary key based one to one associations. They can only be lazily loaded if Hibernate knows that the other side of the association is always present. To indicate to Hibernate that it is the case, use @OneToOne(optional=false).

In hbm.xml, use the following mapping.

<one-to-one
        name="(1)propertyName"
        class=(2)"ClassName"
        cascad(3)e="cascade_style"
        constr(4)ained="true|false"
        fetch=(5)"join|select"
        proper(6)ty-ref="propertyNameFromAssociatedClass"
        access(7)="field|property|ClassName"
        formul(8)a="any SQL expression"
        lazy="(9)proxy|no-proxy|false"
        entity(10)-name="EntityName"
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        foreign-key="foreign_key_name"
/>

1

name:属性名。

2

class(可选 — 默认是通过反射得到的属性类型):被关联的类的名字。

3

cascade(级联)(可选)表明操作是否从父对象级联到被关联的对象。

4

constrained(约束)(可选)表明该类对应的表对应的数据库表,和被关联的对象所对应的数据库表之间,通过一个外键引用对主键进行约束。这个选项影响 save()delete() 在级联执行时的先后顺序以及决定该关联能否被委托(也在 schema export tool 中被使用)。

5

fetch(可选 — 默认为 select):在外连接抓取(outer-join fetching)和序列选择抓取(sequential select fetching)两者中选择其一。

6

property-ref:(可选)指定关联类的属性名,这个属性将会和本类的主键相对应。如果没有指定,会使用对方关联类的主键。

7

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

8

formula (可选):绝大多数一对一的关联都指向其实体的主键。在一些少见的情况中,你可能会指向其他的一个或多个字段,或者是一个表达式,这些情况下,你可以用一个 SQL 公式来表示。(可以在 org.hibernate.test.onetooneformula 找到例子)

9

lazy(可选 — 默认为 proxy):默认情况下,单点关联是经过代理的。lazy="no-proxy"指定此属性应该在实例变量第一次被访问时应该延迟抓取(fetche lazily)(需要运行时字节码的增强)。 lazy="false"指定此关联总是被预先抓取。注意,如果constrained="false", 不可能使用代理,Hibernate会采取预先抓取

10

entity-name(可选):被关联的类的实体名。

主键关联不需要额外的表字段;如果两行是通过这种一对一关系相关联的,那么这两行就共享同样的主关键字值。所以如果你希望两个对象通过主键一对一关联,你必须确认它们被赋予同样的标识值。

比如说,对下面的 EmployeePerson 进行主键一对一关联:


<one-to-one name="person" class="Person"/>

<one-to-one name="employee" class="Employee" constrained="true"/>

现在我们必须确保 PERSON 和 EMPLOYEE 中相关的字段是相等的。我们使用一个被成为 foreign 的特殊的 hibernate 标识符生成策略:


<class name="person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="foreign">
            <param name="property">employee</param>
        </generator>
    </id>
    ...
    <one-to-one name="employee"
        class="Employee"
        constrained="true"/>
</class>

一个刚刚保存的 Person 实例被赋予和该 Personemployee 属性所指向的 Employee 实例同样的关键字值。

There is one more type of property mapping. The @Any mapping defines a polymorphic association to classes from multiple tables. This type of mapping requires more than one column. The first column contains the type of the associated entity. The remaining columns contain the identifier. It is impossible to specify a foreign key constraint for this kind of association. This is not the usual way of mapping polymorphic associations and you should use this only in special cases. For example, for audit logs, user session data, etc.

The @Any annotation describes the column holding the metadata information. To link the value of the metadata information and an actual entity type, The @AnyDef and @AnyDefs annotations are used. The metaType attribute allows the application to specify a custom type that maps database column values to persistent classes that have identifier properties of the type specified by idType. You must specify the mapping from values of the metaType to class names.

@Any( metaColumn = @Column( name = "property_type" ), fetch=FetchType.EAGER )

@AnyMetaDef( 
    idType = "integer", 
    metaType = "string", 
    metaValues = {
        @MetaValue( value = "S", targetEntity = StringProperty.class ),
        @MetaValue( value = "I", targetEntity = IntegerProperty.class )
    } )
@JoinColumn( name = "property_id" )
public Property getMainProperty() {
    return mainProperty;
}

Note that @AnyDef can be mutualized and reused. It is recommended to place it as a package metadata in this case.

//on a package

@AnyMetaDef( name="property" 
    idType = "integer", 
    metaType = "string", 
    metaValues = {
        @MetaValue( value = "S", targetEntity = StringProperty.class ),
        @MetaValue( value = "I", targetEntity = IntegerProperty.class )
    } )
package org.hibernate.test.annotations.any;
//in a class
    @Any( metaDef="property", metaColumn = @Column( name = "property_type" ), fetch=FetchType.EAGER )
    @JoinColumn( name = "property_id" )
    public Property getMainProperty() {
        return mainProperty;
    }

The hbm.xml equivalent is:


<any name="being" id-type="long" meta-type="string">
    <meta-value value="TBL_ANIMAL" class="Animal"/>
    <meta-value value="TBL_HUMAN" class="Human"/>
    <meta-value value="TBL_ALIEN" class="Alien"/>
    <column name="table_name"/>
    <column name="id"/>
</any>
<any
        name="(1)propertyName"
        id-typ(2)e="idtypename"
        meta-t(3)ype="metatypename"
        cascad(4)e="cascade_style"
        access(5)="field|property|ClassName"
        optimi(6)stic-lock="true|false"
>
        <meta-value ... />
        <meta-value ... />
        .....
        <column .... />
        <column .... />
        .....
</any>

1

name:属性名

2

id-type:标识符类型

3

meta-type(可选 -默认是 string):允许辨别标志(discriminator)映射的任何类型。

4

cascade(可选 — 默认是none):级联的类型。

5

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

6

optimistic-lock(可选 — 默认是 true):表明更新此组件是否需要获取乐观锁。换句话说,当这个属性变脏时,是否增加版本号(Version)。

<properties> 元素允许定义一个命名的逻辑分组(grouping)包含一个类中的多个属性。这个元素最重要的用处是允许多个属性的组合作为 property-ref 的目标(target)。这也是定义多字段唯一约束的一种方便途径。例如:

<properties
        name="(1)logicalName"
        insert(2)="true|false"
        update(3)="true|false"
        optimi(4)stic-lock="true|false"
        unique(5)="true|false"
>

        <property ...../>
        <many-to-one .... />
        ........
</properties>

1

name:分组的逻辑名称 — 不是 实际属性的名称。

2

insert:被映射的字段是否出现在 SQL 的 INSERT 语句中?

3

update:被映射的字段是否出现在 SQL 的 UPDATE 语句中?

4

optimistic-lock(可选 — 默认是 true):表明更新此组件是否需要获取乐观锁。换句话说,当这个属性变脏时,是否增加版本号(Version)。

5

unique(可选 — 默认是 false):表明组件映射的所有字段上都有唯一性约束。

例如,如果我们有如下的 <properties> 映射:


<class name="Person">
    <id name="personNumber"/>

    ...
    <properties name="name"
            unique="true" update="false">
        <property name="firstName"/>
        <property name="initial"/>
        <property name="lastName"/>
    </properties>
</class>

然后,我们可能有一些遗留的数据关联,引用 Person 表的这个唯一键,而不是主键:


<many-to-one name="owner"
         class="Person" property-ref="name">
    <column name="firstName"/>
    <column name="initial"/>
    <column name="lastName"/>
</many-to-one>

我们并不推荐这样使用,除非在映射遗留数据的情况下。

The hbm.xml structure has some specificities naturally not present when using annotations, let's describe them briefly.

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

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

<hibernate-mapping
         schem(1)a="schemaName"
         catal(2)og="catalogName"
         defau(3)lt-cascade="cascade_style"
         defau(4)lt-access="field|property|ClassName"
         defau(5)lt-lazy="true|false"
         auto-(6)import="true|false"
         packa(7)ge="package.name"
 />

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"。如果你把一个“导入过”的名字同时对应两个类,Hibernate 会抛出一个异常。

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

The <key> element is featured a few times within this guide. It appears anywhere the parent mapping element defines a join to a new table that references the primary key of the original table. It also defines the foreign key in the joined table:

<key
        column(1)="columnname"
        on-del(2)ete="noaction|cascade"
        proper(3)ty-ref="propertyName"
        not-nu(4)ll="true|false"
        update(5)="true|false"
        unique(6)="true|false"
/>

1

column(可选):外键字段的名称。也可以通过嵌套的 <column> 指定。

2

on-delete(可选,默认是 noaction):表明外键关联是否打开数据库级别的级联删除。

3

property-ref(可选):表明外键引用的字段不是原表的主键(提供给遗留数据)。

4

not-null(可选):表明外键的字段不可为空(这意味着无论何时外键都是主键的一部分)。

5

update(可选):表明外键决不应该被更新(这意味着无论何时外键都是主键的一部分)。

6

unique(可选):表明外键应有唯一性约束(这意味着无论何时外键都是主键的一部分)。

对那些看重删除性能的系统,我们推荐所有的键都应该定义为 on-delete="cascade",这样 Hibernate 将使用数据库级的 ON CASCADE DELETE 约束,而不是多个 DELETE 语句。注意,这个特性会绕过 Hibernate 通常对版本数据(versioned data)采用的乐观锁策略。

not-nullupdate 属性在映射单向一对多关联的时候有用。如果你映射一个单向一对多关联到非空的(non-nullable)外键,你必须<key not-null="true"> 定义此键字段。

和持久化服务相比,Java 级别的对象分为两个组别:

实体entity 独立于任何持有实体引用的对象。与通常的 Java 模型相比,不再被引用的对象会被当作垃圾收集掉。实体必须被显式的保存和删除(除非保存和删除是从父实体向子实体引发的级联)。这和 ODMG 模型中关于对象通过可触及保持持久性有一些不同 — 比较起来更加接近应用程序对象通常在一个大系统中的使用方法。实体支持循环引用和交叉引用,它们也可以加上版本信息。

一个实体的持久状态包含指向其他实体和类型实例的引用。值可以是原始类型,集合(不是集合中的对象),组件或者特定的不可变对象。与实体不同,值(特别是集合和组件)是通过可触及性来进行持久化和删除的。因为值对象(和原始类型数据)是随着包含他们的实体而被持久化和删除的,他们不能被独立的加上版本信息。值没有独立的标识,所以他们不能被两个实体或者集合共享。

直到现在,我们都一直使用术语“持久类”(persistent class)来代表实体。我们仍然会这么做。然而严格说来,不是所有的用户自定义的,带有持久化状态的类都是实体。组件就是用户自定义类,却是值语义的。java.lang.String 类型的 java 属性也是值语义的。给了这个定义以后,我们可以说所有 JDK 提供的类型(类)都是值类型的语义,而用于自定义类型可能被映射为实体类型或值类型语义。采用哪种类型的语义取决于开发人员。在领域模型中,寻找实体类的一个好线索是共享引用指向这个类的单一实例,而组合或聚合通常被转化为值类型。

我们会在本文档中重复碰到这两个概念。

挑战在于将 java 类型系统(和开发者定义的实体和值类型)映射到 SQL/数据库类型系统。Hibernate 提供了连接两个系统之间的桥梁:对于实体类型,我们使用 <class><subclass> 等等。对于值类型,我们使用 <property><component> 及其他,通常跟随着 type 属性。这个属性的值是Hibernate 的映射类型的名字。Hibernate 提供了许多现成的映射(标准的 JDK 值类型)。你也可以编写自己的映射类型并实现自定义的变换策略,随后我们会看到这点。

所有的 Hibernate 内建类型,除了 collections 以外,都支持空(null)语义。

内置的 basic mapping types 可以大致地分类为:

integer, long, short, float, double, character, byte, boolean, yes_no, true_false

这些类型都对应 Java 的原始类型或者其封装类,来符合(特定厂商的)SQL 字段类型。boolean, yes_notrue_false 都是 Java 中 boolean 或者 java.lang.Boolean 的另外说法。

string

java.lang.StringVARCHAR(或者 Oracle 的 VARCHAR2)的映射。

date, time, timestamp

java.util.Date 和其子类到 SQL 类型 DATETIMETIMESTAMP(或等价类型)的映射。

calendar, calendar_date

java.util.Calendar 到 SQL 类型 TIMESTAMPDATE(或等价类型)的映射。

big_decimal, big_integer

java.math.BigDecimaljava.math.BigIntegerNUMERIC(或者 Oracle 的 NUMBER类型)的映射。

locale, timezone, currency

java.util.Localejava.util.TimeZonejava.util.CurrencyVARCHAR(或者 Oracle 的 VARCHAR2 类型)的映射。LocaleCurrency 的实例被映射为它们的 ISO 代码。TimeZone 的实例被影射为它的 ID

class

java.lang.ClassVARCHAR(或者 Oracle 的 VARCHAR2 类型)的映射。Class 被映射为它的全限定名。

binary

把字节数组(byte arrays)映射为对应的 SQL 二进制类型。

text

Maps long Java strings to a SQL LONGVARCHAR or TEXT type.

image

Maps long byte arrays to a SQL LONGVARBINARY.

serializable

把可序列化的 Java 类型映射到对应的 SQL 二进制类型。你也可以为一个并非默认为基本类型的可序列化 Java 类或者接口指定 Hibernate 类型 serializable

clob, blob

JDBC 类 java.sql.Clobjava.sql.Blob的映射。某些程序可能不适合使用这个类型,因为 blob 和 clob 对象可能在一个事务之外是无法重用的。(而且, 驱动程序对这种类型的支持充满着补丁和前后矛盾。)

materialized_clob

Maps long Java strings to a SQL CLOB type. When read, the CLOB value is immediately materialized into a Java string. Some drivers require the CLOB value to be read within a transaction. Once materialized, the Java string is available outside of the transaction.

materialized_blob

Maps long Java byte arrays to a SQL BLOB type. When read, the BLOB value is immediately materialized into a byte array. Some drivers require the BLOB value to be read within a transaction. Once materialized, the byte array is available outside of the transaction.

imm_date, imm_time, imm_timestamp, imm_calendar, imm_calendar_date, imm_serializable, imm_binary

一般来说,映射类型被假定为是可变的 Java 类型,只有对不可变 Java 类型,Hibernate 会采取特定的优化措施,应用程序会把这些对象作为不可变对象处理。比如,你不应该对作为 imm_timestamp 映射的 Date 执行 Date.setTime()。要改变属性的值,并且保存这一改变,应用程序必须对这一属性重新设置一个新的(不一样的)对象。

实体及其集合的唯一标识可以是除了 binaryblobclob 之外的任何基础类型。(联合标识也是允许的,后面会说到。)

org.hibernate.Hibernate 中,定义了基础类型对应的 Type 常量。比如,Hibernate.STRING 代表 string 类型。

开发者创建属于他们自己的值类型也是很容易的。比如说,你可能希望持久化 java.lang.BigInteger 类型的属性,持久化成为 VARCHAR 字段。Hibernate没有内置这样一种类型。自定义类型能够映射一个属性(或集合元素)到不止一个数据库表字段。比如说,你可能有这样的 Java 属性:getName()/setName(),这是 java.lang.String 类型的,对应的持久化到三个字段:FIRST_NAMEINITIALSURNAME

要实现一个自定义类型,可以实现 org.hibernate.UserTypeorg.hibernate.CompositeUserType 中的任一个,并且使用类型的 Java 全限定类名来定义属性。请查看 org.hibernate.test.DoubleStringType 这个例子,看看它是怎么做的。


<property name="twoStrings" type="org.hibernate.test.DoubleStringType">
    <column name="first_string"/>
    <column name="second_string"/>
</property>

注意使用 <column> 标签来把一个属性映射到多个字段的做法。

CompositeUserTypeEnhancedUserTypeUserCollectionTypeUserVersionType 接口为更特殊的使用方式提供支持。

你甚至可以在一个映射文件中提供参数给一个 UserType。 为了这样做,你的 UserType 必须实现 org.hibernate.usertype.ParameterizedType 接口。为了给自定义类型提供参数,你可以在映射文件中使用 <type> 元素。


<property name="priority">
    <type name="com.mycompany.usertypes.DefaultValueIntegerType">
        <param name="default">0</param>
    </type>
</property>

现在,UserType 可以从传入的 Properties 对象中得到 default 参数的值。

如果你非常频繁地使用某一 UserType,可以为他定义一个简称。这可以通过使用 <typedef> 元素来实现。Typedefs 为一自定义类型赋予一个名称,并且如果此类型是参数化的,还可以包含一系列默认的参数值。


<typedef class="com.mycompany.usertypes.DefaultValueIntegerType" name="default_zero">
    <param name="default">0</param>
</typedef>

<property name="priority" type="default_zero"/>

也可以根据具体案例通过属性映射中的类型参数覆盖在 typedef 中提供的参数。

尽管 Hibernate 内建的丰富的类型和对组件的支持意味着你可能很少 需要使用自定义类型。不过,为那些在你的应用中经常出现的(非实体)类使用自定义类型也是一个好方法。例如,一个 MonetaryAmount 类使用 CompositeUserType 来映射是不错的选择,虽然他可以很容易地被映射成组件。这样做的动机之一是抽象。使用自定义类型,以后假若你改变表示金额的方法时,它可以保证映射文件不需要修改。

Generated properties 指的是其值由数据库生成的属性。一般来说,如果对象有任何属性由数据库生成值,Hibernate 应用程序需要进行刷新(refresh)。但如果把属性标明为 generated,就可以转由 Hibernate 来负责这个动作。实际上。对定义了 generated properties 的实体,每当 Hibernate 执行一条 SQL INSERT 或者 UPDATE 语句,会立刻执行一条 select 来获得生成的值。

被标明为 generated 的属性还必须是 non-insertable 和 non-updateable 的。只有 versionstimestampssimple properties 可以被标明为 generated。

never(默认)标明此属性值不是从数据库中生成。

insert — 标明此属性值在 insert 的时候生成,但是不会在随后的 update 时重新生成。比如说创建日期就归属于这类。注意虽然 versiontimestamp 属性可以被标注为 generated,但是不适用这个选项。

always — 标明此属性值在 insert 和 update 时都会被生成。

To mark a property as generated, use @Generated.

Hibernate allows you to customize the SQL it uses to read and write the values of columns mapped to simple properties. For example, if your database provides a set of data encryption functions, you can invoke them for individual columns like this:

@Entity

class CreditCard {
   @Column(name="credit_card_num")
   @ColumnTransformer(
      read="decrypt(credit_card_num)", 
      write="encrypt(?)")
   public String getCreditCardNumber() { return creditCardNumber; }
   public void setCreditCardNumber(String number) { this.creditCardNumber = number; }
   private String creditCardNumber;
}

or in XML


<property name="creditCardNumber">
        <column 
          name="credit_card_num"
          read="decrypt(credit_card_num)"
          write="encrypt(?)"/>
</property>

注意

You can use the plural form @ColumnTransformers if more than one columns need to define either of these rules.

If a property uses more that one column, you must use the forColumn attribute to specify which column, the expressions are targeting.

@Entity

class User {
   @Type(type="com.acme.type.CreditCardType")
   @Columns( {
      @Column(name="credit_card_num"),
      @Column(name="exp_date") } )
   @ColumnTransformer(
      forColumn="credit_card_num", 
      read="decrypt(credit_card_num)", 
      write="encrypt(?)")
   public CreditCard getCreditCard() { return creditCard; }
   public void setCreditCard(CreditCard card) { this.creditCard = card; }
   private CreditCard creditCard;
}

每当属性在查询里被引用时,Hibernate 都自动应用自定义的表达式。这种功能和 derived-property formula 相似,但有两个不同的地方:

  • 属性由一个或多个属性组成,它作为自动模式生成的一部分导出。

  • 属性是可读写的,非只读的。

如果指定了 write 表达式,它必须只包含一个“?”占位符。

允许 CREATE 和 DROP 任意数据库对象,与 Hibernate 的 schema 交互工具组合起来,可以提供在 Hibernate 映射文件中完全定义用户 schema 的能力。虽然这是为创建和销毁 trigger(触发器)或stored procedure(存储过程)等特别设计的,实际上任何可以在 java.sql.Statement.execute() 方法中执行的 SQL 命令都可以在此使用(比如ALTER, INSERT,等等)。本质上有两种模式来定义辅助数据库对象...

第一种模式是在映射文件中显式声明 CREATE 和 DROP 命令:


<hibernate-mapping>
    ...
    <database-object>
        <create>CREATE TRIGGER my_trigger ...</create>
        <drop>DROP TRIGGER my_trigger</drop>
    </database-object>
</hibernate-mapping>

第二种模式是提供一个类,这个类知道如何组织 CREATE 和 DROP 命令。这个特别类必须实现 org.hibernate.mapping.AuxiliaryDatabaseObject 接口。


<hibernate-mapping>
    ...
    <database-object>
        <definition class="MyTriggerDefinition"/>
    </database-object>
</hibernate-mapping>

还有,这些数据库对象可以特别指定为仅在特定的方言中才使用。


<hibernate-mapping>
    ...
    <database-object>
        <definition class="MyTriggerDefinition"/>
        <dialect-scope name="org.hibernate.dialect.Oracle9iDialect"/>
        <dialect-scope name="org.hibernate.dialect.Oracle10gDialect"/>
    </database-object>
</hibernate-mapping>

As an Object/Relational Mapping solution, Hibernate deals with both the Java and JDBC representations of application data. An online catalog application, for example, most likely has Product object with a number of attributes such as a sku, name, etc. For these individual attributes, Hibernate must be able to read the values out of the database and write them back. This 'marshalling' is the function of a Hibernate type, which is an implementation of the org.hibernate.type.Type interface. In addition, a Hibernate type describes various aspects of behavior of the Java type such as "how is equality checked?" or "how are values cloned?".

重要

A Hibernate type is neither a Java type nor a SQL datatype; it provides a information about both.

When you encounter the term type in regards to Hibernate be aware that usage might refer to the Java type, the SQL/JDBC type or the Hibernate type.

Hibernate categorizes types into two high-level groups: value types (see 第 6.1 节 “Value types”) and entity types (see 第 6.2 节 “Entity types”).

The main distinguishing characteristic of a value type is the fact that they do not define their own lifecycle. We say that they are "owned" by something else (specifically an entity, as we will see later) which defines their lifecycle. Value types are further classified into 3 sub-categories: basic types (see 第 6.1.1 节 “Basic value types”), composite types (see 第 6.1.2 节 “Composite types”) amd collection types (see 第 6.1.3 节 “Collection types”).

The norm for basic value types is that they map a single database value (column) to a single, non-aggregated Java type. Hibernate provides a number of built-in basic types, which we will present in the following sections by the Java type. Mainly these follow the natural mappings recommended in the JDBC specification. We will later cover how to override these mapping and how to provide and use alternative type mappings.

org.hibernate.type.StringType

Maps a string to the JDBC VARCHAR type. This is the standard mapping for a string if no Hibernate type is specified.

Registered under string and java.lang.String in the type registry (see 第 6.5 节 “Type registry”).

org.hibernate.type.MaterializedClob

Maps a string to a JDBC CLOB type

Registered under materialized_clob in the type registry (see 第 6.5 节 “Type registry”).

org.hibernate.type.TextType

Maps a string to a JDBC LONGVARCHAR type

Registered under text in the type registry (see 第 6.5 节 “Type registry”).

org.hibernate.type.BooleanType

Maps a boolean to a JDBC BIT type

Registered under boolean and java.lang.Boolean in the type registry (see 第 6.5 节 “Type registry”).

org.hibernate.type.NumericBooleanType

Maps a boolean to a JDBC INTEGER type as 0 = false, 1 = true

Registered under numeric_boolean in the type registry (see 第 6.5 节 “Type registry”).

org.hibernate.type.YesNoType

Maps a boolean to a JDBC CHAR type as ('N' | 'n') = false, ( 'Y' | 'y' ) = true

Registered under yes_no in the type registry (see 第 6.5 节 “Type registry”).

org.hibernate.type.TrueFalseType

Maps a boolean to a JDBC CHAR type as ('F' | 'f') = false, ( 'T' | 't' ) = true

Registered under true_false in the type registry (see 第 6.5 节 “Type registry”).