Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>Integrating BTM with Hibernate</h1>
<p>Hibernate can be integrated straight with any JTA transaction manager. These instructions have been verified against BTM 1.2 and Hibernate 3.2.6.</p>

<p>The biggest added value (omitting the fact that you can use Hibernate and two databases) is Hibernate's <a href="http://www.hibernate.org/hib_docs/reference/en/html/session-configuration.html#configuration-j2ee-currentsession">Current Session context management with JTA</a>. You do not have to take care about opening nor closing <code>Session</code> as Hibernate will automatically bind them to the JTA transaction's lifecycle. You just have to make sure JTA transactions are properly started and ended.</p>

<table class="wysiwyg-macro" data-macro-name="info" data-macro-parameters="title=JPA, Hibernate and BTM" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2luZm86dGl0bGU9SlBBLCBIaWJlcm5hdGUgYW5kIEJUTX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>The example discussed here uses the Hibernate API but the JPA API could be used as well. You just need to use the EntityManager but the same configuration applies.</p></td></tr></table>

<h4>Contents</h4>
<img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e3RvYzptYXhMZXZlbD0zfG1pbkxldmVsPTJ9&amp;locale=en_GB&amp;version=2" data-macro-name="toc" data-macro-parameters="maxLevel=3|minLevel=2">

<h2>JTA datasources</h2>
<p>Hibernate cannot directly create a BTM <code>PoolingDataSource</code>. You will have to create them yourself (either via the API or the Resource Loader) and make sure they are bound to a JNDI server.</p>

<h3>Setting up a JNDI server</h3>
<p>You have to bind the datasources to some JNDI server. You can use any one you wish, including the one embedded in your application server.</p>

<p>In the case you want to run Hibernate in a standalone application, you can use Tomcat's JNDI server as it is very easy to use it in a standalone J2SE application. Just create a <code>jndi.properties</code> file at the root of your classpath. It should only contain this line:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
java.naming.factory.initial=org.apache.naming.java.javaURLContextFactory
</pre></td></tr></table>

<p>Then add these two jar files to your classpath:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
naming-factory.jar
naming-resources.jar
</pre></td></tr></table>

<p>They are available in any Tomcat 5.5 distribution, just look into the <code>TOMCAT_HOME/common/lib</code> folder.</p>

<p>This will configure Tomcat's JNDI server as the default implementation. It is a simple intra-VM server that implements the most important JNDI features. You can now just create a <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/InitialContext.html">InitialContext</a> with the no-args constructor to have access to it.</p>

<h3>API way: Creating the datasources</h3>
<p>As you can expect, you will need to create one <code>PoolingDataSource</code> per database. Say that you want to use two Embedded Derby databases, and configure them via the BTM API. Here is what your code would look like:</p>

PoolingDataSource ds2 = new PoolingDataSource();
ds2.setUniqueName("jdbc/testDS2");
ds2.setClassName("org.apache.derby.jdbc.EmbeddedXADataSource");
ds2.setMaxPoolSize(3);
ds2.getDriverProperties().put("databaseName", "users2");
ds2.init();
</pre></td></tr></table>

<table class="wysiwyg-macro" data-macro-name="tip" data-macro-parameters="title=Datasource's unique name and JNDI location correspondence" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3RpcDp0aXRsZT1EYXRhc291cmNlJ3MgdW5pcXVlIG5hbWUgYW5kIEpOREkgbG9jYXRpb24gY29ycmVzcG9uZGVuY2V9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>It is usually a good idea to set a datasource's unique name to the same value as its JNDI location although this is not mandatory.</p></td></tr></table>

<p>Finally, here is the code to bind the datasources:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
Context ctx = new InitialContext();
ctx.createSubcontext("jdbc");
ctx.rebind("jdbc/testDS1", ds1);
ctx.rebind("jdbc/testDS2", ds2);
ctx.close();
</pre></td></tr></table>

<h3>Resource Loader way: Creating the datasources</h3>
<p>You can use BTM's Resource Loader instead of the BTM API. It is usually a good idea when you want to create a fully standalone application as you can get rid of the datasources creation, JNDI binding and shutdown code.</p>

<p>Create a <code>datasources.properties</code> file in the current directory containing these properties:</p>

resource.ds1.className=org.apache.derby.jdbc.EmbeddedXADataSource
resource.ds1.uniqueName=jdbc/testDS1
resource.ds1.maxPoolSize=3
resource.ds1.driverProperties.databaseName=users1

resource.ds2.className=org.apache.derby.jdbc.EmbeddedXADataSource
resource.ds2.uniqueName=jdbc/testDS2
resource.ds2.maxPoolSize=3
resource.ds2.driverProperties.databaseName=users2
</pre></td></tr></table>

