CookBook

This document describes various recipes for working with Camel

Bean Integration

Camel supports the integration of beans and POJOs in a number of ways

Annotations

If a bean is defined in Spring XML or scanned using the Spring component scanning mechanism and a <camelContext> is used or a CamelBeanPostProcessor then we process a number of Camel annotations to do various things such as injecting resources or producing, consuming or routing messages.

The following annotations is supported and inject by Camel's CamelBeanPostProcessor

Annotation

Description

@EndpointInject

To inject an endpoint, see more details at POJO Producing.

@BeanInject

Camel 2.13: To inject a bean obtained from the Registry. See Bean Injection.

@PropertyInject

Camel 2.12: To inject a value using property placeholder.

@Produce

To inject a producer to send message to an endpoint. See POJO Producing.

@Consume

To inject a consumer on a method. See POJO Consuming.

See more details at:

Example

See the POJO Messaging Example for how to use the annotations for routing and messaging.

Bean Component

The Bean component allows one to invoke a particular method. Alternately the Bean component supports the creation of a proxy via ProxyHelper to a Java interface; which the implementation just sends a message containing a BeanInvocation to some Camel endpoint.

Spring Remoting

We support a Spring Remoting provider which uses Camel as the underlying transport mechanism. The nice thing about this approach is we can use any of the Camel transport Components to communicate between beans. It also means we can use Content Based Router and the other Enterprise Integration Patterns in between the beans; in particular we can use Message Translator to be able to convert what the on-the-wire messages look like in addition to adding various headers and so forth.

Bean binding

Whenever Camel invokes a bean method via one of the above methods (Bean component, Spring Remoting or POJO Consuming) then the Bean Binding mechanism is used to figure out what method to use (if it is not explicit) and how to bind the Message to the parameters possibly using the Parameter Binding Annotations or using a method name option.

Error rendering macro 'include'

org.owasp.validator.html.ScanException: java.util.EmptyStackException

Bean Binding

Bean Binding in Camel defines both which methods are invoked and also how the Message is converted into the parameters of the method when it is invoked.

Choosing the method to invoke

The binding of a Camel Message to a bean method call can occur in different ways, in the following order of importance:

  • if the message contains the header CamelBeanMethodName then that method is invoked, converting the body to the type of the method's argument.
    • From Camel 2.8 onwards you can qualify parameter types to select exactly which method to use among overloads with the same name (see below for more details).
    • From Camel 2.9 onwards you can specify parameter values directly in the method option (see below for more details).
  • you can explicitly specify the method name in the DSL or when using POJO Consuming or POJO Producing
  • if the bean has a method marked with the @Handler annotation, then that method is selected
  • if the bean can be converted to a Processor using the Type Converter mechanism, then this is used to process the message. The ActiveMQ component uses this mechanism to allow any JMS MessageListener to be invoked directly by Camel without having to write any integration glue code. You can use the same mechanism to integrate Camel into any other messaging/remoting frameworks.
  • if the body of the message can be converted to a BeanInvocation (the default payload used by the ProxyHelper) component - then that is used to invoke the method and pass its arguments
  • otherwise the type of the body is used to find a matching method; an error is thrown if a single method cannot be chosen unambiguously.
  • you can also use Exchange as the parameter itself, but then the return type must be void.
  • if the bean class is private (or package-private), interface methods will be preferred (from Camel 2.9 onwards) since Camel can't invoke class methods on such beans

In cases where Camel cannot choose a method to invoke, an AmbiguousMethodCallException is thrown.

By default the return value is set on the outbound message body. 

Asynchronous processing

From Camel 2.18 onwards you can return a CompletionStage implementation (e.g. a CompletableFuture) to implement asynchronous processing.

Please be sure to properly complete the CompletionStage with the result or exception, including any timeout handling. Exchange processing would wait for completion and would not impose any timeouts automatically. It's extremely useful to monitor Inflight repository for any hanging messages.

Note that completing with "null" won't set outbody message body to null, but would keep message intact. This is useful to support methods that don't modify exchange and return CompletableFuture<Void>. To set body to null, just add Exchange method parameter and directly modify exchange messages.

Examples:

Simple asynchronous processor, modifying message body.

public CompletableFuture<String> doSomethingAsync(String body)


Composite processor that do not modify exchange

 public CompletableFuture<Void> doSomethingAsync(String body) {
     return CompletableFuture.allOf(doA(body), doB(body), doC()); 
 }


Parameter binding

When a method has been chosen for invocation, Camel will bind to the parameters of the method.

The following Camel-specific types are automatically bound:

  • org.apache.camel.Exchange
  • org.apache.camel.Message
  • org.apache.camel.CamelContext
  • org.apache.camel.TypeConverter
  • org.apache.camel.spi.Registry
  • java.lang.Exception

So, if you declare any of these types, they will be provided by Camel. Note that Exception will bind to the caught exception of the Exchange - so it's often usable if you employ a Pojo to handle, e.g., an onException route.

What is most interesting is that Camel will also try to bind the body of the Exchange to the first parameter of the method signature (albeit not of any of the types above). So if, for instance, we declare a parameter as String body, then Camel will bind the IN body to this type. Camel will also automatically convert to the type declared in the method signature.

Let's review some examples:

Below is a simple method with a body binding. Camel will bind the IN body to the body parameter and convert it to a String.

public String doSomething(String body)

In the following sample we got one of the automatically-bound types as well - for instance, a Registry that we can use to lookup beans.

public String doSomething(String body, Registry registry) 


We can use Exchange as well:

public String doSomething(String body, Exchange exchange) 


You can also have multiple types:

public String doSomething(String body, Exchange exchange, TypeConverter converter) 


And imagine you use a Pojo to handle a given custom exception InvalidOrderException - we can then bind that as well:

public String badOrder(String body, InvalidOrderException invalid) 


Notice that we can bind to it even if we use a sub type of java.lang.Exception as Camel still knows it's an exception and can bind the cause (if any exists).

So what about headers and other stuff? Well now it gets a bit tricky - so we can use annotations to help us, or specify the binding in the method name option.
See the following sections for more detail.

Binding Annotations

You can use the Parameter Binding Annotations to customize how parameter values are created from the Message

Examples

For example, a Bean such as:

