You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/07/07 06:37:15 UTC
[2/2] camel git commit: Added BAM and BAM example to Gitbook
Added BAM and BAM example to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/95a57380
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/95a57380
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/95a57380
Branch: refs/heads/master
Commit: 95a573808f13d3b9a01a43797c2c3000624a774d
Parents: 12cfccf
Author: Andrea Cosentino <an...@gmail.com>
Authored: Thu Jul 7 08:36:26 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Thu Jul 7 08:36:26 2016 +0200
----------------------------------------------------------------------
docs/user-manual/en/SUMMARY.md | 5 +-
docs/user-manual/en/bam-example.adoc | 117 ++++++++++++++++++++++++++++++
docs/user-manual/en/bam.adoc | 85 ++++++++++++++++++++++
3 files changed, 206 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/95a57380/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 387839a..a0dd8df 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -9,6 +9,7 @@
* [Async](async.adoc)
* [Asynchronous Routing Engine](asynchronous-routing-engine.adoc)
* [BacklogDebugger](backlogdebugger.adoc)
+ * [BAM](bam.adoc)
* [Dozer Type Conversion](dozer-type-conversion.adoc)
* [Endpoint](endpoint.adoc)
* [Exchange](exchange.adoc)
@@ -20,7 +21,6 @@
<!--
* [AOP](aop.adoc)
- * [BAM](bam.adoc)
* [Batch Consumer](batch-consumer.adoc)
* [BrowsableEndpoint](browsable-endpoint.adoc)
* [CamelContext](camelcontext.adoc)
@@ -347,6 +347,9 @@
* [YAML](yaml.adoc)
* [Zipfile](zipfile.adoc)
+* Example
+ * [BAM Example](bam-example.adoc)
+
* User Guide
* [Karaf](karaf.adoc)
* [Testing](testing.adoc)
http://git-wip-us.apache.org/repos/asf/camel/blob/95a57380/docs/user-manual/en/bam-example.adoc
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/bam-example.adoc b/docs/user-manual/en/bam-example.adoc
new file mode 100644
index 0000000..3517c5a
--- /dev/null
+++ b/docs/user-manual/en/bam-example.adoc
@@ -0,0 +1,117 @@
+[[BAMExample-BusinessActivityMonitorExample]]
+Business Activity Monitor (BAM) Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The link:bam.html[BAM] (Business Activity Monitor) example shows how to
+monitor your transaction flows using Camel.
+
+In this example we will use Camel to monitor a business process
+consisting of
+
+* purchase orders
+* invoices
+
+Then we will check to see that for every purchase order created by
+system A, that system B will generate an invoice within the specified
+amount of time (2 seconds in this example). If an invoice is not
+generated within the allowed amount of time and error is generated and
+sent to an link:endpoint.html[Endpoint].
+
+[[BAMExample-Overview]]
+Overview
+^^^^^^^^
+
+This example lives in the _examples/camel-example-bam_ directory. It
+will poll the following directories
+
+* the child _src/data/purchaseOrders_ directory for XML purchase orders
+* the child _src/data/invoices_ directory for XML invoices
+
+The
+http://svn.apache.org/repos/asf/camel/trunk/examples/camel-example-bam/src/main/java/org/apache/camel/example/bam/MyActivities.java[MyActivities]
+class defines the link:bam.html[BAM] activities; that is
+
+* the input sources (the two directories above) which could be any of
+the supported camel link:uris.html[URIs]
+* how the activities relate to each other - namely the
+link:correlation-identifier.html[Correlation Identifier] pattern
+* the maixmum amount of time allowed from the time a purchase order is
+received when if an invoice is not received an error should be raised.
+
+There is also a spring configuration file in
+http://svn.apache.org/repos/asf/camel/trunk/examples/camel-example-bam/src/main/resources/META-INF/spring/camel-context.xml[src/resources/META-INF/services/camel-context.xml]
+which defines the JPA `EntityManagerFactory` and tells Camel to look in
+the *org.apache.camel.example.bam* package to find its routes.
+
+[[BAMExample-Codewalkthrough]]
+Code walkthrough
+^^^^^^^^^^^^^^^^
+
+So lets start with the activities definition in
+http://svn.apache.org/repos/asf/camel/trunk/examples/camel-example-bam/src/main/java/org/apache/camel/example/bam/MyActivities.java[MyActivities]
+
+[source,java]
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+return new ProcessBuilder(entityManagerFactory, transactionTemplate) {
+ public void configure() throws Exception {
+
+ // let's define some activities, correlating on an XPath on the message bodies
+ ActivityBuilder a = activity("seda:a").name("a")
+ .correlate(xpath("/hello/@id"));
+
+ ActivityBuilder b = activity("seda:b").name("b")
+ .correlate(xpath("/hello/@id"));
+
+ // now let's add some rules
+ b.starts().after(a.completes())
+ .expectWithin(seconds(1))
+ .errorIfOver(seconds(errorTimeout)).to("mock:overdue");
+ }
+};
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+The first two lines of code sets up the inputs for the
+link:bam.html[BAM] activities via the *activity()* method which defines
+
+* the link:uris.html[URIs] of the inputs (which could come from any of
+the Camel link:components.html[Components]
+* the link:correlation-identifier.html[Correlation Identifier] used to
+correlate together the purchase order and invoice messages which can be
+any link:expression.html[Expression] via any of the
+link:languages-supported.html[Languages Supported]. In this case we are
+using link:xpath.html[XPath].
+
+Then the final line of code defines the temporal rules to use; namely
+that it is considered to be an error if an invoice is not received
+within 2 seconds of a purchase order being received. When a failure
+occurs in this example we just send it to the link:log.html[Log]
+component to log out an error level message to commons-logging / log4j.
+You could change this to use some of the other
+link:components.html[Components] such as link:activemq.html[ActiveMQ],
+link:jms.html[JMS], link:irc.html[IRC], link:mail.html[Mail],
+link:xmpp.html[XMPP] etc.
+
+[[BAMExample-Runningtheexample]]
+Running the example
+^^^^^^^^^^^^^^^^^^^
+
+To run the example we use the link:camel-maven-plugin.html[Camel Maven
+Plugin]. For example from the source or binary distribution the
+following should work
+
+[source,bash]
+-----------------------------
+cd examples/camel-example-bam
+mvn camel:run
+-----------------------------
+
+If you prefer you can just run the Main directly using
+
+[source,bash]
+---------------------
+mvn compile exec:java
+---------------------
+
+Failing that you can run the Main from inside your IDE if you prefer.
+Follow the link:building.html[Building] instructions to create an
+Eclipse/IDEA project to import
http://git-wip-us.apache.org/repos/asf/camel/blob/95a57380/docs/user-manual/en/bam.adoc
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/bam.adoc b/docs/user-manual/en/bam.adoc
new file mode 100644
index 0000000..ae290dd
--- /dev/null
+++ b/docs/user-manual/en/bam.adoc
@@ -0,0 +1,85 @@
+[[BAM-BusinessActivityMonitoring]]
+Business Activity Monitoring
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The *Camel BAM* module provides a Business Activity Monitoring (BAM)
+framework for testing business processes across multiple message
+exchanges on different link:endpoint.html[Endpoint] instances.
+
+Consider, for example, a simple system in which you submit Purchase
+Orders into system A and then receive Invoices from system B. You might
+want to test that, for a given Purchase Order, you receive a matching
+Invoice from system B within a specific time period.
+
+[[BAM-HowCamelBAMWorks]]
+How Camel BAM Works
+^^^^^^^^^^^^^^^^^^^
+
+Camel BAM uses a link:correlation-identifier.html[Correlation
+Identifier] on an input message to determine the _Process Instance_ to
+which it belongs. The process instance is an entity bean which can
+maintain state for each _Activity_ (where an activity typically maps to
+a single endpoint - such as the submission of Purchase Orders or the
+receipt of Invoices).
+
+[source,java]
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+return new ProcessBuilder(entityManagerFactory, transactionTemplate) {
+ public void configure() throws Exception {
+
+ // let's define some activities, correlating on an XPath on the message bodies
+ ActivityBuilder a = activity("seda:a").name("a")
+ .correlate(xpath("/hello/@id"));
+
+ ActivityBuilder b = activity("seda:b").name("b")
+ .correlate(xpath("/hello/@id"));
+
+ // now let's add some rules
+ b.starts().after(a.completes())
+ .expectWithin(seconds(1))
+ .errorIfOver(seconds(errorTimeout)).to("mock:overdue");
+ }
+};
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+You can then add rules to be triggered when a message is received on any
+activity - such as to set time expectations or perform real time
+reconciliation of values across activities.
+
+[[BAM-SimpleExample]]
+Simple Example
+^^^^^^^^^^^^^^
+
+The following example shows how to perform some time based rules on a
+simple business process of 2 activities - A and B - which correspond
+with Purchase Orders and Invoices in the example above. If you would
+like to experiment with this scenario, you may edit this
+http://svn.apache.org/repos/asf/camel/trunk/components/camel-bam/src/test/java/org/apache/camel/bam/BamRouteTest.java[Test
+Case], which defines the activities and rules, and then tests that they
+work.
+
+As you can see in the above example, we first define two activities, and
+then rules to specify when we expect them to complete for a process
+instance and when an error condition should be raised.p. The
+ProcessBuilder is a link:routebuilder.html[RouteBuilder] and can be
+added to any link:camelcontext.html[CamelContext].
+
+[[BAM-CompleteExample]]
+Complete Example
+^^^^^^^^^^^^^^^^
+
+For a complete example please see the link:bam-example.html[BAM
+Example], which is part of the standard Camel
+link:examples.html[Examples]
+
+[[BAM-UseCases]]
+Use Cases
+^^^^^^^^^
+
+In the world of finance, a common requirement is tracking trades. Often
+a trader will submit a Front Office Trade which then flows through the
+Middle Office and Back Office through various systems to settle the
+trade so that money is exchanged. You may wish to test that the front
+and back office trades match up within a certain time period; if they
+don't match or a back office trade does not arrive within a required
+amount of time, you might signal an alarm.