Appendix C. The producer and consumer templates

Throughout this book, you’ve seen the ProducerTemplate used as an easy way of sending messages to a Camel endpoint. While it was simple to understand in those cases, there are many more options to the ProducerTemplate. There is also an analog for consumers—the ConsumerTemplate, which makes consuming messages easy.

Both of these templates are inspired by the template utility classes in the Spring Framework that simplify access to an API. In Spring, you may have used a JmsTemplate or JdbcTemplate to simplify access to the JMS and JDBC APIs. In the case of Camel, the ProducerTemplate and ConsumerTemplate interfaces allow you to easily work with producers and consumers.

By “easily work,” we mean you can send a message to any kind of Camel component in only one line of code. For example, the following code sends a JMS text message to the ActiveMQ JMS queue named quotes:

producerTemplate.sendBody("activemq:quotes", "Camel Rocks");

Anyone who has worked with the JMS API will know that it takes quite a bit of work to replicate what Camel does in that single line of code.

In this appendix, we’ll show you how to use the ProducerTemplate and ConsumerTemplate in detail.

C.1. The ProducerTemplate

The ProducerTemplate has a lot of methods that at first may seem a bit overwhelming. But these methods make it powerful and flexible, which in turn makes it a time saver in many situations.

Table C.1 lists the most commonly used ProducerTemplate methods. Notice that the table lists two sets of methods: send and request methods. It’s very important to know the difference between these two. Send methods are used for InOnly-style messaging, where you send a message to a given endpoint and don’t expect any reply. Request methods are used for InOut-style messaging, where you send a message to a given endpoint and expect and wait for a reply.

Table C.1. The most commonly used ProducerTemplate methods

Method	MEP	Description
sendBody	InOnly	Sends a message payload to a destination.
sendBodyAndHeader	InOnly	Sends a message payload and a header to a destination.
sendBodyAndHeaders	InOnly	Sends a message payload with a map of headers to a destination.
requestBody	InOut	Sends a message payload to a destination. The reply from the destination is returned.
requestBodyAndHeader	InOut	Sends a message payload and a header to a destination. The reply from the destination is returned.
requestBodyAndHeaders	InOut	Sends a message payload with a map of headers to a destination. The reply from the destination is returned.

The ProducerTemplate has many variations on these methods, which you’ll learn to appreciate over time. Also, for each of these methods there’s a corresponding asynchronous method. If you wanted to send a message body asynchronously, you could use the asyncSendBody method instead of the sendBody method. Chapter 10 details these methods and how to use them.

C.1.1. Using the ProducerTemplate

Here’s an example of how to use the ProducerTemplate to send a message to a JMS topic that’s used to audit orders.

Listing C.1. Using a ProducerTemplate to send a message to a JMS topic

In the constructor, you create a new instance of the ProducerTemplate by invoking createProducerTemplate on the CamelContext. This template is then used when sending the audit messages .

To try this out for yourself, find the appendixC/producer directory in the book’s source and run the following Maven command:

mvn test –Dtest=ProducerTemplateInOnlyTest

If you were instead accessing an HTTP service that returned a reply, you would need to use one of the request methods from table C.1. Here’s how you could do this.

Listing C.2. Using a ProducerTemplate to get a reply from an endpoint

Here you use the requestBody method to invoke a remote HTTP service with a header id set to the specified order ID. You then get the order status returned as a string. Notice that you pass in null for the body because this particular web service only needs the id header. The HTTP producer will send an HTTP GET request in this case.

This example is found in the appendixC/producer directory of the book’s source and can be tested using the following Maven command:

mvn test –Dtest=ProducerTemplateInOutTest

Rather than creating these templates by directly invoking the CamelContext, you can use features built into the Spring DSL to do this. The template and consumerTemplate elements within the camelContext element allow you to create a template and then refer to it later by using its ID. Let’s look at this in action.

Listing C.3. Declaring reusable producer and consumer templates

Within the camelContext element, you declare reusable templates ( and ) that you can wire into the OrderStatusBean from listing C.2 by using the bean ID .

 

Note

You may find the template element name a bit confusing. Why not use the name producerTemplate to align with the consumerTemplate element? At first, in Camel, there was only the producer template so the XML element was named template. When the consumer template was introduced, the template element name was kept to be backwards compatible.

 

You can find listing C.3 along with a test case in the appendixC/producer directory. Run the test case with the following Maven command:

mvn test -Dtest=ProducerTemplateDefinedInSpringTest

Next, we’ll focus on the ConsumerTemplate, which you may not have seen much of yet.

C.2. The ConsumerTemplate

The ConsumerTemplate doesn’t have as many methods as the ProducerTemplate. It only works using the InOnly messaging style, where you use it to poll a given endpoint for a message. Table C.2 lists the methods you’re most likely to use.

Table C.2. The most commonly used ConsumerTemplate methods

Method	MEP	Description
receive	InOnly	Polls an endpoint to receive a message and will wait until a message exists. The entire message is returned.
receive(Timeout)	InOnly	Polls an endpoint to receive a message, and will wait until a timeout occurs. The entire message is returned.
receiveNoWait	InOnly	Polls an endpoint to receive a message, but will not wait if a message doesn’t exist. The entire message is returned.
receiveBody	InOnly	Polls an endpoint to receive a message, and will wait until a message exists. Only the message body is returned.
receiveBody(Timeout)	InOnly	Polls an endpoint to receive a message, and will wait until a timeout occurs. Only the message body is returned.
receiveBodyNoWait	InOnly	Polls an endpoint to receive a message, but will not wait if a message doesn’t exist. Only the message body is returned.

Let’s take a moment to see how you could use the ConsumerTemplate to solve a problem that’s been asked about again and again on the Camel mailing lists: how can you use Camel to empty a JMS queue?

C.2.1. Using the ConsumerTemplate

You can use the ConsumerTemplate much like the ProducerTemplate. For example, you can use it to empty a JMS queue containing new orders, as shown in listing C.4. Notice how easily you can use the receiveBody method from table C.2 to retrieve a message from a JMS queue.

Listing C.4. Using the ConsumerTemplate to poll a JMS queue

The OrderCollectorBean bean uses a setter for the ConsumerTemplate so you can inject it using Spring as follows:

<bean id="orderCollectorBean" class="camelinaction.OrderCollectorBean">
  <property name="consumer" ref="consumerTemplate"/>
</bean>

Of course, this requires that you already have a consumerTemplate element defined, as shown in listing C.3.

 

Tip

The template and consumerTemplate elements are optional. If you have no need to refer to them by ID or configure any options on them, you can just inject them into your bean by type, using Spring’s @Autowired annotation. This is possible because Camel creates a default instance of each on startup.

 

You can then empty the order queue by looping until a null body is returned . By using the receiveBody method with a timeout of 1000 milliseconds, you’ll wait for 1 second before returning a null when the queue is empty.

This example can be found in the appendixC/consumer directory of the book’s source. Run the test case with the following Maven command:

mvn test

The test case essentially populates the “orders” queue in ActiveMQ with a few messages and then invokes the OrderCollectorBean to retrieve them.

C.3. Summary

In this appendix we looked at the extremely useful producer and consumer templates. These two templates give you a way of quickly accessing any Camel endpoint with one method call. In addition to the examples presented in this appendix, the ProducerTemplate is used throughout the book.