An instance of org.apache.camel.Producer
type represents
a target endpoint in a route. The role of the producer is to send requests
(In messages) to a specific physical endpoint and to receive the
corresponding response (Out or Fault message). A
Producer
object is essentially a special kind of Processor
that
appears at the end of a processor chain (equivalent to a route). Figure 9.1 shows the inheritance hierarchy for
producers.
Example 9.1 shows the definition of the
org.apache.camel.Producer
interface.
Example 9.1. Producer Interface
package org.apache.camel; public interface Producer extends Processor, Service, IsSingleton { Endpoint<E> getEndpoint(); Exchange createExchange(); Exchange createExchange(ExchangePattern pattern); Exchange createExchange(E exchange); }
The Producer
interface defines the following
methods:
process()
(inherited from Processor)—The most important method. A producer is essentially a special type of processor that sends a request to an endpoint, instead of forwarding the exchange object to another processor. By overriding theprocess()
method, you define how the producer sends and receives messages to and from the relevant endpoint.getEndpoint()
—Returns a reference to the parent endpoint instance.createExchange()
—These overloaded methods are analogous to the corresponding methods defined in theEndpoint
interface. Normally, these methods delegate to the corresponding methods defined on the parentEndpoint
instance (this is what theDefaultEndpoint
class does by default). Occasionally, you might need to override these methods.
Processing an exchange object in a producer—which usually involves sending a
message to a remote destination and waiting for a reply—can potentially block for a
significant length of time. If you want to avoid blocking the current thread, you can opt to
implement the producer as an asynchronous processor. The asynchronous
processing pattern decouples the preceding processor from the producer, so that the
process()
method returns without delay. See Asynchronous Processing.
When implementing a producer, you
can support the asynchronous processing model by implementing the
org.apache.camel.AsyncProcessor
interface. On its own, this
is not enough to ensure that the asynchronous processing model will be used: it is also
necessary for the preceding processor in the chain to call the asynchronous version of the
process()
method. The definition of the
AsyncProcessor
interface is shown in Example 9.2.
Example 9.2. AsyncProcessor Interface
package org.apache.camel; public interface AsyncProcessor extends Processor { boolean process(Exchange exchange, AsyncCallback callback); }
The asynchronous version of the process()
method
takes an extra argument, callback
, of
org.apache.camel.AsyncCallback
type. The corresponding
AsyncCallback
interface is defined as shown in Example 9.3.
Example 9.3. AsyncCallback Interface
package org.apache.camel; public interface AsyncCallback { void done(boolean doneSynchronously); }
The caller of AsyncProcessor.process()
must provide
an implementation of AsyncCallback
to receive the
notification that processing has finished. The AsyncCallback.done()
method takes a boolean argument that indicates whether the processing was performed
synchronously or not. Normally, the flag would be false
, to indicate
asynchronous processing. In some cases, however, it can make sense for the producer
not to process asynchronously (in spite of being asked to do so). For
example, if the producer knows that the processing of the exchange will complete rapidly, it
could optimise the processing by doing it synchronously. In this case, the
doneSynchronously
flag should be set to
true
.
When implementing a producer, you might find it helpful to call some of the methods in
the org.apache.camel.util.ExchangeHelper
utility class. For full
details of the ExchangeHelper
class, see The ExchangeHelper Class.