spring-boot/spring-boot-samples/spring-boot-sample-jta-jndi/README.adoc

## Introduction

This application is intended to run inside of a Java EE application server such as
JBoss Wildfly. It demonstrates Spring Boot's auto-configuration defaulting for a
container-managed `TransactionManager` and `DataSource`. This example unfortunately
requires a fully configured Wildfly installation. You'll need to configure a PostgreSQL
XA `DataSource` and an XA `ConnectionFactory` in the Java EE application server's
JNDI machinery.

## Setup

### Postgres
We will use postgres as the underlying database, v9.3.5 or above is recommend. Follow
the installation instructions from https://www.postgresql.org/[postgresql.org] or use
a package manager to install the appropriate binaries.

Once installed you will need to initialize and start the server.

[source,indent=0]
----
	$ initdb /usr/local/var/postgres -E utf8
	$ pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start
----

With the server running you can create a user and a database:

[source,indent=0]
----
	$ createuser springboot
	$ createdb bootdemo
----

Finally you can type `psql bootdemo` to configure a password:

[source,indent=0]
----
	ALTER USER springboot WITH PASSWORD 'springboot';
	\q
----


### WildFly 8.1
Download an install WildFly 8.1 from https://wildfly.org/downloads/[wildfly.org]. Once
installed you will need to add a management user by running `$JBOSS_HOME/bin/add-user.sh`
(see the WildFly documentation for details).

You will also need to add a postgresql module. The following commands setup the basic
structure:

[source,indent=0]
----
	$ cd $JBOSS_HOME
	mkdir -p modules/org/postgresql/main
	wget https://jdbc.postgresql.org/download/postgresql-9.3-1102.jdbc41.jar
	mv postgresql-9.3-1102.jdbc41.jar modules/org/postgresql/main
----

You can then add the following to `$JBOSS_HOME/modules/org/postgresql/main/module.xml`:

[source,indent=0]
----
	<?xml version="1.0" encoding="UTF-8"?>
	<module xmlns="urn:jboss:module:1.0" name="org.postgresql">
		<resources>
			<resource-root path="postgresql-9.3-1102.jdbc41.jar"/>
		</resources>
		<dependencies>
			<module name="javax.api"/>
			<module name="javax.transaction.api"/>
		</dependencies>
 	</module>
----

## Configuration
A custom WildFly configuration is required for the XA `DataSource` and `ConnectionFactory`
elements. The `$JBOSS_HOME/standalone/configuration/standalone-full.xml` is a good
starting point, copy this file to
`$JBOSS_HOME/standalone/configuration/standalone-boot-demo.xml` then make the following
changes.

### DataSource
You need to register a PostgreSQL XA `Driver` and then configure an `xa-datasource`.

Here's a complete listing of the `xa-datasource` contribution to the `datasources`
element, and the `driver` contribution to the `drivers` element to configure a PostgreSQL
DB connection to localhost.
https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6/html-single/Administration_and_Configuration_Guide/index.html#Install_a_JDBC_Driver_with_the_Management_Console[You can learn more from the documentation].

[source,xml,indent=0,subs="verbatim,attributes"]
----
	<datasources>
		...
		<xa-datasource
				jndi-name="java:jboss/datasources/bootdemo"
				pool-name="CrmXADS"
				enabled="true">
			<xa-datasource-property name="url">jdbc:postgresql://localhost:5432/crm</xa-datasource-property>
			<driver>postgres</driver>
			<xa-pool>
				<min-pool-size>10</min-pool-size>
				<max-pool-size>20</max-pool-size>
				<prefill>true</prefill>
			</xa-pool>
			<security>
				<user-name>springboot</user-name>
				<password>springboot</password>
			</security>
		</xa-datasource>
		<drivers>
			...
			<driver name="postgres" module="org.postgresql">
				<xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
			</driver>
		</drivers>
	</datasources>
----

### JMS Destination
You will also need to configure a `javax.jms.Destination` by contributing the following to
the `hornetq-server` element:

[source,xml,indent=0,subs="verbatim,attributes"]
----
	<jms-destinations>
		<jms-queue name="accounts">
			<entry name="java:/jms/queue/bootdemo"/>
		</jms-queue>
		...
	</jms-destinations>
----


## Running and deploying the sample
Run Wildfly with the following command:

[source,indent=0]
----
	$JBOSS_HOME/bin/standalone.sh -c standalone-boot-demo.xml
----

Once running you can deploy the application by copying
`target/spring-boot-sample-jta-jndi.war` to `$JBOSS_HOME/standalone/deployments`.

Open a  browser to http://localhost:8080/spring-boot-sample-jta-jndi to trigger the
sample. You should see the current count (it will increment by one on each refresh). If
you check the logs you should see a `----> Josh` message and some counts. Notice how the
`error` message triggers an exception with causes both the database insert and the JMS
message to be rolled back.