[[choice-eip]]
= Choice EIP
:docTitle: Choice
:description: Routes messages based on a series of predicates
:since: 
:supportLevel: Stable

The
http://www.enterpriseintegrationpatterns.com/ContentBasedRouter.html[Content
Based Router] from the xref:enterprise-integration-patterns.adoc[EIP
patterns] allows you to route messages to the correct destination based
on the contents of the message exchanges.

image::eip/ContentBasedRouter.gif[image]

== Choice options

// eip options: START
The Choice EIP supports 2 options which are listed below:

[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *whenClauses* | Sets the when clauses |  | List
| *otherwise* | Sets the otherwise node |  | OtherwiseDefinition
|===
// eip options: END

== Examples

The following example shows how to route a request from an input
*seda:a* endpoint to either *seda:b*, *seda:c* or *seda:d* depending on
the evaluation of various xref:latest@manual:ROOT:predicate.adoc[Predicate] expressions

[source,java]
----
RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        from("direct:a")
            .choice()
                .when(simple("${header.foo} == 'bar'"))
                    .to("direct:b")
                .when(simple("${header.foo} == 'cheese'"))
                    .to("direct:c")
                .otherwise()
                    .to("direct:d");
    }
};

----


And the same example using XML:

[source,xml]
----
<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="direct:a"/>
        <choice>
            <when>
                <simple>${header.foo} == 'bar'</simple>
                <to uri="direct:b"/>
            </when>
            <when>
                <simple>${header.foo} == 'cheese'</simple>
                <to uri="direct:c"/>
            </when>
            <otherwise>
                <to uri="direct:d"/>
            </otherwise>
        </choice>
    </route>
</camelContext>
----

== Usage of endChoice and end
Usage of `endChoice` is not mandatory. However, It should be used whenever you want to return back control to `choice()` dsl so that you can add subsequent `when` and `otherwise` to the choice dsl.
If you want to end entire `choice()` block use `end()`.

=== Example

[source,java]
----

    @Override
    protected RouteBuilder createRouteBuilder() throws Exception {
        return new RouteBuilder() {
            @Override
            public void configure() throws Exception {
                from("direct:start")
                    .choice()
                        .when(body().contains("Camel"))
                        .multicast()
                            .to("mock:foo")
                            .to("mock:bar")
                        .endChoice() //we need to use endChoice to tell Java DSL to return scope back to the choice DSL.
                        .otherwise() 
                            .to("mock:result");
            }
        };
    }
    
----

Another example is explained in the TIP below.

[TIP]
====
See xref:latest@manual:faq:why-can-i-not-use-when-or-otherwise-in-a-java-camel-route.adoc[Why
can I not use when or otherwise in a Java Camel route] if you have
problems with the Java DSL, accepting using `when` or `otherwise`.
====

