Description of problem: The documentation does not cover how transactions work within a service pipeline Version-Release number of selected component (if applicable): 5.3 Expected results: The documentation needs to clearly define how transactions are catered for in a service pipeline. The documentation should identify that a service pipeline can run either in a transaction or not and how these two life cycles differ, specifically when a transactional pipeline commits or rolls back. Firstly, to be transactional, there needs to be a JCA listener on the service with the transact set to true. Even though a non JCA listener has the transact property, these never create a transaction, only if its a JCA listener. Secondly there needs to be information on how to retrieve the TransactionManager object when running in an application server. I did this with a JNDI lookup, however there may be API in SOA-P that I am not aware of, if so this should be documented. Thirdly, the life cycle of a service pipeline when using transactions needs to be documented. What I noticed is that the normal lifecycle is followed, however, the transaction can still be rolled back during the commit phase which occurs after all the onSuccess methods of the actions are called. So this would be critical to understand that even though an action has had its onSuccess invoked, the entire pipeline can still fail and rollback during commit phase which would cause the message to retry the pipe. Fourthly when using JMS JCA listener, the retries will occur from the message queue. If max retries and interval between retries is not set on the queue, then this will be far too aggressive when retrying. This also needs to be documented. For HornetQ, you can include a hornetq-configuration.xml covering the rety policy for the specific queue the service is running from. <configuration xmlns="urn:hornetq" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:hornetq /schema/hornetq-configuration.xsd"> <address-settings> <address-setting match="jms.queue.MyServiceQueue"> <max-delivery-attempts>5</max-delivery-attempts> <redelivery-delay>1000</redelivery-delay> <max-size-bytes>10240</max-size-bytes> </address-setting> </address-settings> </configuration> Lastly the documentation needs to clearly identify that in order for a service action to rollback, it needs to either setRollbackOnly on the current transaction or throw an unchecked / RunTime exception our of the process method.
Jonathan, Thanks for your feedback. It is greatly appreciated. We will review your suggestions and incorporate them into the docs. David
Added topic called Transactions and the Service Pipeline which addresses several of the points raised above: "The service pipeline is capable of running either in a transaction or by itself. To perform the former, a service must have a JCA listener attached to it with the <emphasis>transact</emphasis> property set to <emphasis>true</emphasis>. It must also be told how to retrieve the <property>TransactionManager</property> when running in an application server. This can be accomplished by running JNDI look-up. When working in the service pipeline, transactions can be rolled back during the commit phase which occurs after all the <emphasis>onSuccess</emphasis> methods of the actions are called. The entire pipeline can still fail and rollback during commit phase which would cause the message to retry the pipe." Looking into the other points.
The following topics have been added to the Advanced Topics chapter: Transactions and the Action Pipeline [13020] Rollbacks [13356] Rollbacks and the JMS JCA Listener [13355]