From bc5234ccfab10dfadbf26001ba443fa318887461 Mon Sep 17 00:00:00 2001 From: Christian Bauer Date: Tue, 19 Apr 2005 17:35:20 +0000 Subject: [PATCH] Rewrote J2EE integration section git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@6465 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- reference/en/modules/configuration.xml | 502 ++++++++++++++++--------- 1 file changed, 322 insertions(+), 180 deletions(-) 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. + + + + + +