camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acosent...@apache.org
Subject [1/2] camel git commit: SJMS Batch component Asciidoc documentation
Date Wed, 27 Jan 2016 07:40:27 GMT
Repository: camel
Updated Branches:
  refs/heads/master b3c02c4cc -> 00cab0031


SJMS Batch component Asciidoc documentation


Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/00cab003
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/00cab003
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/00cab003

Branch: refs/heads/master
Commit: 00cab003130db9339eafb4030a9eba9363fa17d6
Parents: becced0
Author: Antonin Stefanutti <antonin@stefanutti.fr>
Authored: Tue Jan 26 19:17:13 2016 +0100
Committer: Andrea Cosentino <ancosen@gmail.com>
Committed: Wed Jan 27 08:39:10 2016 +0100

----------------------------------------------------------------------
 .../camel-sjms/src/main/docs/sjms-batch.adoc    | 158 +++++++++++++++++++
 docs/user-manual/en/SUMMARY.md                  |   1 +
 2 files changed, 159 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/00cab003/components/camel-sjms/src/main/docs/sjms-batch.adoc
----------------------------------------------------------------------
diff --git a/components/camel-sjms/src/main/docs/sjms-batch.adoc b/components/camel-sjms/src/main/docs/sjms-batch.adoc
new file mode 100644
index 0000000..1dc2892
--- /dev/null
+++ b/components/camel-sjms/src/main/docs/sjms-batch.adoc
@@ -0,0 +1,158 @@
+[[ConfluenceContent]]
+[[SJMSBatch-SJMSBatchComponent]]
+SJMS Batch Component
+~~~~~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.16*
+
+SJMS Batch is a specialized component for highly performant,
+transactional batch consumption from a JMS queue. It can be thought of
+as a hybrid of a consumer-only component and an
+link:aggregator2.html[aggregator].
+
+A common use case in Camel is to consume messages from a queue and
+aggregate them before sending the aggregated state to another endpoint.
+In order to ensure that data is not lost if the system performing the
+processing fails, it is typically consumed within a transaction from the
+queue, and once aggregated stored in a persistent
+`AggregationRepository`, such as the one found in the
+link:jdbc.html[JDBC Component].
+
+The behavior of the aggregator pattern involves fetching data from the
+`AggregationRepository` before an incoming message is aggregated, and
+writing back the result afterwards. By nature, the reads and writes take
+progressively longer as the number of aggregated artifacts increases. A
+rough example of this using arbitrary time units that demonstrates the
+impact of this is as follows:
+
+[cols=",,,",options="header",]
+|=======================================
+|Item |Read Time |Write Time |Total Time
+|0 |0 |1 |1
+|1 |1 |2 |4
+|2 |2 |3 |9
+|3 |3 |4 |16
+|4 |4 |5 |25
+|5 |5 |6 |36
+|6 |6 |7 |49
+|7 |7 |8 |64
+|8 |8 |9 |81
+|9 |9 |10 |100
+|=======================================
+
+In contrast, consumption performance using the SJMS Batch component is
+linear. Each message is consumed and aggregated using an
+`AggregationStrategy` before the next one is fetched. As all of the
+consumption and aggregation is performed in a single JMS transaction no
+external storage is required to persist the intermediate state - this
+avoids the read and write costs described above. In practice, this
+yields multiple orders of magnitude higher throughput.
+
+Once a completion condition is met, either by size or period since first
+message, the aggregated `Exchange` is passed into the route. During the
+processing of this `Exchange`, if an exception is thrown or the system
+shuts down, all of the original consumed messages end up back on the
+queue (or are placed on the dead-letter queue depending on the broker
+configuration).
+
+Unlike using a regular aggregator, there is no facility for an
+aggregation condition, meaning that it is not possible to batch consume
+into multiple groups of messages. All consumed messages are aggregated
+together into a single batch.
+
+Multiple JMS consumer support is available which allows you to consume
+in parallel using the one route, and at the same time use facilities
+like JMS message groups to group related messages.
+
+ 
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this component:
+
+[source,xml]
+----
+<dependency>
+    <groupId>org.apache.camel</groupId>
+    <artifactId>camel-sjms</artifactId>
+    <version>x.x.x</version>
+    <!-- use the same version as your Camel core version -->
+</dependency>
+----
+
+[[SJMSBatch-URIformat]]
+URI format
+++++++++++
+
+[source]
+----
+sjms:[queue:]destinationName[?options]
+----
+
+Where `destinationName` is a JMS queue. By default, the
+`destinationName` is interpreted as a queue name.
+
+[source]
+----
+sjms:FOO.BAR
+----
+
+You can include the optional `queue:` prefix, if you prefer:
+
+[source]
+----
+sjms:queue:FOO.BAR
+----
+
+Topic consumption is not supported, as there is no advantage to using
+batch consumption within that context. Topic messages are usually
+non-persistent, and loss is acceptable. If consumed within a transaction
+that fails, a topic message will likely not be redelivered by the
+broker. A plain link:sjms.html[SJMS] consumer endpoint can be used in
+conjunction with a regular non-persistence backed
+link:aggregator2.html[aggregator] in this scenario.
+
+[[SJMSBatch-ComponentOptionsandConfigurations]]
+Component Options and Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The SJMS Batch Component supports the following configuration options:
+
+[width="100%",cols="10%,10%,10%,80%",options="header",]
+|=======================================================================
+|Option |Required |Default Value |Description
+|`aggregationStrategy`
+| icon:check[]
+|`null` |A reference to an `AggregationStrategy` in the Camel registry
+(e.g. `#myAggregationStrategy`)
+
+|`completionSize` |  |`200` a|
+The size of the batch to aggregate.
+
+Care should be taken to ensure that this is not larger than the JMS
+consumer's prefetch buffer, or the maximum page size for a queue on the
+broker; either of these could cause the consumer to hang if no timeout
+is used.
+
+A value of 0 or less indicates that `completionTimeout` only should be
+used.
+
+|`completionTimeout` |  |`500` a|
+The maximum time to wait from the receipt of the first message before
+emitting the Exchange.
+
+A value of 0 or less indicates that `completionSize` only should be
+used.
+
+|`pollDuration` |  |`1000` a|
+The maximum length of a call to `MessageConsumer.receive()`. The time
+remaining before timeout takes precedence within a batch.
+
+This value is effectively the poll time between batches.
+
+|=======================================================================
+
+The `completionSize` endpoint attribute is used in conjunction with
+`completionTimeout`, where the first condition to be met will cause the
+aggregated `Exchange` to be emitted down the route.
+
+ 

http://git-wip-us.apache.org/repos/asf/camel/blob/00cab003/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 802924c..aa03636 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -94,6 +94,7 @@
 	* [JMS](jms.adoc)
 	* [Metrics](metrics.adoc)
 	* [SJMS](sjms.adoc) 
+	* [SJMS Batch](sjms-batch.adoc) 
 
 <!--
 * [Expession Languages](languages.adoc)


Mime
View raw message