NotifierBuilder

Available as of Camel 2.2

The NotifierBuilder is a builder from the org.apache.camel.builder package which allows you to build expressions and then test or wait for that condition to occur. The expressions is based around notifications about Exchange being routed. So what does that mean? It means that you can build an expressions which can tell you when Camel is finished with routing 5 messages etc.

You may want to use this when testing a route which you cannot or will not use Mocks.

Suppose we have a very simple route:

  from("jms:queue:quotes")
     .to("bean:quotes");

Now you want to test this route without using mocks or the likes. Imagine the route being more complex and a production ready route.
We want to test that it could process a message send to that queue. By using the NotifierBuilder we can build an expression which expresses when that condition occurred.

 
  NotifierBuilder notifier = new NotifierBuilder().whenDone(1).create();

  // now use some API to send a message etc. Maybe you cannot use Camel's ProducerTemplate
  // now we want to wait until the message has been routed and completed

  boolean done = notifier.matches(10, TimeUnit.SECONDS);
  assertTrue("Should be done", done);

  // now maybe use some API to see that the message did as expected

This is a very basic example with a simple builder expression. What we said that we want it to match when any Exchange is done. The builder have many more methods to set more complex expressions, which even can be stacked using and, or, not operations.

Methods

These methods is for building the expression:

Method	Description
from(endpointUri)	Matches only when Exchanges are incoming from that particular endpoint. The endpointUri can be a pattern, which is the same pattern matching used by Intercept.
whenReceived(number)	Matches when X number or more messages has been received.
whenDone(number)	Matches when X number or more messages is done.
whenComplete(number)	Matches when X number or more messages is complete.
whenFailed(number)	Matches when X number or more messages is failed.
whenExactlyDone(number)	Matches when exactly X number of messages is done.
whenExactlyComplete(number)	Matches when exactly X number of messages is complete.
whenExactlyFailed(number)	Matches when exactly X number of messages is failed.
whenAnyReceivedMatches(predicate)	Matches if any one of the received messages matched the Predicate.
whenAllReceivedMatches(predicate)	Matches only when all of the received messages matched the Predicate.
whenSatisfied(mock)	Matches if the Mock is satisfied. Is used for fine grained matching by setting the expectations on the Mock which already have a great library for doing so.
whenNotSatisfied(mock)	Matches if the Mock is not satisfied. Is used for fine grained matching by setting the expectations on the Mock which already have a great library for doing so.
and	Appends an additional expressions using the and operator.
or	Appends an additional expressions using the or operator.
not	Appends an additional expressions using the not operator.

And these methods is for using the builder after creating the expression:

Method	Description
create()	Creates the builder expression. After you have created it you can use the `matches` methods.
matches()	Does the builder match currently. This operation returns immediately. This method is to be used after you have created the expression.
matches(timeout, TimeUnit)	Wait until the builder matches or timeout. This method is to be used after you have created the expression.

We will most likely add additional methods in the future, so check out the NotifierBuilder for latest and greatest methods.

Difference between Done and Completed

The difference between done and completed is that done can also include failed messages, where as completed is only successful processed messages.

Examples

        NotifierBuilder notifier = new NotifierBuilder(context)
                .from("direct:foo").whenDone(5)
                .create();

Here we want to match when the direct:foo endpoint have done 5 messages.

        NotifierBuilder notifier = new NotifierBuilder(context)
                .from("jms:*").whenDone(1)
                .create();

Here we just say that at least one message should be done received from any JMS endpoint (notice the wildcard matching).

        NotifierBuilder notifier = new NotifierBuilder(context)
                .from("direct:foo").whenDone(5)
                .and().from("direct:bar").whenDone(7)
                .create();

Here both 5 foo messages and 7 bar messages must be done. Notice the use of the and operator.

        NotifierBuilder notifier = new NotifierBuilder(context)
                .whenAnyReceivedMatches(body().contains("Camel"))
                .create();

Here we want to match when we have received a message which contains Camel in the body.

        // lets use a mock to set the expressions as it got many great assertions for that
        // notice we use mock:assert which does NOT exist in the route, its just a pseudo name
        MockEndpoint mock = getMockEndpoint("mock:assert");
        mock.expectedBodiesReceivedInAnyOrder("Hello World", "Bye World", "Hi World");

        NotifierBuilder notifier = new NotifierBuilder(context)
                .from("direct:foo").whenSatisfied(mock)
                .create();

Now it bring powers to the table. We combine a mock with the builder. We use the mock to set fine grained expectations such as we should receive 3 messages in any order. Then using the builder we can tell that those messages should be received from the direct:foo endpoint.

You can combine multiple expressions as much as you like. However we suggest to use the mock for fine grained expectations that you may already know how to use.

Child pages

NotifierBuilder