This is an automated email from the ASF dual-hosted git repository.
jgallimore pushed a commit to branch tomee-7.0.x
in repository https://gitbox.apache.org/repos/asf/tomee.git
commit c3ec7fa0d06eb3d70183bae19ee3324934c17cd5
Author: Jonathan Gallimore <jo...@jrg.me.uk>
AuthorDate: Fri Jul 12 16:44:21 2019 +0100
Provide some detail on configuring XA datasources
---
docs/configuring-datasources-xa.adoc | 161 +++++++++++++++++++++++++++++++++++
1 file changed, 161 insertions(+)
diff --git a/docs/configuring-datasources-xa.adoc b/docs/configuring-datasources-xa.adoc
new file mode 100644
index 0000000..8619806
--- /dev/null
+++ b/docs/configuring-datasources-xa.adoc
@@ -0,0 +1,161 @@
+= XA DataSource Configuration
+:index-group: Datasource
+:jbake-date: 2019-07-12
+:jbake-type: page
+:jbake-status: published
+
+== Introduction
+
+XA datasources are able to participate in global transactions involving
+more than one resource - for example, scenarios where a transaction needs
+to encompass connections to two different databases,, or a database and
+a JMS resource.
+
+The global transaction manager will provide a two phase commit for all
+the resources enlisted in the transaction - if any of the commit
+operations fail, then all the resources in the global transaction will
+be rolled back.
+
+JTA can still be used with non-XA datasources, however the datasource will
+use a local transaction as opposed to a global transaction.
+
+JDBC drivers providing XA capabilities provide an implementation of
+`javax.sql.XADataSource`. This makes them a little more tricky to configure
+than non-XA datasources. The general technique is to configure an instance
+of the vendor-provided `XADataSource` implementation, and to then point
+the usual non-XA resource at this instance. Sounds complex? Let's walk
+through an example. We'll also provide tested example configs for a number
+of well known databases at the end of this document.
+
+== Example
+
+In this example, we'll look at MySQL. First off, download the MySQL driver
+from: https://dev.mysql.com/downloads/connector/j/. Once you have the .jar
+file, add it to the TomEE `lib` directory. This driver provides the
+`com.mysql.cj.jdbc.MysqlXADataSource` class. The properties that need to
+be configured vary between datasources, so we'll need to get a list of the
+properties and work out the values to set.
+
+From the TomEE bin directory, execute the following command:
+`./tomee.sh setters -c com.mysql.cj.jdbc.MysqlXADataSource` on *nix systems,
+or
+
+`tomee.bat setters -c com.mysql.cj.jdbc.MysqlXADataSource` on Windows systems.
+
+This will give a complete list of paramaters that are available for the XA
+datasource. We'll simply use the `URL` paramater for the datasource.
+
+```
+ <Resource id="demo/jdbc/XADataSourceXA" type="XADataSource" class-name="com.mysql.cj.jdbc.MysqlXADataSource">
+ Url jdbc:mysql://192.168.37.202:3306/movie
+ </Resource>
+```
+
+Next, we create a JtaManaged datasource as we normally would, and point it to the
+XA datasource using the `XaDataSource` attribute.
+
+```
+ <Resource id="demo/jdbc/XADataSource" type="DataSource">
+ XaDataSource demo/jdbc/XADataSourceXA
+ JdbcDriver com.mysql.cj.jdbc.Driver
+ JdbcUrl jdbc:mysql://192.168.37.202:3306/movie
+ username root
+ password my-secret-pw
+ JtaManaged true
+ InitialSize 10
+ MaxActive 128
+ MaxIdle 25
+ MinIdle 10
+ AccessToUnderlyingConnectionAllowed true
+ TestOnBorrow false
+ TestWhileIdle true
+ TimeBetweenEvictionRuns 1 minute
+ MaxWaitTime 0 seconds
+ ValidationQuery select null from dual
+ </Resource>
+```
+
+And finally, a non-JTA managed datasource as well:
+
+```
+ <Resource id="demo/jdbc/XADataSourceUnmanaged" type="DataSource">
+ JdbcDriver com.mysql.cj.jdbc.Driver
+ JdbcUrl jdbc:mysql://192.168.37.202:3306/movie
+ UserName root
+ password my-secret-pw
+ JtaManaged false
+ InitialSize 10
+ MaxActive 100
+ MaxIdle 50
+ MinIdle 10
+ AccessToUnderlyingConnectionAllowed true
+ TestOnBorrow false
+ TestWhileIdle true
+ TimeBetweenEvictionRuns 1 minute
+ MaxWaitTime 0 seconds
+ ValidationQuery select null from dual
+ </Resource>
+```
+
+== Sample configs
+
+=== Oracle
+
+```
+ <Resource id="demo/jdbc/XADataSource" type="DataSource">
+ XaDataSource demo/jdbc/XADataSourceXA
+ JdbcDriver oracle.jdbc.OracleDriver
+ JdbcUrl jdbc:oracle:thin:@//192.168.37.214:1521/XE
+ username system
+ password my-cool-password
+ JtaManaged true
+ InitialSize 10
+ MaxActive 128
+ MaxIdle 25
+ MinIdle 10
+ AccessToUnderlyingConnectionAllowed true
+ TestOnBorrow false
+ TestWhileIdle true
+ TimeBetweenEvictionRuns 1 minute
+ MaxWaitTime 0 seconds
+ PoolPreparedStatements true
+ MaxOpenPreparedStatements 1024
+ ValidationQuery select null from dual
+ </Resource>
+
+ <Resource id="demo/jdbc/XADataSourceXA" type="XADataSource" class-name="oracle.jdbc.xa.client.OracleXADataSource">
+ Url jdbc:oracle:thin:@//192.168.37.214:1521/XE
+ </Resource>
+
+ <Resource id="demo/jdbc/XADataSourceUnmanaged" type="DataSource">
+ JdbcDriver oracle.jdbc.OracleDriver
+ JdbcUrl jdbc:oracle:thin:@//192.168.37.214:1521/XE
+ UserName system
+ password my-cool-password
+ JtaManaged false
+ InitialSize 10
+ MaxActive 100
+ MaxIdle 50
+ MinIdle 10
+ AccessToUnderlyingConnectionAllowed true
+ TestOnBorrow false
+ TestWhileIdle true
+ TimeBetweenEvictionRuns 1 minute
+ MaxWaitTime 0 seconds
+ PoolPreparedStatements true
+ MaxOpenPreparedStatements 1024
+ ValidationQuery select null from dual
+ </Resource>
+```
+
+
+
+=== Microsoft SQL Server
+
+=== MySQL
+
+=== PostgreSQL
+
+=== Derby
+
+=== NuoDB
\ No newline at end of file