Updating Reference Documentation for M4.

spring-integration-reference/src/adapters.xml

@@ -1,7 +1,7 @@
 <?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="adapters">
-  <title>Channel Adapters</title>
+  <title>Adapters</title>
 
   <section id="adapters-intro">
     <title>Introduction</title>

spring-integration-reference/src/appendix.xml

@@ -0,0 +1,25 @@
+<?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="appendix">
+  <title>Appendix</title>
+
+  <section id="appendix-schemas">
+    <title>Spring Integration XML Schema Overview</title>
+    <section>
+      <title>Spring Integration Core</title>
+      <para>
+      </para>
+    </section>
+    <section>
+      <title>Spring Integration Adapters</title>
+      <para>
+      </para>
+    </section>
+    <section>
+      <title>Spring Integration Web Services Support</title>
+      <para>
+      </para>
+    </section>
+  </section>
+
+</chapter>

spring-integration-reference/src/core-api.xml

@@ -102,6 +102,48 @@ new GenericMessage&lt;T&gt;(T payload, MessageHeader headerToCopy)</programlisti
     </para>
   </section>
 
+  <section id="api-source">
+    <title>Source</title>
+    <para>
+      The <interfacename>Source</interfacename> interface defines a single method for receiving
+      <interfacename>Message</interfacename> objects.
+      <programlisting language="java">public interface Source&lt;T&gt; {
+    Message&lt;T&gt; receive();
+}</programlisting>
+      Spring Integration also provides a <classname>MethodInvokingSource</classname> implementation that serves as an
+      adapter for invoking any arbitrary method on a plain Object (i.e. there is no need to implement an interface).
+      To use the <classname>MethodInvokingSource</classname>, provide the Object reference and the method name.
+      <programlisting language="java">MethodInvokingSource source = new MethodInvokingSource();
+source.setObject(new SourceObject());
+source.setMethod("sourceMethod");
+Message&lt;?&gt; result = source.receive();</programlisting>
+      It is generally more common to configure a <classname>MethodInvokingSource</classname> in XML by providing a
+      bean reference.
+      <programlisting language="xml"><![CDATA[<source-adapter id="source" ref="sourceObject" method="sourceMethod"/>]]></programlisting>
+	</para>
+  </section>
+
+  <section id="api-target">
+    <title>Target</title>
+    <para>
+      The <interfacename>Target</interfacename> interface defines a single method for sending
+      <interfacename>Message</interfacename> objects.
+      <programlisting language="java">public interface Target {
+    boolean send(Message&lt;?&gt; message);
+}</programlisting>
+      As with the <interfacename>Source</interfacename>, Spring Integration also provides a
+      <classname>MethodInvokingTarget</classname> adapter class.
+      <programlisting language="java">MethodInvokingTarget target = new MethodInvokingTarget();
+target.setObject(new TargetObject());
+target.setMethodName("targetMethod");
+target.afterPropertiesSet();
+target.send(new StringMessage("test"));</programlisting>
+      Likewise, the corresponding XML configuration is very similar to that of
+      <classname>MethodInvokingSource</classname>.
+      <programlisting language="xml"><![CDATA[<target-adapter id="target" ref="targetObject" method="targetMethod"/>]]></programlisting>
+	</para>
+  </section>
+
   <section id="api-messagechannel">
     <title>MessageChannel</title>
     <para>
@@ -198,17 +240,17 @@ new GenericMessage&lt;T&gt;(T payload, MessageHeader headerToCopy)</programlisti
   <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.
+      So far, you have seen that 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
+      one of the primary responsibilities that it assumes is connecting the channels to the handlers. It also connects
+      Sources and Targets to channels, and it manages the scheduling of pollers and dispatchers.
     </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
