[
https://issues.apache.org/jira/browse/CAMEL-11497?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16392688#comment-16392688
]
ASF GitHub Bot commented on CAMEL-11497:
----------------------------------------
onderson closed pull request #2250: CAMEL-11497 - add rollback-eip considering
transactional-client.adoc …
URL: https://github.com/apache/camel/pull/2250
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/camel-core/src/main/docs/eips/rollback-eip.adoc
b/camel-core/src/main/docs/eips/rollback-eip.adoc
new file mode 100644
index 00000000000..2222a749340
--- /dev/null
+++ b/camel-core/src/main/docs/eips/rollback-eip.adoc
@@ -0,0 +1,252 @@
+[[rollback-eip]]
+
+Rollback might be needed if there is a transaction or transactional pieces in
your design.
+
+Camel recommends supporting the
+http://www.enterpriseintegrationpatterns.com/TransactionalClient.html[Transactional
+Client] from the link:enterprise-integration-patterns.html[EIP patterns]
+using spring transactions.
+
+image:http://www.enterpriseintegrationpatterns.com/img/TransactionalClientSolution.gif[image]
+
+Transaction Oriented Endpoints like
link:https://github.com/apache/camel/blob/master/components/camel-jms/src/main/docs/jms-component.adoc[JMS]
support using a
+transaction for both inbound and outbound message exchanges. Endpoints
+that support transactions will participate in the current transaction
+context that they are called from.
+
+Configuration of Redelivery
+
+The redelivery in transacted mode is *not* handled by Camel but by the
+backing system (the transaction manager). In such cases you should
+resort to the backing system how to configure the redelivery.
+
+You should use the
+http://camel.apache.org/maven/current/camel-spring/apidocs/org/apache/camel/spring/SpringRouteBuilder.html[SpringRouteBuilder]
+to setup the routes since you will need to setup the spring context with
+the TransactionTemplates that will define the transaction manager
+configuration and policies.
+
+For inbound endpoint to be transacted, they normally need to be
+configured to use a Spring PlatformTransactionManager. In the case of
+the JMS component, this can be done by looking it up in the spring
+context.
+
+You first define needed object in the spring configuration.
+
+[source,xml]
+--------------------------------------------------------
+<bean id="jmsTransactionManager"
class="org.springframework.jms.connection.JmsTransactionManager">
+ <property name="connectionFactory" ref="jmsConnectionFactory" />
+</bean>
+<bean id="jmsConnectionFactory"
class="org.apache.activemq.ActiveMQConnectionFactory">
+ <property name="brokerURL" value="tcp://localhost:61616"/>
+</bean>
+--------------------------------------------------------
+
+Then you look them up and use them to create the JmsComponent.
+
+[source,java]
+----
+PlatformTransactionManager transactionManager = (PlatformTransactionManager)
spring.getBean("jmsTransactionManager");
+ConnectionFactory connectionFactory = (ConnectionFactory)
spring.getBean("jmsConnectionFactory");
+JmsComponent component =
JmsComponent.jmsComponentTransacted(connectionFactory, transactionManager);
+component.getConfiguration().setConcurrentConsumers(1);
+ctx.addComponent("activemq", component);
+----
+
+[[TransactionalClient-TransactionPolicies]]
+Transaction Policies
+++++++++++++++++++++
+
+Outbound endpoints will automatically enlist in the current transaction
+context. But what if you do not want your outbound endpoint to enlist in
+the same transaction as your inbound endpoint? The solution is to add a
+Transaction Policy to the processing route. You first have to define
+transaction policies that you will be using. The policies use a spring
+TransactionTemplate under the covers for declaring the transaction
+demarcation to use. So you will need to add something like the following
+to your spring xml:
+
+[source,xml]
+--------------------------------------------------------
+<bean id="PROPAGATION_REQUIRED"
class="org.apache.camel.spring.spi.SpringTransactionPolicy">
+ <property name="transactionManager" ref="jmsTransactionManager"/>
+</bean>
+<bean id="PROPAGATION_REQUIRES_NEW"
class="org.apache.camel.spring.spi.SpringTransactionPolicy">
+ <property name="transactionManager" ref="jmsTransactionManager"/>
+ <property name="propagationBehaviorName" value="PROPAGATION_REQUIRES_NEW"/>
+</bean>
+--------------------------------------------------------
+
+Then in your
+http://camel.apache.org/maven/current/camel-spring/apidocs/org/apache/camel/spring/SpringRouteBuilder.html[SpringRouteBuilder],
+you just need to create new SpringTransactionPolicy objects for each of
+the templates.
+
+[source,java]
+----
+public void configure() {
+ ...
+ Policy requried = bean(SpringTransactionPolicy.class,
"PROPAGATION_REQUIRED"));
+ Policy requirenew = bean(SpringTransactionPolicy.class,
"PROPAGATION_REQUIRES_NEW"));
+ ...
+}
+----
+Once created, you can use the Policy objects in your processing routes:
+
+[source,java]
+----
+ // Send to bar in a new transaction
+from("activemq:queue:foo").policy(requirenew).to("activemq:queue:bar");
+// Send to bar without a transaction.
+from("activemq:queue:foo").policy(notsupported).to("activemq:queue:bar");
+----
+
+[[TransactionalClient-OSGiBlueprint]]
+OSGi Blueprint
+++++++++++++++
+
+If you are using
link:https://github.com/apache/camel/blob/master/docs/user-manual/en/using-osgi-blueprint-with-camel.adoc[OSGi
+Blueprint] then you most likely have to explicit declare a policy and
+refer to the policy from the transacted in the route.
+
+[source,xml]
+--------------------------------------------------------
+<bean id="required"
class="org.apache.camel.spring.spi.SpringTransactionPolicy">
+ <property name="transactionManager" ref="jmsTransactionManager"/>
+ <property name="propagationBehaviorName" value="PROPAGATION_REQUIRED"/>
+</bean>
+--------------------------------------------------------
+
+And then refer to "required" from the route:
+
+[source,xml]
+--------------------------------------------------------
+<route>
+ <from uri="activemq:queue:foo"/>
+ <transacted ref="required"/>
+ <to uri="activemq:queue:bar"/>
+</route>
+--------------------------------------------------------
+
+[[TransactionalClient-DatabaseSample]]
+Database Sample
+^^^^^^^^^^^^^^^
+
+In this sample we want to ensure that two endpoints is under transaction
+control. These two endpoints inserts data into a database. +
+The sample is in its full as a
+https://github.com/apache/camel/blob/master/components/camel-spring/src/test/java/org/apache/camel/spring/interceptor/TransactionalClientDataSourceMinimalConfigurationTest.java[unit
+test].
+
+First of all we setup the usual spring stuff in its configuration file.
+Here we have defined a DataSource to the HSQLDB and a most
+importantly the Spring DataSource TransactionManager that is doing the
+heavy lifting of ensuring our transactional policies. You are of course
+free to use any of the Spring based TransactionManager, eg. if you are
+in a full blown J2EE container you could use JTA or the WebLogic or
+WebSphere specific managers.
+
+As we use the new convention over configuration we do *not* need to
+configure a transaction policy bean, so we do not have any
+`PROPAGATION_REQUIRED` beans. All the beans needed to be configured is
+*standard* Spring beans only, eg. there are no Camel specific
+configuration at
+all.link:https://github.com/apache/camel/blob/master/components/camel-spring/src/test/resources/org/apache/camel/spring/interceptor/springTransactionalClientDataSourceMinimalConfiguration.xml[springTransactionalClientDataSourceMinimalConfiguration]Then
+we are ready to define our Camel routes. We have two routes: 1 for
+success conditions, and 1 for a forced rollback condition. +
+This is after all based on a unit test. Notice that we mark each route
+as transacted using the *transacted*
+tag.link:https://github.com/apache/camel/blob/master/components/camel-spring/src/test/resources/org/apache/camel/spring/interceptor/springTransactionalClientDataSourceMinimalConfiguration.xml[springTransactionalClientDataSourceMinimalConfiguration]That
+is all that is needed to configure a Camel route as being transacted.
+Just remember to use the *transacted* DSL. The rest is standard Spring
+XML to setup the transaction manager.
+
+[[TransactionalClient-JMSSample]]
+JMS Sample
+^^^^^^^^^^
+
+In this sample we want to listen for messages on a queue and process the
+messages with our business logic java code and send them along. Since
+its based on a
link:https://github.com/apache/camel/blob/master/components/camel-jms/src/test/java/org/apache/camel/component/jms/tx/TransactionMinimalConfigurationTest.java[TransactionMinimalConfigurationTest.java]
the destination is a mock endpoint.
+
+First we configure the standard Spring XML to declare a JMS connection
+factory, a JMS transaction manager and our ActiveMQ component that we
+use in our
+routing.link:https://github.com/apache/camel/blob/master/components/camel-jms/src/test/resources/org/apache/camel/component/jms/tx/TransactionMinimalConfigurationTest.xml[TransactionMinimalConfigurationTest.xml]And
+then we configure our routes. Notice that all we have to do is mark the
+route as transacted using the *transacted*
+tag.link:https://github.com/apache/camel/blob/master/components/camel-jms/src/test/resources/org/apache/camel/component/jms/tx/TransactionMinimalConfigurationTest.xml[TransactionMinimalConfigurationTest.xml]
+
+Transaction error handler
+
+When a route is marked as transacted using *transacted* Camel will
+automatic use the
+link:transactionerrorhandler.html[TransactionErrorHandler] as
+link:https://github.com/apache/camel/blob/master/docs/user-manual/en/error-handler.adoc[Error
Handler]. It supports basically the same
+feature set as the link:defaulterrorhandler.html[DefaultErrorHandler],
+so you can for instance use link:exception-clause.html[Exception Clause]
+as well.
+
+[[TransactionalClient-IntegrationTestingwithSpring]]
+Integration Testing with Spring
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An Integration Test here means a test runner class annotated
+`@RunWith(SpringJUnit4ClassRunner.class).`
+
+When following the Spring Transactions documentation it is tempting to
+annotate your integration test with `@Transactional` then seed your
+database before firing up the route to be tested and sending a message
+in. This is incorrect as Spring will have an in-progress transaction,
+and Camel will wait on this before proceeding, leading to the route
+timing out.
+
+Instead, remove the `@Transactional` annotation from the test method and
+seed the test data within a `TransactionTemplate` execution which will
+ensure the data is committed to the database before Camel attempts to
+pick up and use the transaction manager. A simple
+example
https://github.com/rajivj2/example2/blob/master/src/test/java/com/example/NotificationRouterIT.java[can
+be found on GitHub].
+
+Spring's transactional model ensures each transaction is bound to one
+thread. A Camel route may invoke additional threads which is where the
+blockage may occur. This is not a fault of Camel but as the programmer
+you must be aware of the consequences of beginning a transaction in a
+test thread and expecting a separate thread created by your Camel route
+to be participate, which it cannot. You can, in your test, mock the
+parts that cause separate threads to avoid this issue.
+
+[[TransactionalClient-Usingmultiplerouteswithdifferentpropagationbehaviors]]
+Using multiple routes with different propagation behaviors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.2* +
+Suppose you want to route a message through two routes and by which the
+2nd route should run in its own transaction. How do you do that? You use
+propagation behaviors for that where you configure it as follows:
+
+* The first route use `PROPAGATION_REQUIRED`
+* The second route use `PROPAGATION_REQUIRES_NEW`
+
+This is configured in the Spring XML
+file.link:https://github.com/apache/camel/blob/master/components/camel-spring/src/test/resources/org/apache/camel/spring/interceptor/MixedTransactionPropagationTest.xml[MixedTransactionPropagationTest.xml]Then
+in the routes you use transacted DSL to indicate which of these two
+propagations it
+uses.link:https://github.com/apache/camel/blob/master/components/camel-spring/src/test/java/org/apache/camel/spring/interceptor/MixedTransactionPropagationTest.java[MixedTransactionPropagationTest.java]Notice
+how we have configured the `onException` in the 2nd route to indicate in
+case of any exceptions we should handle it and just rollback this
+transaction. This is done using the `markRollbackOnlyLast` which tells
+Camel to only do it for the current transaction and not globally.
+
+[[TransactionalClient-SeeAlso]]
+See Also
+++++++++
+
+* link:error-handling-in-camel.html[Error handling in Camel]
+* link:transactionerrorhandler.html[TransactionErrorHandler]
+*
link:https://github.com/apache/camel/blob/master/docs/user-manual/en/error-handler.adoc[Error
Handler]
+*
link:https://github.com/apache/camel/blob/master/components/camel-jms/src/main/docs/jms-component.adoc[JMS]
+*
link:https://github.com/apache/camel/blob/master/docs/user-manual/en/oncompletion.adoc[On
Completion]
+
+link:using-this-pattern.html[Using This Pattern]
\ No newline at end of file
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
> Migrate the rest of the Confluence content
> ------------------------------------------
>
> Key: CAMEL-11497
> URL: https://issues.apache.org/jira/browse/CAMEL-11497
> Project: Camel
> Issue Type: Sub-task
> Components: website
> Reporter: Zoran Regvart
> Assignee: Önder Sezgin
> Priority: Major
> Fix For: Future
>
>
> There are still pages in the Confluence that are not migrated to Asciidoctor
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
