diff --git a/reference/en/modules/configuration.xml b/reference/en/modules/configuration.xml
index f268c7f94a..1648e0da85 100644
--- a/reference/en/modules/configuration.xml
+++ b/reference/en/modules/configuration.xml
@@ -122,35 +122,6 @@
-
-
JDBC connections
@@ -1129,157 +1100,6 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]>
-
- Transaction strategy configuration
-
-
- If you wish to use the Hibernate Transaction API instead
- of directly calling a particular system transaction API, you must
- specify a factory class for Transaction instances by
- setting the property hibernate.transaction.factory_class.
- The Transaction API hides the underlying transaction
- mechanism and allows Hibernate code to run in managed and non-managed environments.
-
-
-
- There are three standard (built-in) choices:
-
-
-
-
- org.hibernate.transaction.JDBCTransactionFactory
-
- delegates to database (JDBC) transactions (default)
-
-
-
- org.hibernate.transaction.JTATransactionFactory
-
-
- delegates to JTA (if an existing transaction is underway, the
- Session performs its work in that context, otherwise
- a new transaction is started)
-
-
-
-
- org.hibernate.transaction.CMTTransactionFactory
-
- delegates to a container managed JTA transaction
-
-
-
-
-
- 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) require access to the
- JTA TransactionManager in a management environment. 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 <literal>SessionFactory</literal>
-
-
- 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 in a managed environment.
-
-
-
- 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, eg. 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.
-
-
-
- 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 1, which acts as a Singleton registry.
-
-
-
-
Query Language Substitution
@@ -1524,5 +1344,327 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]>
+
+ 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 <literal>SessionFactory</literal>
+
+
+ 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.
+
+
+
+
+
+