Message-ID: <1345330164.5787.1369521398162.JavaMail.firstname.lastname@example.org> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_5786_596975075.1369521397719" ------=_Part_5786_596975075.1369521397719 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
BTM XA datasources can be created via some java code or via a BTM-specif= ic tool called the Resource Loader. You are free to choose the method you p= refer, there is absolutely no difference between them.
BTM comes bundled with a JDBC XA connection pool which is very easy to c= onfigure. You basically have to create an instance of bitronix.tm.resource.jdbc.PoolingData= Source set some properties and you're done.
Here is an example of datasource creation that connects to an Oracle dat= abase:
1. The Bitronix
PoolingDataSource is a ja=
vabean that implements
2. You have to specify the driver's
XADataSource implementation here. implementation does not implement
3. Each datasource must be assigned a unique name. This i= s required for distributed crash recovery.
4. This datasource can contain at least 0 connection. 0 i= s the default value when unspecified.
5. This datasource can contain at most 5 connections.
6. If there aren't enough connections in the pool to fulf= ill a request, new connections will be created, by increments of 1 at a tim= e.
7. You have to set
true if you want to be able to run SQL statements outside of XA transactio=
ns scope. Defaults to false.
8. When specified, this query will be executed to check t= hat the connection is still valid before handing it to the application code= .
useTmJoin to false if the vendor's
isSameRM() properly. Refer to the JdbcXaSupportEvaluation page to see if your database nee=
ds it. Defaults to true.
deferConnectionRelease to false if t=
XADataSource implementation supports transactions =
interleaving. Refer to the JdbcXaSupportEvaluation page to see if your database supports it. Defa=
ults to true.
automaticEnlistingEnabled to false i=
f you do not want the
PoolingDataSource to automatically enlis=
t/delist the connections into the XA transactions. You then have to enlist =
XAResource objects manually into the
objects for them to participate in XA transactions. Defaults to true.
12. The amount of seconds the pool will block when a conn= ection is requested but the pool is empty and cannot grow anymore. Defaults= to 30.
13. The amount of seconds the pool will wait when a conne= ction has been tested invalid before trying to acquire a new one. Defaults = to 1.
14. The amount of prepared statements cached per pooled c= onnection. Defaults to 0, meaning statement caching is disabled.
15,16,17. The driverProperties is a
rties object. You have to add into it a set of property name / prope=
rty value of the
OracleXADataSource class. You have to refer t=
o the driver's documentation to know what can / has to be set. The OracleXADataSource javadoc contains this list for the Ora=
cle case. BTM will perform conversion from
lean or to
int when necessary.
18,19. You can now use the
like any other
20. Remember to close the
after you're done with it to release the connections.
|No XADataSource implementation ?|
If your =
database vendor does not provide a
You do not have to set properties that have a default value. Here is a s=
implified version of the previous code creating a
code> with minimal settings:
This will create a
PoolingDataSource that will work exactly=
the same as the previous one. The only difference is that unspecified prop=
erties have been left untouched with their default value.
The connection pool will be initialized during the first call to
etConnection(). It might be desirable to initialize the pool eagerly=
, like during application startup rather than having to wait for the first =
requests. This can be done by calling
Now line 10 will initialize the pool instead of line 11.
|Initialization must happen before TM startup=
Please remember that connection pools should always be initialized befor=
e BTM starts up, ie: before calling
If you do not follow this rule, BTM might not be able to fully recover X= A transactions pending finalization because not all resources are available= for startup recovery.
To circumvent this problem, BTM will run a full recovery each time a new= connection pool is registered after it started up. You should not rely on = this as pending XA transactions might still hold locks on registered connec= tion pools that could block new transactions.
If this is problematic for you, please let us know by voting for BTM-4.
A datasource configuration utility is also bundled with BTM. It is conve= nient to use it rather than create your datasources in code. Refer to the <= a href=3D"/display/BTM/ResourceLoader12">Resource Loader page for more = details.
Here is the equivalent Resource Loader configuration of the previous cod= e example:
|Datasource initialization / shutdown|
The = Resource Loader will always eager initialize the created datasources and cl= ose them when the transaction manager shuts down.
You just have to write those properties in a simple text file and tell B=
TM where to load it by setting the
resourceConfigurationFilename property of the Configuration12=
Now you also have to know how to get the datasource created by the Resou= rce Loader. There are multiple ways:
bitronix.tm.resource.bind=3Dtrueto your resource l= oader properties file. The datasources will then be bound to the default JN= DI server using their
uniqueNameas their JNDI name.
addrTyp= esomewhere in your JNDI tree. The
bitronix.tm.resource.Resour= ceObjectFactoryclass will just return the datasource with the speci= fied
uniqueName. This is explained more in-depth in the Tomcat12 integration page.