<table class="wysiwyg-macro" data-macro-name="tip" data-macro-parameters="title=Resource Loader JNDI binding" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3RpcDp0aXRsZT1SZXNvdXJjZSBMb2FkZXIgSk5ESSBiaW5kaW5nfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>When you configure the Resource Loader to bind datasources to JNDI (by setting the <code>bitronix.tm.resource.bind</code> property to <code>true</code>) it will bind them using the unique name as the JNDI location.</p></td></tr></table>

<p>In your application code, you will have to configure BTM to use the resource loader:</p>

<p>This has the exact same behavior as creating the <code>PoolingDataSource</code> objects and binding them to JNDI yourself. It is just more convenient.</p>

<h2>Hibernate Session factories</h2>
<p>You need to configure exactly one <code>SessionFactory</code> per datasource.</p>

<h3>Datasource JNDI location</h3>
<p>You have to tell Hibernate where to get the BTM datasource via JNDI. Add a <a href="http://www.hibernate.org/hib_docs/reference/en/html/session-configuration.html#d0e1714">connection.datasource</a> property and set its value to the JNDI location of your datasource:</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;property name="connection.datasource">jdbc/testDS1&lt;/property>
</pre></td></tr></table>

<h3>Current session context</h3>
<p>You have to set <a href="http://www.hibernate.org/hib_docs/reference/en/html/session-configuration.html#configuration-misc-properties">current_session_context_class</a> to <code>jta</code>.</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;property name="current_session_context_class">jta&lt;/property>
</pre></td></tr></table>

<h3>Transaction factory class</h3>
<p>You have to set <a href="http://www.hibernate.org/hib_docs/reference/en/html/session-configuration.html#configuration-transaction-properties">transaction.factory_class</a> to <a href="http://www.hibernate.org/hib_docs/v3/api/org/hibernate/transaction/JTATransactionFactory.html">org.hibernate.transaction.JTATransactionFactory</a>.</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;property name="transaction.factory_class">org.hibernate.transaction.JTATransactionFactory&lt;/property>
</pre></td></tr></table>

<h3>Transaction manager lookup class</h3>
<p>You have to set <a href="http://www.hibernate.org/hib_docs/reference/en/html/session-configuration.html#configuration-transaction-properties">transaction.manager_lookup_class</a> to an implementation of <a href="http://www.hibernate.org/hib_docs/v3/api/org/hibernate/transaction/TransactionManagerLookup.html">TransactionManagerLookup</a> that you have to create yourself. Here is an example implementation if this interface:</p>

import java.util.Properties;
import javax.transaction.TransactionManager;
import org.hibernate.HibernateException;
import org.hibernate.transaction.TransactionManagerLookup;
import bitronix.tm.TransactionManagerServices;

public class BitronixTransactionManagerLookup implements TransactionManagerLookup {

public TransactionManager getTransactionManager(Properties props) throws HibernateException {
        return TransactionManagerServices.getTransactionManager();
    }

public String getUserTransactionName() {
        return "UserTransaction";
    }

}
</pre></td></tr></table>

<p>Then add this property:</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;property name="transaction.manager_lookup_class">bitronix.examples.hibernate.BitronixTransactionManagerLookup&lt;/property>
</pre></td></tr></table>

<h3>SessionFactory XML configuration files</h3>
<p>Here is what the <code>hibernate_testDS1.cfg.xml</code> file will look like for the first datasource. Some other mandatory properties also have to be added, like the <code>dialect</code>, <code>cache.provider_class</code> and of course the required object mappings.</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="XML" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6WE1MfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;?xml version='1.0' encoding='utf-8'?>
&lt;!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

&lt;hibernate-configuration>

&lt;session-factory>
        &lt;property name="connection.datasource">jdbc/testDS1&lt;/property>
        &lt;property name="current_session_context_class">jta&lt;/property>
        &lt;property name="transaction.factory_class">org.hibernate.transaction.JTATransactionFactory&lt;/property>
        &lt;property name="transaction.manager_lookup_class">bitronix.examples.hibernate.BitronixTransactionManagerLookup&lt;/property>

&lt;property name="dialect">org.hibernate.dialect.DerbyDialect&lt;/property>
        &lt;property name="cache.provider_class">org.hibernate.cache.NoCacheProvider&lt;/property>
        &lt;property name="show_sql">true&lt;/property>

&lt;mapping resource="bitronix/examples/hibernate/entities/User.hbm.xml"/>
    &lt;/session-factory>

&lt;/hibernate-configuration>
</pre></td></tr></table>

<p>And here is the <code>hibernate_testDS2.cfg.xml</code> for the second datasource:</p>

