Configuration
Because Hibernate is designed to operate in many different environments, there
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. Just put the example file in your classpath and customize it.
Programmatic configuration
An instance of org.hibernate.cfg.Configuration
represents an entire set of mappings of an application's Java types to an
SQL database. The Configuration is used to build an
(immutable) SessionFactory. The mappings are compiled
from various XML mapping files.
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():
An alternative (sometimes better) way is to specify the mapped class, and
let Hibernate find the mapping document for you:
Then Hibernate will look for mapping files named
/org/hibernate/auction/Item.hbm.xml and
/org/hibernate/auction/Bid.hbm.xml in the classpath.
This approach eliminates any hardcoded filenames.
A Configuration also allows you to specify configuration
properties:
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).
hibernate.properties is the easiest approach if you
want to get started quickly.
The Configuration is intended as a startup-time object,
to be discarded once a SessionFactory is created.
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:
Hibernate does allow your application to instantiate more than one
SessionFactory. This is useful if you are using more than
one database.
JDBC connections
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:
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.
Hibernate will obtain (and pool) connections using java.sql.DriverManager
if you set the following properties:
Hibernate JDBC Properties
Property name
Purpose
hibernate.connection.driver_class
jdbc driver class
hibernate.connection.url
jdbc URL
hibernate.connection.username
database user
hibernate.connection.password
database user password
hibernate.connection.pool_size
maximum number of pooled connections
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.
C3P0 is an open source JDBC connection pool distributed along with
Hibernate in the lib directory. Hibernate will use its
C3P0ConnectionProvider for connection pooling if you set
hibernate.c3p0.* properties. If you'd like to use Proxool
refer to the packaged hibernate.properties and the Hibernate
web site for more information.
Here is an example hibernate.properties file for C3P0:
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:
Hibernate Datasource Properties
Propery name
Purpose
hibernate.connection.datasource
datasource JNDI name
hibernate.jndi.url
URL of the JNDI provider (optional)
hibernate.jndi.class
class of the JNDI InitialContextFactory (optional)
hibernate.connection.username
database user (optional)
hibernate.connection.password
database user password (optional)
Here's an example hibernate.properties file for an
application server provided JNDI datasource:
JDBC connections obtained from a JNDI datasource will automatically participate
in the container-managed transactions of the application server.
Arbitrary connection properties may be given by prepending
"hibernate.connnection" to the property name. For example, you
may specify a charSet using hibernate.connection.charSet.
You may define your own plugin strategy for obtaining JDBC connections by implementing the
interface org.hibernate.connection.ConnectionProvider. You may select
a custom implementation by setting hibernate.connection.provider_class.
Optional configuration properties
There are a number of other properties that control the behaviour of Hibernate
at runtime. All are optional and have reasonable default values.
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.
Hibernate Configuration Properties
Property name
Purpose
hibernate.dialect
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
Qualify unqualified tablenames with the given schema/tablespace
in generated SQL.
eg.
SCHEMA_NAME
hibernate.default_catalog
Qualify unqualified tablenames with the given catalog
in generated SQL.
eg.
CATALOG_NAME
hibernate.session_factory_name
The SessionFactory will be automatically
bound to this name in JNDI after it has been created.
eg.
jndi/composite/name
hibernate.max_fetch_depth
Set a maximum "depth" for the outer join fetch tree
for single-ended associations (one-to-one, many-to-one).
A 0 disables default outer join fetching.
eg.
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.default_entity_mode
Set a default mode for entity representation for all sessions
opened from this SessionFactory
dynamic-map, dom4j,
pojo
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
A non-zero value determines the JDBC fetch size (calls
Statement.setFetchSize()).
hibernate.jdbc.batch_size
A non-zero value enables use of JDBC2 batch updates by Hibernate.
eg.
recommended values between 5 and 30
hibernate.jdbc.batch_versioned_data
Set 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.
eg.
true | false
hibernate.jdbc.factory_class
Select a custom Batcher. Most applications
will not need this configuration property.
eg.
classname.of.Batcher
hibernate.jdbc.use_scrollable_resultset
Enables use of JDBC2 scrollable resultsets by Hibernate.
This property is only necessary when using user supplied
JDBC connections, Hibernate uses connection metadata otherwise.
eg.
true | false
hibernate.jdbc.use_streams_for_binary
Use streams when writing/reading binary
or serializable types to/from JDBC
(system-level property).
eg.
true | false
hibernate.jdbc.use_get_generated_keys
Enable use of JDBC3 PreparedStatement.getGeneratedKeys()
to retrieve natively generated keys after insert. Requires JDBC3+ driver
and JRE1.4+, set to false if your driver has problems with the Hibernate
identifier generators. By default, tries to determine the driver capabilites
using connection metadata.
eg.
true|false
hibernate.connection.provider_class
The classname of a custom ConnectionProvider which provides
JDBC connections to Hibernate.
eg.
classname.of.ConnectionProvider
hibernate.connection.isolation
Set the JDBC transaction isolation level. Check
java.sql.Connection for meaningful values but
note that most databases do not support all isolation levels.
eg.
1, 2, 4, 8
hibernate.connection.autocommit
Enables autocommit for JDBC pooled connections (not recommended).
eg.
true | false
hibernate.connection.<propertyName>
Pass the JDBC property propertyName
to DriverManager.getConnection().
hibernate.jndi.<propertyName>
Pass the property propertyName to
the JNDI InitialContextFactory.
Hibernate Cache Properties
Property name
Purpose
hibernate.cache.provider_class
The classname of a custom CacheProvider.
eg.
classname.of.CacheProvider
hibernate.cache.use_minimal_puts
Optimize second-level cache operation to minimize writes, at the
cost of more frequent reads. This setting is most useful for
clustered caches and, in Hibernate3, is enabled by default for
clustered cache implementations.
eg.
true|false
hibernate.cache.use_query_cache
Enable the query cache, individual queries still have to be set cachable.
eg.
true|false
hibernate.cache.use_second_level_cache
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
The classname of a custom QueryCache interface,
defaults to the built-in StandardQueryCache.
eg.
classname.of.QueryCache
hibernate.cache.region_prefix
A prefix to use for second-level cache region names.
eg.
prefix
hibernate.cache.use_structured_entries
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
The classname of a TransactionFactory
to use with Hibernate Transaction API
(defaults to JDBCTransactionFactory).
eg.
classname.of.TransactionFactory
jta.UserTransaction
A JNDI name used by JTATransactionFactory to
obtain the JTA UserTransaction from the
application server.
eg.
jndi/composite/name
hibernate.transaction.manager_lookup_class
The classname of a TransactionManagerLookup
- required when JVM-level caching is enabled or when using hilo
generator in a JTA environment.
eg.
classname.of.TransactionManagerLookup
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
Mapping from tokens in Hibernate queries to SQL tokens
(tokens might be function or literal names, for example).
eg.
hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC
hibernate.hbm2ddl.auto
Automatically export schema DDL to the database when the
SessionFactory is created. With
create-drop, the database schema
will be dropped when the SessionFactory
is closed explicitly.
eg.
update | create | create-drop
hibernate.cglib.use_reflection_optimizer
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
SQL Dialects
You should always set the hibernate.dialect property to the correct
org.hibernate.dialect.Dialect subclass for your database. If you
specify a dialect, Hibernate will use sensible defaults for some of the
other properties listed above, saving you the effort of specifying them manually.
Hibernate SQL Dialects (hibernate.dialect)
RDBMS
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
Outer Join Fetching
If your database supports ANSI, Oracle or Sybase style outer joins, outer join
fetching will often increase performance by limiting the number of round
trips to and from the database (at the cost of possibly more work performed by
the database itself). Outer join fetching allows a whole graph of objects connected
by many-to-one, one-to-many, many-to-many and one-to-one associations to be retrieved
in a single SQL SELECT.
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
one-to-one and many-to-one associations which have been mapped with
fetch="join".
See for more information.
Binary Streams
Oracle limits the size of byte arrays that may
be passed to/from its JDBC driver. If you wish to use large instances of
binary or serializable type, you should
enable hibernate.jdbc.use_streams_for_binary.
This is a system-level setting only.
Second-level and query cache
The properties prefixed by hibernate.cache
allow you to use a process or cluster scoped second-level cache system
with Hibernate. See the for
more details.
Query Language Substitution
You may define new Hibernate query tokens using hibernate.query.substitutions.
For example:
hibernate.query.substitutions true=1, false=0
would cause the tokens true and false to be translated to
integer literals in the generated SQL.
hibernate.query.substitutions toLowercase=LOWER
would allow you to rename the SQL LOWER function.
Hibernate statistics
If you enable hibernate.generate_statistics, Hibernate will
expose a number of metrics that are useful when tuning a running system via
SessionFactory.getStatistics(). Hibernate can even be configured
to expose these statistics via JMX. Read the Javadoc of the interfaces in
org.hibernate.stats for more information.
Logging
Hibernate logs various events using Apache commons-logging.
The commons-logging service will direct output to either Apache Log4j
(if you include log4j.jar in your classpath) or
JDK1.4 logging (if running under JDK1.4 or above). You may download
Log4j from http://jakarta.apache.org.
To use Log4j you will need to place a log4j.properties
file in your classpath, an example properties file is distributed with
Hibernate in the src/ directory.
We strongly recommend that you familiarize yourself with Hibernate's log
messages. A lot of work has been put into making the Hibernate log as
detailed as possible, without making it unreadable. It is an essential
troubleshooting device. The most interesting log categories are the
following:
Hibernate Log Categories
Category
Function
org.hibernate.SQL
Log all SQL DML statements as they are executed
org.hibernate.type
Log all JDBC parameters
org.hibernate.tool.hbm2ddl
Log all SQL DDL statements as they are executed
org.hibernate.pretty
Log the state of all entities (max 20 entities) associated
with the session at flush time
org.hibernate.cache
Log all second-level cache activity
org.hibernate.transaction
Log transaction related activity
org.hibernate.jdbc
Log all JDBC resource acquisition
org.hibernate.hql.ast
Log HQL and SQL ASTs and other information about
query parsing
org.hibernate.secure
Log all JAAS authorization requests
org.hibernate
Log everything (a lot of information, but very useful for
troubleshooting)
When developing applications with Hibernate, you should almost always work with
debug enabled for the category org.hibernate.SQL,
or, alternatively, the property hibernate.show_sql enabled.
Implementing a NamingStrategy
The interface org.hibernate.cfg.NamingStrategy allows you
to specify a "naming standard" for database objects and schema elements.
You may provide rules for automatically generating database identifiers from
Java identifiers or for processing "logical" column and table names given in
the mapping file into "physical" table and column names. This feature helps
reduce the verbosity of the mapping document, eliminating repetitive noise
(TBL_ prefixes, for example). The default strategy used by
Hibernate is quite minimal.
You may specify a different strategy by calling
Configuration.setNamingStrategy() before adding mappings:
org.hibernate.cfg.ImprovedNamingStrategy is a built-in
strategy that might be a useful starting point for some applications.
XML configuration file
An alternative approach to configuration is to specify a full configuration in
a file named hibernate.cfg.xml. This file can be used as a
replacement for the hibernate.properties file or, if both
are present, to override properties.
The XML configuration file is by default expected to be in the root o
your CLASSPATH. Here is an example:
java:/comp/env/jdbc/MyDB
org.hibernate.dialect.MySQLDialect
false
org.hibernate.transaction.JTATransactionFactory
java:comp/UserTransaction
]]>
As you can see, the advantage of this approach is the externalization of the
mapping file names to configuration. The hibernate.cfg.xml
is also more convenient once you have to tune the Hibernate cache. Note that is
your choice to use either hibernate.properties or
hibernate.cfg.xml, both are equivalent, except for the above
mentioned benefits of using the XML syntax.
With the XML configuration, starting Hibernate is then as simple as
You can pick a different XML configuration file using
J2EE Application Server integration
Hibernate has the following integration points for J2EE infrastructure:
Container-managed datasources: Hibernate can use
JDBC connections managed by the container and provided through JNDI. Usually,
a JTA compatible TransactionManager and a
ResourceManager take care of transaction management (CMT),
esp. distributed transaction handling across several datasources. You may
of course also demarcate transaction boundaries programatically (BMT) or
you might want to use the optional Hibernate Transaction
API for this to keep your code portable.
Automatic JNDI binding: Hibernate can bind its
SessionFactory to JNDI after startup.
JTA Session binding: The Hibernate Session
may be automatically bound to the scope of JTA transactions if you use EJBs. Simply
lookup the SessionFactory from JNDI and get the current
Session. Let Hibernate take care of flushing and closing the
Session when your JTA transaction completes. Transaction
demarcation is declarative, in EJB deployment descriptors.
JMX deployment: If you have a JMX capable application server
(e.g. JBoss AS), you can chose to deploy Hibernate as a managed MBean. This saves
you the one line startup code to build your SessionFactory from
a Configuration. The container will startup your
HibernateService, and ideally also take care of service
dependencies (Datasource has to be available before Hibernate starts, etc).
Transaction strategy configuration
The Hibernate Session API is independent of any transaction
demarcation system in your architecture. If you let Hibernate use JDBC directly,
through a connection pool, you may begin and end your transactions by calling
the JDBC API. If you run in a J2EE application server, you might want to use bean-managed
transactions and call the JTA API and UserTransaction when needed.
To keep your code portable between these two (and other) environments we recommend the optional
Hibernate Transaction API, which wraps and hides the underlying system.
You have to specify a factory class for Transaction instances by setting the
Hibernate configuration property hibernate.transaction.factory_class.
There are three standard (built-in) choices:
org.hibernate.transaction.JDBCTransactionFactory
delegates to database (JDBC) transactions (default)
org.hibernate.transaction.JTATransactionFactory
delegates to container-managed transaction if an existing transaction is
underway in this context (e.g. EJB session bean method), otherwise
a new transaction is started and bean-managed transaction are used.
org.hibernate.transaction.CMTTransactionFactory
delegates to container-managed JTA transactions
You may also define your own transaction strategies (for a CORBA transaction service,
for example).
Some features in Hibernate (i.e. the second level cache, automatic JTA and Session binding, etc.)
require access to the JTA TransactionManager in a managed environment.
In an application server you have to specify how Hibernate should obtain a reference to the
TransactionManager, since J2EE does not standardize a single mechanism:
JTA TransactionManagers
Transaction Factory
Application Server
org.hibernate.transaction.JBossTransactionManagerLookup
JBoss
org.hibernate.transaction.WeblogicTransactionManagerLookup
Weblogic
org.hibernate.transaction.WebSphereTransactionManagerLookup
WebSphere
org.hibernate.transaction.WebSphereExtendedJTATransactionLookup
WebSphere 6
org.hibernate.transaction.OrionTransactionManagerLookup
Orion
org.hibernate.transaction.ResinTransactionManagerLookup
Resin
org.hibernate.transaction.JOTMTransactionManagerLookup
JOTM
org.hibernate.transaction.JOnASTransactionManagerLookup
JOnAS
org.hibernate.transaction.JRun4TransactionManagerLookup
JRun4
org.hibernate.transaction.BESTransactionManagerLookup
Borland ES
JNDI-bound SessionFactory
A JNDI bound Hibernate SessionFactory can simplify the lookup
of the factory and the creation of new Sessions. Note that this
is not related to a JNDI bound Datasource, both simply use the
same registry!
If you wish to have the SessionFactory bound to a JNDI namespace, specify
a name (eg. java:hibernate/SessionFactory) using the property
hibernate.session_factory_name. If this property is omitted, the
SessionFactory will not be bound to JNDI. (This is especially useful in
environments with a read-only JNDI default implementation, e.g. Tomcat.)
When binding the SessionFactory to JNDI, Hibernate will use the values of
hibernate.jndi.url, hibernate.jndi.class to instantiate
an initial context. If they are not specified, the default InitialContext
will be used.
Hibernate will automatically place the SessionFactory in JNDI after
you call cfg.buildSessionFactory(). This means you will at least have
this call in some startup code (or utility class) in your application, unless you use
JMX deployment with the HibernateService (discussed later).
If you use a JNDI SessionFactory, an EJB or any other class may
obtain the SessionFactory using a JNDI lookup. Note that this
setup is not neccessary if you use the HibernateUtil helper class
introduced in chapter one, which acts as a Singleton registry. However,
HibernateUtil is more common in a non-managed environment.
Automatic JTA and Session binding
For non-managed environments we suggested HibernateUtil with
a static SessionFactory, and ThreadLocal
management of the Hibernate Session. This approach isn't easy
to use in an EJB environment, as several EJB's may execute inside the same
transaction but not the same thread. We recommend that you bind the
SessionFactory to JNDI in a managend environment.
Instead of rolling your own ThreadLocal utility, use the
getCurrentSession() method on the SessionFactory
to obtain a Hibernate Session. If there is no Hibernate
Session in current JTA transaction, one will be started and
assigned. If you have set both the hibernate.transaction.flush_before_completion
and hibernate.transaction.auto_close_session configuration options,
the Session will also be flushed and closed automatically
when the container ends the JTA transactions.
If you, for example, use the DAO design pattern to write your persistence layer,
all DAO's lookup the SessionFactory when needed and open the
"current" Session. There is no need to pass instances of SessionFactory
or Session around between controlling code and DAO code.
JMX deployment
The line cfg.buildSessionFactory() still has to be executed
somewhere to get a SessionFactory into JNDI. You can do this
either in a static initializer block (like the one in
HibernateUtil) or you deploy Hibernate as a managed
service.
Hibernate is distributed with org.hibernate.jmx.HibernateService
for deployment on an application server with JMX capabilities, such as JBoss AS.
The actual deployment and configuration is vendor specific. Here is an example
jboss-service.xml for JBoss 4.0.x:
jboss.jca:service=RARDeployer
jboss.jca:service=LocalTxCM,name=HsqlDS
java:/hibernate/SessionFactory
java:HsqlDS
org.hibernate.dialect.HSQLDialect
org.hibernate.transaction.JTATransactionFactory
org.hibernate.transaction.JBossTransactionManagerLookup
true
true
5
true
org.hibernate.cache.EhCacheProvider
true
true
auction/Item.hbm.xml,auction/Category.hbm.xml
]]>
This file is deployed in a directory called META-INF and packaged
in a JAR file with the extension .sar (service archive). You also need
to package Hibernate, its required third-party libraries, your compiled persistent classes,
as well as your mapping files in the same archive. Your enterprise beans (usually session
beans) may be kept in their own JAR file, but you may include this EJB JAR file in the
your main service archive to get a single (hot-)deployable unit. Consult the JBoss AS
documentation for more information about JMX service and EJB deployment.