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 <[email protected]> Authored: Wed Jan 27 13:42:54 2016 +0100 Committer: Andrea Cosentino <[email protected]> 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)