&lt;hibernate-configuration>

&lt;session-factory>
        &lt;property name="connection.datasource">jdbc/testDS2&lt;/property>
        &lt;property name="current_session_context_class">jta&lt;/property>
        &lt;property name="transaction.factory_class">org.hibernate.transaction.JTATransactionFactory&lt;/property>
        &lt;property name="transaction.manager_lookup_class">bitronix.examples.hibernate.BitronixTransactionManagerLookup&lt;/property>

&lt;mapping resource="bitronix/examples/hibernate/entities/User.hbm.xml"/>
    &lt;/session-factory>

&lt;/hibernate-configuration>
</pre></td></tr></table>

<h2>End result</h2>
<p>Now that Hibernate and BTM are properly configured, you can simply use the JTA and Hibernate APIs in your application.</p>

<h3>Application code</h3>
<p>Here is what your code will look like when you want to update the content of both databases atomically:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
for (int i=0; i&lt;10 ;i++) {
    System.out.println("Iteration #" + (i+1));
    userTransaction.setTransactionTimeout(60);
    userTransaction.begin();
    
    try {
        System.out.println("*** DB1 ***");
        persistUser(sf1, "user");
        listUsers(sf1);
    
        System.out.println("*** DB2 ***");
        persistUser(sf2, "user");
        listUsers(sf2);
    
        userTransaction.commit();
    }
    catch (Exception ex) {
        ex.printStackTrace();
        userTransaction.rollback();
    }
}
</pre></td></tr></table>

<p>Say that <code>persistUser()</code> creates a new user, in <em>no way</em> will a user be created in one database and not in the other.</p>

<h2>Download</h2>
<p>You can download a sample runnable application putting these explanations in practice. It contains all the code that has been skipped for clarity in this page. Both the API and Resource Loader ways are implemented so you can try both and see which one you prefer.</p>

<p>You can download this demo here: <a href="http://www.bitronix.be/examples/HibernateBTM12.zip">HibernateBTM12.zip</a>.</p>

<p>There is an ant <strong>build.xml</strong> file included as well as a the necessary batch and shell scripts required to run the application from Windows or Unix.</p>

<p>Before you run the application, you have to create the Derby database. Just run the included <strong>derby-create.sh</strong> or <strong>derby-create.bat</strong> script to do so, it will create two directories called <strong>users1</strong> and <strong>users2</strong>. Then you can start the demo by either running <strong>run_api.sh</strong> or <strong>run_api.bat</strong> for the API version, <strong>run_rl.sh</strong> or <strong>run_rl.bat</strong> for the Resource Loader version.</p>

<p>Here is the list of JAR files with version required to run this demo. They're all included in the downloadable ZIP file.</p>

<table class="confluenceTable"><tbody>
<tr>
<th class="confluenceTh"><p> JAR name </p></th>
<th class="confluenceTh"><p> Version </p></th>
</tr>
<tr>
<td class="confluenceTd"><p> btm-1.2.jar </p></td>
<td class="confluenceTd"><p> BTM 1.2 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> geronimo-spec-jta-1.0.1B-rc4.jar </p></td>
<td class="confluenceTd"><p> BTM 1.2 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> slf4j-api-1.4.3.jar </p></td>
<td class="confluenceTd"><p> SLF4J 1.4.3 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> slf4j-jdk14-1.4.3.jar </p></td>
<td class="confluenceTd"><p> SLF4J 1.4.3 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> derby-10.3.1.4.jar </p></td>
<td class="confluenceTd"><p> Derby 10.3.1.4 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> derbytools-10.3.1.4.jar </p></td>
<td class="confluenceTd"><p> Derby 10.3.1.4 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> antlr-2.7.6.jar </p></td>
<td class="confluenceTd"><p> Hibernate 3.2.6 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> asm.jar </p></td>
<td class="confluenceTd"><p> Hibernate 3.2.6 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> cglib-2.1.3.jar </p></td>
<td class="confluenceTd"><p> Hibernate 3.2.6 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> commons-collections-2.1.1.jar </p></td>
<td class="confluenceTd"><p> Hibernate 3.2.6 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> commons-logging-1.0.4.jar </p></td>
<td class="confluenceTd"><p> Hibernate 3.2.6 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> dom4j-1.6.1.jar </p></td>
<td class="confluenceTd"><p> Hibernate 3.2.6 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> hibernate3.jar </p></td>
<td class="confluenceTd"><p> Hibernate 3.2.6 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> naming-factory.jar </p></td>
<td class="confluenceTd"><p> Tomcat 5.5.23 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> naming-resources.jar </p></td>
<td class="confluenceTd"><p> Tomcat 5.5.23 </p></td>
</tr>
</tbody></table>