第 4 章 配置
由于Hibernate是为了能在各种不同环境下工作而设计的, 因此存在着大量的配置参数. 幸运的是多数配置参数都 有比较直观的默认值,
并有随Hibernate一同分发的配置样例hibernate.properties (位于etc/)来展示各种配置选项. 所需做的仅仅是将这个样例文件复制到类路径 (classpath)下做一些自定义的修改.
一个org.hibernate.cfg.Configuration实例代表了一个应用程序中Java类型 到SQL数据库映射的完整集合.Configuration被用来构建一个
(不可变的 (immutable))SessionFactory. 映射定义则由不同的XML映射定义文件编译而来.
你可以直接实例化Configuration来获取一个实例，并为它指定XML映射定义 文件. 如果映射定 义文件在类路径(classpath)中, 请使用addResource():
Configuration cfg = new Configuration() .addResource("Item.hbm.xml") .addResource("Bid.hbm.xml");
一个替代方法（有时是更好的选择）是，指定被映射的类，让Hibernate帮你寻找映射定义文件:
Configuration cfg = new Configuration() .addClass(org.hibernate.auction.Item.class) .addClass(org.hibernate.auction.Bid.class);
Hibernate将会在类路径(classpath)中寻找名字为 /org/hibernate/auction/Item.hbm.xml和/org/hibernate/auction/Bid.hbm.xml映射定义文件. 这种方式消除了任何对文件名的硬编码(hardcoded).
Configuration也允许你指定配置属性:
Configuration cfg = new Configuration() .addClass(org.hibernate.auction.Item.class) .addClass(org.hibernate.auction.Bid.class)
.setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect") .setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
.setProperty("hibernate.order_updates", "true");
当然这不是唯一的传递Hibernate配置属性的方式, 其他可选方式还包括:
-
传一个java.util.Properties实例给 Configuration.setProperties().
-
将hibernate.properties放置在类路径(classpath)的根目录下 (root directory).
-
通过java -Dproperty=value来设置系统 (System)属性.
-
在hibernate.cfg.xml中加入元素 <property> (稍后讨论).
如果想尽快体验Hbernate, hibernate.properties是最简单的方式.
Configuration实例是一个启动期间（startup-time）的对象, 一旦SessionFactory创建完成它就被丢弃了.
当所有映射定义被Configuration解析后, 应用程序必须获得一个用于构造Session实例的工厂. 这个工厂将被应用程序的所有线程共享:
SessionFactory sessions = cfg.buildSessionFactory();
Hibernate允许你的应用程序创建多个SessionFactory实例. 这对 使用多个数据库的应用来说很有用.
通常你希望SessionFactory来为你创建和缓存(pool)JDBC连接. 如果你采用这种方式, 只需要如下例所示那样，打开一个Session:
Session session = sessions.openSession(); // open a new Session
一旦你需要进行数据访问时, 就会从连接池(connection pool)获得一个JDBC连接.
为了使这种方式工作起来, 我们需要向Hibernate传递一些JDBC连接的属性. 所有Hibernate属性的名字和语义都在org.hibernate.cfg.Environment中定义.
我们现在将描述JDBC连接配置中最重要的设置.
如果你设置如下属性，Hibernate将使用java.sql.DriverManager来获得(和缓存)JDBC连接 :
表 4.1. Hibernate JDBC属性
| hibernate.connection.driver_class | jdbc驱动类 |
| hibernate.connection.url | jdbc URL |
| hibernate.connection.username | 数据库用户 |
| hibernate.connection.password | 数据库用户密码 |
| hibernate.connection.pool_size | 连接池容量上限数目 |
但Hibernate自带的连接池算法相当不成熟. 它只是为了让你快些上手，不适合用于产品系统或性能测试中。 出于最佳性能和稳定性考虑你应该使用第三方的连接池。
只需要连接池的特定设置替换 hibernate.connection.pool_size。这将关闭Hibernate自带的连接池. 例如, 你可能会想用C3P0.
C3P0是一个随Hibernate一同分发的开源的JDBC连接池, 它位于lib目录下。 如果你设置了hibernate.c3p0.*相关的属性, Hibernate将使用 C3P0ConnectionProvider来缓存JDBC连接.
如果你更原意使用Proxool, 请参考发 行包中的hibernate.properties并到Hibernate网站获取更多的信息.
这是一个使用C3P0的hibernate.properties样例文件:
hibernate.connection.driver_class = org.postgresql.Driverhibernate.connection.url = jdbc:postgresql://localhost/mydatabase
hibernate.connection.username = myuserhibernate.connection.password = secrethibernate.c3p0.min_size=5
hibernate.c3p0.max_size=20hibernate.c3p0.timeout=1800hibernate.c3p0.max_statements=50hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect
为了能在应用程序服务器(application server)中使用Hibernate, 你应当总是将Hibernate 配置成注册在JNDI中的Datasource处获得连接，你至少需要设置下列属性中的一个:
表 4.2. Hibernate数据源属性
| hibernate.connection.datasource | 数据源JNDI名字 |
| hibernate.jndi.url | JNDI提供者的URL (可选) |
| hibernate.jndi.class | JNDI InitialContextFactory类 (可选) |
| hibernate.connection.username | 数据库用户 (可选) |
| hibernate.connection.password | 数据库用户密码 (可选) |
这里有一个使用应用程序服务器JNDI数据源的hibernate.properties样例文件:
hibernate.connection.datasource = java:/comp/env/jdbc/testhibernate.transaction.factory_class = \ org.hibernate.transaction.JTATransactionFactory
hibernate.transaction.manager_lookup_class = \ org.hibernate.transaction.JBossTransactionManagerLookuphibernate.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在运行期的行为. 它们都是可选的, 并拥有适当的默认值.
警告: 其中一些属性是"系统级(system-level)的". 系统级属性可以通过java -Dproperty=value或hibernate.properties来设置, 而不能用上面描述的其他方法来设置.
表 4.3. Hibernate配置属性
| hibernate.dialect | 一个Hibernate Dialect类名允许Hibernate针对特定的关系数据库生成优化的SQL. 取值 full.classname.of.Dialect |
| hibernate.show_sql | 输出所有SQL语句到控制台. 取值 true | false |
| hibernate.default_schema | 在生成的SQL中, 将给定的schema/tablespace附加于非全限定名的表名上. 取值 SCHEMA_NAME |
| hibernate.default_catalog | 在生成的SQL中, 将给定的catalog附加于没全限定名的表名上. 取值 CATALOG_NAME |
| hibernate.session_factory_name | SessionFactory创建后，将自动使用这个名字绑定到JNDI中. 取值 jndi/composite/name |
| hibernate.max_fetch_depth | 为单向关联(一对一, 多对一)的外连接抓取（outer join fetch）树设置最大深度. 值为0意味着将关闭默认的外连接抓取. 取值 建议在0到3之间取值 |
| hibernate.default_batch_fetch_size | 为Hibernate关联的批量抓取设置默认数量. 取值 建议的取值为4, 8, 和16 |
| hibernate.default_entity_mode | 为由这个SessionFactory打开的所有Session指定默认的实体表现模式. 取值 dynamic-map, dom4j, pojo |
| hibernate.order_updates | 强制Hibernate按照被更新数据的主键，为SQL更新排序。这么做将减少在高并发系统中事务的死锁。 取值 true | false |
| hibernate.generate_statistics | 如果开启, Hibernate将收集有助于性能调节的统计数据. 取值 true | false |
| hibernate.use_identifer_rollback | 如果开启, 在对象被删除时生成的标识属性将被重设为默认值. 取值 true | false |
| hibernate.use_sql_comments | 如果开启, Hibernate将在SQL中生成有助于调试的注释信息, 默认值为false. 取值 true | false |
表 4.4. Hibernate JDBC和连接(connection)属性
| hibernate.jdbc.fetch_size | 非零值，指定JDBC抓取数量的大小 (调用Statement.setFetchSize()). |
| hibernate.jdbc.batch_size | 非零值，允许Hibernate使用JDBC2的批量更新. 取值 建议取5到30之间的值 |
| hibernate.jdbc.batch_versioned_data | 如果你想让你的JDBC驱动从executeBatch()返回正确的行计数 , 那么将此属性设为true(开启这个选项通常是安全的). 同时，Hibernate将为自动版本化的数据使用批量DML. 默认值为false. eg. true | false |
| hibernate.jdbc.factory_class | 选择一个自定义的Batcher. 多数应用程序不需要这个配置属性. eg. classname.of.Batcher |
| hibernate.jdbc.use_scrollable_resultset | 允许Hibernate使用JDBC2的可滚动结果集. 只有在使用用户提供的JDBC连接时，这个选项才是必要的, 否则Hibernate会使用连接的元数据. 取值 true | false |
| hibernate.jdbc.use_streams_for_binary | 在JDBC读写binary (二进制)或serializable (可序列化) 的类型时使用流(stream)(系统级属性). 取值 true | false |
| hibernate.jdbc.use_get_generated_keys | 在数据插入数据库之后，允许使用JDBC3PreparedStatement.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. 取值 on_close | after_transaction | after_statement | auto |
| hibernate.connection.<propertyName> | 将JDBC属性propertyName传递到DriverManager.getConnection()中去. |
| hibernate.jndi.<propertyName> | 将属性propertyName传递到JNDI InitialContextFactory中去. |
表 4.5. Hibernate缓存属性
| hibernate.cache.provider_class | 自定义的CacheProvider的类名. 取值 classname.of.CacheProvider |
| hibernate.cache.use_minimal_puts | 以频繁的读操作为代价, 优化二级缓存来最小化写操作. 在Hibernate3中，这个设置对的集群缓存非常有用, 对集群缓存的实现而言，默认是开启的. 取值 true|false |
| hibernate.cache.use_query_cache | 允许查询缓存, 个别查询仍然需要被设置为可缓存的. 取值 true|false |
| hibernate.cache.use_second_level_cache | 能用来完全禁止使用二级缓存. 对那些在类的映射定义中指定<cache>的类，会默认开启二级缓存. 取值 true|false |
| hibernate.cache.query_cache_factory | 自定义的实现QueryCache接口的类名, 默认为内建的StandardQueryCache. 取值 classname.of.QueryCache |
| hibernate.cache.region_prefix | 二级缓存区域名的前缀. 取值 prefix |
| hibernate.cache.use_structured_entries | 强制Hibernate以更人性化的格式将数据存入二级缓存. 取值 true|false |
表 4.6. Hibernate事务属性
| hibernate.transaction.factory_class | 一个TransactionFactory的类名, 用于Hibernate TransactionAPI (默认为JDBCTransactionFactory). 取值 classname.of.TransactionFactory |
| jta.UserTransaction | 一个JNDI名字，被JTATransactionFactory用来从应用服务器获取JTA UserTransaction. 取值 jndi/composite/name |
| hibernate.transaction.manager_lookup_class | 一个TransactionManagerLookup的类名 - 当使用JVM级缓存，或在JTA环境中使用hilo生成器的时候需要该类. 取值 classname.of.TransactionManagerLookup |
| hibernate.transaction.flush_before_completion | 如果开启, session在事务完成后将被自动清洗(flush). (在Hibernate和CMT一起使用时很有用.) 取值 true | false |
| hibernate.transaction.auto_close_session | 如果开启, session在事务完成后将被自动关闭. (在Hibernate和CMT一起使用时很有用.) 取值 true | false |
表 4.7. 其他属性
| hibernate.query.factory_class | 选择HQL解析器的实现. 取值 org.hibernate.hql.ast.ASTQueryTranslatorFactory ororg.hibernate.hql.classic. ClassicQueryTranslatorFactory |
| hibernate.query.substitutions | 将Hibernate查询中的符号映射到SQL查询中的符号 (符号可能是函数名或常量名字). 取值 hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC |
| hibernate.hbm2ddl.auto | 在SessionFactory创建时，自动将数据库schema的DDL导出到数据库. 使用 create-drop时,在显式关闭 SessionFactory时，将drop掉数据库schema. 取值 update | create | create-drop |
| hibernate.cglib.use_reflection_optimizer | 开启CGLIB来替代运行时反射机制(系统级属性). 反射机制有时在除错时比较有用. 注意即使关闭这个优化, Hibernate还是需要CGLIB. 你不能在hibernate.cfg.xml中设置此属性. 取值 true | false |
你应当总是为你的数据库属性hibernate.dialect设置正确的 org.hibernate.dialect.Dialect子类. 如果你指定一种方言, Hibernate将为上面列出的一些属性使用合理的默认值, 为你省去了手工指定它们的功夫.
表 4.8. Hibernate SQL方言 (hibernate.dialect)
| DB2 | org.hibernate.dialect.DB2Dialect |
| DB2 AS/400 | org.hibernate.dialect.DB2400Dialect |
| DB2 OS390 | org.hibernate.dialect.DB2390Dialect |
| PostgreSQL | org.hibernate.dialect.PostgreSQLDialect |
| MySQL | org.hibernate.dialect.MySQLDialect |
| MySQL with InnoDB | org.hibernate.dialect.MySQLInnoDBDialect |
| MySQL with MyISAM | org.hibernate.dialect.MySQLMyISAMDialect |
| Oracle (any version) | org.hibernate.dialect.OracleDialect |
| Oracle 9i/10g | org.hibernate.dialect.Oracle9Dialect |
| Sybase | org.hibernate.dialect.SybaseDialect |
| Sybase Anywhere | org.hibernate.dialect.SybaseAnywhereDialect |
| Microsoft SQL Server | org.hibernate.dialect.SQLServerDialect |
| SAP DB | org.hibernate.dialect.SAPDBDialect |
| Informix | org.hibernate.dialect.InformixDialect |
| HypersonicSQL | org.hibernate.dialect.HSQLDialect |
| Ingres | org.hibernate.dialect.IngresDialect |
| Progress | org.hibernate.dialect.ProgressDialect |
| Mckoi SQL | org.hibernate.dialect.MckoiDialect |
| Interbase | org.hibernate.dialect.InterbaseDialect |
| Pointbase | org.hibernate.dialect.PointbaseDialect |
| FrontBase | org.hibernate.dialect.FrontbaseDialect |
| Firebird | org.hibernate.dialect.FirebirdDialect |
如果你的数据库支持ANSI, Oracle或Sybase风格的外连接, 外连接抓取常能通过限制往返数据库次数 (更多的工作交由数据库自己来完成)来提高效率. 外连接允许在单个SELECTSQL语句中，
通过many-to-one, one-to-many, many-to-many和one-to-one关联获取连接对象的整个对象图.
将hibernate.max_fetch_depth设为0能在全局 范围内禁止外连接抓取. 设为1或更高值能启用one-to-one和many-to-oneouter关联的外连接抓取, 它们通过 fetch="join"来映射.
Oracle限制那些通过JDBC驱动传输的字节数组的数目. 如果你希望使用二进值 (binary)或 可序列化的 (serializable)类型的大对象, 你应该开启 hibernate.jdbc.use_streams_for_binary属性. 这是系统级属性.
以hibernate.cache为前缀的属性允许你在Hibernate中，使用进程或群集范围内的二级缓存系统. 参见第 20.2 节 “二级缓存（The Second Level Cache） ”获取更多的详情.
你可以使用hibernate.query.substitutions在Hibernate中定义新的查询符号. 例如:
hibernate.query.substitutions true=1, false=0
将导致符号true和false在生成的SQL中被翻译成整数常量.
hibernate.query.substitutions toLowercase=LOWER
将允许你重命名SQL中的LOWER函数.
Hibernate使用Apache commons-logging来为各种事件记录日志.
commons-logging将直接输出到Apache Log4j(如果在类路径中包括log4j.jar)或 JDK1.4 logging (如果运行在JDK1.4或以上的环境下). 你可以从http://jakarta.apache.org 下载Log4j. 要使用Log4j，你需要将log4j.properties文件放置在类路径下, 随Hibernate 一同分发的样例属性文件在src/目录下.
我们强烈建议你熟悉一下Hibernate的日志消息. 在不失可读性的前提下， 我们做了很多工作，使Hibernate的日志可能地详细. 这是必要的查错利器. 最令人感兴趣的日志分类有如下这些:
表 4.9. Hibernate日志类别
| org.hibernate.SQL | 在所有SQL DML语句被执行时为它们记录日志 |
| org.hibernate.type | 为所有JDBC参数记录日志 |
| org.hibernate.tool.hbm2ddl | 在所有SQL DDL语句执行时为它们记录日志 |
| org.hibernate.pretty | 在session清洗(flush)时，为所有与其关联的实体(最多20个)的状态记录日志 |
| org.hibernate.cache | 为所有二级缓存的活动记录日志 |
| org.hibernate.transaction | 为事务相关的活动记录日志 |
| org.hibernate.jdbc | 为所有JDBC资源的获取记录日志 |
| org.hibernate.hql.ast | 为HQL和SQL的自动状态转换和其他关于查询解析的信息记录日志 |
| org.hibernate.secure | 为JAAS认证请求做日志 |
| org.hibernate | 为任何Hibernate相关信息做日志 (信息量较大, 但对查错非常有帮助) |
在使用Hibernate开发应用程序时, 你应当总是为org.hibernate.SQL 开启debug级别的日志记录,或者开启hibernate.show_sql属性来代替它。.
org.hibernate.cfg.NamingStrategy接口允许你为数据库中的对象和schema 元素指定一个“命名标准”.
你可能会提供一些通过Java标识生成数据库标识或将映射定义文件中"逻辑"表/列名处理成"物理"表/列名的规则. 这个特性有助于减少冗长的映射定义文件.
在加入映射定义前，你可以调用 Configuration.setNamingStrategy()指定一个不同的命名策略:
SessionFactory sf = new Configuration() .setNamingStrategy(ImprovedNamingStrategy.INSTANCE) .addFile("Item.hbm.xml")
.addFile("Bid.hbm.xml") .buildSessionFactory();
org.hibernate.cfg.ImprovedNamingStrategy是一个内建的命名策略, 对 一些应用程序而言，可能是非常有用的起点.
4.7. XML配置文件
另一个配置方法是在hibernate.cfg.xml文件中指定一套完整的配置. 这个文件可以当成hibernate.properties的替代。 若两个文件同时存在，它将重载前者的属性.
评论