Overview:
=========
  The purpose of the jms_transacted quickstart is to show how the JMS transport 
  in the ESB can be configured to use transactions and how redelivery can be 
  accomplished by taking advantage of the JMS transport.

  This quickstart consists of a single service that contains 4 actions:
  1. Log a statement that we have entered the quickstart.
  2. Insert the contents of the ESB Message object to a database table
  3. Call a custom action that throws an exception if the message has not
	 been redelivered. (more on this later)
  4. Log a statement that we are about to exit the quickstart.

  The main thing to look for is that the first time we enter the action processing
  pipleline, we insert a row into the database, but since the commit is not done
  until the whole pipeline has been executed (as we are using the jms-jca-provider)
  the commit for this insert is not performed. The same goes for the message 
  acknowledement of the JMS Message, which in turn causes the JMS message to be
  put back onto the queue.

  For more details about how this quickstart works look at the 
  "What to look at in this Quckstart" section below.

  This quickstart uses jms-jca-provider and more information about jms jca can
  be found here: http://wiki.jboss.org/wiki/Wiki.jsp?page=UsingJCAWithJBossESB
  
Running this quickstart:
========================
  Please refer to 'ant help-quickstarts' for prerequisites about the quickstarts
  and a more detailed descripton of the different ways to run the quickstarts.

To Run '.esb' archive mode:
===========================
  1. In a command terminal window in this folder ("Window1"), type:
	 'ant deploy'
	 This will deploy the quickstart
  2. Open another command terminal window in this folder ("Window2"), type:
     'ant runtest'
  3. Switch back to Application Server console to see the output from the ESB
  4. In this folder ("Window1"), type:
	 'ant select'
	 This will display the content of the database table
  5. [optional] In this folder ("Window1"), type:
	 'ant truncate'
	 This will delete the content of the database table.
  6. In this folder ("Window1"), type:
	 'ant undeploy'
	 This will undeploy the quickstart.

What to look at in this Quickstart:
===================================
  1. DBInsertAction
	 Inserts the contents of the ESB Message object into the database table 
	 by using the sql statement defined in the property 'db-insert-sql'.
	 This class contains a counter that is incremented for each call. This 
	 counter is added to the text inserted into the table. The string looks 
	 like this:
		[Hello Transacted JMS World] counter[1]] // counter == 1;
	 This is done to seperate the inserts and visually verify that the correct
	 data is committed to the database. In a normal run, when the counter is
	 '1', the counter should be 2 indicating that only the second commit succeeded.
	  
  2. ThrowExceptionAction
	 Checks if the ESB Messae property 'javax.jms.message.redelivered' 
	 is false, in which case an IllegalArgumentException will be thrown.
	 This will will cause the message to be redelivered by JMS transaction handling.

  3. jboss-esb.xml
     The message-filter for the jms-bus-filter now specifies 'transacted' attribute.

  4. 'ant select'
	 Ant target that will display all the rows in the database table.

  5. 'ant truncate'
	 Ant target that will delete all the rows in the database table.
	 Useful to clear the table after multiple runs.


Inside look:
============
  1. Transactions with JMSGateway

	 Lets walk through a client publishing a message to a queue. The queue
	 will be the queue that our gateway is configured to listen on.

	 1. Client publishes message to JMS queue. It can use a JMS session that
	 	is transacted to do so or not. It does not matter.
	 2. The gateway listener will create a JMS session, or use an existing
		session from the pool, that is transacted. While the JMS Listener
		is running it will consume a JMS message from the queue, package the 
		contents of that JMS message into an ESB Message, and use a courier to 
		pass the message on to the action pipeline.

		Commit:
	    When the message has be sent to the courier, and no exception has
		been thrown, the transaction will commit and acknowledge that it
		has accepted the JMS Message. 

		Rollback:
		But if an exception has occurred, the transaction will be rolled-back 
		and the JMS message will not be acknowledged, hence it will be put 
		back on the queue. 

		Usecase for transactions in JMSGateway
		Now, this situation may seem far fetched, but one usecase for 
		it might be that the task of packaging the content of the JMS 
		Message into the ESB Message is a memory intensive process. 
		Lets say that one of your machines is under more heavy load then others 
		which could cause it to throw an OutOfMemory Exception. In this case the 
		message could be picked up by another ESB instance, which hopefully 
		can deal with the message.