public class Bar {
    public String doSomething(String body) {
    // process the in body and return whatever you want 
    return "Bye World"; 
} 

Or the Exchange example. Notice that the return type must be void when there is only a single parameter of the type org.apache.camel.Exchange:

 public class Bar {
     public void doSomething(Exchange exchange) {
         // process the exchange 
         exchange.getIn().setBody("Bye World"); 
 }


@Handler

You can mark a method in your bean with the @Handler annotation to indicate that this method should be used for Bean Binding.
This has an advantage as you need not specify a method name in the Camel route, and therefore do not run into problems after renaming the method in an IDE that can't find all its references.

public class Bar {
    @Handler 
    public String doSomething(String body) {
        // process the in body and return whatever you want 
        return "Bye World"; 
    }
} 


Parameter binding using method option

Available as of Camel 2.9

Camel uses the following rules to determine if it's a parameter value in the method option

  • The value is either true or false which denotes a boolean value
  • The value is a numeric value such as 123 or 7
  • The value is a String enclosed with either single or double quotes
  • The value is null which denotes a null value
  • It can be evaluated using the Simple language, which means you can use, e.g., body, header.foo and other Simple tokens. Notice the tokens must be enclosed with ${ }.

Any other value is consider to be a type declaration instead - see the next section about specifying types for overloaded methods.

When invoking a Bean you can instruct Camel to invoke a specific method by providing the method name:

.bean(OrderService.class, "doSomething")

 

Here we tell Camel to invoke the doSomething method - Camel handles the parameters' binding. Now suppose the method has 2 parameters, and the 2nd parameter is a boolean where we want to pass in a true value:

public void doSomething(String payload, boolean highPriority) {
    ... 
}

 

This is now possible in Camel 2.9 onwards:

.bean(OrderService.class, "doSomething(*, true)") 


In the example above, we defined the first parameter using the wild card symbol *, which tells Camel to bind this parameter to any type, and let Camel figure this out. The 2nd parameter has a fixed value of true. Instead of the wildcard symbol we can instruct Camel to use the message body as shown:

.bean(OrderService.class, "doSomething(${body}, true)") 

 

The syntax of the parameters is using the Simple expression language so we have to use ${ } placeholders in the body to refer to the message body.

If you want to pass in a null value, then you can explicit define this in the method option as shown below:

.to("bean:orderService?method=doSomething(null, true)")


Specifying null as a parameter value instructs Camel to force passing a null value.

Besides the message body, you can pass in the message headers as a java.util.Map:

.bean(OrderService.class, "doSomethingWithHeaders(${body}, ${headers})") 

You can also pass in other fixed values besides booleans. For example, you can pass in a String and an integer:

.bean(MyBean.class, "echo('World', 5)") 


In the example above, we invoke the echo method with two parameters. The first has the content 'World' (without quotes), and the 2nd has the value of 5.
Camel will automatically convert these values to the parameters' types.

Having the power of the Simple language allows us to bind to message headers and other values such as:

.bean(OrderService.class, "doSomething(${body}, ${header.high})") 

You can also use the OGNL support of the Simple expression language. Now suppose the message body is an object which has a method named asXml. To invoke the asXml method we can do as follows:

.bean(OrderService.class, "doSomething(${body.asXml}, ${header.high})") 

Instead of using .bean as shown in the examples above, you may want to use .to instead as shown:

.to("bean:orderService?method=doSomething(${body.asXml}, ${header.high})") 


Using type qualifiers to select among overloaded methods

Available as of Camel 2.8

If you have a Bean with overloaded methods, you can now specify parameter types in the method name so Camel can match the method you intend to use.
Given the following bean:

 from("direct:start")
    .bean(MyBean.class, "hello(String)")
    .to("mock:result");

Then the MyBean has 2 overloaded methods with the names hello and times. So if we want to use the method which has 2 parameters we can do as follows in the Camel route:

from("direct:start")
    .bean(MyBean.class, "hello(String,String)")
    .to("mock:result"); 

We can also use a * as wildcard so we can just say we want to execute the method with 2 parameters we do

 from("direct:start")
    .bean(MyBean.class, "hello(*,*)")
    .to("mock:result");

By default Camel will match the type name using the simple name, e.g. any leading package name will be disregarded. However if you want to match using the FQN, then specify the FQN type and Camel will leverage that. So if you have a com.foo.MyOrder and you want to match against the FQN, and not the simple name "MyOrder", then follow this example:

.bean(OrderService.class, "doSomething(com.foo.MyOrder)")


Camel currently only supports either specifying parameter binding or type per parameter in the method name option. You cannot specify both at the same time, such as

 doSomething(com.foo.MyOrder ${body}, boolean ${header.high})

This may change in the future.

Error rendering macro 'include'

null

Parameter Binding Annotations

camel-core

The annotations below are all part of camel-core and thus does not require camel-spring or Spring. These annotations can be used with the Bean component or when invoking beans in the DSL

Annotations can be used to define an Expression or to extract various headers, properties or payloads from a Message when invoking a bean method (see Bean Integration for more detail of how to invoke bean methods) together with being useful to help disambiguate which method to invoke.

If no annotations are used then Camel assumes that a single parameter is the body of the message. Camel will then use the Type Converter mechanism to convert from the expression value to the actual type of the parameter.

The core annotations are as follows

Annotation

Meaning

Parameter

@Body

To bind to an inbound message body

 

@ExchangeException

To bind to an Exception set on the exchange

 

@Header

To bind to an inbound message header

String name of the header

@Headers

To bind to the Map of the inbound message headers

 

@OutHeaders

To bind to the Map of the outbound message headers

 

@Property

To bind to a named property on the exchange

String name of the property

@Properties

To bind to the property map on the exchange

 

@Handler

Not part as a type parameter but stated in this table anyway to spread the good word that we have this annotation in Camel now. See more at Bean Binding.

 

The follow annotations @Headers, @OutHeaders and @Properties binds to the backing java.util.Map so you can alter the content of these maps directly, for instance using the put method to add a new entry. See the OrderService class at Exception Clause for such an example. You can use @Header("myHeader") and @Property("myProperty") to access the backing java.util.Map.

Example

In this example below we have a @Consume consumer (like message driven) that consumes JMS messages from the activemq queue. We use the @Header and @Body parameter binding annotations to bind from the JMSMessage to the method parameters.

public class Foo {
	
