[[kestrel-component]]
= Kestrel Component (deprecated)
:page-source: components/camel-kestrel/src/main/docs/kestrel-component.adoc

*Available as of Camel version 2.6*


The Kestrel component allows messages to be sent to a
https://github.com/robey/kestrel[Kestrel] queue, or messages to be
consumed from a Kestrel queue. This component uses the
http://code.google.com/p/spymemcached/[spymemcached] client for
memcached protocol communication with Kestrel servers.

WARNING: The kestrel project is inactive and the Camel team regard this
components as deprecated.


== URI format

[source,java]
-------------------------------------------
kestrel://[addresslist/]queuename[?options]
-------------------------------------------

Where *queuename* is the name of the queue on Kestrel. The *addresslist*
part of the URI may include one or more `host:port` pairs. For example,
to connect to the queue `foo` on `kserver01:22133`, use:

[source,java]
-----------------------------
kestrel://kserver01:22133/foo
-----------------------------

If the addresslist is omitted, `localhost:22133` is assumed, i.e.:

[source,java]
-------------
kestrel://foo
-------------

Likewise, if a port is omitted from a `host:port` pair in addresslist,
the default port 22133 is assumed, i.e.:

[source,java]
-----------------------
kestrel://kserver01/foo
-----------------------

Here is an example of a Kestrel endpoint URI used for producing to a
clustered queue:

[source,java]
-----------------------------------------------------------------
kestrel://kserver01:22133,kserver02:22133,kserver03:22133/massive
-----------------------------------------------------------------

Here is an example of a Kestrel endpoint URI used for consuming
concurrently from a queue:

[source,java]
-----------------------------------------------------------------------
kestrel://kserver03:22133/massive?concurrentConsumers=25&waitTimeMs=500
-----------------------------------------------------------------------

== Options





// component options: START
The Kestrel component supports 2 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *configuration* (advanced) | To use a shared configured configuration as base for creating new endpoints. |  | KestrelConfiguration
| *resolveProperty Placeholders* (advanced) | Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders. | true | boolean
|===
// component options: END







// endpoint options: START
The Kestrel endpoint is configured using URI syntax:

----
kestrel:addresses/queue
----

with the following path and query parameters:

=== Path Parameters (2 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *addresses* | The address(es) on which kestrel is running | localhost:22133 | String[]
| *queue* | *Required* The queue we are polling |  | String
|===


=== Query Parameters (6 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *concurrentConsumers* (common) | How many concurrent listeners to schedule for the thread pool | 1 | int
| *waitTimeMs* (common) | How long a given wait should block (server side), in milliseconds | 100 | int
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
| *exceptionHandler* (consumer) | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. |  | ExceptionHandler
| *exchangePattern* (consumer) | Sets the exchange pattern when the consumer creates an exchange. |  | ExchangePattern
| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean
|===
// endpoint options: END
// spring-boot-auto-configure options: START
== Spring Boot Auto-Configuration

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

[source,xml]
----
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-kestrel-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----


The component supports 5 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.component.kestrel.configuration.addresses* | The address(es) on which kestrel is running |  | String[]
| *camel.component.kestrel.configuration.concurrent-consumers* | How many concurrent listeners to schedule for the thread pool | 1 | Integer
| *camel.component.kestrel.configuration.wait-time-ms* | How long a given wait should block (server side), in milliseconds | 100 | Integer
| *camel.component.kestrel.enabled* | Enable kestrel component | true | Boolean
| *camel.component.kestrel.resolve-property-placeholders* | Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders. | true | Boolean
|===
// spring-boot-auto-configure options: END




== Configuring the Kestrel component using Spring XML

The simplest form of explicit configuration is as follows:

[source,xml]
---------------------------------------------------------------------------------------------------------------
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

  <bean id="kestrel" class="org.apache.camel.component.kestrel.KestrelComponent"/>

  <camelContext xmlns="http://camel.apache.org/schema/spring">
  </camelContext>

</beans>
---------------------------------------------------------------------------------------------------------------

That will enable the Kestrel component with all default settings, i.e.
it will use `localhost:22133`, 100ms wait time, and a single
non-concurrent consumer by default.

To use specific options in the base configuration (which supplies
configuration to endpoints whose `?properties` are not specified), you
can set up a KestrelConfiguration POJO as follows:

[source,xml]
---------------------------------------------------------------------------------------------------------------
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

  <bean id="kestrelConfiguration" class="org.apache.camel.component.kestrel.KestrelConfiguration">
    <property name="addresses" value="kestrel01:22133"/>
    <property name="waitTimeMs" value="100"/>
    <property name="concurrentConsumers" value="1"/>
  </bean>

  <bean id="kestrel" class="org.apache.camel.component.kestrel.KestrelComponent">
    <property name="configuration" ref="kestrelConfiguration"/>
  </bean>

  <camelContext xmlns="http://camel.apache.org/schema/spring">
  </camelContext>

</beans>
---------------------------------------------------------------------------------------------------------------

== Usage Examples

=== Example 1: Consuming

[source,java]
-------------------------------------------------------------------------------
from("kestrel://kserver02:22133/massive?concurrentConsumers=10&waitTimeMs=500")
  .bean("myConsumer", "onMessage");
-------------------------------------------------------------------------------

[source,java]
-------------------------------------------
public class MyConsumer {
    public void onMessage(String message) {
        ...
    }
}
-------------------------------------------

=== Example 2: Producing

[source,java]
------------------------------------------------------------------------------
public class MyProducer {
    @EndpointInject(uri = "kestrel://kserver01:22133,kserver02:22133/myqueue")
    ProducerTemplate producerTemplate;

    public void produceSomething() {
        producerTemplate.sendBody("Hello, world.");
    }
}
------------------------------------------------------------------------------

=== Example 3: Spring XML Configuration

[source,xml]
----------------------------------------------------------------------------------------
  <camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
      <from uri="kestrel://ks01:22133/sequential?concurrentConsumers=1&waitTimeMs=500"/>
      <bean ref="myBean" method="onMessage"/>
    </route>
    <route>
      <from uri="direct:start"/>
      <to uri="kestrel://ks02:22133/stuff"/>
    </route>
  </camelContext>
----------------------------------------------------------------------------------------

[source,java]
-------------------------------------------
public class MyBean {
    public void onMessage(String message) {
        ...
    }
}
-------------------------------------------

== Dependencies

The Kestrel component has the following dependencies:

* `spymemcached` 2.5 (or greater)

=== spymemcached

You *must* have the `spymemcached` jar on your classpath. Here is a
snippet you can use in your pom.xml:

[source,java]
------------------------------------
<dependency>
  <groupId>spy</groupId>
  <artifactId>memcached</artifactId>
  <version>2.5</version>
</dependency>
------------------------------------

Alternatively, you can
http://code.google.com/p/spymemcached/downloads/list[download the jar]
directly.

Warning: Limitations

NOTE: The spymemcached client library does *not* work properly with
kestrel when JVM assertions are enabled. There is a known issue with
spymemcached when assertions are enabled and a requested key contains
the `/t=...` extension (i.e. if you're using the `waitTimeMs` option on
an endpoint URI, which is highly encouraged).
Fortunately, JVM assertions are *disabled by default*, unless you
http://download.oracle.com/javase/1.4.2/docs/guide/lang/assert.html[explicitly
enable them], so this should not present a problem under normal
circumstances.
Something to note is that Maven's Surefire test plugin *enables*
assertions. If you're using this component in a Maven test environment,
you may need to set `enableAssertions` to `false`. Please refer to the
http://maven.apache.org/plugins/maven-surefire-plugin/test-mojo.html[surefire:test
reference] for details.