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/27 13:43:41 UTC
camel git commit: Added camel-beanstalk docs to gitbook
Repository: camel
Updated Branches:
refs/heads/master 4979edfc0 -> ab7aca061
Added camel-beanstalk 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/ab7aca06
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/ab7aca06
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/ab7aca06
Branch: refs/heads/master
Commit: ab7aca06107e0d8df7df4a77083c1e9cd24292a6
Parents: 4979edf
Author: Andrea Cosentino <an...@gmail.com>
Authored: Wed Jan 27 13:42:54 2016 +0100
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Wed Jan 27 13:42:54 2016 +0100
----------------------------------------------------------------------
.../src/main/docs/beanstalk.adoc | 228 +++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 229 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/ab7aca06/components/camel-beanstalk/src/main/docs/beanstalk.adoc
----------------------------------------------------------------------
diff --git a/components/camel-beanstalk/src/main/docs/beanstalk.adoc b/components/camel-beanstalk/src/main/docs/beanstalk.adoc
new file mode 100644
index 0000000..a1df59b
--- /dev/null
+++ b/components/camel-beanstalk/src/main/docs/beanstalk.adoc
@@ -0,0 +1,228 @@
+[[Beanstalk-Beanstalkcomponent]]
+Beanstalk component
+~~~~~~~~~~~~~~~~~~~
+
+*Available in Camel 2.15*
+
+camel-beanstalk project provides a Camel component for job retrieval and
+post-processing of Beanstalk jobs.
+
+You can find the detailed explanation of Beanstalk job lifecycle
+at http://github.com/kr/beanstalkd/blob/v1.3/doc/protocol.txt[Beanstalk
+protocol].
+
+[[Beanstalk-Dependencies]]
+Dependencies
+^^^^^^^^^^^^
+
+Maven users need to add the following dependency to their `pom.xml`
+
+[source,xml]
+------------------------------------------
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-beanstalk</artifactId>
+ <version>${camel-version}</version>
+</dependency>
+------------------------------------------
+
+where `${camel-version`} must be replaced by the actual version of Camel
+(2.15.0 or higher).
+
+[[Beanstalk-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,xml]
+------------------------------------------
+beanstalk://[host[:port]][/tube][?options]
+------------------------------------------
+
+You may omit either `port` or both `host` and `port`: for the Beanstalk
+defaults to be used (“localhost” and 11300). If you omit `tube`,
+Beanstalk component will use the tube with name “default”.
+
+When listening, you may probably want to watch for jobs from several
+tubes. Just separate them with plus sign, e.g.
+
+[source,java]
+---------------------------------------
+beanstalk://localhost:11300/tube1+tube2
+---------------------------------------
+
+Tube name will be URL decoded, so if your tube names include special
+characters like + or ?, you need to URL-encode them appropriately, or
+use the RAW syntax, see link:how-do-i-configure-endpoints.html[more
+details here].
+
+By the way, you cannot specify several tubes when you are writing jobs
+into Beanstalk.
+
+[[Beanstalk-CommonURIoptions]]
+Common URI options
+^^^^^^^^^^^^^^^^^^
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Name |Default value |Description
+
+|jobPriority |1000 |Job priority. (0 is the highest,
+see http://github.com/kr/beanstalkd/blob/v1.3/doc/protocol.txt[Beanstalk
+protocol])
+
+|jobDelay |0 |Job delay in seconds.
+
+|jobTimeToRun |60 |Job time to run in seconds. (when 0, the beanstalkd daemon raises it to
+1 automatically,
+see http://github.com/kr/beanstalkd/blob/v1.3/doc/protocol.txt[Beanstalk
+protocol])
+
+|=======================================================================
+
+
+[[Beanstalk-ProducerUIRoptions]]
+Producer URI options
+^^^^^^^^^^^^^^^^^^^^
+
+Producer behavior is affected by the `command` parameter which tells
+what to do with the job, it can be
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Name |Default value |Description
+
+|command |put |* `put` means to put the job into Beanstalk. Job body is specified in
+the Camel message body. Job ID will be returned
+in _beanstalk.jobId_ message header.
+* `delete`, `release`, `touch` or `bury` expect Job ID in the message
+header _beanstalk.jobId_. Result of the operation is returned
+in _beanstalk.result_ message header
+* `kick` expects the number of jobs to kick in the message body and
+returns the number of jobs actually kicked out in the message
+header _beanstalk.result_.
+|=======================================================================
+
+
+[[Beanstalk-ConsumerUIRoptions]]
+Consumer UIR options
+^^^^^^^^^^^^^^^^^^^^
+
+The consumer may delete the job immediately after reserving it or wait
+until Camel routes process it. While the first scenario is more like a
+“message queue”, the second is similar to “job queue”. This behavior is
+controlled by `consumer.awaitJob` parameter, which equals `true` by
+default (following Beanstalkd nature).
+
+When synchronous, the consumer calls `delete` on successful job
+completion and calls `bury` on failure. You can choose which command to
+execute in the case of failure by
+specifying `consumer.onFailure` parameter in the URI. It can take values
+of `bury`, `delete` or `release`.
+
+There is a boolean parameter `consumer.useBlockIO` which corresponds to
+the same parameter in JavaBeanstalkClient library. By default it
+is `true`.
+
+Be careful when specifying `release`, as the failed job will immediately
+become available in the same tube and your consumer will try to acquire
+it again. You can `release` and specify _jobDelay_ though.
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Name |Default value |Description
+
+|onFailure |bury |Command to use when processing failed. You can choose among: bury,
+delete or release.
+
+|useBlockIO |true |Whether to use blockIO.
+
+|awaitJob |true |Whether to wait for job to complete before ack the job from beanstalk
+|=======================================================================
+
+The beanstalk consumer is a Scheduled link:polling-consumer.html[Polling
+Consumer] which means there is more options you can configure, such as
+how frequent the consumer should poll. For more details
+see link:polling-consumer.html[Polling Consumer].
+
+[[Beanstalk-ConsumerHeaders]]
+Consumer Headers
+^^^^^^^^^^^^^^^^
+
+The consumer stores a number of job headers in the Exchange message:
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Property |Type |Description
+
+|_beanstalk.jobId_ |long | Job ID
+
+|_beanstalk.tube_ |string |the name of the tube that contains this job
+
+|_beanstalk.state_ |string |“ready” or “delayed” or “reserved” or “buried” (must be “reserved”)
+
+|_beanstalk.priority_ |long |the priority value set
+
+|_beanstalk.age_ |int |the time in seconds since the put command that created this job
+
+|_beanstalk.time-left_ |int |the number of seconds left until the server puts this job into the ready
+queue
+
+|_beanstalk.timeouts_ |int |the number of times this job has timed out during a reservation
+
+|_beanstalk.releases_ |int |the number of times a client has released this job from a reservation
+
+|_beanstalk.buries_ |int |the number of times this job has been buried
+
+|_beanstalk.kicks_ |int |the number of times this job has been kicked
+|=======================================================================
+
+[[Beanstalk-Examples]]
+Examples
+^^^^^^^^
+
+This Camel component lets you both request the jobs for processing and
+supply them to Beanstalkd daemon. Our simple demo routes may look like
+
+[source,java]
+----------------------------------------------------------------------------------------------
+from("beanstalk:testTube").
+ log("Processing job #${property.beanstalk.jobId} with body ${in.body}").
+ process(new Processor() {
+ @Override
+ public void process(Exchange exchange) {
+ // try to make integer value out of body
+ exchange.getIn().setBody( Integer.valueOf(exchange.getIn().getBody(classOf[String])) );
+ }
+ }).
+ log("Parsed job #${property.beanstalk.jobId} to body ${in.body}");
+----------------------------------------------------------------------------------------------
+
+[source,java]
+---------------------------------------------------------------------
+from("timer:dig?period=30seconds").
+ setBody(constant(10)).log("Kick ${in.body} buried/delayed tasks").
+ to("beanstalk:testTube?command=kick");
+---------------------------------------------------------------------
+
+In the first route we are listening for new jobs in tube “testTube”.
+When they are arriving, we are trying to parse integer value from the
+message body. If done successful, we log it and this successful exchange
+completion makes Camel component to _delete_ this job from Beanstalk
+automatically. Contrary, when we cannot parse the job data, the exchange
+failed and the Camel component _buries_ it by default, so that it can be
+processed later or probably we are going to inspect failed jobs
+manually.
+
+So the second route periodically requests Beanstalk to _kick_ 10 jobs
+out of buried and/or delayed state to the normal queue.
+
+
+
+[[Beanstalk-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:configuring-camel.html[Configuring Camel]
+* link:component.html[Component]
+* link:endpoint.html[Endpoint]
+* link:getting-started.html[Getting Started]
+
http://git-wip-us.apache.org/repos/asf/camel/blob/ab7aca06/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index e9a8d17..8f0cef5 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -92,6 +92,7 @@
* [Barcode](barcode-data-format.adoc)
* [Base64](base64.adoc)
* [BeanIO](beanio.adoc)
+ * [Beanstalk](beanstalk.adoc)
* [CDI](cdi.adoc)
* [JMS](jms.adoc)
* [Metrics](metrics.adoc)