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/01/26 16:47:53 UTC
camel git commit: Added camel-bam docs to gitbook
Repository: camel
Updated Branches:
refs/heads/master 851c2a96c -> cff089ee6
Added camel-bam docs to gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/cff089ee
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/cff089ee
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/cff089ee
Branch: refs/heads/master
Commit: cff089ee61b75143d8aabe10c4f97a65221b0d33
Parents: 851c2a9
Author: Andrea Cosentino <an...@gmail.com>
Authored: Tue Jan 26 16:47:12 2016 +0100
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Tue Jan 26 16:47:34 2016 +0100
----------------------------------------------------------------------
.../camel-bam/src/main/docs/bam-example.adoc | 97 ++++++++++++++++++++
components/camel-bam/src/main/docs/bam.adoc | 85 +++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
3 files changed, 183 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/cff089ee/components/camel-bam/src/main/docs/bam-example.adoc
----------------------------------------------------------------------
diff --git a/components/camel-bam/src/main/docs/bam-example.adoc b/components/camel-bam/src/main/docs/bam-example.adoc
new file mode 100644
index 0000000..072607e
--- /dev/null
+++ b/components/camel-bam/src/main/docs/bam-example.adoc
@@ -0,0 +1,97 @@
+[[BAMExample-BusinessActivityMonitor(BAM)Example]]
+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]
+
+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,java]
+-----------------------------
+cd examples/camel-example-bam
+mvn camel:run
+-----------------------------
+
+If you prefer you can just run the Main directly using
+
+[source,java]
+---------------------
+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/cff089ee/components/camel-bam/src/main/docs/bam.adoc
----------------------------------------------------------------------
diff --git a/components/camel-bam/src/main/docs/bam.adoc b/components/camel-bam/src/main/docs/bam.adoc
new file mode 100644
index 0000000..e6ef9e0
--- /dev/null
+++ b/components/camel-bam/src/main/docs/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).
+
+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.
+
+[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");
+ }
+};
+-------------------------------------------------
+
+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:examples/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.
http://git-wip-us.apache.org/repos/asf/camel/blob/cff089ee/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index fe0852b..5901f26 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -88,6 +88,7 @@
* [AWS SNS](aws-sns.adoc)
* [AWS SQS](aws-sqs.adoc)
* [AWS SWF](aws-swf.adoc)
+ * [Bam](bam.adoc)
* [CDI](cdi.adoc)
* [JMS](jms.adoc)
* [Metrics](metrics.adoc)