= Beanstalk Component
:doctitle: Beanstalk
:shortname: beanstalk
:artifactid: camel-beanstalk
:description: Retrieve and post-process Beanstalk jobs.
:since: 2.15
:supportlevel: Stable
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:camel-spring-boot-name: beanstalk

*Since Camel {since}*

*{component-header}*

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

== 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.

== URI format

------------------------------------------
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.

---------------------------------------
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 xref:manual:faq:how-do-i-configure-endpoints.adoc[more
details here].

By the way, you cannot specify several tubes when you are writing jobs
into Beanstalk.

// component-configure options: START

// component-configure options: END

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
// component options: END

// endpoint options: START

// endpoint options: END



Producer behavior is affected by the `command` parameter which tells
what to do with the job, it can be

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 `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 `onFailure` parameter in the URI. It can take values
of `bury`, `delete` or `release`.

There is a boolean parameter `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.

The beanstalk consumer is a Scheduled xref:eips:polling-consumer.adoc[Polling
Consumer] which means there is more options you can configure, such as
how frequent the consumer should poll. For more details
see Polling Consumer.

== 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
|=======================================================================

== 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 #${exchangeProperty.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 #${exchangeProperty.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.




include::spring-boot:partial$starter.adoc[]