    @Consume(uri = "activemq:my.queue")
    public void doSomething(@Header("JMSCorrelationID") String correlationID, @Body String body) {
		// process the inbound message here
    }

}

In the above Camel will extract the value of Message.getJMSCorrelationID(), then using the Type Converter to adapt the value to the type of the parameter if required - it will inject the parameter value for the correlationID parameter. Then the payload of the message will be converted to a String and injected into the body parameter.

You don't necessarily need to use the @Consume annotation if you don't want to as you could also make use of the Camel DSL to route to the bean's method as well.

Using the DSL to invoke the bean method

Here is another example which does not use POJO Consuming annotations but instead uses the DSL to route messages to the bean method

public class Foo {
    public void doSomething(@Header("JMSCorrelationID") String correlationID, @Body String body) {
		// process the inbound message here
    }

}

The routing DSL then looks like this

from("activemq:someQueue").
  to("bean:myBean");

Here myBean would be looked up in the Registry (such as JNDI or the Spring ApplicationContext), then the body of the message would be used to try figure out what method to call.

If you want to be explicit you can use

from("activemq:someQueue").
  to("bean:myBean?methodName=doSomething");

And here we have a nifty example for you to show some great power in Camel. You can mix and match the annotations with the normal parameters, so we can have this example with annotations and the Exchange also:

    public void doSomething(@Header("user") String user, @Body String body, Exchange exchange) {
        exchange.getIn().setBody(body + "MyBean");
    }

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Extract Transform Load (ETL)

The ETL (Extract, Transform, Load) is a mechanism for loading data into systems or databases using some kind of Data Format from a variety of sources; often files then using Pipes and Filters, Message Translator and possible other Enterprise Integration Patterns.

So you could query data from various Camel Components such as File, HTTP or JPA, perform multiple patterns such as Splitter or Message Translator then send the messages to some other Component.

To show how this all fits together, try the ETL Example

Mock Component

Testing Summary Include

The Mock component provides a powerful declarative testing mechanism, which is similar to jMock in that it allows declarative expectations to be created on any Mock endpoint before a test begins. Then the test is run, which typically fires messages to one or more endpoints, and finally the expectations can be asserted in a test case to ensure the system worked as expected.

This allows you to test various things like:

