diff --git a/reference/en/modules/configuration.xml b/reference/en/modules/configuration.xml
index b1710029e4..005849fadb 100644
--- a/reference/en/modules/configuration.xml
+++ b/reference/en/modules/configuration.xml
@@ -7,8 +7,7 @@
are a large number of configuration parameters. Fortunately, most have sensible
default values and Hibernate is distributed with an example
hibernate.properties file in etc/ that shows
- the various options. You usually only have to put that file in your classpath
- and customize it.
+ the various options. Just put the example file in your classpath and customize it.
@@ -23,18 +22,18 @@
- You may obtain a Configuration instance by
- instantiating it directly. Heres an example of setting up a datastore from
- mappings defined in two XML mapping files (in the classpath):
+ You may obtain a Configuration instance by instantiating
+ it directly and specifying XML mapping documents. If the mapping files are
+ in the classpath, use addResource():
+ .addResource("Item.hbm.xml")
+ .addResource("Bid.hbm.xml");]]>
- An alternative (sometimes better) way is to let Hibernate load a mapping file
- using getResourceAsStream():
+ An alternative (sometimes better) way is to specify the mapped class, and
+ let Hibernate find the mapping document for you:
- A Configuration also specifies various optional properties:
+ A Configuration also allows you to specify configuration
+ properties:
-
+ .setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect")
+ .setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
+ .setProperty("hibernate.order_updates", "true");]]>
+
+
+ This is not the only way to pass configuration properties to Hibernate.
+ The various options include:
+
+
+
+
+
+ Pass an instance of java.util.Properties to
+ Configuration.setProperties().
+
+
+
+
+ Place hibernate.properties in a root directory
+ of the classpath.
+
+
+
+
+ Set System properties using
+ java -Dproperty=value.
+
+
+
+
+ Include <property> elements in
+ hibernate.cfg.xml (discussed later).
+
+
+
- A Configuration is intended as a startup-time object, to be
- discarded once a SessionFactory is built.
+ hibernate.properties is the easiest approach is you
+ want to get started quickly.
- Instead of adding mapping files and setting properties programatially, you may
- also place Hibernate configuration files in your classpath, as you will see
- later.
+ The Configuration is intended as a startup-time object,
+ to be discarded once a SessionFactory is created.
@@ -76,20 +107,22 @@ Configuration cfg = new Configuration()
Obtaining a SessionFactory
- When all mappings have been parsed by the Configuration, the application
- must obtain a factory for Session instances. This factory is intended
- to be shared by all application threads:
+ When all mappings have been parsed by the Configuration,
+ the application must obtain a factory for Session instances.
+ This factory is intended to be shared by all application threads:
- However, Hibernate does allow your application to instantiate more than one
- SessionFactory. This is useful if you are using more than one database.
+ Hibernate does allow your application to instantiate more than one
+ SessionFactory. This is useful if you are using more than
+ one database.
+
- Hibernate provided JDBC connection
+ JDBC connections
- Alternatively, you can have the SessionFactory
- open connections for you. The SessionFactory
- must be provided with JDBC connection properties in one of the
- following ways:
+ Usually, you want to have the SessionFactory create and pool JDBC
+ connections for you. If you take this approach, opening a Session
+ is as simple as:
-
-
-
- Pass an instance of java.util.Properties to
- Configuration.setProperties().
-
-
-
-
- Place hibernate.properties in a root directory of
- the classpath.
-
-
-
-
- Set System properties using
- java -Dproperty=value.
-
-
-
-
- Include <property> elements in
- hibernate.cfg.xml (discussed later).
-
-
-
-
+
+
- If you take this approach, opening a Session is as simple as:
+ As soon as you do something that requires access to the database, a JDBC connection
+ will be obtained from the pool.
-
-
+ For this to work, we need to pass some JDBC connection properties to Hibernate.
All Hibernate property names and semantics are defined on the class
org.hibernate.cfg.Environment. We will now describe the most
important settings for JDBC connection configuration.
@@ -230,11 +236,13 @@ Session session = sessions.openSession(conn);
- Hibernate's own connection pooling algorithm is however quite rudimentary. It is intended
- to help you get started and is not intended for use in a production system
- or even for performance testing. Use a third party pool for best performance and stability,
- i.e., replace the hibernate.connection.pool_size property with
- connection pool specific settings. This will turn off Hibernate's internal pool.
+ Hibernate's own connection pooling algorithm is however quite rudimentary.
+ It is intended to help you get started and is not intended for use
+ in a production system or even for performance testing. You should
+ use a third party pool for best performance and stability. Just replace the
+ hibernate.connection.pool_size property with connection
+ pool specific settings. This will turn off Hibernate's internal pool. For
+ example, you might like to use C3P0.
@@ -247,7 +255,7 @@ Session session = sessions.openSession(conn);
- This is an example using C3P0:
+ Here is an example hibernate.properties file for C3P0:
- For use inside an application server, Hibernate may obtain connections from a
- javax.sql.Datasource registered in JNDI. Set the following
- properties:
+ For use inside an application server, you should almost always configure
+ Hibernate to obtain connections from an application server
+ Datasource registered in JNDI. You'll need to set at
+ least one of the following properties:
@@ -323,10 +332,11 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]>
- This is an example using an application server provided JNDI datasource:
+ Here's an example hibernate.properties file for an
+ application server provided JNDI datasource:
-
Arbitrary connection properties may be given by prepending
"hibernate.connnection" to the property name. For example, you
- may specify a charSet using hibernate.connnection.charSet.
+ may specify a charSet using hibernate.connection.charSet.
@@ -362,10 +372,10 @@ hibernate.dialect = \
- System-level properties can only be set via java -Dproperty=value or
- be defined in hibernate.properties and not with an instance of
- Properties passed to the Configuration. They
- are also not available in the hibernate.cfg.xml file, discusse later.
+ Warning: some of these properties are "system-level" only.
+ System-level properties can be set only via java -Dproperty=value or
+ hibernate.properties. They may not be set by
+ the other techniques described above.
@@ -385,14 +395,27 @@ hibernate.dialect = \
hibernate.dialect
- The classname of a Hibernate Dialect - enables
- certain platform dependent features.
+ The classname of a Hibernate Dialect which
+ allows Hibernate to generate SQL optimized for a particular
+ relational database.
eg.
full.classname.of.Dialect
+
+
+ hibernate.show_sql
+
+
+ Write all SQL statements to console.
+
+ eg.
+ true | false
+
+
+
hibernate.default_schema
@@ -442,10 +465,93 @@ hibernate.dialect = \
A 0 disables default outer join fetching.
eg.
- recommended values between 0 and 3
+ recommended values between 0 and
+ 3
+
+
+ hibernate.default_batch_fetch_size
+
+
+ Set a default size for Hibernate batch fetching of associations.
+
+ eg.
+ recommended values 4, 8,
+ 16
+
+
+
+
+
+ hibernate.order_updates
+
+
+ Force Hibernate to order SQL updates by the primary key value
+ of the items being updates. This will result in fewer transaction
+ deadlocks in highly concurrent systems.
+
+ eg.
+ true | false
+
+
+
+
+
+ hibernate.generate_statistics
+
+
+ If enabled, Hibernate will collect statistics useful for
+ performance tuning.
+
+ eg.
+ true | false
+
+
+
+
+
+ hibernate.use_identifer_rollback
+
+
+ If enabled, generated identifier properties will be
+ reset to default values when objects are deleted.
+
+ eg.
+ true | false
+
+
+
+
+
+ hibernate.use_sql_comments
+
+
+ If turned on, Hibernate will generate comments inside the SQL, for
+ easier debugging, defaults to false.
+
+ eg.
+ true | false
+
+
+
+
+
+
+
+
+ Hibernate JDBC and Connection Properties
+
+
+
+
+
+ Property name
+ Purpose
+
+
+
hibernate.jdbc.fetch_size
@@ -541,28 +647,17 @@ hibernate.dialect = \
- hibernate.cglib.use_reflection_optimizer
+ hibernate.connection.provider_class
- Enables use of CGLIB instead of runtime reflection (System-level
- property). Reflection can sometimes be useful when troubleshooting,
- note that Hibernate always requires CGLIB even if you turn off the
- optimizer. You can not set this property in hibernate.cfg.xml.
+ The classname of a custom ConnectionProvider which provides
+ JDBC connections to Hibernate.
eg.
- true | false
+ classname.of.ConnectionProvider
-
-
- hibernate.jndi.<propertyName>
-
-
- Pass the property propertyName to
- the JNDI InitialContextFactory.
-
-
hibernate.connection.isolation
@@ -577,6 +672,18 @@ hibernate.dialect = \
+
+
+ hibernate.connection.autocommit
+
+
+ Enables autocommit for JDBC pooled connections (not recommended).
+
+ eg.
+ true | false
+
+
+
hibernate.connection.<propertyName>
@@ -588,17 +695,30 @@ hibernate.dialect = \
- hibernate.connection.provider_class
+ hibernate.jndi.<propertyName>
- The classname of a custom ConnectionProvider.
-
- eg.
- classname.of.ConnectionProvider
-
+ Pass the property propertyName to
+ the JNDI InitialContextFactory.
+
+
+
+
+
+ Hibernate Cache Properties
+
+
+
+
+ Property name
+ Purpose
+
+
+
+
hibernate.cache.provider_class
@@ -635,6 +755,20 @@ hibernate.dialect = \
+
+
+ hibernate.cache.use_second_level_cacge
+
+
+ May be used to completely disable the second level cache, which is enabled
+ by default for classes which specify a <cache>
+ mapping.
+
+ eg.
+ true|false
+
+
+
hibernate.cache.query_cache_factory
@@ -665,13 +799,30 @@ hibernate.dialect = \
hibernate.cache.use_structured_entries
- TODO
+ Forces Hibernate to store data in the second-level cache
+ in a more human-friendly format.
eg.
true|false
+
+
+
+
+
+ Hibernate Transaction Properties
+
+
+
+
+
+ Property name
+ Purpose
+
+
+
hibernate.transaction.factory_class
@@ -713,6 +864,63 @@ hibernate.dialect = \
+
+
+ hibernate.transaction.flush_before_completion
+
+
+ If enabled, the session will be automatically flushed during the
+ before completion phase of the transaction. (Very useful when
+ using Hibernate with CMT.)
+
+ eg.
+ true | false
+
+
+
+
+
+ hibernate.transaction.auto_close_session
+
+
+ If enabled, the session will be automatically closed during the
+ before completion phase of the transaction. (Very useful when
+ using Hibernate with CMT.)
+
+ eg.
+ true | false
+
+
+
+
+
+
+
+
+ Miscellaneous Properties
+
+
+
+
+
+ Property name
+ Purpose
+
+
+
+
+
+ hibernate.query.factory_class
+
+
+ Chooses the HQL parser implementation.
+
+ eg.
+ org.hibernate.hql.ast.ASTQueryTranslatorFactory or
+ org.hibernate.hql.classic.ClassicQueryTranslatorFactory
+
+
+
hibernate.query.substitutions
@@ -726,18 +934,6 @@ hibernate.dialect = \
-
-
- hibernate.show_sql
-
-
- Write all SQL statements to console.
-
- eg.
- true | false
-
-
-
hibernate.hbm2ddl.auto
@@ -756,39 +952,15 @@ hibernate.dialect = \
- hibernate.generate_statistics
+ hibernate.cglib.use_reflection_optimizer
- If enabled, Hibernate will collect statistics useful for
- performance tuning.
+ Enables use of CGLIB instead of runtime reflection (System-level
+ property). Reflection can sometimes be useful when troubleshooting,
+ note that Hibernate always requires CGLIB even if you turn off the
+ optimizer. You can not set this property in hibernate.cfg.xml.
- eg.
- true | false
-
-
-
-
-
- hibernate.use_identifer_rollback
-
-
- If enabled, generated identifier properties will be
- reset to default values when objects are deleted.
-
- eg.
- true | false
-
-
-
-
-
- hibernate.use_sql_comments
-
-
- If turned on, Hibernate will generate comments inside the SQL, for
- easier debugging, defaults to false.
-
- eg.
+ eg.
true | false
@@ -834,11 +1006,17 @@ hibernate.dialect = \
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 9/10g org.hibernate.dialect.Oracle9Dialect
+ Oracle 9i/10g org.hibernate.dialect.Oracle9Dialect
Sybase org.hibernate.dialect.SybaseDialect
@@ -885,7 +1063,7 @@ hibernate.dialect = \
-
+
Outer Join Fetching
@@ -901,12 +1079,8 @@ hibernate.dialect = \
Outer join fetching may be disabled globally by setting
the property hibernate.max_fetch_depth to 0.
A setting of 1 or higher enables outer join fetching for
- all one-to-one and many-to-one associations if no other fetching strategy is
- defined in the mapping and if proxying of the target entity
- class has been turned off (thus disabling lazy loading). However, one-to-many
- associations and collections are never fetched with an outer-join, unless
- explicitly declared for each particular association. This
- behavior can also be overriden at runtime with Hibernate queries.
+ one-to-one and many-to-one associations which have been mapped with
+ fetch="join".