Added Camel-LevelDB 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/9aa27a3b Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/9aa27a3b Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/9aa27a3b Branch: refs/heads/master Commit: 9aa27a3b7a22b382442a98639fb8a7ffd13c8d89 Parents: d83af66 Author: Andrea Cosentino <[email protected]> Authored: Thu May 5 13:37:40 2016 +0200 Committer: Andrea Cosentino <[email protected]> Committed: Thu May 5 13:37:40 2016 +0200 ---------------------------------------------------------------------- .../camel-leveldb/src/main/docs/leveldb.adoc | 171 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 172 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/9aa27a3b/components/camel-leveldb/src/main/docs/leveldb.adoc ---------------------------------------------------------------------- diff --git a/components/camel-leveldb/src/main/docs/leveldb.adoc b/components/camel-leveldb/src/main/docs/leveldb.adoc new file mode 100644 index 0000000..17351d6 --- /dev/null +++ b/components/camel-leveldb/src/main/docs/leveldb.adoc @@ -0,0 +1,171 @@ +[[LevelDB-LevelDB]] +LevelDB +~~~~~~~ + +*Available as of Camel 2.10* + +https://code.google.com/p/leveldb/[Leveldb] is a very lightweight and +embedable key value database. It allows together with Camel to provide +persistent support for various Camel features such as +link:aggregator2.html[Aggregator]. + +Current features it provides: + +* LevelDBAggregationRepository + +[[LevelDB-UsingLevelDBAggregationRepository]] +Using LevelDBAggregationRepository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`LevelDBAggregationRepository` is an `AggregationRepository` which on +the fly persists the aggregated messages. This ensures that you will not +loose messages, as the default aggregator will use an in memory only +`AggregationRepository`. + +It has the following options: + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= + +|Option |Type |Description + +|`repositoryName` |String |A mandatory repository name. Allows you to use a shared `LevelDBFile` +for multiple repositories. + +|`persistentFileName` |String |Filename for the persistent storage. If no file exists on startup a new +file is created. + +|`levelDBFile` |LevelDBFile |Use an existing configured +`org.apache.camel.component.leveldb.LevelDBFile` instance. + +|`sync` |boolean |*Camel 2.12:* Whether or not the LevelDBFile should sync on write or +not. Default is false. By sync on write ensures that its always waiting +for all writes to be spooled to disk and thus will not loose updates. +See http://leveldb.googlecode.com/svn/trunk/doc/index.html[LevelDB docs] +for more details about async vs sync writes. + +|`returnOldExchange` |boolean |Whether the get operation should return the old existing Exchange if any +existed. By default this option is `false` to optimize as we do not need +the old exchange when aggregating. + +|`useRecovery` |boolean |Whether or not recovery is enabled. This option is by default `true`. +When enabled the Camel link:aggregator2.html[Aggregator] automatic +recover failed aggregated exchange and have them resubmitted. + +|`recoveryInterval` |long |If recovery is enabled then a background task is run every x'th time to +scan for failed exchanges to recover and resubmit. By default this +interval is 5000 millis. + +|`maximumRedeliveries` |int |Allows you to limit the maximum number of redelivery attempts for a +recovered exchange. If enabled then the Exchange will be moved to the +dead letter channel if all redelivery attempts failed. By default this +option is disabled. If this option is used then the `deadLetterUri` +option must also be provided. + +|`deadLetterUri` |String |An endpoint uri for a link:dead-letter-channel.html[Dead Letter Channel] +where exhausted recovered Exchanges will be moved. If this option is +used then the `maximumRedeliveries` option must also be provided. +|======================================================================= + +The `repositoryName` option must be provided. Then either the +`persistentFileName` or the `levelDBFile` must be provided. + +[[LevelDB-Whatispreservedwhenpersisting]] +What is preserved when persisting +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`LevelDBAggregationRepository` will only preserve any `Serializable` +compatible message body data types. Message headers must be primitive / +string / numbers / etc. If a data type is not such a type its dropped +and a `WARN` is logged. And it only persists the `Message` body and the +`Message` headers. The `Exchange` properties are *not* persisted. + +[[LevelDB-Recovery]] +Recovery +^^^^^^^^ + +The `LevelDBAggregationRepository` will by default recover any failed +link:exchange.html[Exchange]. It does this by having a background tasks +that scans for failed link:exchange.html[Exchange]s in the persistent +store. You can use the `checkInterval` option to set how often this task +runs. The recovery works as transactional which ensures that Camel will +try to recover and redeliver the failed link:exchange.html[Exchange]. +Any link:exchange.html[Exchange] which was found to be recovered will be +restored from the persistent store and resubmitted and send out again. + +The following headers is set when an link:exchange.html[Exchange] is +being recovered/redelivered: + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Header |Type |Description + +|`Exchange.REDELIVERED` |Boolean |Is set to true to indicate the link:exchange.html[Exchange] is being +redelivered. + +|`Exchange.REDELIVERY_COUNTER` |Integer |The redelivery attempt, starting from 1. +|======================================================================= + +Only when an link:exchange.html[Exchange] has been successfully +processed it will be marked as complete which happens when the `confirm` +method is invoked on the `AggregationRepository`. This means if the same +link:exchange.html[Exchange] fails again it will be kept retried until +it success. + +You can use option `maximumRedeliveries` to limit the maximum number of +redelivery attempts for a given recovered link:exchange.html[Exchange]. +You must also set the `deadLetterUri` option so Camel knows where to +send the link:exchange.html[Exchange] when the `maximumRedeliveries` was +hit. + +You can see some examples in the unit tests of camel-leveldb, for +example +https://svn.apache.org/repos/asf/camel/trunk/components/camel-leveldb/src/test/java/org/apache/camel/component/leveldb/LevelDBAggregateRecoverTest.java[this +test]. + +[[LevelDB-UsingLevelDBAggregationRepositoryinJavaDSL]] +Using LevelDBAggregationRepository in Java DSL +++++++++++++++++++++++++++++++++++++++++++++++ + +In this example we want to persist aggregated messages in the +`target/data/leveldb.dat` file. + +[[LevelDB-UsingLevelDBAggregationRepositoryinSpringXML]] +Using LevelDBAggregationRepository in Spring XML +++++++++++++++++++++++++++++++++++++++++++++++++ + +The same example but using Spring XML instead: + +[[LevelDB-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +To use link:leveldb.html[LevelDB] in your camel routes you need to add +the a dependency on *camel-leveldb*. + +If you use maven you could just add the following to your pom.xml, +substituting the version number for the latest & greatest release (see +link:download.html[the download page for the latest versions]). + +[source,xml] +---------------------------------------- +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-leveldb</artifactId> + <version>2.10.0</version> +</dependency> +---------------------------------------- + +[[LevelDB-SeeAlso]] +See Also +^^^^^^^^ + +* link:configuring-camel.html[Configuring Camel] +* link:component.html[Component] +* link:endpoint.html[Endpoint] +* link:getting-started.html[Getting Started] + +* link:aggregator2.html[Aggregator] +* link:hawtdb.html[HawtDB] +* link:components.html[Components] + http://git-wip-us.apache.org/repos/asf/camel/blob/9aa27a3b/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 86f524d..5cad8b7 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -182,6 +182,7 @@ * [Kubernetes](kubernetes.adoc) * [Kura](kura.adoc) * [LDAP](ldap.adoc) + * [LevelDB](leveldb.adoc) * [Metrics](metrics.adoc) * [Mock](mock.adoc) * [NATS](nats.adoc)
