461 lines
24 KiB
XML
461 lines
24 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
<chapter id="api">
|
|
<title>The Core API</title>
|
|
|
|
<section id="api-message">
|
|
<title>Message</title>
|
|
<para>
|
|
The Spring Integration <interfacename>Message</interfacename> is a generic container for data. Any object can
|
|
be provided as the payload, and each <interfacename>Message</interfacename> also includes a header containing
|
|
user-extensible properties as key-value pairs. Here is the definition of the
|
|
<interfacename>Message</interfacename> interface:
|
|
<programlisting language="java">public interface Message<T> {
|
|
Object getId();
|
|
MessageHeader getHeader();
|
|
T getPayload();
|
|
boolean isExpired();
|
|
}</programlisting>
|
|
And the header provides the following properties:
|
|
<table id="api-message-headerproperties">
|
|
<title>Properties of the MessageHeader</title>
|
|
<tgroup cols="2">
|
|
<colspec align="left" />
|
|
<thead>
|
|
<row>
|
|
<entry align="center">Property Name</entry>
|
|
<entry align="center">Property Type</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>timestamp</entry>
|
|
<entry>java.util.Date</entry>
|
|
</row>
|
|
<row>
|
|
<entry>expiration</entry>
|
|
<entry>java.util.Date</entry>
|
|
</row>
|
|
<row>
|
|
<entry>correlationId</entry>
|
|
<entry>java.lang.Object</entry>
|
|
</row>
|
|
<row>
|
|
<entry>returnAddress</entry>
|
|
<entry>java.lang.Object (can be a String or MessageChannel)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>sequenceNumber</entry>
|
|
<entry>int</entry>
|
|
</row>
|
|
<row>
|
|
<entry>sequenceSize</entry>
|
|
<entry>int</entry>
|
|
</row>
|
|
<row>
|
|
<entry>priority</entry>
|
|
<entry>MessagePriority (an <emphasis>enum</emphasis>)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>properties</entry>
|
|
<entry>java.util.Properties</entry>
|
|
</row>
|
|
<row>
|
|
<entry>attributes</entry>
|
|
<entry>Map<String,Object></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
<para>
|
|
The base implementation of the <interfacename>Message</interfacename> interface is
|
|
<classname>GenericMessage<T></classname>, and it provides three constructors:
|
|
<programlisting language="java">new GenericMessage<T>(Object id, T payload);
|
|
new GenericMessage<T>(T payload);
|
|
new GenericMessage<T>(T payload, MessageHeader headerToCopy)</programlisting>
|
|
When no id is provided, a random unique id will be generated. The constructor that accepts a
|
|
<classname>MessageHeader</classname> will copy properties, attributes, and any 'returnAddress' from the
|
|
provided header. There are also two convenient subclasses available currently:
|
|
<classname>StringMessage</classname> and <classname>ErrorMessage</classname>. The latter accepts any
|
|
<classname>Throwable</classname> object as its payload.
|
|
</para>
|
|
<para>
|
|
The <classname>MessagePriority</classname> is only considered when using a <classname>PriorityChannel</classname>
|
|
(as described in the next section). It is defined as an <emphasis>enum</emphasis> with five possible values:
|
|
<programlisting language="java">public enum MessagePriority {
|
|
HIGHEST,
|
|
HIGH,
|
|
NORMAL,
|
|
LOW,
|
|
LOWEST
|
|
}</programlisting>
|
|
</para>
|
|
<para>
|
|
The <interfacename>Message</interfacename> is obviously a very important part of the API. By encapsulating the
|
|
data in a generic wrapper, the messaging system can pass it around without any knowledge of the data's type. As
|
|
the system evolves to support new types, or when the types themselves are modified and/or extended, the messaging
|
|
system will not be affected by such changes. On the other hand, when some component in the messaging system
|
|
<emphasis>does</emphasis> require access to information about the <interfacename>Message</interfacename>, such
|
|
metadata can typically be stored to and retrieved from the metadata in the header (the 'properties' and
|
|
'attributes').
|
|
</para>
|
|
</section>
|
|
|
|
<section id="api-messagechannel">
|
|
<title>MessageChannel</title>
|
|
<para>
|
|
While the <interfacename>Message</interfacename> plays the crucial role of encapsulating data, it is the
|
|
<interfacename>MessageChannel</interfacename> that decouples message producers from message consumers.
|
|
Spring Integration's <interfacename>MessageChannel</interfacename> interface is defined as follows.
|
|
<programlisting language="java"><![CDATA[public interface MessageChannel {
|
|
String getName();
|
|
void setName(String name);
|
|
DispatcherPolicy getDispatcherPolicy();
|
|
boolean send(Message message);
|
|
boolean send(Message message, long timeout);
|
|
Message receive();
|
|
Message receive(long timeout);
|
|
List<Message<?>> clear();
|
|
List<Message<?>> purge(MessageSelector selector);
|
|
}]]></programlisting>
|
|
When sending a message, the return value will be <emphasis>true</emphasis> if the message is sent successfully.
|
|
If the send call times out or is interrupted, then it will return <emphasis>false</emphasis>. Likewise when
|
|
receiving a message, the return value will be <emphasis>null</emphasis> in the case of a timeout or interrupt.
|
|
The <classname>QueueChannel</classname> implementation wraps a queue. It provides a no-argument constructor as
|
|
well as a constructor that accepts the queue capacity:
|
|
<programlisting language="java">public QueueChannel(int capacity)</programlisting>
|
|
Specifying a capacity of 0 will create a "direct-handoff" channel where a sender will block until the channel's
|
|
<methodname>receive()</methodname> method is called. Otherwise a channel that has not reached its capacity limit
|
|
will store messages in its internal queue, and the <methodname>send()</methodname> method will return immediately
|
|
even if no receiver is ready to handle the message.
|
|
</para>
|
|
<para>
|
|
Whereas the <classname>QueueChannel</classname> enforces first-in/first-out (FIFO) ordering, the
|
|
<classname>PriorityChannel</classname> is an alternative implementation that allows for messages to be ordered
|
|
within the channel based upon a priority. By default the priority is determined by the
|
|
'<literal>priority</literal>' property within each message's header. However, for custom priority determination
|
|
logic, a comparator of type <classname>Comparator<Message<?>></classname> can be provided to the
|
|
<classname>PriorityChannel</classname>'s constructor.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="api-channelinterceptor">
|
|
<title>ChannelInterceptor</title>
|
|
<para>
|
|
One of the advantages of a messaging architecture is the ability to provide common behavior and capture
|
|
meaningful information about the messages passing through the system in a non-invasive way. Since the
|
|
<interfacename>Messages</interfacename> are being sent to and received from
|
|
<interfacename>MessageChannels</interfacename>, those channels provide an opportunity for intercepting
|
|
the send and receive operations. The <interfacename>ChannelInterceptor</interfacename> strategy interface
|
|
provides methods for each of those operations:
|
|
<programlisting language="java"><![CDATA[public interface ChannelInterceptor {
|
|
boolean preSend(Message<?> message, MessageChannel channel);
|
|
void postSend(Message<?> message, MessageChannel channel, boolean sent);
|
|
boolean preReceive(MessageChannel channel);
|
|
void postReceive(Message<?> message, MessageChannel channel);
|
|
}]]></programlisting>
|
|
After implementing the interface, registering the interceptor with a channel is just a matter of calling:
|
|
<programlisting language="java">channel.addInterceptor(someChannelInterceptor);</programlisting>
|
|
The methods that return a <literal>boolean</literal> value can return '<literal>false</literal>' to prevent the
|
|
send or receive operation from proceeding (send would return 'false' and receive would return 'null').
|
|
</para>
|
|
<para>
|
|
Because it is rarely necessary to implement all of the interceptor methods, a
|
|
<classname>ChannelInterceptorAdapter</classname> class is also available for sub-classing. It provides no-op
|
|
methods (the <literal>void</literal> methods are empty, and the <literal>boolean</literal> methods return
|
|
<literal>true</literal>). Therefore, it is often easiest to extend that class and just implement the method(s)
|
|
that you need as in the following example.
|
|
<programlisting language="java"><![CDATA[public class CountingChannelInterceptor extends ChannelInterceptorAdapter {
|
|
|
|
private final AtomicInteger sendCount = new AtomicInteger();
|
|
|
|
@Override
|
|
public boolean preSend(Message<?> message, MessageChannel channel) {
|
|
sendCount.incrementAndGet();
|
|
return true;
|
|
}
|
|
}]]></programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="api-messagehandler">
|
|
<title>MessageHandler</title>
|
|
<para>
|
|
So far we have seen that generic message objects are sent-to and received-from simple channel objects. Here is
|
|
Spring Integration's callback interface for handling the <interfacename>Messages</interfacename>:
|
|
<programlisting language="java">public interface MessageHandler {
|
|
Message<?> handle(Message<?> message);
|
|
}</programlisting>
|
|
The handler plays an important role, since it is typically responsible for translating between the generic
|
|
<interfacename>Message</interfacename> objects and the domain objects or primitive values expected by business
|
|
components that consume the message payload. That said, developers will rarely need to implement this interface
|
|
directly. While that option will always be available, we will soon discuss the higher-level configuration options
|
|
including both annotation-driven techniques and XML-based configuration with convenient namespace support.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="api-messagebus">
|
|
<title>MessageBus</title>
|
|
<para>
|
|
There is a rather obvious gap in what we have reviewed thus far. The
|
|
<interfacename>MessageChannel</interfacename> provides a <methodname>receive()</methodname> method that returns
|
|
a <interfacename>Message</interfacename>, and the <interfacename>MessageHandler</interfacename> provides a
|
|
<methodname>handle()</methodname> method that accepts a <interfacename>Message</interfacename>, but how do the
|
|
messages get passed from the channel to the handler? As mentioned earlier, the <classname>MessageBus</classname>
|
|
provides a runtime form of inversion of control, and so the short answer is: you don't need to worry about it.
|
|
Nevertheless since this is a reference guide, we will explore this in a bit of detail.
|
|
</para>
|
|
<para>
|
|
The <interfacename>MessageBus</interfacename> is an example of a mediator. It performs a number of roles - mostly
|
|
by delegating to other strategies. One of its fundamental responsibilities is to manage registration of the
|
|
<interfacename>MessageChannels</interfacename> and <interfacename>MessageHandlers</interfacename>. It provides
|
|
the following methods:
|
|
<programlisting language="java">public void registerChannel(String name, MessageChannel channel)
|
|
|
|
public void registerHandler(String name, MessageHandler handler,
|
|
Subscription subscription)
|
|
|
|
public void registerHandler(String name, MessageHandler handler,
|
|
Subscription subscription,
|
|
ConcurrencyPolicy concurrencyPolicy)</programlisting>
|
|
As those method signatures reveal, the message bus is handling several of the concerns here so that the channel
|
|
and handler objects can be as simple as possible. These responsibilities include the creation and lifecycle
|
|
management of message dispatchers, the activation of handler subscriptions, and the configuration of thread
|
|
pools. The bus coordinates all of that behavior based upon the metadata provided via these registration methods,
|
|
and typically developers will not even use this API directly since the metadata can be provided in XML and/or
|
|
annotations. We will briefly take a look at each of those metadata objects.
|
|
</para>
|
|
<para>
|
|
The bus creates and manages dispatchers that pull messages from a channel in order to push those messages to
|
|
handlers subscribed to that channel. Each channel has a <classname>DispatcherPolicy</classname> that contains
|
|
metadata for configuring those dispatchers:
|
|
<table id="api-messagebus-dispatcherpolicy">
|
|
<title>Properties of the DispatcherPolicy</title>
|
|
<tgroup cols="3">
|
|
<colspec align="left"/>
|
|
<thead>
|
|
<row>
|
|
<entry align="center">Property Name</entry>
|
|
<entry align="center">Default Value</entry>
|
|
<entry align="center">Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>publishSubscribe</entry>
|
|
<entry>false</entry>
|
|
<entry>whether the dispatcher should attempt to publish to all of its handlers (rather than just one)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>maxMessagesPerTask</entry>
|
|
<entry>1</entry>
|
|
<entry>maximum number of messages to retrieve per poll</entry>
|
|
</row>
|
|
<row>
|
|
<entry>receiveTimeout</entry>
|
|
<entry>1000 (milliseconds)</entry>
|
|
<entry>how long to block on the receive call (0 for no blocking, -1 for indefinite block)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>rejectionLimit</entry>
|
|
<entry>5</entry>
|
|
<entry>maximum number of attempts to invoke handlers (e.g. no threads available)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>retryInterval</entry>
|
|
<entry>1000 (milliseconds)</entry>
|
|
<entry>amount of time to wait between successive attempts to invoke handlers</entry>
|
|
</row>
|
|
<row>
|
|
<entry>shouldFailOnRejectionLimit</entry>
|
|
<entry>true</entry>
|
|
<entry>whether to throw a <classname>MessageDeliveryException</classname> if the 'rejectionLimit' is
|
|
reached - if this is set to 'false', then such undeliverable messages would be dropped silently</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
<para>
|
|
The bus registers handlers with a channel's dispatcher based upon the <classname>Subscription</classname>
|
|
metadata provided to the <methodname>registerHandler()</methodname> method.
|
|
<table id="api-messagebus-subscription">
|
|
<title>Properties of the Subscription</title>
|
|
<tgroup cols="2">
|
|
<colspec align="left" />
|
|
<thead>
|
|
<row>
|
|
<entry align="center">Property Name</entry>
|
|
<entry align="center">Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>channel</entry>
|
|
<entry>the channel instance to subscribe to (an object reference)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>channelName</entry>
|
|
<entry>the name of the channel to subscribe to - only used as a fallback if 'channel' is null</entry>
|
|
</row>
|
|
<row>
|
|
<entry>schedule</entry>
|
|
<entry>the scheduling metadata (see below)</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
The scheduling metadata is provided as an implementation of the <interfacename>Schedule</interfacename>
|
|
interface. This is an abstraction designed to allow extensibility of schedulers for messaging tasks. Currently,
|
|
there is a single implementation named <classname>PollingSchedule</classname> that provides the following
|
|
properties:
|
|
<table id="api-messagebus-pollingschedule">
|
|
<title>Properties of the PollingSchedule</title>
|
|
<tgroup cols="3">
|
|
<colspec align="left"/>
|
|
<thead>
|
|
<row>
|
|
<entry align="center">Property Name</entry>
|
|
<entry align="center">Default Value</entry>
|
|
<entry align="center">Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>period</entry>
|
|
<entry>N/A</entry>
|
|
<entry>the delay interval between each poll</entry>
|
|
</row>
|
|
<row>
|
|
<entry>initialDelay</entry>
|
|
<entry>0</entry>
|
|
<entry>the delay prior to the first poll</entry>
|
|
</row>
|
|
<row>
|
|
<entry>timeUnit</entry>
|
|
<entry>TimeUnit.MILLISECONDS</entry>
|
|
<entry>time unit for 'period' and 'initialDelay'</entry>
|
|
</row>
|
|
<row>
|
|
<entry>fixedRate</entry>
|
|
<entry>false</entry>
|
|
<entry>'false' indicates fixed-delay (no backlog)</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
The <classname>PollingSchedule</classname> constructor requires the 'period' value.
|
|
</para>
|
|
<para>
|
|
The <classname>ConcurrencyPolicy</classname> is an optional parameter to provide when registering a handler.
|
|
When the <interfacename>MessageBus</interfacename> registers a handler, it will use these properties to configure
|
|
that handler's thread pool. These parameters are configurable on a per-handler basis since handlers may have
|
|
different performance characteristics and may have different expectations with regard to the volume of
|
|
throughput. The following table lists the available properties and their default values:
|
|
<table id="api-messagebus-concurrencypolicy">
|
|
<title>Properties of the ConcurrencyPolicy</title>
|
|
<tgroup cols="3">
|
|
<colspec align="left"/>
|
|
<thead>
|
|
<row>
|
|
<entry align="center">Property Name</entry>
|
|
<entry align="center">Default Value</entry>
|
|
<entry align="center">Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>coreSize</entry>
|
|
<entry>1</entry>
|
|
<entry>the core size of the thread pool</entry>
|
|
</row>
|
|
<row>
|
|
<entry>maxSize</entry>
|
|
<entry>10</entry>
|
|
<entry>the maximum size the thread pool can reach when under demand</entry>
|
|
</row>
|
|
<row>
|
|
<entry>queueCapacity</entry>
|
|
<entry>0</entry>
|
|
<entry>capacity of the queue which defers an increase of the pool size</entry>
|
|
</row>
|
|
<row>
|
|
<entry>keepAliveSeconds</entry>
|
|
<entry>60</entry>
|
|
<entry>how long added threads (beyond core size) should remain idle before being removed from the pool</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="api-messageendpoint">
|
|
<title>MessageEndpoint</title>
|
|
<para>
|
|
When <interfacename>MessageHandlers</interfacename> are registered with the <classname>MessageBus</classname>,
|
|
the bus assigns the handler to a dispatcher based on the provided schedule as described above. Internally, the
|
|
bus is creating and registering an instance that implements the <interfacename>MessageEndpoint</interfacename>
|
|
interface. This is where other handler metadata enters the picture (e.g. the concurrency settings). Basically,
|
|
you can consider the endpoint to be a composite handler built from a simple implementation of the
|
|
<interfacename>MessageHandler</interfacename> along with its metadata. In fact, the
|
|
<interfacename>MessageEndpoint</interfacename> does extend the <interfacename>MessageHandler</interfacename>
|
|
interface.
|
|
<programlisting language="java">public interface MessageEndpoint extends MessageHandler {
|
|
String getName();
|
|
Subscription getSubscription();
|
|
ConcurrencyPolicy getConcurrencyPolicy();
|
|
}</programlisting>
|
|
</para>
|
|
<para>
|
|
When using the API, it's simpler to register handlers with metadata and leave the message endpoint as an internal
|
|
responsibility of the bus. However, it is possible to create endpoints directly. Spring Integration provides a
|
|
single implementation: <classname>DefaultMessageEndpoint</classname>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="api-messageselector">
|
|
<title>MessageSelector</title>
|
|
<para>
|
|
As described above, when a <interfacename>MessageHandler</interfacename> is registered with the message bus, it
|
|
is hosted by an endpoint and thereby subscribed to a channel. Often it is necessary to provide additional
|
|
<emphasis>dynamic</emphasis> logic to determine what messages the handler should receive. The
|
|
<interfacename>MessageSelector</interfacename> strategy interface fulfills that role.
|
|
<programlisting language="java"><![CDATA[public interface MessageSelector {
|
|
boolean accept(Message<?> message);
|
|
}]]></programlisting>
|
|
A <interfacename>MessageEndpoint</interfacename> can be configured with zero or more selectors, and will only
|
|
receive messages that are accepted by each selector. Even though the interface is simple to implement, a couple
|
|
common selector implementations are provided. For example, the <classname>PayloadTypeSelector</classname>
|
|
provides similar functionality to Datatype Channels (as described in <xref linkend="namespace-channel"/>)
|
|
except that in this case the type-matching can be done by the endpoint rather than the channel.
|
|
<programlisting language="java"><![CDATA[PayloadTypeSelector selector = new PayloadTypeSelector(String.class, Integer.class);
|
|
assertTrue(selector.accept(new StringMessage("example")));
|
|
assertTrue(selector.accept(new GenericMessage<Integer>(123)));
|
|
assertFalse(selector.accept(new GenericMessage<SomeObject>(someObject)));
|
|
]]></programlisting>
|
|
Another simple but useful <interfacename>MessageSelector</interfacename> provided out-of-the-box is the
|
|
<classname>UnexpiredMessageSelector</classname>. As the name suggests, it only accepts messages that have
|
|
not yet expired.
|
|
</para>
|
|
<para>
|
|
Essentially, using a selector provides <emphasis>reactive</emphasis> routing whereas the Datatype Channel
|
|
and Message Router provide <emphasis>proactive</emphasis> routing. However, selectors accommodate additional
|
|
uses. For example, the <interfacename>MessageChannel</interfacename>'s 'purge' method accepts a selector:
|
|
<programlisting language="java">channel.purge(someSelector);</programlisting>
|
|
There is even a <classname>ChannelPurger</classname> utility class whose purge operation is a good candidate for
|
|
Spring's JMX support:
|
|
<programlisting language="java">ChannelPurger purger = new ChannelPurger(new ExampleMessageSelector(), channel);
|
|
purger.purge();</programlisting>
|
|
</para>
|
|
<para>
|
|
Implementations of <interfacename>MessageSelector</interfacename> might provide opportunities for reuse on
|
|
channels in addition to endpoints. For that reason, Spring Integration provides a simple selector-wrapping
|
|
<interfacename>ChannelInterceptor</interfacename> that accepts one or more selectors in its constructor.
|
|
<programlisting language="java">MessageSelectingInterceptor interceptor =
|
|
new MessageSelectingInterceptor(selector1, selector2);
|
|
channel.addInterceptor(interceptor);</programlisting>
|
|
</para>
|
|
</section>
|
|
</chapter> |