+      by delegating to other strategies. One of its main 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)
@@ -394,24 +436,26 @@ public void registerHandler(String name, MessageHandler handler,
   <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>
+      As described in <xref linkend="overview"/>, there are three implementations of the
+      <interfacename>MessageEndpoint</interfacename> interface: <classname>SourceEndpoint</classname>,
+      <classname>TargetEndpoint</classname>, and <classname>HandlerEndpoint</classname>. These endpoints provide the
+      metadata necessary for the <classname>MessageBus</classname> to manage <interfacename>Sources</interfacename>,
+      <interfacename>Targets</interfacename>, and <interfacename>MessageHandlers</interfacename> respectively.
     </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>.
+      For a <interfacename>SourceEndpoint</interfacename>, the <classname>MessageBus</classname> schedules a task for
+      polling the <interfacename>Source</interfacename> based on the provided schedule.
+    </para>
+    <para>
+      When a <interfacename>Target</interfacename> or <interfacename>MessageHandler</interfacename> is registered with
+      the <classname>MessageBus</classname>, the bus assigns it to a dispatcher that polls a
+      <interfacename>MessageChannel</interfacename> based on the provided schedule. Targets and handlers may also
+      provide concurrency settings in which case a thread pool will be created for asynchronous processing of messages.
+    </para>
+    <para>
+      Rather than programming to the API directly, it is simpler and more common to register sources, targets, and
+      handlers with either XML or annotation-based metadata. Then, the message endpoint is an internal responsibility
+      of the bus. The configuration options are discussed in detail in <xref linkend="configuration"/>.
     </para>
   </section>
 

spring-integration-reference/src/overview.xml

@@ -100,31 +100,144 @@
 	    framework while handling that object. It consists of a payload and header and has a unique identifier. The
         payload can be of any type and the header holds commonly required information such as timestamp, expiration,
         and return address. Developers can also store any arbitrary key-value properties or attributes in the header.
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/message.png" format="PNG"/>
+          </imageobject>
+        </mediaobject>        
+      </para>
+    </section>
+    <section id="overview-components-source">
+      <title>Message Source</title>
+      <para>
+        Since a Spring Integration Message is a generic wrapper for any Object, there is no limit to the number of
+        potential sources for such messages. In fact, a Source implementation can act as an adapter that converts
+        Objects from any other system into Spring Integration Messages.
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/source.png" format="PNG"/>
+          </imageobject>
+        </mediaobject>
+        To facilitate the conversion of Objects to Messages, Spring Integration also defines a strategy interface
+        for creating Messages called <interfacename>MessageCreator</interfacename>. While it is relatively easy to
+        implement Source directly, an adapter is also available for invoking arbitrary methods on plain Objects. Also,
+        several Source implementations are already available within the Spring Integration Adapters module. For a
+        detailed discussion of the various adapters, see <xref linkend="adapters"/>.
+      </para>
+    </section>
+    <section>
+      <title>Message Target</title>
+      <para>
+        Just as a Source enables Message reception, a Target handles the responsibility of sending Messages. As with
+        a Source, a Target can act as an adapter that converts Messages into the Objects expected by some other system.
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/target.png" format="PNG"/>
+          </imageobject>
+        </mediaobject>
+        Spring Integration provides a strategy interface for mapping Messages to Objects called
+        <interfacename>MessaegMapper</interfacename>. The Target interface may be implemented directly, but an adapter
+        is also available for invoking arbitrary methods on plain Objects (delegating to the Message-mapping strategy
+        in the process). As with Sources, several Target implementations are already available within the Spring
+        Integration Adapters module as discussed in <xref linkend="adapters"/>.
+      </para>
+    </section>
+    <section id="overview-components-handler">
+      <title>Message Handler</title>
+      <para>
+        As described above, the Source and Target components support conversion between Objects and Messages so that
+        application code and/or external systems can be connected to a Spring Integration application rather easily.
+        However, both Source and Target are unidirectional while the application code or external system to be invoked
+        may provide a return value. The Message Handler interface supports these request-reply scenarios.
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/handler.png" format="PNG"/>
+          </imageobject>
+        </mediaobject>
+        As with the Source and Target, Spring Integration also provides an adapter that itself implements the Message
+        Handler interface while supporting the invocation of arbitrary methods on plain Objects. The adapter relies
+        upon the message-creating and message-mapping strategies to handle the bidirectional Object/Message conversion.
+        For more information about the Message Handler, see <xref linkend="api-messagehandler"/>.
       </para>
     </section>
     <section id="overview-components-channel">
       <title>Message Channel</title>
       <para>
         A Message Channel represents the "pipe" of a pipes-and-filters architecture. Producers send Messages to
-        a MessageChannel, and consumers receive Messages from a MessageChannel. The send and receive methods both come
-        in two forms: one that blocks indefinitely and one that accepts a timeout (for an immediate return, specify a
-        timeout value of 0). There are two main types of channels: <emphasis>Point-to-Point</emphasis> channels where
-        typically a single consumer will receive the Message and <emphasis>Publish-Subscribe</emphasis> channels where
-        all subscribers should receive the Message.
+        a channel, and consumers receive Messages from a channel. By providing both send and receive operations, a
+        Message Channel basically combines the roles of Source and Target.
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/channel.png" format="PNG"/>
+          </imageobject>
+        </mediaobject>
+        Spring Integration provides a number of different channel implementations: QueueChannel, PriorityChannel,
+        RendezvousChannel, DirectChannel, and ThreadLocalChannel. These are described in detail in
+        <xref linkend="api-messagechannel"/>.
       </para>
     </section>
     <section id="overview-components-endpoint">
       <title>Message Endpoint</title>
       <para>
-        A Message Endpoint represents the "filter" of a pipes-and-filters architecture. The endpoint's primary role is
-        to connect application code to the messaging framework and to do so in a non-invasive manner. In other words,
-        the application code should have no awareness of the messaging framework. This is similar to the role of a
-        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
-        "hosts" and delegates to a <interfacename>MessageHandler</interfacename> strategy interface as described in
-        <xref linkend="api-messagehandler"/>.
+        Thus far, the component diagrams show Consumers, Producers, and Requesters invoking the Source, Target, and
+        Message Handlers respectively. However, one of the primary goals of Spring Integration is to simplify the
+        development of enterprise integration solutions through <emphasis>inversion of control</emphasis>. This means
+        that you should not have to implement such Producers, Consumers, and Requesters directly. Instead, you should
+        be able to focus on your domain logic with an implementation based on plain Objects. Then, by providing
+        declarative configuration, you can "connect" your application code to the messaging infrastructure provided by
+        Spring Integration. The components responsible for these connections are Message Endpoints. 
       </para>
+      <para>
+        A Message Endpoint represents the "filter" of a pipes-and-filters architecture. As mentioned above, the
+        endpoint's primary role is to connect application code to the messaging framework and to do so in a
+        non-invasive manner. In other words, the application code should have no awareness of the Message objects or
+        the Message Channels. This is similar to the role of a Controller in the MVC paradigm. Just as a Controller
+        handles HTTP requests, the Message Endpoint handles Messages. Just as Controllers are mapped to URL patterns,
+        Message Endpoints are mapped to Message Channels. The goal is the same in both cases: isolate application code
+        from the infrastructure. Spring Integration provides three types of endpoints - one for each of the component
+        types described above: Source Endpoint, Target Endpoint, and Handler Endpoint.
+      </para>
+      <section>
+        <title>Source Endpoint</title>
+        <para>
+          A Source Endpoint connects any Source implementation to a Message Channel. The invocation of the Source's
+          receive operation is controlled by scheduling information provided within the Source Endpoint's
+          configuration. Any time the receive operation returns a non-null Message, it is sent to the channel.
+          <mediaobject>
+            <imageobject>
+              <imagedata align="center" fileref="images/source-endpoint.png" format="PNG"/>
+            </imageobject>
+          </mediaobject>
+        </para>
+      </section>
+      <section>
+        <title>Target Endpoint</title>
+        <para>
+          A Target Endpoint connects a Message Channel to any Target implementation. The invocation of the Message
+          Channel's receive operation is controlled by scheduling information provided within the Target Endpoint's
+          configuration. Any time a non-null Message is received from the channel, it is sent to the Target.
+          <mediaobject>
+            <imageobject>
+              <imagedata align="center" fileref="images/target-endpoint.png" format="PNG"/>
+            </imageobject>
+          </mediaobject>
+        </para>
+      </section>
+      <section>
+        <title>Handler Endpoint</title>
+        <para>
+          Since Message Handler's are capable of returning reply Messages, the Handler Endpoint has some additional
+          responsibilities. The general behavior is the same as the Target Endpoint, but the Handler Endpoint must
+          make a distinction between "input-channel" and "output-channel". Whenever the Message Handler does return
+          a reply Message, that Message is sent to the output channel. If no output channel has been configured, then
+          the reply will be sent to the channel specified as the Message header's "return address" if available.
+          <mediaobject>
+            <imageobject>
+              <imagedata align="center" fileref="images/handler-endpoint.png" format="PNG"/>
+            </imageobject>
+          </mediaobject>
+        </para>
+      </section>
     </section>
     <section id="overview-component-router">
       <title>Message Router</title>
@@ -133,18 +246,11 @@
         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">
-      <title>Channel Adapter</title>
-      <para>
-        A Channel Adapter is used to connect components to a Message Channel when those components are not themselves
-        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 <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.).
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/router.png" format="PNG"/>
+          </imageobject>
+        </mediaobject>
       </para>
     </section>
     <section id="overview-component-bus">

spring-integration-reference/src/spring-integration-reference.xml

@@ -5,7 +5,7 @@
     <title>Spring Integration Reference Manual</title>
 
     <productname>Spring Integration</productname>
-    <releaseinfo>1.0.0.M3 (Milestone 3)</releaseinfo>
+    <releaseinfo>1.0.0.M4 (Milestone 4)</releaseinfo>
 
     <mediaobject>
       <imageobject role="fo">
@@ -38,5 +38,6 @@
   <xi:include href="./configuration.xml"/>
   <xi:include href="./samples.xml"/>
   <xi:include href="./resources.xml"/>
+  <xi:include href="./appendix.xml"/>
 
 </book>