[[routingSlip-eip]]
= Routing Slip EIP
:docTitle: Routing Slip
:description: Routes a message through a series of steps that are pre-determined (the slip)
:since: 
:supportLevel: Stable

image::eip/RoutingTableSimple.gif[image]

TIP: See the `cacheSize` option for more details on _how much cache_ to use depending on how many or few unique endpoints are used.

== Options

// eip options: START
The Routing Slip EIP supports 3 options which are listed below:

[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *uriDelimiter* | Sets the uri delimiter to use | , | String
| *ignoreInvalidEndpoints* | Ignore the invalidate endpoint exception when try to create a producer with that endpoint | false | Boolean
| *cacheSize* | Sets the maximum size used by the org.apache.camel.spi.ProducerCache which is used to cache and reuse producers when using this routing slip, when uris are reused. Beware that when using dynamic endpoints then it affects how well the cache can be utilized. If each dynamic endpoint is unique then its best to turn of caching by setting this to -1, which allows Camel to not cache both the producers and endpoints; they are regarded as prototype scoped and will be stopped and discarded after use. This reduces memory usage as otherwise producers/endpoints are stored in memory in the caches. However if there are a high degree of dynamic endpoints that have been used before, then it can benefit to use the cache to reuse both producers and endpoints and therefore the cache size can be set accordingly or rely on the default size (1000). If there is a mix of unique and used before dynamic endpoints, then setting a reasonable cache size can help reduce memory usage to avoid storing too many non frequent used producers. |  | Integer
|===
// eip options: END

== Example
The following route will take any messages sent to the Apache ActiveMQ queue SomeQueue and pass them into the Routing Slip pattern.

[source,java]
---------------------
from("activemq:SomeQueue")
  .routingSlip("aRoutingSlipHeader");
---------------------

Messages will be checked for the existence of the `aRoutingSlipHeader` header.
The value of this header should be a comma-delimited list of endpoint URIs you wish the message to be routed to.
The Message will be routed in a pipeline fashion, i.e., one after the other. The Routing Slip sets a property, `Exchange.SLIP_ENDPOINT`, on the Exchange which contains the current endpoint as it advanced though the slip. This allows you to _know_ how far we have processed in the slip.

The Routing Slip will compute the slip *beforehand* which means, the slip is only computed once. If you need to compute the slip _on-the-fly_ then use the Dynamic Router pattern instead.

== Configuration Options
Here we set the header name and the URI delimiter to something different.

#=== Using the Fluent Builders
[source,java]
---------------------
from("direct:c").routingSlip(header("aRoutingSlipHeader"), "#");
---------------------

#=== Using the Spring XML Extensions

[source,xml]
---------------------
<camelContext id="buildRoutingSlip" xmlns="http://activemq.apache.org/camel/schema/spring">
  <route>
    <from uri="direct:c"/>
    <routingSlip uriDelimiter="#">
       <header>aRoutingSlipHeader</header>
    </routingSlip>
  </route>
</camelContext>
---------------------

== Ignore Invalid Endpoints

The Routing Slip supports ignoreInvalidEndpoints which the Recipient List also supports. You can use it to skip endpoints which are invalid.
[source,java]
---------------------
from("direct:a")
  .routingSlip("myHeader")
  .ignoreInvalidEndpoints();
---------------------

And in Spring XML its an attribute on the recipient list tag:

[source,xml]
---------------------
<route>
  <from uri="direct:a"/>
  <routingSlip ignoreInvalidEndpoints="true"/>
    <header>myHeader</header>
  </routingSlip>
</route>
---------------------

Then let's say the myHeader contains the following two endpoints direct:foo,xxx:bar. The first endpoint is valid and works. However the second endpoint is invalid and will just be ignored. Camel logs at INFO level, so you can see why the endpoint was invalid.

== Expression Support

The Routing Slip supports to take the expression parameter as the Recipient List does. You can tell Camel the expression that you want to use to get the routing slip.

[source,java]
---------------------
from("direct:a")
  .routingSlip(header("myHeader"))
  .ignoreInvalidEndpoints();
---------------------

And in Spring XML its an attribute on the recipient list tag.
[source,xml]
---------------------
<route>
  <from uri="direct:a"/>
  <!--NOTE from Camel 2.4.0, you need to specify the expression element inside of the routingSlip element -->
  <routingSlip ignoreInvalidEndpoints="true">
    <header>myHeader</header>
  </routingSlip>
</route>
---------------------

== Further Examples
For further examples of this pattern in use you could look at the routing slip test cases.

== Using This Pattern
If you would like to use this EIP Pattern then please read the Getting Started, you may also find the Architecture useful particularly the description of Endpoint and URIs. Then you could try out some of the Examples first before trying this pattern out.
