From hibernate-commits at lists.jboss.org Wed Jun 23 18:33:25 2010
Content-Type: multipart/mixed; boundary="===============0313218219619428310=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r19805 -
core/trunk/documentation/manual/src/main/docbook/en-US/content.
Date: Wed, 23 Jun 2010 18:33:24 -0400
Message-ID: <201006232233.o5NMXOwF013911@svn01.web.mwc.hst.phx2.redhat.com>
--===============0313218219619428310==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Author: epbernard
Date: 2010-06-23 18:33:24 -0400 (Wed, 23 Jun 2010)
New Revision: 19805
Modified:
core/trunk/documentation/manual/src/main/docbook/en-US/content/configura=
tion.xml
Log:
HHH-5337 Documentation for hibernate.hbm2ddl.import_files
Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/co=
nfiguration.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/configur=
ation.xml 2010-06-23 22:33:00 UTC (rev 19804)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/configur=
ation.xml 2010-06-23 22:33:24 UTC (rev 19805)
@@ -1,4 +1,4 @@
-
+
-
-
%BOOK_ENTITIES;
-
]>
-
- Configuration
- =
-
- Hibernate is designed to operate in many different environments an=
d, as such, there
- is a broad range of configuration parameters. Fortunately, most ha=
ve sensible
- default values and Hibernate is distributed with an example =
- hibernate.properties file in etc/ that displays
- the various options. Simply put the example file in your classpath=
and customize it to suit your needs.
-
+ Configuration
=
-
- Programmatic configuration
+ Hibernate is designed to operate in many different environments an=
d,
+ as such, there is a broad range of configuration parameters. Fortunately,
+ most have sensible default values and Hibernate is distributed with an
+ example hibernate.properties file in
+ etc/ that displays the various options. Simply put the
+ example file in your classpath and customize it to suit your needs.
=
-
- An instance of org.hibernate.cfg.Configuration represents an entire set of mappings
- of an application's Java types to an SQL database. The org.hibernate.cfg.Configuration
- is used to build an immutable org.hibernate.Ses=
sionFactory. The mappings
- are compiled from various XML mapping files.
-
+
+ Programmatic configuration
=
-
- You can obtain a org.hibernate.cfg.Configuration instance by instantiating
- it directly and specifying XML mapping documents. If the mappi=
ng files are in the classpath,
- use addResource(). For example:
-
+ An instance of
+ org.hibernate.cfg.Configuration represents an
+ entire set of mappings of an application's Java types to an SQL databa=
se.
+ The org.hibernate.cfg.Configuration is used to
+ build an immutable
+ org.hibernate.SessionFactory. The mappi=
ngs
+ are compiled from various XML mapping files.
=
- You can obtain a
+ org.hibernate.cfg.Configuration instance by
+ instantiating it directly and specifying XML mapping documents. If the
+ mapping files are in the classpath, use addResource().
+ For example:
+
+ Configuration cfg =3D new Configuration()
.addResource("Item.hbm.xml")
- .addResource("Bid.hbm.xml");]]>
+ .addResource("Bid.hbm.xml");
=
-
- An alternative way is to specify the mapped class and
- allow Hibernate to find the mapping document for you:
-
+ An alternative way is to specify the mapped class and allow
+ Hibernate to find the mapping document for you:
=
- Configuration cfg =3D new Configuration()
.addClass(org.hibernate.auction.Item.class)
- .addClass(org.hibernate.auction.Bid.class);]]>
+ .addClass(org.hibernate.auction.Bid.class);
=
-
- Hibernate will then search 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 org.hibernate.cfg.Configuration also =
allows you to specify configuration
- properties. For example:
-
+ Hibernate will then search for mapping files named
+ /org/hibernate/auction/Item.hbm.xml and
+ /org/hibernate/auction/Bid.hbm.xml in the classpa=
th.
+ This approach eliminates any hardcoded filenames.
=
- A org.hibernate.cfg.Configuration also al=
lows
+ you to specify configuration properties. For example:
+
+ Configuration cfg =3D new Configuration()
.addClass(org.hibernate.auction.Item.class)
.addClass(org.hibernate.auction.Bid.class)
.setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDi=
alect")
.setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/te=
st")
- .setProperty("hibernate.order_updates", "true");]]>
- =
-
- This is not the only way to pass configuration properties to H=
ibernate. =
- Some alternative options include:
-
+ .setProperty("hibernate.order_updates", "true");
=
-
-
-
- Pass an instance of java.util.Properties to
- Configuration.setProperties().
-
-
-
-
- Place a file named hibernate.properties in a root directory of the classpath.
-
-
-
-
- Set System properties using java -Dproperty=3Dvalue.
-
-
-
-
- Include <property> elements in
- hibernate.cfg.xml (this is discusse=
d later).
-
-
-
+ This is not the only way to pass configuration properties to
+ Hibernate. Some alternative options include:
=
-
- If you want to get started quicklyhibernate.properti=
es is the easiest approach.
-
+
+
+ Pass an instance of java.util.Properties
+ to Configuration.setProperties().
+
=
-
- The org.hibernate.cfg.Configuration is =
intended as a startup-time object that will
- be discarded once a SessionFactory is creat=
ed.
-
+
+ Place a file named hibernate.properties=
in
+ a root directory of the classpath.
+
=
-
- =
-
- Obtaining a SessionFactory
+
+ Set System properties using java
+ -Dproperty=3Dvalue.
+
=
-
- When all mappings have been parsed by the org.hiber=
nate.cfg.Configuration,
- the application must obtain a factory for org.h=
ibernate.Session instances.
- This factory is intended to be shared by all application threa=
ds:
-
+
+ Include <property> elements in
+ hibernate.cfg.xml (this is discussed later).
+
+
=
-
+ If you want to get started
+ quicklyhibernate.properties is the easiest
+ approach.
=
-
- Hibernate does allow your application to instantiate more than=
one
- org.hibernate.SessionFactory. T=
his is useful if you are using more than
- one database.
-
+ The org.hibernate.cfg.Configuration is
+ intended as a startup-time object that will be discarded once a
+ SessionFactory is created.
+
=
-
+
+ Obtaining a SessionFactory
=
-
- JDBC connections
+ When all mappings have been parsed by the
+ org.hibernate.cfg.Configuration, the application
+ must obtain a factory for
+ org.hibernate.Session instances. This
+ factory is intended to be shared by all application threads:
=
-
- It is advisable to have the org.hibernate.Sessi=
onFactory create and pool
- JDBC connections for you. If you take this approach, opening a=
org.hibernate.Session
- is as simple as:
-
+ SessionFactory sessions =3D cfg.buildSes=
sionFactory();
=
-
- =
-
- Once you start a task that requires access to the database, a =
JDBC connection will be obtained from
- the pool.
-
+ Hibernate does allow your application to instantiate more than o=
ne
+ org.hibernate.SessionFactory. This is
+ useful if you are using more than one database.
+
=
-
- Before you can do this, you first need to pass some JDBC conne=
ction properties to Hibernate. All Hibernate property
- names and semantics are defined on the class org.hi=
bernate.cfg.Environment. =
- The most important settings for JDBC connection configuration =
are outlined below.
-
+
+ JDBC connections
=
-
- Hibernate will obtain and pool connections using ja=
va.sql.DriverManager
- if you set the following properties:
-
+ It is advisable to have the
+ org.hibernate.SessionFactory create and
+ pool JDBC connections for you. If you take this approach, opening a
+ org.hibernate.Session is as simple
+ as:
=
-
- Hibernate JDBC Properties
-
+ Session session =3D sessions.openSession=
(); // open a new Session
+
+ Once you start a task that requires access to the database, a JD=
BC
+ connection will be obtained from the pool.
+
+ Before you can do this, you first need to pass some JDBC connect=
ion
+ properties to Hibernate. All Hibernate property names and semantics are
+ defined on the class org.hibernate.cfg.Environment.
+ The most important settings for JDBC connection configuration are outl=
ined
+ below.
+
+ 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<=
/entry>
+
+ 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 n=
ot
+ 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 inte=
rnal
+ pool. For example, you might like to use c3p0.
+
+ C3P0 is an open source JDBC connection pool distributed along wi=
th
+ Hibernate in the lib directory. Hibernate will use
+ its org.hibernate.connection.C3P0ConnectionProvider
+ for connection pooling if you set hibernate.c3p0.*
+ properties. If you would like to use Proxool, refer to the packaged
+ hibernate.properties and the Hibernate web site f=
or
+ more information.
+
+ The following is an example
+ hibernate.properties file for c3p0:
+
+ hibernate.connection.driver_class =3D org.postgresql.D=
river
+hibernate.connection.url =3D jdbc:postgresql://localhost/mydatabase
+hibernate.connection.username =3D myuser
+hibernate.connection.password =3D secret
+hibernate.c3p0.min_size=3D5
+hibernate.c3p0.max_size=3D20
+hibernate.c3p0.timeout=3D1800
+hibernate.c3p0.max_statements=3D50
+hibernate.dialect =3D org.hibernate.dialect.PostgreSQLDialect
+
+ For use inside an application server, you should almost always
+ configure Hibernate to obtain connections from an application server
+ javax.sql.Datasource registered in JNDI.
+ You will need to set at least one of the following properties:
+
+
+ Hibernate Datasource Properties
+
+
+
+
+
+
+
+
+ Property 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 is an example hibernate.properties file
+ for an application server provided JNDI datasource:
+
+ hibernate.connection.datasource =3D java:/comp/env/jdb=
c/test
+hibernate.transaction.factory_class =3D \
+ org.hibernate.transaction.JTATransactionFactory
+hibernate.transaction.manager_lookup_class =3D \
+ org.hibernate.transaction.JBossTransactionManagerLookup
+hibernate.dialect =3D org.hibernate.dialect.PostgreSQLDialect
+
+ JDBC connections obtained from a JNDI datasource will automatica=
lly
+ participate in the container-managed transactions of the application
+ server.
+
+ Arbitrary connection properties can be given by prepending
+ "hibernate.connection" to the connection property n=
ame.
+ For example, you can specify a charSet connection
+ property using hibernate.connection.charSet.
+
+ You can define your own plugin strategy for obtaining JDBC
+ connections by implementing the interface
+ org.hibernate.connection.ConnectionProvider,
+ and specifying your custom implementation via the
+ hibernate.connection.provider_class property.
+
+
+
+ Optional configuration properties
+
+ There are a number of other properties that control the behavior=
of
+ Hibernate at runtime. All are optional and have reasonable default
+ values.
+
+
+ Some of these properties are "system-level"
+ only. System-level properties can be set only via
+ java -Dproperty=3Dvalue or
+ hibernate.properties. They
+ cannot be set by the other techniques describ=
ed
+ above.
+
+
+
+ Hibernate Configuration Properties
+
+
+
+
+
+
+
+
+ Property name
+
+ Purpose
+
+
+
+
+
+ hibernate.dialect
+
+ The classname of a Hibernate
+ org.hibernate.dialect.Dialect which all=
ows
+ Hibernate to generate SQL optimized for a particular relational
+ database. e.g.
+ full.classname.of.Dialect In
+ most cases Hibernate will actually be able to choose the corre=
ct
+ org.hibernate.dialect.Dialect
+ implementation based on the JDBC metadata
+ returned by the JDBC driver.
+
+
+
+ hibernate.show_sql
+
+ Write all SQL statements to console. This is an alterna=
tive
+ to setting the log category org.hibernate.SQL
+ to debug. e.g. true |
+ false
+
+
+
+ hibernate.format_sql
+
+ Pretty print the SQL in the log and console.
+ e.g. true |
+ false
+
+
+
+ hibernate.default_schema
+
+ Qualify unqualified table names with the given
+ schema/tablespace in generated SQL. e.g. SCHEMA_NAME
+
+
+
+
+ hibernate.default_catalog
+
+ Qualifies unqualified table names with the given catalo=
g in
+ generated SQL. e.g.
+ CATALOG_NAME
+
+
+
+ hibernate.session_factory_name
+
+ The
+ org.hibernate.SessionFactory wi=
ll
+ be automatically bound to this name in JNDI after it has been
+ created. e.g.
+ jndi/composite/name
+
+
+
+ hibernate.max_fetch_depth
+
+ Sets 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.
+ e.g. recommended values b=
etween
+ 0 and 3
+
+
+
+ hibernate.default_batch_fetch_size=
+
+ Sets a default size for Hibernate batch fetching of
+ associations. e.g.
+ recommended values 4, 8,
+ 16
+
+
+
+ hibernate.default_entity_mode
+
+ Sets a default mode for entity representation for all
+ sessions opened from this SessionFactory
+ dynamic-map, dom4j,
+ pojo
+
+
+
+ hibernate.order_updates
+
+ Forces Hibernate to order SQL updates by the primary key
+ value of the items being updated. This will result in fewer
+ transaction deadlocks in highly concurrent systems.
+ e.g. true |
+ false
+
+
+
+ hibernate.generate_statistics
+
+ If enabled, Hibernate will collect statistics useful for
+ performance tuning. e.g.
+ true | false
+
+
+
+ hibernate.use_identifier_rollback<=
/entry>
+
+ If enabled, generated identifier properties will be res=
et
+ to default values when objects are deleted. e.g. true |
+ false
+
+
+
+ hibernate.use_sql_comments
+
+ If turned on, Hibernate will generate comments inside t=
he
+ SQL, for easier debugging, defaults to false.
+ e.g.
+ 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. e.g.
+ recommended values between 5 and
+ 30
+
+
+
+ hibernate.jdbc.batch_versioned_data
+
+ Set this property to true if your JD=
BC
+ driver returns correct row counts from
+ executeBatch(). Iit is usually safe to turn
+ this option on. Hibernate will then use batched DML for
+ automatically versioned data. Defaults to
+ false. e.g. true |
+ false
+
+
+
+ hibernate.jdbc.factory_class
+
+ Select a custom
+ org.hibernate.jdbc.Batcher. Most
+ applications will not need this configuration property.
+ e.g.
+ classname.of.BatcherFactory
+
+
+
+ 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.
+ e.g. true |
+ false
+
+
+
+ hibernate.jdbc.use_streams_for_binary
+
+ Use streams when writing/reading binary
+ or serializable types to/from JDBC.
+ *system-level property* e.g. true |
+ false
+
+
+
+ hibernate.jdbc.use_get_generated_keys
+
+ Enables 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 w=
ith
+ the Hibernate identifier generators. By default, it tries to
+ determine the driver capabilities using connection metadata.
+ e.g.
+ true|false
+
+
+
+ hibernate.connection.provider_class
+
+ The classname of a custom
+ org.hibernate.connection.ConnectionProvider
+ which provides JDBC connections to Hibernate. e.g.
+ classname.of.ConnectionProvider
+
+
+
+ hibernate.connection.isolation
+
+ Sets the JDBC transaction isolation level. Check
+ java.sql.Connection for meaning=
ful
+ values, but note that most databases do not support all isolat=
ion
+ levels and some define additional, non-standard isolations.
+ e.g. 1, 2, 4,
+ 8
+
+
+
+ hibernate.connection.autocommit
+
+ Enables autocommit for JDBC pooled connections (it is n=
ot
+ recommended). e.g.
+ true | false
+
+
+
+ hibernate.connection.release_mode<=
/entry>
+
+ Specifies when Hibernate should release JDBC connection=
s.
+ By default, a JDBC connection is held until the session is
+ explicitly closed or disconnected. For an application server J=
TA
+ datasource, use after_statement to aggressi=
vely
+ release connections after every JDBC call. For a non-JTA
+ connection, it often makes sense to release the connection at =
the
+ end of each transaction, by using
+ after_transaction. auto =
will
+ choose after_statement for the JTA and CMT
+ transaction strategies and after_transaction
+ for the JDBC transaction strategy. e.g. auto (defau=
lt) |
+ on_close | after_transaction
+ | after_statement This setti=
ng
+ only affects Sessions returned from
+ SessionFactory.openSession. For
+ Sessions obtained through
+ SessionFactory.getCurrentSession, the
+ CurrentSessionContext implementation config=
ured
+ for use controls the connection release mode for those
+ Sessions. See
+
+
+
+ hibernate.connection.<=
;propertyName>
+
+ Pass the JDBC property
+ <propertyName> to
+ DriverManager.getConnection().
+
+
+
+ hibernate.jndi.<prope=
rtyName>
+
+ Pass the property <propertyName>
+ to the JNDI InitialContextFactory.
+
+
+
+
+
+
+ Hibernate Cache Properties
+
+
+
+
+
+
+
+
+ Property name
+
+ Purpose
+
+
+
+
+
+ hibernate.cache.provider_class
+
+ The classname of a custom CacheProvider.
+ e.g.
+ classname.of.CacheProvider
+
+
+
+ hibernate.cache.use_minimal_puts
+
+ Optimizes second-level cache operation to minimize writ=
es,
+ 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. e.g. true|false
+
+
+
+
+ hibernate.cache.use_query_cache
+
+ Enables the query cache. Individual queries still have =
to
+ be set cachable. e.g.
+ true|false
+
+
+
+ hibernate.cache.use_second_level_cache
+
+ Can be used to completely disable the second level cach=
e,
+ which is enabled by default for classes which specify a
+ <cache> mapping. e.g. true|false
+
+
+
+
+ hibernate.cache.query_cache_factory<=
/entry>
+
+ The classname of a custom QueryCache
+ interface, defaults to the built-in
+ StandardQueryCache. e.g.
+ classname.of.QueryCache
+
+
+
+ hibernate.cache.region_prefix
+
+ A prefix to use for second-level cache region names.
+ e.g. prefix
+
+
+
+
+ hibernate.cache.use_structured_entries
+
+ Forces Hibernate to store data in the second-level cach=
e in
+ a more human-friendly format. e.g. true|false
+
+
+
+
+
+
+
+ Hibernate Transaction Properties
+
+
+
+
+
+
+
+
+ Property name
+
+ Purpose
+
+
+
+
+
+ hibernate.transaction.factory_class<=
/entry>
+
+ The classname of a TransactionFactory to
+ use with Hibernate Transaction API (default=
s to
+ JDBCTransactionFactory). e.g.
+ classname.of.TransactionFactory
+
+
+
+ jta.UserTransaction
+
+ A JNDI name used by
+ JTATransactionFactory to obtain the JTA
+ UserTransaction from the application server.
+ e.g.
+ jndi/composite/name
+
+
+
+ hibernate.transaction.manager_lookup_class
+
+ The classname of a
+ TransactionManagerLookup. It is required wh=
en
+ JVM-level caching is enabled or when using hilo generator in a=
JTA
+ environment. e.g.
+ classname.of.TransactionManagerLookup
+
+
+
+
+ hibernate.transaction.flush_before_completion<=
/literal>
+
+ If enabled, the session will be automatically flushed
+ during the before completion phase of the transaction. Built-in
+ and automatic session context management is preferred, see . e.g. true |
+ false
+
+
+
+ hibernate.transaction.auto_close_session
+
+ If enabled, the session will be automatically closed du=
ring
+ the after completion phase of the transaction. Built-in and
+ automatic session context management is preferred, see . e.g. true |
+ false
+
+
+
+
+
+
+ Miscellaneous Properties
+
+
+
+
+
+
+
+
+ Property name
+
+ Purpose
+
+
+
+
+
+ hibernate.current_session_context_class
+
+ Supply a custom strategy for the scoping of the "curren=
t"
+ Session. See for more informati=
on
+ about the built-in strategies. e.g. jta |
+ thread | managed |
+ custom.Class
+
+
+
+ hibernate.query.factory_class
+
+ Chooses the HQL parser implementation. e.g.
+ org.hibernate.hql.ast.ASTQueryTranslatorFactory
+ or
+ org.hibernate.hql.classic.ClassicQueryTranslatorFacto=
ry
+
+
+
+
+ hibernate.query.substitutions
+
+ Is used to map from tokens in Hibernate queries to SQL
+ tokens (tokens might be function or literal names, for example=
).
+ e.g.
+ hqlLiteral=3DSQL_LITERAL, hqlFunction=3DSQLFUNC
+
+
+
+
+ hibernate.hbm2ddl.auto
+
+ Automatically validates or exports 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. e.g.
+ validate | update |
+ create | create-drop
+
+
+
+
+ hibernate.hbm2ddl.import_file
+
+ 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.cglib.use_reflection_optimizer
+
+ Enables the use of CGLIB instead of runtime reflection
+ (System-level property). Reflection can sometimes be useful wh=
en
+ troubleshooting. Hibernate always requires CGLIB even if you t=
urn
+ off the optimizer. You cannot set this property in
+ hibernate.cfg.xml. e.g. true |
+ false
+
+
+
+
+
+
+ SQL Dialects
+
+ 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 sens=
ible
+ defaults for some of the other properties listed above. This means t=
hat
+ you will not have to specify them manually.
+
+
+ Hibernate SQL Dialects
+ (<literal>hibernate.dialect</literal>)
+
+
+
+
+
-
- hibernate.connection.driver_class
-
-
- JDBC driver class
-
+ RDBMS
+
+ Dialect
+
+
+
-
- hibernate.connection.url
-
-
- JDBC URL
-
+ DB2
+
+ org.hibernate.dialect.DB2Dialect
+
-
- hibernate.connection.username
-
-
- database user
-
+ DB2 AS/400
+
+ org.hibernate.dialect.DB2400Dialect
+
-
- hibernate.connection.password
-
-
- database user password
-
+ DB2 OS390
+
+ org.hibernate.dialect.DB2390Dialect
+
-
- hibernate.connection.pool_size
-
-
- maximum number of pooled connections
-
+ PostgreSQL
+
+ org.hibernate.dialect.PostgreSQLDialect
-
-
-
=
-
- Hibernate's own connection pooling algorithm is, however, quit=
e rudimentary. =
- It is intended to help you get started and is not in=
tended for use =
- in a production system, or even for performance tes=
ting. You should
- use a third party pool for best performance and stability. Jus=
t replace the =
- hibernate.connection.pool_size property w=
ith connection
- pool specific settings. This will turn off Hibernate's interna=
l pool. For
- example, you might like to use c3p0.
-
+
+ MySQL
=
-
- C3P0 is an open source JDBC connection pool distributed along =
with Hibernate in the lib
- directory. Hibernate will use its org.hibernate.con=
nection.C3P0ConnectionProvider
- for connection pooling if you set hibernate.c3p0.* properties. If you would like to use Proxool,
- refer to the packaged hibernate.properties and the Hibernate web site for more
- information.
-
+ org.hibernate.dialect.MySQLDialect=
+
=
-
- The following is an example hibernate.properties file for c3p0:
-
+
+ MySQL with InnoDB
=
- =
-
+ org.hibernate.dialect.MySQLInnoDBDialect
+
=
-
- For use inside an application server, you should almost always=
configure Hibernate to obtain connections
- from an application server javax.sql.Datasource=
registered in JNDI. You will
- need to set at least one of the following properties:
-
-
-
- Hibernate Datasource Properties
-
-
-
-
-
- Property name
- Purpose
-
-
-
-
- hibernate.connection.datasource
-
-
- datasource JNDI name
-
+ MySQL with MyISAM
+
+ org.hibernate.dialect.MySQLMyISAMDialect
+
-
- hibernate.jndi.url
-
-
- URL of the JNDI provider (optiona=
l)
-
+ Oracle (any version)
+
+ org.hibernate.dialect.OracleDialect
+
-
- hibernate.jndi.class
-
-
- class of the JNDI InitialContextFac=
tory (optional)
-
+ Oracle 9i
+
+ org.hibernate.dialect.Oracle9iDialect
+
-
- hibernate.connection.username
-
-
- database user (optional)
-
+ Oracle 10g
+
+ org.hibernate.dialect.Oracle10gDialect
+
-
- hibernate.connection.password
-
-
- database user password (optional)
-
+ Sybase
+
+ org.hibernate.dialect.SybaseDialect
-
-
-
=
-
- Here is an example hibernate.properties f=
ile for an application server provided JNDI
- datasource:
-
+
+ Sybase Anywhere
=
-
+ org.hibernate.dialect.SybaseAnywhereDialect<=
/literal>
+
=
-
- JDBC connections obtained from a JNDI datasource will automati=
cally participate
- in the container-managed transactions of the application serve=
r.
-
+
+ Microsoft SQL Server
=
-
- Arbitrary connection properties can be given by prepending "hibernate.connection" to the
- connection property name. For example, you can specify a charSet
- connection property using hibernate.connection.charS=
et.
-
+ org.hibernate.dialect.SQLServerDialect
+
=
-
- You can define your own plugin strategy for obtaining JDBC con=
nections by implementing the
- interface org.hibernate.connection.ConnectionPr=
ovider, and specifying your
- custom implementation via the hibernate.connection.p=
rovider_class property.
-
+
+ SAP DB
=
-
+ org.hibernate.dialect.SAPDBDialect=
+
=
-
- Optional configuration properties
- =
-
- There are a number of other properties that control the behavi=
or of Hibernate at runtime. All are optional
- and have reasonable default values.
-
+
+ Informix
=
-
- Some of these properties are "system-lev=
el" only. System-level properties can
- be set only via java -Dproperty=3Dvalue or =
hibernate.properties. They
- cannot be set by the other techniques des=
cribed above.
-
+ org.hibernate.dialect.InformixDialect
+
=
-
- Hibernate Configuration Properties
-
-
-
-
-
- Property name
- Purpose
-
-
-
-
-
- hibernate.dialect
-
-
- The classname of a Hibernate org.hi=
bernate.dialect.Dialect which
- allows Hibernate to generate SQL optimized for=
a particular relational database.
-
- e.g. =
- full.classname.of.Dialect
-
-
- In most cases Hibernate will actually be a=
ble to choose the correct
- org.hibernate.dialect.Dialect implementation based on the
- JDBC metadata returned =
by the JDBC driver.
-
-
-
-
-
- hibernate.show_sql
-
-
- Write all SQL statements to console. This is a=
n alternative
- to setting the log category org.hiber=
nate.SQL
- to debug.
-
- e.g. =
- true | false
-
-
-
-
-
- hibernate.format_sql
-
-
- Pretty print the SQL in the log and console.
-
- e.g. =
- true | false
-
-
-
-
-
- hibernate.default_schema
-
-
- Qualify unqualified table names with the given=
schema/tablespace
- in generated SQL.
-
- e.g. =
- SCHEMA_NAME
-
-
-
-
-
- hibernate.default_catalog
-
-
- Qualifies unqualified table names with the giv=
en catalog
- in generated SQL.
-
- e.g. =
- CATALOG_NAME
-
-
-
-
-
- hibernate.session_factory_name
-
-
- The org.hibernate.SessionFactor=
y will be automatically
- bound to this name in JNDI after it has been c=
reated.
-
- e.g. =
- jndi/composite/name
-
-
-
-
-
- hibernate.max_fetch_depth
-
-
- Sets a maximum "depth" for the outer join fetc=
h tree
- for single-ended associations (one-to-one, man=
y-to-one).
- A 0 disables default outer =
join fetching.
-
- e.g. =
- recommended values between 0 and =
- 3
-
-
-
-
-
- hibernate.default_batch_fetch_size
-
-
- Sets a default size for Hibernate batch fetchi=
ng of associations.
-
- e.g. =
- recommended values 4, <=
literal>8, =
- 16
-
-
-
-
-
- hibernate.default_entity_mode
-
-
- Sets a default mode for entity representation =
for all sessions
- opened from this SessionFactory
-
- dynamic-map, d=
om4j,
- pojo
-
-
-
-
-
- hibernate.order_updates
-
-
- Forces Hibernate to order SQL updates by the p=
rimary key value
- of the items being updated. This will result i=
n fewer transaction
- deadlocks in highly concurrent systems.
-
- e.g. =
- true | false
-
-
-
-
-
- hibernate.generate_statistics
-
-
- If enabled, Hibernate will collect statistics =
useful for
- performance tuning.
-
- e.g.
- true | false
-
-
-
-
-
- hibernate.use_identifier_rollback
-
-
- If enabled, generated identifier properties wi=
ll be
- reset to default values when objects are delet=
ed.
-
- e.g.
- true | false
-
-
-
-
-
- hibernate.use_sql_comments
-
-
- If turned on, Hibernate will generate comments=
inside the SQL, for
- easier debugging, defaults to false.
-
- e.g.
- true | false
-
-
-
-
-
-
+
+ HypersonicSQL
=
-
- Hibernate JDBC and Connection Properties
-
-
-
-
- Property name
- Purpose
-
-
-
-
-
- hibernate.jdbc.fetch_size
-
-
- A non-zero value determines the JDBC fetch siz=
e (calls
- Statement.setFetchSize()).
-
-
-
-
- hibernate.jdbc.batch_size
-
-
- A non-zero value enables use of JDBC2 batch up=
dates by Hibernate.
-
- e.g.
- recommended values between 5 and 30
-
-
-
-
-
- hibernate.jdbc.batch_versioned_data<=
/property>
-
-
- Set this property to true i=
f your JDBC driver returns
- correct row counts from executeBatch(=
). Iit is usually
- safe to turn this option on. Hibernate will th=
en use batched DML for
- automatically versioned data. Defaults to false.
-
- e.g.
- true | false
-
-
-
-
-
- hibernate.jdbc.factory_class
-
-
- Select a custom org.hibernate.j=
dbc.Batcher. Most applications
- will not need this configuration property.
-
- e.g.
- classname.of.BatcherFactory
-
-
-
-
-
- hibernate.jdbc.use_scrollable_result=
set
-
-
- Enables use of JDBC2 scrollable resultsets by =
Hibernate.
- This property is only necessary when using use=
r-supplied
- JDBC connections. Hibernate uses connection me=
tadata otherwise.
-
- e.g. =
- true | false
-
-
-
-
-
- hibernate.jdbc.use_streams_for_binar=
y
-
-
- Use streams when writing/reading bina=
ry or serializable
- types to/from JDBC. *system-level pr=
operty*
-
- e.g.
- true | false
-
-
-
-
-
- hibernate.jdbc.use_get_generated_key=
s
-
-
- Enables use of JDBC3 PreparedStatemen=
t.getGeneratedKeys()
- to retrieve natively generated keys after inse=
rt. Requires JDBC3+ driver
- and JRE1.4+, set to false if your driver has p=
roblems with the Hibernate
- identifier generators. By default, it tries to=
determine the driver capabilities
- using connection metadata.
-
- e.g.
- true|false
-
-
-
-
-
- hibernate.connection.provider_class<=
/property>
-
-
- The classname of a custom org.h=
ibernate.connection.ConnectionProvider
- which provides JDBC connections to Hibernate.
-
- e.g. =
- classname.of.ConnectionProvider
-
-
-
-
-
- hibernate.connection.isolation
-
-
- Sets the JDBC transaction isolation level. Check <=
interfacename>java.sql.Connection
- for meaningful values, but note that most database=
s do not support all isolation levels and some
- define additional, non-standard isolations.
-
- e.g. =
- 1, 2, 4, 8
-
-
-
-
-
- hibernate.connection.autocommit
-
-
- Enables autocommit for JDBC pooled connections=
(it is not recommended).
-
- e.g.
- true | false
-
-
-
-
-
- hibernate.connection.release_mode
-
-
- Specifies when Hibernate should release JDBC c=
onnections. By default, =
- a JDBC connection is held until the session is=
explicitly closed or
- disconnected. For an application server JTA da=
tasource, use
- after_statement to aggressi=
vely release connections
- after every JDBC call. For a non-JTA connectio=
n, it often makes sense to
- release the connection at the end of each tran=
saction, by using
- after_transaction. auto will
- choose after_statement for =
the JTA and CMT transaction
- strategies and after_transaction for the JDBC =
- transaction strategy.
-
- e.g. =
- auto (default) | on_close |
- after_transaction | after_statement
-
-
- This setting only affects Session=
s returned from
- SessionFactory.openSession. For Sessions
- obtained through SessionFactory.g=
etCurrentSession, the
- CurrentSessionContext i=
mplementation configured for use
- controls the connection release mode for t=
hose Sessions.
- See
-
-
-
-
-
- hibernate.connection.<propertyName>
-
-
- Pass the JDBC property <propertyN=
ame>
- to DriverManager.getConnection().
-
-
-
-
- hibernate.jndi.=
<propertyName>
-
-
- Pass the property <propertyName&g=
t; to
- the JNDI InitialContextFactory.
-
-
-
-
-
+ org.hibernate.dialect.HSQLDialect<=
/entry>
+
=
-
- Hibernate Cache Properties
-
-
-
-
-
- Property name
- Purpose
-
-
-
-
-
- hibernate.cache.provider_class
-
-
- The classname of a custom CacheProvid=
er.
-
- e.g. =
- classname.of.CacheProvider
-
-
-
-
-
- hibernate.cache.use_minimal_puts
-
-
- Optimizes second-level cache operation to mini=
mize writes, at the
- cost of more frequent reads. This setting is m=
ost useful for =
- clustered caches and, in Hibernate3, is enable=
d by default for
- clustered cache implementations.
-
- e.g. =
- true|false
-
-
-
-
-
- hibernate.cache.use_query_cache
-
-
- Enables the query cache. Individual queries st=
ill have to be set cachable.
-
- e.g. =
- true|false
-
-
-
-
-
- hibernate.cache.use_second_level_cach=
e
-
-
- Can be used to completely disable the second l=
evel cache, which is enabled
- by default for classes which specify a <cache>
- mapping.
-
- e.g. =
- true|false
-
-
-
-
-
- hibernate.cache.query_cache_factory
-
-
- The classname of a custom QueryCache<=
/literal> interface,
- defaults to the built-in StandardQuer=
yCache.
-
- e.g.
- classname.of.QueryCache
-
-
-
-
-
- hibernate.cache.region_prefix
-
-
- A prefix to use for second-level cache region =
names.
-
- e.g. =
- prefix
-
-
-
-
-
- hibernate.cache.use_structured_entrie=
s
-
-
- Forces Hibernate to store data in the second-l=
evel cache
- in a more human-friendly format.
-
- e.g.
- true|false
-
-
-
-
-
-
+
+ Ingres
=
-
- Hibernate Transaction Properties
-
-
-
-
-
- Property name
- Purpose
-
-
-
-
-
- hibernate.transaction.factory_class
-
-
- The classname of a TransactionFactory=
- to use with Hibernate Transaction API
- (defaults to JDBCTransactionFactory).
-
- e.g. =
- classname.of.TransactionFactory
-
-
-
-
-
- jta.UserTransaction
-
-
- A JNDI name used by JTATransactionFac=
tory to
- obtain the JTA UserTransaction from the
- application server.
-
- e.g. =
- jndi/composite/name
-
-
-
-
-
- hibernate.transaction.manager_lookup_=
class
-
-
- The classname of a TransactionManager=
Lookup. It is
- required when JVM-level caching is enabled or =
when using hilo =
- generator in a JTA environment.
-
- e.g. =
- classname.of.TransactionManagerLo=
okup
-
-
-
-
-
- hibernate.transaction.flush_before_co=
mpletion
-
-
- If enabled, the session will be automatically =
flushed during the
- before completion phase of the transaction. Bu=
ilt-in and
- automatic session context management is prefer=
red, see
- .
-
- e.g. =
- true | false
-
-
-
-
-
- hibernate.transaction.auto_close_sess=
ion
-
-
- If enabled, the session will be automatically =
closed during the
- after completion phase of the transaction. Bui=
lt-in and
- automatic session context management is prefer=
red, see
- .
-
- e.g. =
- true | false
-
-
-
-
-
-
+ org.hibernate.dialect.IngresDialect
+
=
-
- Miscellaneous Properties
-
-
-
-
-
- Property name
- Purpose
-
-
-
-
-
- hibernate.current_session_context_cla=
ss
-
-
- Supply a custom strategy for the scoping of th=
e "current"
- Session. See
- for more
- information about the built-in strategies.
-
- e.g.
- jta | thread |
- managed | cust=
om.Class
-
-
-
-
-
- hibernate.query.factory_class
-
-
- Chooses the HQL parser implementation.
-
- e.g. =
- org.hibernate.hql.ast.ASTQueryTra=
nslatorFactory or
- org.hibernate.hql.classic.Classic=
QueryTranslatorFactory
-
-
-
-
-
- hibernate.query.substitutions
-
-
- Is used to map from tokens in Hibernate querie=
s to SQL tokens
- (tokens might be function or literal names, fo=
r example).
-
- e.g. =
- hqlLiteral=3DSQL_LITERAL, hqlFunc=
tion=3DSQLFUNC
-
-
-
-
-
- hibernate.hbm2ddl.auto
-
-
- Automatically validates or exports schema DDL =
to the database =
- when the SessionFactory is =
created. With
- create-drop, the database s=
chema will be =
- dropped when the SessionFactory is closed =
- explicitly.
-
- e.g. =
- validate | upd=
ate | =
- create | creat=
e-drop
-
-
-
-
-
- hibernate.cglib.use_reflection_optimi=
zer
-
-
- Enables the use of CGLIB instead of runtime re=
flection (System-level
- property). Reflection can sometimes be useful =
when troubleshooting.
- Hibernate always requires CGLIB even if you tu=
rn off the
- optimizer. You cannot set this property in hibernate.cfg.xml.
-
- e.g. =
- true | false
-
-
-
-
-
-
+
+ Progress
=
-
- SQL Dialects
+ org.hibernate.dialect.ProgressDialect
+
=
-
- Always set the hibernate.dialect proper=
ty to the correct
- org.hibernate.dialect.Dialect subclass =
for your database. If you
- specify a dialect, Hibernate will use sensible defaults fo=
r some of the
- other properties listed above. This means that you will no=
t have to specify them manually.
-
+
+ Mckoi SQL
=
-
- Hibernate SQL Dialects (<literal>hibernate.dialect<=
/literal>)
-
-
-
-
- RDBMS
- Dialect
-
-
-
-
- DB2 org.hiberna=
te.dialect.DB2Dialect
-
-
- DB2 AS/400 org.=
hibernate.dialect.DB2400Dialect
-
-
- DB2 OS390 org.h=
ibernate.dialect.DB2390Dialect
-
-
- PostgreSQL org.=
hibernate.dialect.PostgreSQLDialect
-
-
- MySQL org.hiber=
nate.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 org.h=
ibernate.dialect.Oracle9iDialect
-
-
- Oracle 10g org.=
hibernate.dialect.Oracle10gDialect
-
-
- Sybase org.hibe=
rnate.dialect.SybaseDialect
-
-
- Sybase Anywhere org.hibernate.dialect.SybaseAnywhereDialect
-
-
- Microsoft SQL Server org.hibernate.dialect.SQLServerDialect
-
-
- SAP DB org.hibe=
rnate.dialect.SAPDBDialect
-
-
- Informix org.hi=
bernate.dialect.InformixDialect
-
-
- HypersonicSQL o=
rg.hibernate.dialect.HSQLDialect
-
-
- Ingres org.hibe=
rnate.dialect.IngresDialect
-
-
- Progress org.hi=
bernate.dialect.ProgressDialect
-
-
- Mckoi SQL org.h=
ibernate.dialect.MckoiDialect
-
-
- Interbase org.h=
ibernate.dialect.InterbaseDialect
-
-
- Pointbase org.h=
ibernate.dialect.PointbaseDialect
-
-
- FrontBase org.h=
ibernate.dialect.FrontbaseDialect
-
-
- Firebird org.hi=
bernate.dialect.FirebirdDialect
-
-
-
-
+ org.hibernate.dialect.MckoiDialect=
+
=
-
+
+ Interbase
=
-
- Outer Join Fetching
+ org.hibernate.dialect.InterbaseDialect
+
=
-
- If your database supports ANSI, Oracle or Sybase style out=
er joins, outer join
- fetching will often increase performance by lim=
iting the number of round
- trips to and from the database. This is, however, at the c=
ost of possibly more work performed by
- the database itself. Outer join fetching allows a whole gr=
aph of objects connected
- by many-to-one, one-to-many, many-to-many and one-to-one a=
ssociations to be retrieved =
- in a single SQL SELECT.
-
+
+ Pointbase
=
-
- Outer join fetching can 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 that have been map=
ped with =
- fetch=3D"join".
-
+ org.hibernate.dialect.PointbaseDialect
+
=
-
- See for more info=
rmation.
-
+
+ FrontBase
=
-
+ org.hibernate.dialect.FrontbaseDialect
+
=
-
- Binary Streams
+
+ Firebird
=
-
- Oracle limits the size of byte arrays t=
hat can
- be passed to and/or from its JDBC driver. If you wish to u=
se large instances of
- binary or serializable type, you should
- enable hibernate.jdbc.use_streams_for_binary.
- This is a system-level setting only.
-
+ org.hibernate.dialect.FirebirdDialect
+
+
+
+
+
=
-
+
+ Outer Join Fetching
=
-
- Second-level and query cache
+ 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. This is, however, at the cost of possibly more work perfor=
med
+ 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.
=
-
- 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 information.
-
+ Outer join fetching can 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 associati=
ons
+ that have been mapped with fetch=3D"join".
=
-
+ See for more
+ information.
+
=
-
- Query Language Substitution
+
+ Binary Streams
=
-
- You can define new Hibernate query tokens using h=
ibernate.query.substitutions.
- For example:
-
+ Oracle limits the size of byte arrays that =
can
+ be passed to and/or 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.
+
=
- hibernate.query.substitutions true=3D1, false=
=3D0
+
+ Second-level and query cache
=
-
- This would cause the tokens true and false to be translated to
- integer literals in the generated SQL.
-
+ The properties prefixed by hibernate.cache
+ allow you to use a process or cluster scoped second-level cache syst=
em
+ with Hibernate. See the for m=
ore
+ information.
+
=
- hibernate.query.substitutions toLowercase=3DLO=
WER
+
+ Query Language Substitution
=
-
- This would allow you to rename the SQL LOWER function.
-
+ You can define new Hibernate query tokens using
+ hibernate.query.substitutions. For example:
=
-
+ hibernate.query.substitutions true=3D1, false=3D0
=
-
- Hibernate statistics
+ This would cause the tokens true and
+ false to be translated to integer literals in the
+ generated SQL.
=
-
- If you enable hibernate.generate_statistics, Hibernate =
- exposes a number of metrics that are useful when tuning a =
running system via
- SessionFactory.getStatistics(). Hiberna=
te can even be configured
- to expose these statistics via JMX. Read the Javadoc of th=
e interfaces in
- org.hibernate.stats for more informatio=
n.
-
+ hibernate.query.substitutions toLowercase=3DLOWER
=
-
+ This would allow you to rename the SQL LOWER
+ function.
=
-
- Logging
+
+ Hibernate statistics
=
-
- Hibernate utilizes Simple=
Logging Facade for Java
- (SLF4J) in order to log various system events. SLF4J can direc=
t your logging output to
- several logging frameworks (NOP, Simple, log4j version 1.2, JD=
K 1.4 logging, JCL or logback) depending on your
- chosen binding. In order to setup logging you will need slf4j-api.jar in
- your classpath together with the jar file for your preferred b=
inding - slf4j-log4j12.jar =
- in the case of Log4J. See the SLF4J documentation for more detail.
- To use Log4j you will also need to place a log4j.pro=
perties file in your classpath.
- An example properties file is distributed with Hibernate in th=
e src/ directory.
-
- =
-
- It is recommended 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 e=
ssential
- troubleshooting device. The most interesting log categories ar=
e 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 enti=
ties) associated
- with the session at flush time
-
-
-
- org.hibernate.cache<=
/entry>
- 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.AST
-
- Log HQL and SQL ASTs during query parsing
-
-
-
- org.hibernate.secure=
- Log all JAAS authorization requests
-
-
- org.hibernate
-
- Log everything. This is a lot of informati=
on but it is 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.
-
- =
- =
+ If you enable hibernate.generate_statistics,
+ Hibernate exposes 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.
+
=
-
- Implementing a <literal>NamingStrategy</literal>
+
+ Logging
=
-
- The interface org.hibernate.cfg.NamingStrategy allows you
- to specify a "naming standard" for database objects and schema=
elements.
-
+ Hibernate utilizes Simple L=
ogging
+ Facade for Java (SLF4J) in order to log various system events.
+ SLF4J can direct your logging output to several logging frameworks (NO=
P,
+ Simple, log4j version 1.2, JDK 1.4 logging, JCL or logback) depending =
on
+ your chosen binding. In order to setup logging you will need
+ slf4j-api.jar in your classpath together with the=
jar
+ file for your preferred binding - slf4j-log4j12.jar
+ in the case of Log4J. See the SLF4J documentation for more
+ detail. To use Log4j you will also need to place a
+ log4j.properties file in your classpath. An examp=
le
+ properties file is distributed with Hibernate in the
+ src/ directory.
=
-
- You can provide rules for automatically generating database id=
entifiers 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 repe=
titive noise
- (TBL_ prefixes, for example). The default s=
trategy used by
- Hibernate is quite minimal.
-
+ It is recommended 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:
=
-
- You can specify a different strategy by calling
- Configuration.setNamingStrategy() before ad=
ding mappings:
-
+
+ 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) associa=
ted
+ 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.AST
+
+ Log HQL and SQL ASTs during query parsing
+
+
+
+ org.hibernate.secure
+
+ Log all JAAS authorization requests
+
+
+
+ org.hibernate
+
+ Log everything. This is a lot of information but it is
+ 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 <literal>NamingStrategy</literal>
+
+ The interface org.hibernate.cfg.NamingStrategy
+ allows you to specify a "naming standard" for database objects and sch=
ema
+ elements.
+
+ You can provide rules for automatically generating database
+ identifiers from Java identifiers or for processing "logical" column a=
nd
+ 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 can specify a different strategy by calling
+ Configuration.setNamingStrategy() before adding
+ mappings:
+
+ SessionFactory sf =3D new Configuration()
.setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
.addFile("Item.hbm.xml")
.addFile("Bid.hbm.xml")
- .buildSessionFactory();]]>
- =
-
- org.hibernate.cfg.ImprovedNamingStrategy is=
a built-in
- strategy that might be a useful starting point for some applic=
ations.
-
+ .buildSessionFactory();
=
-
+ org.hibernate.cfg.ImprovedNamingStrategy is a
+ built-in strategy that might be a useful starting point for some
+ applications.
+
=
-
- XML configuration file
+
+ XML configuration file
=
-
- An alternative approach to configuration is to specify a full =
configuration in
- a file named hibernate.cfg.xml. This file c=
an be used as a
- replacement for the hibernate.properties fi=
le or, if both
- are present, to override properties.
-
+ An alternative approach to configuration is to specify a full
+ configuration in a file named hibernate.cfg.xml. Th=
is
+ 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 of
- your CLASSPATH. Here is an example:
-
+ The XML configuration file is by default expected to be in the r=
oot
+ of your CLASSPATH. Here is an example:
=
-
-<?xml version=3D'1.0' encoding=3D'utf-=
8'?>
+<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD//EN"
- "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
+ "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
=
-
+<hibernate-configuration>
=
-
-
+ <!-- a SessionFactory instance listed as /jndi/name -->
+ <session-factory
+ name=3D"java:hibernate/SessionFactory">
=
-
- java:/comp/env/jdbc/MyDB<=
/property>
- org.hibernate.dialect.MySQLDialect
- false
-
+ <!-- properties -->
+ <property name=3D"connection.datasource">java:/comp/env/jdbc=
/MyDB</property>
+ <property name=3D"dialect">org.hibernate.dialect.MySQLDialec=
t</property>
+ <property name=3D"show_sql">false</property>
+ <property name=3D"transaction.factory_class">
org.hibernate.transaction.JTATransactionFactory
-
- java:comp/UserTransaction
+ </property>
+ <property name=3D"jta.UserTransaction">java:comp/UserTransac=
tion</property>
=
-
-
-
+ <!-- mapping files -->
+ <mapping resource=3D"org/hibernate/auction/Item.hbm.xml"/>
+ <mapping resource=3D"org/hibernate/auction/Bid.hbm.xml"/>
=
-
-
-
-
+ <!-- cache settings -->
+ <class-cache class=3D"org.hibernate.auction.Item" usage=3D"read=
-write"/>
+ <class-cache class=3D"org.hibernate.auction.Bid" usage=3D"read-=
only"/>
+ <collection-cache collection=3D"org.hibernate.auction.Item.bids=
" usage=3D"read-write"/>
=
-
+ </session-factory>
=
-]]>
+</hibernate-configuration>
=
-
- The advantage of this approach is the externalization of the
- mapping file names to configuration. The hibernate.cf=
g.xml
- is also more convenient once you have to tune the Hibernate ca=
che. It is
- your choice to use either hibernate.properties or
- hibernate.cfg.xml. Both are equivalent, exc=
ept for the above
- mentioned benefits of using the XML syntax.
-
+ The advantage of this approach is the externalization of the map=
ping
+ file names to configuration. The hibernate.cfg.xml =
is
+ also more convenient once you have to tune the Hibernate cache. It 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 simpl=
e as:
-
+ With the XML configuration, starting Hibernate is then as simple
+ as:
=
-
+ SessionFactory sf =3D new Configuration(=
).configure().buildSessionFactory();
=
-
- You can select a different XML configuration file using:
-
+ You can select a different XML configuration file using:
=
- SessionFactory sf =3D new Configuration()
.configure("catdb.cfg.xml")
- .buildSessionFactory();]]>
+ .buildSessionFactory();
+
=
-
+
+ J2EE Application Server integration
=
-
- J2EE Application Server integration
+ Hibernate has the following integration points for J2EE
+ infrastructure:
=
-
- Hibernate has the following integration points for J2EE infras=
tructure:
-
+
+
+ Container-managed datasources: Hibernate
+ can use JDBC connections managed by the container and provided thr=
ough
+ JNDI. Usually, a JTA compatible TransactionManager
+ and a ResourceManager take care of transaction
+ management (CMT), especially distributed transaction handling acro=
ss
+ several datasources. You can also demarcate transaction boundaries
+ programmatically (BMT), or you might want to use the optional
+ Hibernate Transaction API for this to keep your
+ code portable.
+
+
=
-
-
-
- Container-managed datasources: Hibern=
ate can use
- JDBC connections managed by the container and provided thr=
ough JNDI. Usually,
- a JTA compatible TransactionManager and=
a
- ResourceManager take care of transactio=
n management (CMT),
- especially distributed transaction handling across several=
datasources. You can
- also demarcate transaction boundaries programmatically (BM=
T), or
- you might want to use the optional Hibernate Tran=
saction
- API for this to keep your code portable.
-
-
-
+
+
+ Automatic JNDI binding: Hibernate can b=
ind
+ its SessionFactory to JNDI after startup.
+
+
=
-
-
-
- Automatic JNDI binding: Hibernate can=
bind its
- SessionFactory to JNDI after startup.
-
-
-
+
+
+ JTA Session binding: the Hibernate
+ Session can be automatically bound to the scope=
of
+ JTA transactions. Simply lookup the SessionFactory
+ from JNDI and get the current Session. Let
+ Hibernate manage flushing and closing the Session
+ when your JTA transaction completes. Transaction demarcation is ei=
ther
+ declarative (CMT) or programmatic (BMT/UserTransaction).
+
+
=
-
-
-
- JTA Session binding: the Hibernate Session
- can be automatically bound to the scope of JTA transaction=
s. Simply
- lookup the SessionFactory from JNDI and=
get the current
- Session. Let Hibernate manage flushing =
and closing the
- Session when your JTA transaction compl=
etes. Transaction
- demarcation is either declarative (CMT) or programmatic (B=
MT/UserTransaction).
-
-
-
+
+
+ JMX deployment: if you have a JMX capab=
le
+ application server (e.g. JBoss AS), you can choose to deploy Hiber=
nate
+ as a managed MBean. This saves you the one line startup code to bu=
ild
+ your SessionFactory from a
+ Configuration. The container will startup your
+ HibernateService and also take care of service
+ dependencies (datasource has to be available before Hibernate star=
ts,
+ etc).
+
+
=
-
-
-
- JMX deployment: if you have a JMX cap=
able application server
- (e.g. JBoss AS), you can choose to deploy Hibernate as a m=
anaged MBean. This saves
- you the one line startup code to build your Sessi=
onFactory from
- a Configuration. The container will sta=
rtup your
- HibernateService and also take care of =
service
- dependencies (datasource has to be available before Hibern=
ate starts, etc).
-
-
-
+ Depending on your environment, you might have to set the
+ configuration option
+ hibernate.connection.aggressive_release to true if =
your
+ application server shows "connection containment" exceptions.
=
-
- Depending on your environment, you might have to set the confi=
guration option
- hibernate.connection.aggressive_release to =
true if your
- application server shows "connection containment" exceptions.
-
+
+ Transaction strategy configuration
=
-
- 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 can 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.
=
-
- The Hibernate Session API is independen=
t of any transaction
- demarcation system in your architecture. If you let Hibern=
ate use JDBC directly
- through a connection pool, you can begin and end your tran=
sactions 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 UserTransac=
tion 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 underl=
ying
+ system. You have to specify a factory class for
+ Transaction instances by setting the Hibernate
+ configuration property
+ hibernate.transaction.factory_class.
=
-
- To keep your code portable between these two (and other) e=
nvironments we recommend the optional
- Hibernate Transaction API, which wraps =
and hides the underlying system.
- You have to specify a factory class for Transacti=
on instances by setting the
- Hibernate configuration property hibernate.transa=
ction.factory_class.
-
+ There are three standard, or built-in, choices:
=
-
- There are three standard, or built-in, choices:
-
+
+
+ org.hibernate.transaction.JDBCTransactionFactory<=
/literal>
=
-
-
- org.hibernate.transaction.JDBCTransacti=
onFactory
-
- delegates to database (JDBC) transactions (d=
efault)
-
-
-
- org.hibernate.transaction.JTATransactio=
nFactory
-
-
- delegates to container-managed transactions if=
an existing transaction is
- underway in this context (for example, EJB ses=
sion bean method). Otherwise,
- a new transaction is started and bean-managed =
transactions are used.
-
-
-
-
- org.hibernate.transaction.CMTTransactio=
nFactory
-
- delegates to container-managed JTA transacti=
ons
-
-
-
+
+ delegates to database (JDBC) transactions (default)
+
+
=
-
- You can also define your own transaction strategies (for a=
CORBA transaction service,
- for example).
-
+
+ org.hibernate.transaction.JTATransactionFactory
=
-
- Some features in Hibernate (i.e., the second level cache, =
Contextual Sessions with JTA, etc.)
- require access to the JTA TransactionManager in a managed environment.
- In an application server, since J2EE does not standardize =
a single mechanism, you have to specify how Hibernate should obtain a refer=
ence to the
- TransactionManager:
-
+
+ delegates to container-managed transactions if an existi=
ng
+ transaction is underway in this context (for example, EJB sess=
ion
+ bean method). Otherwise, a new transaction is started and
+ bean-managed transactions are used.
+
+
=
-
- JTA TransactionManagers
-
-
-
-
-
- Transaction Factory
- Application Server
-
-
-
-
- org.hibernate.transaction.JBos=
sTransactionManagerLookup
- JBoss
-
-
- org.hibernate.transaction.Webl=
ogicTransactionManagerLookup
- Weblogic
-
-
- org.hibernate.transaction.WebS=
phereTransactionManagerLookup
- WebSphere
-
-
- org.hibernate.transaction.WebS=
phereExtendedJTATransactionLookup
- WebSphere 6
-
-
- org.hibernate.transaction.Orio=
nTransactionManagerLookup
- Orion
-
-
- org.hibernate.transaction.Resi=
nTransactionManagerLookup
- Resin
-
-
- org.hibernate.transaction.JOTM=
TransactionManagerLookup
- JOTM
-
-
- org.hibernate.transaction.JOnA=
STransactionManagerLookup
- JOnAS
-
-
- org.hibernate.transaction.JRun=
4TransactionManagerLookup
- JRun4
-
-
- org.hibernate.transaction.BEST=
ransactionManagerLookup
- Borland ES
-
-
-
-
+
+ org.hibernate.transaction.CMTTransactionFactory
=
-
+
+ delegates to container-managed JTA transactions
+
+
+
=
-
- JNDI-bound <literal>SessionFactory</literal>
+ You can also define your own transaction strategies (for a COR=
BA
+ transaction service, for example).
=
-
- A JNDI-bound Hibernate SessionFactory c=
an simplify the lookup
- function of the factory and create new Sessions. This
- is not, however, related to a JNDI bound Datasour=
ce; both simply use the
- same registry.
-
+ Some features in Hibernate (i.e., the second level cache,
+ Contextual Sessions with JTA, etc.) require access to the JTA
+ TransactionManager in a managed environment. In an
+ application server, since J2EE does not standardize a single mechani=
sm,
+ you have to specify how Hibernate should obtain a reference to the
+ TransactionManager:
=
-
- If you wish to have the SessionFactory =
bound to a JNDI namespace, specify
- a name (e.g. java:hibernate/SessionFactory) using the property
- hibernate.session_factory_name. If this=
property is omitted, the
- SessionFactory will not be bound to JND=
I. This is especially useful in
- environments with a read-only JNDI default implementation =
(in Tomcat, for example).
-
+
+ JTA TransactionManagers
=
-
- 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 SessionFac=
tory in JNDI after
- you call cfg.buildSessionFactory(). Thi=
s means you will have
- this call in some startup code, or utility class in your a=
pplication, unless you use
- JMX deployment with the HibernateService (this is discussed later in greater detail).
-
+
=
-
- If you use a JNDI SessionFactory, an EJ=
B or any other class, you can
- obtain the SessionFactory using a JNDI =
lookup.
-
+
+
+ Transaction Factory
=
-
- It is recommended that you bind the SessionFactor=
y to JNDI in
- a managed environment and use a static =
singleton otherwise.
- To shield your application code from these details, we als=
o 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.
-
+ Application Server
+
+
=
-
+
+
+ org.hibernate.transaction.JBossTransactionMa=
nagerLookup
=
-
- Current Session context management with JTA
+ JBoss
+
=
-
- The easiest way to handle Sessions and =
transactions is
- Hibernate's automatic "current" Session=
management.
- For a discussion of contextual sessions see .
- Using the "jta" session context, if the=
re 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 complet=
es, close
- after the transaction completes, and aggressively release JDB=
C 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 cod=
e 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, decla=
rative transaction
- demarcation with CMT is preferred.
-
+
+ org.hibernate.transaction.WeblogicTransactio=
nManagerLookup
=
-
+ Weblogic
+
=
-
- JMX deployment
+
+ org.hibernate.transaction.WebSphereTransacti=
onManagerLookup
=
-
- The line cfg.buildSessionFactory() stil=
l has to be executed
- somewhere to get a SessionFactory into =
JNDI. You can do this
- either in a static initializer block, l=
ike the one in
- HibernateUtil, or you can deploy Hibern=
ate as a managed
- service.
-
+ WebSphere
+
=
-
- Hibernate is distributed with org.hibernate.jmx.H=
ibernateService
- for deployment on an application server with JMX capabilit=
ies, such as JBoss AS.
- The actual deployment and configuration is vendor-specific=
. Here is an example
- jboss-service.xml for JBoss 4.0.x:
-
+
+ org.hibernate.transaction.WebSphereExtendedJ=
TATransactionLookup
=
-
-
+ WebSphere 6
+
=
-
+
+ org.hibernate.transaction.OrionTransactionMa=
nagerLookup
=
-
- jboss.jca:service=3DRARDeployer
- jboss.jca:service=3DLocalTxCM,name=3DHsqlDS
+ Orion
+
=
-
- java:/hibernate/SessionFactory
+
+ org.hibernate.transaction.ResinTransactionMa=
nagerLookup
=
-
- java:HsqlDS
- org.hibernate.dialect.HSQLDialect
+ Resin
+
=
-
-
- org.hibernate.transaction.JTATransactionFactory
-
- org.hibernate.transaction.JBossTransactionManagerLookup
- true
- true
+
+ org.hibernate.transaction.JOTMTransactionMan=
agerLookup
=
-
- 5
+ JOTM
+
=
-
- true
- org.hibernate.cache.EhCacheProv=
ider
- true
+
+ org.hibernate.transaction.JOnASTransactionMa=
nagerLookup
=
-
- true
+ JOnAS
+
=
-
- auction/Item.hbm.xml,auction/Category=
.hbm.xml
+
+ org.hibernate.transaction.JRun4TransactionMa=
nagerLookup
=
-
+ JRun4
+
=
-]]>
+
+ org.hibernate.transaction.BESTransactionMana=
gerLookup
=
-
- 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 en=
terprise beans (usually session
- beans) can be kept in their own JAR file, but you can incl=
ude this EJB JAR file in the
- main service archive to get a single (hot-)deployable unit=
. Consult the JBoss AS
- documentation for more information about JMX service and E=
JB deployment.
-
+ Borland ES
+
+
+
+
+
=
-
+
+ JNDI-bound <literal>SessionFactory</literal>
=
+ A JNDI-bound Hibernate SessionFactory can
+ simplify the lookup function of the factory and create new
+ Sessions. This is not, however, related to a JNDI
+ bound Datasource; both simply use the same
+ registry.
+
+ If you wish to have the SessionFactory boun=
d to
+ a JNDI namespace, specify a name (e.g.
+ 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 (in Tomcat, for example).
+
+ 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 ha=
ve
+ this call in some startup code, or utility class in your application,
+ unless you use JMX deployment with the
+ HibernateService (this is discussed later in grea=
ter
+ detail).
+
+ If you use a JNDI SessionFactory, an EJB or=
any
+ other class, you can obtain the SessionFactory us=
ing
+ a JNDI lookup.
+
+ It is recommended that you bind the
+ SessionFactory to JNDI in a managed environment a=
nd
+ 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 help=
er
+ class, such as HibernateUtil.getSessionFactory().
+ Note that such a class is also a convenient way to startup Hibernate=
=E2=80=94see
+ chapter 1.
=
-
+
+ Current Session context management with JTA
=
+ The easiest way to handle Sessions and
+ transactions is Hibernate's automatic "current"
+ Session management. For a discussion of contextual
+ sessions see . Usin=
g the
+ "jta" session context, if there is no Hibernate
+ Session associated with the current JTA transacti=
on,
+ one will be started and associated with that JTA transaction the fir=
st
+ time you call sessionFactory.getCurrentSession().=
The
+ Sessions retrieved via
+ getCurrentSession() in the"jta"
+ context are set to automatically flush before the transaction comple=
tes,
+ 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 J=
TA
+ transaction to which it is associated, keeping user code clean of su=
ch
+ management concerns. Your code can either use JTA programmatically
+ through UserTransaction, or (recommended for port=
able
+ code) use the Hibernate Transaction API to set
+ transaction boundaries. If you run in an EJB container, declarative
+ transaction demarcation with CMT is preferred.
+
+
+
+ JMX deployment
+
+ The line cfg.buildSessionFactory() still ha=
s to
+ be executed somewhere to get a SessionFactory into
+ JNDI. You can do this either in a static initiali=
zer
+ block, like the one in HibernateUtil, or you can
+ 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:
+
+ <?xml version=3D"1.0"?>
+<server>
+
+<mbean code=3D"org.hibernate.jmx.HibernateService"
+ name=3D"jboss.jca:service=3DHibernateFactory,name=3DHibernateFactory"&=
gt;
+
+ <!-- Required services -->
+ <depends>jboss.jca:service=3DRARDeployer</depends>
+ <depends>jboss.jca:service=3DLocalTxCM,name=3DHsqlDS</depends=
>
+
+ <!-- Bind the Hibernate service to JNDI -->
+ <attribute name=3D"JndiName">java:/hibernate/SessionFactory</=
attribute>
+
+ <!-- Datasource settings -->
+ <attribute name=3D"Datasource">java:HsqlDS</attribute>
+ <attribute name=3D"Dialect">org.hibernate.dialect.HSQLDialect<=
;/attribute>
+
+ <!-- Transaction integration -->
+ <attribute name=3D"TransactionStrategy">
+ org.hibernate.transaction.JTATransactionFactory</attribute>
+ <attribute name=3D"TransactionManagerLookupStrategy">
+ org.hibernate.transaction.JBossTransactionManagerLookup</attrib=
ute>
+ <attribute name=3D"FlushBeforeCompletionEnabled">true</attrib=
ute>
+ <attribute name=3D"AutoCloseSessionEnabled">true</attribute&g=
t;
+
+ <!-- Fetching options -->
+ <attribute name=3D"MaximumFetchDepth">5</attribute>
+
+ <!-- Second-level caching -->
+ <attribute name=3D"SecondLevelCacheEnabled">true</attribute&g=
t;
+ <attribute name=3D"CacheProviderClass">org.hibernate.cache.EhCac=
heProvider</attribute>
+ <attribute name=3D"QueryCacheEnabled">true</attribute>
+
+ <!-- Logging -->
+ <attribute name=3D"ShowSqlEnabled">true</attribute>
+
+ <!-- Mapping files -->
+ <attribute name=3D"MapResources">auction/Item.hbm.xml,auction/Ca=
tegory.hbm.xml</attribute>
+
+</mbean>
+
+</server>
+
+ 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 archiv=
e.
+ Your enterprise beans (usually session beans) can be kept in their o=
wn
+ JAR file, but you can include this EJB JAR file in the main service
+ archive to get a single (hot-)deployable unit. Consult the JBoss AS
+ documentation for more information about JMX service and EJB
+ deployment.
+
+
+
--===============0313218219619428310==--