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>JMS pools configuration</h1>

<p>BTM XA connection factories can be created - like their JDBC counterparts - via some java code or via a BTM-specific tool called the Resource Loader. You are free to choose the method you prefer, there is absolutely no difference between them.</p>

<table class="wysiwyg-macro" data-macro-name="info" data-macro-parameters="title=Supported JMS versions" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2luZm86dGl0bGU9U3VwcG9ydGVkIEpNUyB2ZXJzaW9uc30&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>BTM only supports the JMS 1.1 API. Only servers supporting it can be used with BTM. There is currently no way to make BTM work with JMS 1.0.2 API.</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>Using the BTM API</h2>
<p>BTM comes bundled with a JMS XA connection pool which is very easy to configure. You basically have to create an instance of <a href="http://btm.codehaus.org/api/1.2/bitronix/tm/resource/jms/PoolingConnectionFactory.html">bitronix.tm.resource.jms.PoolingConnectionFactory</a> set some properties and you're done.</p>

<p>Here is an example of datasource creation that connects to an ActiveMQ JMS server:</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>
PoolingConnectionFactory myConnectionFactory = new PoolingConnectionFactory ();                   (1)
myConnectionFactory.setClassName("org.apache.activemq.ActiveMQXAConnectionFactory");              (2)
myConnectionFactory.setUniqueName("activemq");                                                    (3)
myConnectionFactory.setMinPoolSize(1);                                                            (4)
myConnectionFactory.setMaxPoolSize(5);                                                            (5)
myConnectionFactory.setAllowLocalTransactions(true);                                              (6)
myConnectionFactory.setUser("user");                                                              (7)
myConnectionFactory.setPassword("password");                                                      (8)
myConnectionFactory.getDriverProperties().setProperty("brokerURL", "tcp://localhost:61616");      (9)

Connection c = myConnectionFactory.createConnection();                                            (10)
 // create some session then send or receive some message
c.close();                                                                                        (11)

myConnectionFactory.close();                                                                      (12)
</pre></td></tr></table>

<p> <strong>1.</strong> The Bitronix <code>PoolingConnectionFactory</code> is a javabean that implements <code>javax.jms.ConnectionFactory</code>.<br />
 <strong>2.</strong> You have to specify the JMS server's <code>XAConnectionFactory</code> implementation here.<br />
 <strong>3.</strong> Each connection factory must be assigned a unique name. This is required for distributed crash recovery.<br />
 <strong>4.</strong> This connection factory can contain at least 1 connection. 0 is the default value when unspecified.<br />
 <strong>5.</strong> This connection factory can contain at most 5 connections.<br />
 <strong>6.</strong> You have to set <code>allowLocalTransactions</code> to true if you want to be able to send or receive messages outside of XA transactions scope.<br />
 <strong>7,8.</strong> When both are set, the pooled connections will be created using the provided user and password instead of without credentials. This works like if you called <code>ConnectionFactory.createConnection(user, password)</code> instead of <code>ConnectionFactory.createConnection()</code>.<br />
 <strong>9.</strong> The driverProperties is a <code>java.util.Properties</code> object. You have to add into it a set of property name / property value of the <code>ActiveMQXAConnectionFactory</code> class. You have to refer to the JMS server's documentation to know what can / has to be set. The <a href="http://activemq.apache.org/maven/activemq-core/apidocs/org/apache/activemq/ActiveMQXAConnectionFactory.html">ActiveMQXAConnectionFactory javadoc</a> contains this list for the ActiveMQ case. BTM will perform conversion from <code>String</code> to <code>boolean</code> or to <code>int</code> when necessary.<br />
 <strong>10,11.</strong> You can now use the <code>PoolingConnectionFactory</code> like any other <code>javax.jms.ConnectionFactory</code>.<br />
 <strong>12.</strong> Remember to close the <code>PoolingConnectionFactory</code> after you're done with it to release the connections.</p>

<table class="wysiwyg-macro" data-macro-name="tip" data-macro-parameters="title=No class implemeting XAConnectionFactory ?" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3RpcDp0aXRsZT1ObyBjbGFzcyBpbXBsZW1ldGluZyBYQUNvbm5lY3Rpb25GYWN0b3J5ID99&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 might be that the <code>XAConnectionFactory</code> class cannot be directly instantiated because the JMS specification only specifies that implementations of this class should only be available from JNDI.<br />
If your vendor only allows <code>XAConnectionFactory</code> implementations to be acquired from JNDI, you should have a look at <a class="confluence-link" href="/display/BTM/JndiXaConnectionFactory" data-linked-resource-id="183075038" data-linked-resource-type="page" data-linked-resource-default-alias="JndiXaConnectionFactory" data-base-url="http://docs.codehaus.org">XA Connection factories only available from JNDI</a>.</p></td></tr></table>

