Spring/spring-integration
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

reference documentation updates for M2

Browse Source
This commit is contained in:
Mark Fisher
2008-02-27 20:55:25 +00:00
parent 949848fb04
commit 82ce4ad3cf
3 changed files with 62 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
spring-integration-reference/reference/src/core-api.xml
View File

@@ -13,6 +13,7 @@
Object getId();
MessageHeader getHeader();
T getPayload();
boolean isExpired();
}</programlisting>
And the header provides the following properties:
<table id="api-message-headerproperties">
@@ -39,8 +40,8 @@
<entry>java.lang.Object</entry>
</row>
<row>
<entry>replyChannelName</entry>
<entry>java.lang.String</entry>
<entry>returnAddress</entry>
<entry>java.lang.Object (can be a String or MessageChannel)</entry>
</row>
<row>
<entry>sequenceNumber</entry>
@@ -50,6 +51,10 @@
<entry>sequenceSize</entry>
<entry>int</entry>
</row>
<row>
<entry>priority</entry>
<entry>int</entry>
</row>
<row>
<entry>properties</entry>
<entry>java.util.Properties</entry>
@@ -64,11 +69,14 @@
</para>
<para>
The base implementation of the <interfacename>Message</interfacename> interface is
<classname>GenericMessage&lt;T&gt;</classname>, and it provides two constructors:
<classname>GenericMessage&lt;T&gt;</classname>, and it provides three constructors:
<programlisting>new GenericMessage&lt;T&gt;(Object id, T payload);
new GenericMessage&lt;T&gt;(T payload);</programlisting>
When no id is provided, a random unique id will be generated. There are also two convenient subclasses available
currently: <classname>StringMessage</classname> and <classname>ErrorMessage</classname>. The latter accepts any
new GenericMessage&lt;T&gt;(T payload);
new GenericMessage&lt;T&gt;(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>
@@ -88,20 +96,35 @@ new GenericMessage&lt;T&gt;(T payload);</programlisting>
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>public interface MessageChannel {
<programlisting><![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);
}</programlisting>
The <classname>SimpleChannel</classname> implementation wraps a queue. It provides a no-argument constructor as
well as a constructor that accepts the queue capacity:
<programlisting>public SimpleChannel(int capacity)</programlisting>
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>SimpleChannel</classname> implementation wraps a queue. It provides a no-argument constructor as
well as a constructor that accepts the queue capacity:
<programlisting>public SimpleChannel(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>SimpleChannel</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&lt;Message&lt;?&gt;&gt;</classname> can be provided to the
<classname>PriorityChannel</classname>'s constructor.
</para>
</section>
@@ -114,10 +137,10 @@ new GenericMessage&lt;T&gt;(T payload);</programlisting>
Message&lt;?&gt; handle(Message&lt;?&gt; message);
}</programlisting>
The handler plays an important role, since it is typically responsible for translating between the generic
<interfacename>Message</interfacename> objects and the business components that consume the message payload.
That said, developers will rarely need to implement this callback 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.
<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>
@@ -139,12 +162,14 @@ new GenericMessage&lt;T&gt;(T payload);</programlisting>
the following methods:
<programlisting>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>
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.
We will briefly take a look at each of those metadata objects.
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
@@ -162,6 +187,11 @@ public void registerHandler(String name, MessageHandler handler, Subscription su
</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>
@@ -221,9 +251,10 @@ public void registerHandler(String name, MessageHandler handler, Subscription su
</tbody>
</tgroup>
</table>
The scheduling metadata is provided with an instance 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 called <classname>PollingSchedule</classname> that provides the following properties:
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 called <classname>PollingSchedule</classname> that provides the following
properties:
<table id="api-messagebus-pollingschedule">
<title>Properties of the PollingSchedule</title>
<tgroup cols="3">

15
spring-integration-reference/reference/src/overview.xml
View File

@@ -121,17 +121,17 @@
Controller in the MVC paradigm. Just as a Controller handles HTTP requests, the endpoint handles Messages. Just
as Controllers are mapped to URL patterns, endpoints are mapped to Message Channels. The goal is the same in
both cases: isolate application code from the infrastructure. In Spring Integration, the Message Endpoint
invokes a <interfacename>MessageHandler</interfacename> callback interface as described in
"hosts" and delegates to a <interfacename>MessageHandler</interfacename> strategy interface as described in
<xref linkend="api-messagehandler"/>.
</para>
</section>
<section id="overview-component-router">
<title>Message Router</title>
<para>
A Message Router is a particular type of endpoint that is capable of receiving a Message and then deciding what
channel or channels should receive the Message next. Typically the decision is based upon the Message's content
and/or metadata. A Message Router is often used as a dynamic alternative to configuring the input and output
channels for an endpoint.
A Message Router is a particular type of <interfacename>MessageHandler</interfacename> that is capable of
receiving a Message and then deciding what channel or channels should receive the Message next. Typically the
decision is based upon the Message's content and/or metadata. A Message Router is often used as a dynamic
alternative to configuring the input and output channels for an endpoint.
</para>
</section>
<section id="overview-component-channeladapter">
@@ -141,8 +141,9 @@
Message Endpoints. These adapters provide a mechanism for connecting to external systems, such as JMS queues
or a File system. Channel Adapters may be configured for input and/or output. An input (source) adapter will
receive (or poll for) data, convert that data to a Message, and then send that Message to its Message Channel.
An output (target) adapter is simply another type of Message Endpoint, but when it receives a Message, it will
convert it to the target's expected type and then "send" it (publish to a JMS queue, write to a File, etc.).
An output (target) adapter is simply another type of <interfacename>MessageHandler</interfacename>, but when it
receives a Message, it will convert it to the target's expected type and then "send" it (publish to a JMS
queue, write to a File, etc.).
</para>
</section>
<section id="overview-component-bus">

4
spring-integration-reference/reference/src/spring-integration-reference.xml
View File

@@ -13,7 +13,7 @@
<title>Spring Integration Reference Manual</title>
<productname>Spring Integration</productname>
<releaseinfo>1.0.0.m1 (Milestone 1)</releaseinfo>
<releaseinfo>1.0.0.m2 (Milestone 2)</releaseinfo>
<mediaobject>
<imageobject role="fo">
@@ -31,7 +31,7 @@
</author>
</authorgroup>
<legalnotice>Copyright &copy; SpringSource Inc., 2007</legalnotice>
<legalnotice>Copyright &copy; SpringSource Inc., 2008</legalnotice>
</bookinfo>
<toc></toc>