  • The correct number of messages are received on each endpoint,
  • The correct payloads are received, in the right order,
  • Messages arrive on an endpoint in order, using some Expression to create an order testing function,
  • Messages arrive match some kind of Predicate such as that specific headers have certain values, or that parts of the messages match some predicate, such as by evaluating an XPath or XQuery Expression.

Note that there is also the Test endpoint which is a Mock endpoint, but which uses a second endpoint to provide the list of expected message bodies and automatically sets up the Mock endpoint assertions. In other words, it's a Mock endpoint that automatically sets up its assertions from some sample messages in a File or database, for example.

Mock endpoints keep received Exchanges in memory indefinitely

Remember that Mock is designed for testing. When you add Mock endpoints to a route, each Exchange sent to the endpoint will be stored (to allow for later validation) in memory until explicitly reset or the JVM is restarted. If you are sending high volume and/or large messages, this may cause excessive memory use. If your goal is to test deployable routes inline, consider using NotifyBuilder or AdviceWith in your tests instead of adding Mock endpoints to routes directly.

From Camel 2.10 onwards there are two new options retainFirst, and retainLast that can be used to limit the number of messages the Mock endpoints keep in memory.

URI format

mock:someName[?options]

Where someName can be any string that uniquely identifies the endpoint.

You can append query options to the URI in the following format, ?option=value&option=value&...

Options

confluenceTableSmall

Option

Default

Description

reportGroup

null

A size to use a throughput logger for reporting

retainFirst

 

Camel 2.10: To only keep first X number of messages in memory.

retainLast

 

Camel 2.10: To only keep last X number of messages in memory.

Simple Example

Here's a simple example of Mock endpoint in use. First, the endpoint is resolved on the context. Then we set an expectation, and then, after the test has run, we assert that our expectations have been met.

MockEndpoint resultEndpoint = context.resolveEndpoint("mock:foo", MockEndpoint.class); resultEndpoint.expectedMessageCount(2); // send some messages ... // now lets assert that the mock:foo endpoint received 2 messages resultEndpoint.assertIsSatisfied();

You typically always call the assertIsSatisfied() method to test that the expectations were met after running a test.

Camel will by default wait 10 seconds when the assertIsSatisfied() is invoked. This can be configured by setting the setResultWaitTime(millis) method.

Using assertPeriod

Available as of Camel 2.7
When the assertion is satisfied then Camel will stop waiting and continue from the assertIsSatisfied method. That means if a new message arrives on the mock endpoint, just a bit later, that arrival will not affect the outcome of the assertion. Suppose you do want to test that no new messages arrives after a period thereafter, then you can do that by setting the setAssertPeriod method, for example:

MockEndpoint resultEndpoint = context.resolveEndpoint("mock:foo", MockEndpoint.class); resultEndpoint.setAssertPeriod(5000); resultEndpoint.expectedMessageCount(2); // send some messages ... // now lets assert that the mock:foo endpoint received 2 messages resultEndpoint.assertIsSatisfied();

Setting expectations

You can see from the javadoc of MockEndpoint the various helper methods you can use to set expectations. The main methods are as follows:

confluenceTableSmall

Method

Description

expectedMessageCount(int)

To define the expected message count on the endpoint.

expectedMinimumMessageCount(int)

To define the minimum number of expected messages on the endpoint.

expectedBodiesReceived(...)

To define the expected bodies that should be received (in order).

expectedHeaderReceived(...)

To define the expected header that should be received

expectsAscending(Expression)

To add an expectation that messages are received in order, using the given Expression to compare messages.

expectsDescending(Expression)

To add an expectation that messages are received in order, using the given Expression to compare messages.

expectsNoDuplicates(Expression)

To add an expectation that no duplicate messages are received; using an Expression to calculate a unique identifier for each message. This could be something like the JMSMessageID if using JMS, or some unique reference number within the message.

Here's another example:

resultEndpoint.expectedBodiesReceived("firstMessageBody", "secondMessageBody", "thirdMessageBody");

Adding expectations to specific messages

In addition, you can use the message(int messageIndex) method to add assertions about a specific message that is received.

For example, to add expectations of the headers or body of the first message (using zero-based indexing like java.util.List), you can use the following code:

resultEndpoint.message(0).header("foo").isEqualTo("bar");

There are some examples of the Mock endpoint in use in the camel-core processor tests.

Mocking existing endpoints

Available as of Camel 2.7

Camel now allows you to automatically mock existing endpoints in your Camel routes.

How it works

Important: The endpoints are still in action. What happens differently is that a Mock endpoint is injected and receives the message first and then delegates the message to the target endpoint. You can view this as a kind of intercept and delegate or endpoint listener.

Suppose you have the given route below:

{snippet:id=route|title=Route|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/AdviceWithMockEndpointsTest.java}

You can then use the adviceWith feature in Camel to mock all the endpoints in a given route from your unit test, as shown below:

{snippet:id=e1|title=adviceWith mocking all endpoints|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/AdviceWithMockEndpointsTest.java}

Notice that the mock endpoints is given the uri mock:<endpoint>, for example mock:direct:foo. Camel logs at INFO level the endpoints being mocked:

INFO Adviced endpoint [direct://foo] with mock endpoint [mock:direct:foo] Mocked endpoints are without parameters

Endpoints which are mocked will have their parameters stripped off. For example the endpoint "log:foo?showAll=true" will be mocked to the following endpoint "mock:log:foo". Notice the parameters have been removed.

Its also possible to only mock certain endpoints using a pattern. For example to mock all log endpoints you do as shown:

{snippet:id=e2|lang=java|title=adviceWith mocking only log endpoints using a pattern|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/AdviceWithMockEndpointsTest.java}

The pattern supported can be a wildcard or a regular expression. See more details about this at Intercept as its the same matching function used by Camel.

Mind that mocking endpoints causes the messages to be copied when they arrive on the mock.
That means Camel will use more memory. This may not be suitable when you send in a lot of messages.

Mocking existing endpoints using the camel-test component

Instead of using the adviceWith to instruct Camel to mock endpoints, you can easily enable this behavior when using the camel-test Test Kit.
The same route can be tested as follows. Notice that we return "*" from the isMockEndpoints method, which tells Camel to mock all endpoints.
If you only want to mock all log endpoints you can return "log*" instead.

{snippet:id=e1|lang=java|title=isMockEndpoints using camel-test kit|url=camel/trunk/components/camel-test/src/test/java/org/apache/camel/test/patterns/IsMockEndpointsJUnit4Test.java}

Mocking existing endpoints with XML DSL

If you do not use the camel-test component for unit testing (as shown above) you can use a different approach when using XML files for routes.
The solution is to create a new XML file used by the unit test and then include the intended XML file which has the route you want to test.

Suppose we have the route in the camel-route.xml file:

{snippet:id=e1|lang=xml|title=camel-route.xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/mock/camel-route.xml}

Then we create a new XML file as follows, where we include the camel-route.xml file and define a spring bean with the class org.apache.camel.impl.InterceptSendToMockEndpointStrategy which tells Camel to mock all endpoints:

{snippet:id=e1|lang=xml|title=test-camel-route.xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/mock/InterceptSendToMockEndpointStrategyTest.xml}

Then in your unit test you load the new XML file (test-camel-route.xml) instead of camel-route.xml.

To only mock all Log endpoints you can define the pattern in the constructor for the bean:

xml<bean id="mockAllEndpoints" class="org.apache.camel.impl.InterceptSendToMockEndpointStrategy"> <constructor-arg index="0" value="log*"/> </bean>

Mocking endpoints and skip sending to original endpoint

Available as of Camel 2.10

Sometimes you want to easily mock and skip sending to a certain endpoints. So the message is detoured and send to the mock endpoint only. From Camel 2.10 onwards you can now use the mockEndpointsAndSkip method using AdviceWith or the Test Kit. The example below will skip sending to the two endpoints "direct:foo", and "direct:bar".

{snippet:id=e1|lang=java|title=adviceWith mock and skip sending to endpoints|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/AdviceWithMockMultipleEndpointsWithSkipTest.java}

The same example using the Test Kit

{snippet:id=e1|lang=java|title=isMockEndpointsAndSkip using camel-test kit|url=camel/trunk/components/camel-test/src/test/java/org/apache/camel/test/patterns/IsMockEndpointsAndSkipJUnit4Test.java}

Limiting the number of messages to keep

Available as of Camel 2.10

The Mock endpoints will by default keep a copy of every Exchange that it received. So if you test with a lot of messages, then it will consume memory.
From Camel 2.10 onwards we have introduced two options retainFirst and retainLast that can be used to specify to only keep N'th of the first and/or last Exchanges.

For example in the code below, we only want to retain a copy of the first 5 and last 5 Exchanges the mock receives.

MockEndpoint mock = getMockEndpoint("mock:data"); mock.setRetainFirst(5); mock.setRetainLast(5); mock.expectedMessageCount(2000); ... mock.assertIsSatisfied();

Using this has some limitations. The getExchanges() and getReceivedExchanges() methods on the MockEndpoint will return only the retained copies of the Exchanges. So in the example above, the list will contain 10 Exchanges; the first five, and the last five.
The retainFirst and retainLast options also have limitations on which expectation methods you can use. For example the expectedXXX methods that work on message bodies, headers, etc. will only operate on the retained messages. In the example above they can test only the expectations on the 10 retained messages.

Testing with arrival times

Available as of Camel 2.7

The Mock endpoint stores the arrival time of the message as a property on the Exchange.

Date time = exchange.getProperty(Exchange.RECEIVED_TIMESTAMP, Date.class);

You can use this information to know when the message arrived on the mock. But it also provides foundation to know the time interval between the previous and next message arrived on the mock. You can use this to set expectations using the arrives DSL on the Mock endpoint.

For example to say that the first message should arrive between 0-2 seconds before the next you can do:

mock.message(0).arrives().noLaterThan(2).seconds().beforeNext();

You can also define this as that 2nd message (0 index based) should arrive no later than 0-2 seconds after the previous:

mock.message(1).arrives().noLaterThan(2).seconds().afterPrevious();

You can also use between to set a lower bound. For example suppose that it should be between 1-4 seconds:

mock.message(1).arrives().between(1, 4).seconds().afterPrevious();

You can also set the expectation on all messages, for example to say that the gap between them should be at most 1 second:

mock.allMessages().arrives().noLaterThan(1).seconds().beforeNext(); time units

In the example above we use seconds as the time unit, but Camel offers milliseconds, and minutes as well.

Endpoint See Also

Testing

Testing is a crucial activity in any piece of software development or integration. Typically Camel Riders use various different technologies wired together in a variety of patterns with different expression languages together with different forms of Bean Integration and Dependency Injection so its very easy for things to go wrong! (smile) . Testing is the crucial weapon to ensure that things work as you would expect.

Camel is a Java library so you can easily wire up tests in whatever unit testing framework you use (JUnit 3.x (deprecated), 4.x, or TestNG). However the Camel project has tried to make the testing of Camel as easy and powerful as possible so we have introduced the following features.

Testing Mechanisms

The following mechanisms are supported:

Name

Component

Description

Camel Test

camel-test

Is a standalone Java library letting you easily create Camel test cases using a single Java class for all your configuration and routing without using CDI, Spring or Guice for Dependency Injection which does not require an in-depth knowledge of Spring + Spring Test or Guice.  Supports JUnit 3.x (deprecated) and JUnit 4.x based tests.

CDI Testingcamel-test-cdi

Provides a JUnit 4 runner that bootstraps a test environment using CDI so that you don't have to be familiar with any CDI testing frameworks and can concentrate on the testing logic of your Camel CDI applications. Testing frameworks like Arquillian or PAX Exam, can be used for more advanced test cases, where you need to configure your system under test in a very fine-grained way or target specific CDI containers.

Spring Testing

camel-test-spring

Supports JUnit 3.x (deprecated) or JUnit 4.x based tests that bootstrap a test environment using Spring without needing to be familiar with Spring Test. The plain JUnit 3.x/4.x based tests work very similar to the test support classes in camel-test.

Also supports Spring Test based tests that use the declarative style of test configuration and injection common in Spring Test. The Spring Test based tests provide feature parity with the plain JUnit 3.x/4.x based testing approach.

Note: camel-test-spring is a new component from Camel 2.10. For older Camel release use camel-test which has built-in Spring Testing.

Blueprint Testing

camel-test-blueprint

Camel 2.10: Provides the ability to do unit testing on blueprint configurations

Guice

camel-guice

Deprecated

Uses Guice to dependency inject your test classes

Camel TestNG

camel-testng

Deprecated

Supports plain TestNG based tests with or without CDISpring or Guice for Dependency Injection which does not require an in-depth knowledge of CDI, Spring + Spring Test or Guice.  

From Camel 2.10: this component supports Spring Test based tests that use the declarative style of test configuration and injection common in Spring Test and described in more detail under Spring Testing.

In all approaches the test classes look pretty much the same in that they all reuse the Camel binding and injection annotations.

Camel Test Example

Here is the Camel Test example:{snippet:lang=java|id=example|url=camel/trunk/components/camel-test/src/test/java/org/apache/camel/test/patterns/FilterTest.java}Notice how it derives from the Camel helper class CamelTestSupport but has no CDI, Spring or Guice dependency injection configuration but instead overrides the createRouteBuilder() method.

CDI Test Example

Here is the CDI Testing example:{snippet:lang=java|id=example|url=camel/trunk/components/camel-test-cdi/src/test/java/org/apache/camel/test/cdi/FilterTest.java}You can find more testing patterns illustrated in the camel-example-cdi-test example and the test classes that come with it.

Spring Test with XML Config Example

Here is the Spring Testing example using XML Config:{snippet:lang=java|id=example|url=camel/trunk/components/camel-spring/src/test/java/org/apache/camel/spring/patterns/FilterTest.java}Notice that we use @DirtiesContext on the test methods to force Spring Testing to automatically reload the CamelContext after each test method - this ensures that the tests don't clash with each other, e.g., one test method sending to an endpoint that is then reused in another test method.

Also note the use of @ContextConfiguration to indicate that by default we should look for the FilterTest-context.xml on the classpath to configure the test case which looks like this:{snippet:lang=xml|id=example|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/patterns/FilterTest-context.xml}

Spring Test with Java Config Example

Here is the Spring Testing example using Java Config.

For more information see Spring Java Config.{snippet:lang=java|id=example|url=camel/trunk/components/camel-spring-javaconfig/src/test/java/org/apache/camel/spring/javaconfig/patterns/FilterTest.java}This is similar to the XML Config example above except that there is no XML file and instead the nested ContextConfig class does all of the configuration; so your entire test case is contained in a single Java class. We currently have to reference by class name this class in the @ContextConfiguration which is a bit ugly. Please vote for SJC-238 to address this and make Spring Test work more cleanly with Spring JavaConfig.

Its totally optional but for the ContextConfig implementation we derive from SingleRouteCamelConfiguration which is a helper Spring Java Config class which will configure the CamelContext for us and then register the RouteBuilder we create.

Since Camel 2.11.0 you can use the CamelSpringJUnit4ClassRunner with CamelSpringDelegatingTestContextLoader like example using Java Config with CamelSpringJUnit4ClassRunner:{snippet:lang=java|id=example|url=camel/trunk/components/camel-spring-javaconfig/src/test/java/org/apache/camel/spring/javaconfig/test/CamelSpringDelegatingTestContextLoaderTest.java}

Spring Test with XML Config and Declarative Configuration Example

Here is a Camel test support enhanced Spring Testing example using XML Config and pure Spring Test based configuration of the Camel Context:{snippet:lang=java|id=e1|url=camel/trunk/components/camel-test-spring/src/test/java/org/apache/camel/test/spring/CamelSpringJUnit4ClassRunnerPlainTest.java}Notice how a custom test runner is used with the @RunWith annotation to support the features of CamelTestSupport through annotations on the test class. See Spring Testing for a list of annotations you can use in your tests.

Blueprint Test

Here is the Blueprint Testing example using XML Config:{snippet:lang=java|id=example|url=camel/trunk/components/camel-test-blueprint/src/test/java/org/apache/camel/test/blueprint/DebugBlueprintTest.java}Also notice the use of getBlueprintDescriptors to indicate that by default we should look for the camelContext.xml in the package to configure the test case which looks like this:{snippet:lang=xml|id=example|url=camel/trunk/components/camel-test-blueprint/src/test/resources/org/apache/camel/test/blueprint/camelContext.xml}

Testing Endpoints

Camel provides a number of endpoints which can make testing easier.

Name

Description

DataSet

For load & soak testing this endpoint provides a way to create huge numbers of messages for sending to Components and asserting that they are consumed correctly

Mock

For testing routes and mediation rules using mocks and allowing assertions to be added to an endpoint

Test

Creates a Mock endpoint which expects to receive all the message bodies that could be polled from the given underlying endpoint

The main endpoint is the Mock endpoint which allows expectations to be added to different endpoints; you can then run your tests and assert that your expectations are met at the end.

Stubbing out physical transport technologies

If you wish to test out a route but want to avoid actually using a real physical transport (for example to unit test a transformation route rather than performing a full integration test) then the following endpoints can be useful.

Name

Description

Direct

Direct invocation of the consumer from the producer so that single threaded (non-SEDA) in VM invocation is performed which can be useful to mock out physical transports

SEDA

Delivers messages asynchronously to consumers via a java.util.concurrent.BlockingQueue which is good for testing asynchronous transports

Stub

Works like SEDA but does not validate the endpoint URI, which makes stubbing much easier.

Testing existing routes

Camel provides some features to aid during testing of existing routes where you cannot or will not use Mock etc. For example you may have a production ready route which you want to test with some 3rd party API which sends messages into this route.

Name

Description

NotifyBuilder

Allows you to be notified when a certain condition has occurred. For example when the route has completed five messages. You can build complex expressions to match your criteria when to be notified.

AdviceWith

Allows you to advice or enhance an existing route using a RouteBuilder style. For example you can add interceptors to intercept sending outgoing messages to assert those messages are as expected.

Error rendering macro 'include'

org.owasp.validator.html.ScanException: java.util.EmptyStackException

Spring Testing

Testing is a crucial part of any development or integration work. The Spring Framework offers a number of features that makes it easy to test while using Spring for Inversion of Control which works with JUnit 3.x, JUnit 4.x, and TestNG.

We can use Spring for IoC and the Camel Mock and Test endpoints to create sophisticated integration/unit tests that are easy to run and debug inside your IDE.  There are three supported approaches for testing with Spring in Camel.

Name

Testing Frameworks Supported

Description

Required Camel Test Dependencies

CamelSpringTestSupport

  • JUnit 3.x (deprecated)
  • JUnit 4.x
  • TestNG - Camel 2.8

Provided by:

  • org.apache.camel.test.CamelSpringTestSupport
  • org.apache.camel.test.junit4.CamelSpringTestSupport
  • org.apache.camel.testng.CamelSpringTestSupport

These base classes provide feature parity with the simple CamelTestSupport classes from Camel Test but do not support Spring annotations on the test class such as @Autowired@DirtiesContext, and @ContextConfiguration.

  • JUnit 3.x (deprecated) - camel-test-spring
  • JUnit 4.x - camel-test-spring
  • TestNG - camel-test-ng

Plain Spring Test

  • JUnit 3.x
  • JUnit 4.x
  • TestNG

Either extend the abstract base classes:

  • org.springframework.test.context.junit38.AbstractJUnit38SpringContextTests
  • org.springframework.test.context.junit38.AbstractJUnit4SpringContextTests
  • etc.

provided in Spring Test or use the Spring Test JUnit4 runner.  

These approaches support both the Camel annotations and Spring annotations. However, they do NOT have feature parity with:

  • org.apache.camel.test.CamelTestSupport
  • org.apache.camel.test.junit4.CamelTestSupport
  • org.apache.camel.testng.CamelSpringTestSupport
  • JUnit 3.x (deprecated) - None
  • JUnit 4.x - None
  • TestNG - None

Camel Enhanced Spring Test

  • JUnit 4.x - Camel 2.10
  • TestNG - Camel 2.10

Either:

  • use the org.apache.camel.test.junit4.CamelSpringJUnit4ClassRunner runner with the @RunWith annotation,
  • or extend org.apache.camel.testng.AbstractCamelTestNGSpringContextTests to enable feature parity with org.apache.camel.test.CamelTestSupport and org.apache.camel.test.junit4.CamelTestSupport. These classes support the full suite of Spring Test annotations such as @Autowired@DirtiesContext, and @ContextConfiguration.

JUnit 3.x (deprecated) - camel-test-spring

JUnit 4.x - camel-test-spring

TestNG - camel-test-ng

CamelSpringTestSupport

The following Spring test support classes:

  • org.apache.camel.test.CamelSpringTestSupport
  • org.apache.camel.test.junit4.CamelSpringTestSupport, and
  • org.apache.camel.testng.CamelSpringTestSupport

extend their non-Spring aware counterparts:

  • org.apache.camel.test.CamelTestSupport
  • org.apache.camel.test.junit4.CamelTestSupport, and 
  • org.apache.camel.testng.CamelTestSupport

and deliver integration with Spring into your test classes.  

Instead of instantiating the CamelContext and routes programmatically, these classes rely on a Spring context to wire the needed components together.  If your test extends one of these classes, you must provide the Spring context by implementing the following method.

javaprotected abstract AbstractApplicationContext createApplicationContext();

You are responsible for the instantiation of the Spring context in the method implementation.  All of the features available in the non-Spring aware counterparts from Camel Test are available in your test.

Plain Spring Test

In this approach, your test classes directly inherit from the Spring Test abstract test classes or use the JUnit 4.x test runner provided in Spring Test.  This approach supports dependency injection into your test class and the full suite of Spring Test annotations. However, it does not support the features provided by the CamelSpringTestSupport classes.

Plain Spring Test using JUnit 3.x with XML Config Example

Here is a simple unit test using JUnit 3.x support from Spring Test using XML Config.{snippet:lang=java|id=example|url=camel/trunk/components/camel-spring/src/test/java/org/apache/camel/spring/patterns/FilterTest.java}Notice that we use @DirtiesContext on the test methods to force Spring Testing to automatically reload the CamelContext after each test method - this ensures that the tests don't clash with each other, e.g., one test method sending to an endpoint that is then reused in another test method.

Also notice the use of @ContextConfiguration to indicate that by default we should look for the file FilterTest-context.xml on the classpath to configure the test case. The test context looks like:{snippet:lang=xml|id=example|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/patterns/FilterTest-context.xml}This test will load a Spring XML configuration file called FilterTest-context.xml from the classpath in the same package structure as the FilterTest class and initialize it along with any Camel routes we define inside it, then inject the CamelContext instance into our test case.

For instance, like this maven folder layout:

src/test/java/org/apache/camel/spring/patterns/FilterTest.java src/test/resources/org/apache/camel/spring/patterns/FilterTest-context.xml

Plain Spring Test Using JUnit 4.x With Java Config Example

You can completely avoid using an XML configuration file by using Spring Java Config.  Here is a unit test using JUnit 4.x support from Spring Test using Java Config.{snippet:lang=java|id=example|url=camel/trunk/components/camel-spring-javaconfig/src/test/java/org/apache/camel/spring/javaconfig/patterns/FilterTest.java}This is similar to the XML Config example above except that there is no XML file and instead the nested ContextConfig class does all of the configuration; so your entire test case is contained in a single Java class. We currently have to reference by class name this class in the @ContextConfiguration which is a bit ugly. Please vote for SJC-238 to address this and make Spring Test work more cleanly with Spring JavaConfig.

Plain Spring Test Using JUnit 4.0.x Runner With XML Config

You can avoid extending Spring classes by using the SpringJUnit4ClassRunner provided by Spring Test.  This custom JUnit runner means you are free to choose your own class hierarchy while retaining all the capabilities of Spring Test.

This is for Spring 4.0.x. If you use Spring 4.1 or newer, then see the next section.

java@RunWith(SpringJUnit4ClassRunner.class) @ContextConfiguration public class MyCamelTest {     @Autowired     protected CamelContext camelContext;     @EndpointInject(uri = "mock:foo")     protected MockEndpoint foo; @Test @DirtiesContext     public void testMocksAreValid() throws Exception { // ...                foo.message(0).header("bar").isEqualTo("ABC");         MockEndpoint.assertIsSatisfied(camelContext);     } }

Plain Spring Test Using JUnit 4.1.x Runner With XML Config

You can avoid extending Spring classes by using the SpringJUnit4ClassRunner provided by Spring Test.  This custom JUnit runner means you are free to choose your own class hierarchy while retaining all the capabilities of Spring Test.

From Spring 4.1, you need to use the @BootstrapWith annotation to configure it to use Camel testing, as shown below.

java@RunWith(CamelSpringJUnit4ClassRunner.class) @BootstrapWith(CamelTestContextBootstrapper.class) @ContextConfiguration public class MyCamelTest {     @Autowired     protected CamelContext camelContext;     @EndpointInject(uri = "mock:foo")     protected MockEndpoint foo; @Test @DirtiesContext     public void testMocksAreValid() throws Exception { // ...                foo.message(0).header("bar").isEqualTo("ABC");         MockEndpoint.assertIsSatisfied(camelContext);     } }

Camel Enhanced Spring Test

Using the org.apache.camel.test.junit4.CamelSpringJUnit4ClassRunner runner with the @RunWith annotation or extending org.apache.camel.testng.AbstractCamelTestNGSpringContextTests provides the full feature set of Spring Test with support for the feature set provided in the CamelTestSupport classes.  

A number of Camel specific annotations have been developed in order to provide for declarative manipulation of the Camel context(s) involved in the test.  These annotations free your test classes from having to inherit from the CamelSpringTestSupport classes and also reduce the amount of code required to customize the tests.

Annotation Class

Applies To

Description

Default Behavioir If Not Present

Default Behavior If Present

org.apache.camel.test.spring.DisableJmx

Class

Indicates if JMX should be globally disabled in the CamelContexts that are bootstrapped  during the test through the use of Spring Test loaded application contexts.

JMX is disabled

JMX is disabled

org.apache.camel.test.spring.ExcludeRoutes

Class

Indicates if certain route builder classes should be excluded from discovery.  Initializes a org.apache.camel.spi.PackageScanClassResolver to exclude a set of given classes from being resolved. Typically this is used at test time to exclude certain routes, which might otherwise be just noisy, from being discovered and initialized.

Not enabled and no routes are excluded

No routes are excluded

org.apache.camel.test.spring.LazyLoadTypeConverters

Class

Deprecated.

Indicates if the CamelContexts that are bootstrapped during the test through the use of Spring Test loaded application contexts should use lazy loading of type converters.

Type converters are not lazy loaded

Type converters are not lazy loaded

org.apache.camel.test.spring.MockEndpoints

Class

Triggers the auto-mocking of endpoints whose URIs match the provided filter.  The default filter is "*" which matches all endpoints.  See org.apache.camel.impl.InterceptSendToMockEndpointStrategy for more details on the registration of the mock endpoints.

Not enabled

All endpoints are sniffed and recorded in a mock endpoint.

org.apache.camel.test.spring.MockEndpointsAndSkip

Class

Triggers the auto-mocking of endpoints whose URIs match the provided filter.  The default filter is "*", which matches all endpoints.  See org.apache.camel.impl.InterceptSendToMockEndpointStrategy for more details on the registration of the mock endpoints.  This annotation will also skip sending the message to matched endpoints as well.

Not enabled

All endpoints are sniffed and recorded in a mock endpoint.  The original endpoint is not invoked.

org.apache.camel.test.spring.ProvidesBreakpoint

Method

Indicates that the annotated method returns an org.apache.camel.spi.Breakpoint for use in the test.  Useful for intercepting traffic to all endpoints or simply for setting a break point in an IDE for debugging.  The method must be public, static, take no arguments, and return org.apache.camel.spi.Breakpoint.

N/A

The returned Breakpoint is registered in the CamelContext(s)

org.apache.camel.test.spring.ShutdownTimeout

Class

Indicates to set the shutdown timeout of all CamelContexts instantiated through the use of Spring Test loaded application contexts.  If no annotation is used, the timeout is automatically reduced to 10 seconds by the test framework.

10 seconds

10 seconds

org.apache.camel.test.spring.UseAdviceWith

Class

Indicates the use of adviceWith() within the test class.  If a class is annotated with this annotation and UseAdviceWith#value() returns true, any CamelContexts bootstrapped during the test through the use of Spring Test loaded application contexts will not be started automatically. 

The test author is responsible for injecting the Camel contexts into the test and executing CamelContext#start() on them at the appropriate time after any advice has been applied to the routes in the CamelContext(s).

CamelContexts do not automatically start.

CamelContexts do not automatically start.

org.apache.camel.test.spring.UseOverridePropertiesWithPropertiesComponent

Method

Camel 2.16:Indicates that the annotated method returns a java.util.Properties for use in the test, and that those properties override any existing properties configured on the PropertiesComponent.

 

Override properties

The following example illustrates the use of the @MockEndpoints annotation in order to setup mock endpoints as interceptors on all endpoints using the Camel Log component and the @DisableJmx annotation to enable JMX which is disabled during tests by default.  

Note: we still use the @DirtiesContext annotation to ensure that the CamelContext, routes, and mock endpoints are reinitialized between test methods.java@RunWith(CamelSpringJUnit4ClassRunner.class) @BootstrapWith(CamelTestContextBootstrapper.class) @ContextConfiguration @DirtiesContext(classMode = ClassMode.AFTER_EACH_TEST_METHOD) @MockEndpoints("log:*") @DisableJmx(false) public class CamelSpringJUnit4ClassRunnerPlainTest { @Autowired protected CamelContext camelContext2; protected MockEndpoint mockB; @EndpointInject(uri = "mock:c", context = "camelContext2") protected MockEndpoint mockC; @Produce(uri = "direct:start2", context = "camelContext2") protected ProducerTemplate start2; @EndpointInject(uri = "mock:log:org.apache.camel.test.junit4.spring", context = "camelContext2") protected MockEndpoint mockLog; @Test public void testPositive() throws Exception { mockC.expectedBodiesReceived("David"); mockLog.expectedBodiesReceived("Hello David"); start2.sendBody("David"); MockEndpoint.assertIsSatisfied(camelContext); }

Adding More Mock Expectations

If you wish to programmatically add any new assertions to your test you can easily do so with the following. Notice how we use @EndpointInject to inject a Camel endpoint into our code then the Mock API to add an expectation on a specific message.

java@ContextConfiguration public class MyCamelTest extends AbstractJUnit38SpringContextTests { @Autowired protected CamelContext camelContext; @EndpointInject(uri = "mock:foo") protected MockEndpoint foo; public void testMocksAreValid() throws Exception { // lets add more expectations foo.message(0).header("bar").isEqualTo("ABC"); MockEndpoint.assertIsSatisfied(camelContext); } }

Further Processing the Received Messages

Sometimes once a Mock endpoint has received some messages you want to then process them further to add further assertions that your test case worked as you expect.

So you can then process the received message exchanges if you like...

java@ContextConfiguration public class MyCamelTest extends AbstractJUnit38SpringContextTests { @Autowired protected CamelContext camelContext; @EndpointInject(uri = "mock:foo") protected MockEndpoint foo; public void testMocksAreValid() throws Exception { // lets add more expectations... MockEndpoint.assertIsSatisfied(camelContext); // now lets do some further assertions List<Exchange> list = foo.getReceivedExchanges(); for (Exchange exchange : list) { Message in = exchange.getIn(); // ... } } }

Sending and Receiving Messages

It might be that the Enterprise Integration Patterns you have defined in either Spring XML or using the Java DSL do all of the sending and receiving and you might just work with the Mock endpoints as described above. However sometimes in a test case its useful to explicitly send or receive messages directly.

To send or receive messages you should use the Bean Integration mechanism. For example to send messages inject a ProducerTemplate using the @EndpointInject annotation then call the various send methods on this object to send a message to an endpoint. To consume messages use the @MessageDriven annotation on a method to have the method invoked when a message is received.

javapublic class Foo { @EndpointInject(uri = "activemq:foo.bar") ProducerTemplate producer; public void doSomething() { // lets send a message! producer.sendBody("<hello>world!</hello>"); } // lets consume messages from the 'cheese' queue @MessageDriven(uri="activemq:cheese") public void onCheese(String name) { // ... } }

See Also

Error rendering macro 'include'

null

Templating

When you are testing distributed systems its a very common requirement to have to stub out certain external systems with some stub so that you can test other parts of the system until a specific system is available or written etc.

A great way to do this is using some kind of Template system to generate responses to requests generating a dynamic message using a mostly-static body.

There are a number of templating components included in the Camel distribution you could use

or the following external Camel components

Example

Here's a simple example showing how we can respond to InOut requests on the My.Queue queue on ActiveMQ with a template generated response. The reply would be sent back to the JMSReplyTo Destination.

from("activemq:My.Queue").
  to("velocity:com/acme/MyResponse.vm");

If you want to use InOnly and consume the message and send it to another destination you could use

from("activemq:My.Queue").
  to("velocity:com/acme/MyResponse.vm").
  to("activemq:Another.Queue");

See Also

  • Mock for details of mock endpoint testing (as opposed to template based stubs).

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Error rendering macro 'include'

null

Introduction

When sending an Exchange to an Endpoint you can either use a Route or a ProducerTemplate. This works fine in many scenarios. However you may need to guarantee that an exchange is delivered to the same endpoint that you delivered a previous exchange on. For example in the case of delivering a batch of exchanges to a MINA socket you may need to ensure that they are all delivered through the same socket connection. Furthermore once the batch of exchanges have been delivered the protocol requirements may be such that you are responsible for closing the socket.

Using a Producer

To achieve fine grained control over sending exchanges you will need to program directly to a Producer. Your code will look similar to:

  CamelContext camelContext = ...

  // Obtain an endpoint and create the producer we will be using.
  Endpoint endpoint = camelContext.getEndpoint("someuri:etc");
  Producer producer = endpoint.createProducer();
  producer.start();

  try {
    // For each message to send...
    Object requestMessage = ...
    Exchange exchangeToSend = producer.createExchange();
    exchangeToSend().setBody(requestMessage);
    producer.process(exchangeToSend);
    ...

  } finally {
    // Tidy the producer up.
    producer.stop();
  }

In the case of using Apache MINA the producer.stop() invocation will cause the socket to be closed.

  • No labels