camel-beanstalk
camel-beanstalk copied to clipboard
osinka
Apache Camel component for Beanstalk
bq. This component will be "part of Apache Camel 2.15":https://github.com/osinka/camel-beanstalk/issues/8
h1. Camel component for Beanstalk
"Beanstalk":http://kr.github.com/beanstalkd/ is a simple work queue service.
"Apache Camel":http://camel.apache.org/ is an integration framework.
@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 "Beanstalk protocol":http://github.com/kr/beanstalkd/blob/v1.3/doc/protocol.txt
h2. Example
This Camel component lets you both request the jobs for processing and supply them to Beanstalkd daemon. Our simple demo routes may look like
bc. 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}");
bc. 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 failes 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.
h2. Component URI format
The component URI is
bc. beanstalk://[host[:port]][/tube]?query
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.
bc. 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.
By the way, you cannot specify several tubes when you are writing jobs into Beanstalk.
h3. Parameters
Common parameters are listed below along with the message header names. Message header always takes the highest precedence over the URI.
|. Parameter|. Header|. Unit|. Default| |@jobPriority@|beanstalk.priority|integer|1000 (0 is the highest, see "Beanstalk protocol":http://github.com/kr/beanstalkd/blob/v1.3/doc/protocol.txt)| |@jobDelay@|beanstalk.delay|seconds|0| |@jobTimeToRun@|beanstalk.timeToRun|seconds|60 (when 0, the beanstalkd daemon raises it to 1 automatically, see "Beanstalk protocol":http://github.com/kr/beanstalkd/blob/v1.3/doc/protocol.txt)|
h3. Producer parameters
Producer behaviour is affected by the @command@ parameter which tells what to do with the job, it can be
- @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.
h3. Consumer parameters
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.
The consumer stores a number of job properties in the @Exchange@:
|. Property|. Unit|_. 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|
h2. Using
For Apache Camel 2.11.x :
bc.
For Apache Camel 2.10.x :
bc.
h2. License
This component is distributed under "Apache License 2.0":http://www.apache.org/licenses/LICENSE-2.0
osinka