[[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]