<h3>Eager initialization</h3>
<p>Like for JDBC, the connection pool will be initialized during the first call to <code>createConnection()</code>. It might be desirable to initialize the pool eagerly, like during application startup rather than having to wait for the first request. This can be done by calling <code>init()</code>:</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>
PoolingConnectionFactory myConnectionFactory = new PoolingConnectionFactory ();                   (1)
myConnectionFactory.setClassName("org.apache.activemq.ActiveMQXAConnectionFactory");              (2)
myConnectionFactory.setUniqueName("activemq");                                                    (3)
myConnectionFactory.setMaxPoolSize(5);                                                            (4)
myConnectionFactory.setAllowLocalTransactions(true);                                              (5)
myConnectionFactory.getDriverProperties().setProperty("brokerURL", "tcp://localhost:61616");      (6)
myConnectionFactory.init();                                                                       (7)

Connection c = myConnectionFactory.createConnection();                                            (8)
 // create some session then send or receive some message
c.close();                                                                                        (9)

myConnectionFactory.close();                                                                      (10)
</pre></td></tr></table>

<p>Now line 7 will initialize the pool and create the 5 connections to the JMS server instead of line 8.</p>

<h2>Using the Resource Loader</h2>

<p>A connection factory configuration utility is also bundled with BTM. It is convenient to use it rather than create your connection factory in code. Refer to the <a class="confluence-link" href="/display/BTM/ResourceLoader12" data-linked-resource-id="72056885" data-linked-resource-type="page" data-linked-resource-default-alias="ResourceLoader12" data-base-url="http://docs.codehaus.org">Resource Loader</a> page for more details.</p>

<p>Here is the equivalent Resource Loader configuration of the previous code example:</p>

<p>You just have to write those properties in a simple text file and tell BTM where to load it by setting the <code>resourceConfigurationFilename</code> property of the <a class="confluence-link" href="/display/BTM/Configuration12" data-linked-resource-id="5636097" data-linked-resource-type="page" data-linked-resource-default-alias="Configuration12" data-base-url="http://docs.codehaus.org">Configuration12</a> object.</p>

<table class="wysiwyg-macro" data-macro-name="tip" data-macro-parameters="title=Eager initialization" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3RpcDp0aXRsZT1FYWdlciBpbml0aWFsaXphdGlvbn0&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 Resource Loader will always eager initialize the created connection factories.</p></td></tr></table>

<p>Now you also have to know how to get the connection factory created by the Resource Loader. There are multiple ways:</p>

<ul>
	<li>Add <code>bitronix.tm.resource.bind=true</code> to your resource loader properties file. The connection factories will then be bound to the default JNDI server using their <code>uniqueName</code> as their JNDI name.</li>
</ul>

<ul>
	<li>Another way (in case the JNDI context is read only, like in Tomcat) is to bind a <a href="http://btm.codehaus.org/api/1.2/bitronix/tm/resource/ResourceObjectFactory.html">bitronix.tm.resource.ResourceObjectFactory</a> object, passing it a <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/Reference.html">javax.naming.Reference</a> containing a <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/StringRefAddr.html">javax.naming.StringRefAddr</a> containing the connection factory's <code>uniqueName</code> as <code>addrType</code> somewhere in your JNDI tree. The <code>bitronix.tm.resource.ResourceObjectFactory</code> class will just return the connection factory with the specified <code>uniqueName</code>. This is explained more in-depth in the <a class="confluence-link" href="/display/BTM/Tomcat12" data-linked-resource-id="9240733" data-linked-resource-type="page" data-linked-resource-default-alias="Tomcat12" data-base-url="http://docs.codehaus.org">Tomcat12</a> integration page.</li>
</ul>

<ul>
	<li>The last way is to call <a href="http://btm.codehaus.org/api/1.2/bitronix/tm/resource/ResourceRegistrar.html#get(java.lang.String)">bitronix.tm.resource.ResourceRegistrar.get(String uniqueName)</a>. This is the least preferred method as this ties your code to BTM which you probably want to avoid.<br />
<img class="confluence-embedded-image confluence-external-resource" src="http://www.bitronix.be/images/shim.gif" data-image-src="http://www.bitronix.be/images/shim.gif"></li>
</ul>