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

Major progress on Gradle port

Browse Source 
Complete:
--------
- src/* documentation resources moved to 'docs' subproject

- docbook sources upgraded to Docbook 5

- formatted all docbook sources to strip tab characters and
  eliminate trailing whitespace

- all projects compile and test successfully

- all artifacts upload successfully to s3, static.sf.org, etc.

Remaining:
---------
- documentation L&F needs work. CSS, images, and highlighting aren't
  hooked up properly

- spring-integration-jdbc codegen bits in Maven POM need to be
  transcribed into gradle

- dependencies that were optional or provided scope in maven are
  currently 'compile' scope in Gradle.  Need to figure out support
  in Gradle to fix this.

- run through Eclipse classpath and project generation scenarios

- delete all Maven artifacts
This commit is contained in:
Chris Beams
2010-10-26 18:43:14 -04:00
parent d677da9c62
commit 677fca51a9
207 changed files with 10983 additions and 1459 deletions
Download Patch File Download Diff File Expand all files Collapse all files

405
docs/src/reference/docbook/router.xml Normal file
View File

@@ -0,0 +1,405 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="router"
xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Router</title>
<section id="router-implementations">
<title>Router Implementations</title>
<para>
Since content-based routing often requires some domain-specific logic, most use-cases will require
Spring Integration's options for delegating to POJOs using the XML namespace support and/or Annotations.
Both of these are discussed below, but first we present a couple implementations that are available
out-of-the-box since they fulfill generic, but common, requirements.
</para>
<section id="router-implementations-payloadtyperouter">
<title>PayloadTypeRouter</title>
<para>
A <classname>PayloadTypeRouter</classname> will send Messages to the channel as defined by payload-type
mappings.
<programlisting language="xml"><![CDATA[<bean id="payloadTypeRouter" class="org.springframework.integration.router.PayloadTypeRouter">
<property name="payloadTypeChannelMap">
<map>
<entry key="java.lang.String" value-ref="stringChannel"/>
<entry key="java.lang.Integer" value-ref="integerChannel"/>
</map>
</property>
</bean>]]></programlisting>
</para>
<para>
Configuration of <classname>PayloadTypeRouter</classname> is also supported via the namespace provided by Spring Integration (see <xref linkend="configuration-namespace"/>),
which essentially simplifies configuration by combining <code>&lt;router/&gt;</code> configuration and its corresponding implementation defined using <code>&lt;bean/&gt;</code> element
into a single and more concise configuration element.
The example below demonstrates <classname>PayloadTypeRouter</classname> configuration which is equivalent to the one above using Spring Integration's namespace support:
</para>
<para>
<programlisting language="xml"><![CDATA[<payload-type-router input-channel="routingChannel">
<mapping type="java.lang.String" channel="stringChannel" />
<mapping type="java.lang.Integer" channel="integerChannel" />
</payload-type-router>]]></programlisting>
</para>
</section>
<section id="router-implementations-headervaluerouter">
<title>HeaderValueRouter</title>
<para>
A <classname>HeaderValueRouter</classname> will send Messages to the channel based on the individual header value mappings.
When <code>HeaderValueRouter</code> is created it is initialized with the <emphasis>name</emphasis> of the header to be evaluated, using <code>constructor-arg</code>.
The <emphasis>value</emphasis> of the header could be one of two things:</para>
<para>
1. Arbitrary value
</para>
<para>
2. Channel name
</para>
<para>
If arbitrary value, then a <code>channelResolver</code> should be provided to map <emphasis>header values</emphasis> to <emphasis>channel names</emphasis>.
The example below uses <code>MapBasedChannelResolver</code> to set up a map of header values to channel names.
<programlisting language="xml"><![CDATA[ <bean id="myHeaderValueRouter"
class="org.springframework.integration.router.HeaderValueRouter">
<constructor-arg value="someHeaderName" />
<property name="channelResolver">
<bean class="org.springframework.integration.channel.MapBasedChannelResolver">
<property name="channelMap">
<map>
<entry key="someHeaderValue" value-ref="channelA" />
<entry key="someOtherHeaderValue" value-ref="channelB" />
</map>
</property>
</bean>
</property>
</bean>
]]></programlisting>
If <code>channelResolver</code> is not specified, then the <emphasis>header value</emphasis> will be treated as a <emphasis>channel name</emphasis>
making configuration much simpler, where no <code>channelResolver</code> needs to be specified.
<programlisting language="xml"><![CDATA[
<bean id="myHeaderValueRouter"
class="org.springframework.integration.router.HeaderValueRouter">
<constructor-arg value="someHeaderName" />
</bean>
]]></programlisting>
</para>
<para>
Similar to the <classname>PayloadTypeRouter</classname>, configuration of <classname>HeaderValueRouter</classname> is also supported via namespace support provided by Spring Integration (see <xref linkend="configuration-namespace"/>).
The example below demonstrates two types of namespace-based configuration of <classname>HeaderValueRouter</classname> which are equivalent to the ones above using Spring Integration namespace support:
</para>
<para>1. Configuration where mapping of header values to channels is required</para>
<para>
<programlisting language="xml"><![CDATA[<header-value-router input-channel="routingChannel" header-name="testHeader">
<mapping value="someHeaderValue" channel="channelA" />
<mapping value="someOtherHeaderValue" channel="channelB" />
</header-value-router>]]></programlisting>
</para>
<para>2. Configuration where mapping of header values is not required if header values themselves represent the channel names</para>
<para>
<programlisting language="xml"><![CDATA[<header-value-router input-channel="routingChannel" header-name="testHeader"/>]]></programlisting>
</para>
<note>
The two router implementations shown above share some common properties, such as "defaultOutputChannel" and "resolutionRequired".
If "resolutionRequired" is set to "true", and the router is unable to determine a target channel (e.g. there is
no matching payload for a PayloadTypeRouter and no "defaultOutputChannel" has been specified), then an Exception
will be thrown.
</note>
</section>
<section id="router-implementations-recipientlistrouter">
<title>RecipientListRouter</title>
<para>
A <classname>RecipientListRouter</classname> will send each received Message to a statically-defined
list of Message Channels:
<programlisting language="xml"><![CDATA[<bean id="recipientListRouter" class="org.springframework.integration.router.RecipientListRouter">
<property name="channels">
<list>
<ref bean="channel1"/>
<ref bean="channel2"/>
<ref bean="channel3"/>
</list>
</property>
</bean>]]></programlisting>
</para>
</section>
<para>
Configuration for <classname>RecipientListRouter</classname> is also supported via namespace support provided by Spring Integration (see <xref linkend="configuration-namespace"/>).
The example below demonstrates namespace-based configuration of <classname>RecipientListRouter</classname> and all the supported attributes using Spring Integration namespace support:
</para>
<para>
<programlisting language="xml"><![CDATA[<recipient-list-router id="customRouter" input-channel="routingChannel"
timeout="1234"
ignore-send-failures="true"
apply-sequence="true">
<recipient channel="channel1"/>
<recipient channel="channel2"/>
</recipient-list-router>]]></programlisting>
</para>
<note>
The 'apply-sequence' flag here has the same affect as it does for a publish-subscribe-channel,
and like publish-subscribe-channel it is disabled by default on the recipient-list-router. Refer to
<xref linkend="channel-configuration-pubsubchannel"/> for more information.
</note>
</section>
<section id="router-namespace">
<title>The &lt;router&gt; element</title>
<para>
The "router" element provides a simple way to connect a router to an input channel, and also accepts the
optional default output channel. The "ref" may provide the bean name of a custom Router implementation
(extending AbstractMessageRouter):
<programlisting language="xml"><![CDATA[<router ref="payloadTypeRouter" input-channel="input1" default-output-channel="defaultOutput1"/>
<router ref="recipientListRouter" input-channel="input2" default-output-channel="defaultOutput2"/>
<router ref="customRouter" input-channel="input3" default-output-channel="defaultOutput3"/>
<beans:bean id="customRouterBean class="org.foo.MyCustomRouter"/>]]></programlisting>
Alternatively, the "ref" may point to a simple Object that contains the @Router annotation (see below), or the
"ref" may be combined with an explicit "method" name. When specifying a "method", the same behavior applies as
described in the @Router annotation section below.
<programlisting language="xml"><![CDATA[<router input-channel="input" ref="somePojo" method="someMethod"/>]]></programlisting>
Using a "ref" attribute is generally recommended if the custom router implementation can be reused in other
<code>&lt;router&gt;</code> definitions. However if the custom router implementation should be scoped to a
concrete definition of the <code>&lt;router&gt;</code>, you can provide an inner bean definition:
<programlisting language="xml"><![CDATA[<router method="someMethod" input-channel="input3" default-output-channel="defaultOutput3">
<beans:bean class="org.foo.MyCustomRouter"/>
</router>]]></programlisting>
</para>
<note>
<para>
Using both the "ref" attribute and an inner handler definition in the same <code>&lt;router&gt;</code> configuration
is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
</para>
</note>
</section>
<section id="router-annotation">
<title>The @Router Annotation</title>
<para>
When using the <interfacename>@Router</interfacename> annotation, the annotated method can return either the
<interfacename>MessageChannel</interfacename> or <classname>String</classname> type. In the case of the latter,
the endpoint will resolve the channel name as it does for the default output. Additionally, the method can return
either a single value or a collection. When a collection is returned, the reply message will be sent to multiple
channels. To summarize, the following method signatures are all valid.
<programlisting language="java">@Router
public MessageChannel route(Message message) {...}
@Router
public List&lt;MessageChannel&gt; route(Message message) {...}
@Router
public String route(Foo payload) {...}
@Router
public List&lt;String&gt; route(Foo payload) {...}</programlisting>
</para>
<para>
In addition to payload-based routing, a common requirement is to route based on metadata available within the
message header as either a property or attribute. Rather than requiring use of the
<interfacename>Message</interfacename> type as the method parameter, the <interfacename>@Router</interfacename>
annotation may also use the @Header parameter annotation that is documented in <xref linkend="annotations"/>.
<programlisting language="java">@Router
public List&lt;String&gt; route(@Header("orderStatus") OrderStatus status)</programlisting>
</para>
</section>
<note>
For routing of XML-based Messages, including XPath support, see <xref linkend="xml"/>.
</note>
<section id="dynamic-routers">
<title>Dynamic Routers</title>
<para>
So as you can see, Spring Integration provides quite a few different router configurations for most common
<emphasis>content-based routing</emphasis> use cases as well as the option of implementing custom routers as POJOs.
For example; <emphasis>Payload Type Router</emphasis> provides a simple way to configure a router which computes <code>channels</code>
based on the <code>payload type</code> of the incoming Message while <emphasis>Header Value Router</emphasis> provides the
same convenience in configuring a router which computes <code>channels</code> based on evaluating the value
of a particular Message Header. There is also an <emphasis>expression-based</emphasis> (SpEL) routers where the <code>channel</code>
is determined based on evaluating an expression which gives these type of routers some dynamic characteristics.
</para>
<para>
However these routers share one common attribute - <emphasis>static configuration</emphasis>. Even in the case of
expression-based routers, the expression itself is defined as part of the router configuration which means that
<quote>the same expression operating on the same value will always result in the computation of the same channel</quote>.
This is good in most cases since such routes are well defined and therefore predictable. But there are times when we
need to change router configurations dynamically so message flows could be routed to a different channel.
</para>
<para> <emphasis>For example:</emphasis> </para>
<para>
You might want to bring down some part of your system for maintenance. So, temporarily you want to re-reroute
messages to a different message flow. Or you may want to introduce more granularity to your message flow by adding another
route to handle a more concrete type of java.lang.Number (in cases of Payload Type Router).
</para>
<para>
Unfortunately with static router configuration to accomplish this you'd have to bring down your entire application,
change the configuration of the router (change routes) and bring it back up. This is obviously not the solution.
</para>
<para>
<ulink url="http://www.eaipatterns.com/DynamicRouter.html">
Dynamic Router
</ulink>
pattern describes the mechanisms by which one can change/configure routers dynamically without
bringing down your system or individual routers. 
</para>
<para>
Before we get into the specifics of how it is accomplished in Spring Integration lets quickly summarize the
typical flow of the router, which consists of 3 simple steps:
<itemizedlist>
<listitem>
<para><emphasis>Step 1</emphasis> - Compute <code>channel identifier</code> which is a value calculated by the
router once it receives the Message. Typically it is a <classname>String</classname> or and instance of the actual
<classname>MessageChannel</classname>.</para>
</listitem>
<listitem>
<para><emphasis>Step 2</emphasis> - Resolve <code>channel identifier</code> to <code>channel name</code>. We'll describe
specifics of this process in a moment.</para>
</listitem>
<listitem>
<para><emphasis>Step 3</emphasis> - Resolve <code>channel name</code> to the actual <classname>MessageChannel</classname> </para>
</listitem>
</itemizedlist>
</para>
<para>
There is not much that could be done with regard to router dynamics if Step 1 results in the actual instance of the
<classname>MessageChannel</classname> simply because <classname>MessageChannel</classname> is the <emphasis>final product</emphasis> of any
router's job. However, if Step 1 results in <code>channel identifier</code> that is not and instance of <classname>MessageChannel</classname>,
then there are quite a few possibilities to influence the process of calculating what will be the final instance of the <classname>Message Channel</classname>.
Lets look at couple of the examples in the context of the 3 steps mentioned above: 
</para>
<para>
<emphasis>Payload Type Router</emphasis>
</para>
<para>
<programlisting language="xml"><![CDATA[<payload-type-router input-channel="routingChannel">
<mapping type="java.lang.String" channel="channel1" />
<mapping type="java.lang.Integer" channel="channel2" />
</payload-type-router>]]></programlisting>
</para>
<para>
Within the context of the Payload Type Router the 3 steps mentioned above would be realized as:
<itemizedlist>
<listitem>
<para><emphasis>Step 1</emphasis> - Compute <code>channel identifier</code> which is the fully qualified name of the payload type
(e.g., java.lang.String).</para>
</listitem>
<listitem>
<para><emphasis>Step 2</emphasis> - Resolve <code>channel identifier</code> to <code>channel name</code> where
the result of the previous step is used to select the appropriate value from the <emphasis>payload type mapping</emphasis>
defined via <code>mapping</code> element.</para>
</listitem>
<listitem>
<para><emphasis>Step 3</emphasis> - Resolve <code>channel name</code> to the actual instance of the
<classname>MessageChannel</classname> where using <classname>ChannelResolver</classname> router will obtain a
reference to a bean (which is hopefully a <classname>MessageChannel</classname>) identified by the result of the
previous step.</para>
</listitem>
</itemizedlist>
In other words each step feeds the next step until thr process completes.
</para>
<para>
<emphasis>Header Value Router</emphasis>
</para>
<para>
<programlisting language="xml"><![CDATA[<header-value-router input-channel="inputChannel" header-name="testHeader">
<mapping value="foo" channel="fooChannel" />
<mapping value="bar" channel="barChannel" />
</header-value-router>]]></programlisting>
</para>
<para>
Similar to the PayloadTypeRouter:
<itemizedlist>
<listitem>
<para><emphasis>Step 1</emphasis> - Compute <code>channel identifier</code> which is the value of the header identified by the
<code>header-name</code> attribute.</para>
</listitem>
<listitem>
<para><emphasis>Step 2</emphasis> - Resolve <code>channel identifier</code> to <code>channel name</code> where
the result of the previous step is used to select the appropriate value from the <emphasis>general mapping</emphasis>
defined via <code>mapping</code> element.</para>
</listitem>
<listitem>
<para><emphasis>Step 3</emphasis> - Resolve <code>channel name</code> to the actual instance of the
<classname>MessageChannel</classname> where using <classname>ChannelResolver</classname> router will obtain a
reference to a bean (which is hopefully a <classname>MessageChannel</classname>) identified by the result of the
previous step.</para>
</listitem>
</itemizedlist>
</para>
<para>
The above two configurations of two different router types look almost identical.
However if we look at the different configuration of the <classname>HeaderValueRouter</classname> we clearly see that
there is no <code>mapping</code> sub element:
<programlisting language="xml"><![CDATA[<header-value-router input-channel="inputChannel" header-name="testHeader">]]></programlisting>
But configuration is still perfectly valid. So the natural question is what about the maping in the Step 2?
</para>
<para>
What this means is that Step 2 is now an optional step. If mapping is not defined then the <code>channel identifier</code>
value computed in Step 1 will automatically be treated as the <code>channel name</code> which will now be resolved to the
actual <classname>MessageChannel</classname> in the Step 3. What it also means is that Step 2 is one of the key steps to
provide dynamic characteristics to the routers, since it introduces a process which
<emphasis>allows you to change the way 'channel identifier' resolves to 'channel name'</emphasis>,
thus influencing the process of determining the final instance of the <classname>MessageChannel</classname> from the initial
<code>channel identifier</code>. 
</para>
<para><emphasis>For Example:</emphasis> </para>
<para>
In the above configuration lets assume that the <code>testHeader</code> value is 'kermit' which is now a <code>channel identifier</code>
(Step 1). Since there is no mapping in this router, resolving this <code>channel identifier</code> to a <code>channel name</code>
(Step 2) is impossible and this <code>channel identifier</code> is now treated as <code>channel name</code>. However what if
there was mapping but for a different value, the end result would still be the same and that is:
<emphasis>if new value can not be determined through the process of resolving 'channel identifier' to a 'channel name',
such 'channel identifier' becomes 'channel name'</emphasis>
</para>
<para>
So all that is left is for Step 3 to resolve <code>channel name</code> ('kermit') to an actual instance of the
<classname>MessageChannel</classname> identified by this name. That will be done via default
<interface>ChannelResolver</interface> implementation which is <classname>BeanFactoryChannelResolver</classname> which
basically does a bean lookup by the name provided. So now all messages which contain the header/value pair as <code>testHeader=kermit</code>
are going to be routed to a 'kermit' <classname>MessageChannel</classname>.
</para>
<para>
But what if you want to route these messages to 'simpson' channel? Obviously changing static configuration would work,
but would also require bringing your system down. However if you had access to <code>channel identifier</code> map, then you
could just introduce a new mapping where header/value pair is now <code>kermit=simpson</code>, thus allowing Step 2 to treat
'kermit' as <code>channel identifier</code> while resolving it to 'simpson' as <code>channel name</code> .
</para>
<para>
The same obviously applies for <classname>PayloadTypeRouter</classname> where you can now remap or remove a particular <emphasis>payload type
mapping</emphasis>, and every other router including <emphasis>expression-based</emphasis> routers since their computed value
will now have a chance to go through Step 2 to be aditionally resolved to the actual <code>channel name</code>.
</para>
<para>
In Spring Integration 2.0 routers hierarchy underwent major refactoring and now any router that is a subclass of the
<classname>AbstractMessageRouter</classname> (all framework defined routers) is a Dynamic Router simply because
<code>channelIdentiferMap</code> is defined at the <classname>AbstractMessageRouter</classname> with convenient accessors
and modifiers exposed as public methods allowing you to change/add/remove router mapping at runtime via JMX (see section section 29) or
ControlBus (see section section 29.7) functionality. 
</para>
<para>
<emphasis>Control Bus</emphasis>
</para>
<para>
One of the way to manage the router mappings is through the <ulink url="http://www.eaipatterns.com/ControlBus.html">Control Bus</ulink>
which exposes a Control Channel where you can send
control messages to manage and monitor Spring Integration components which includes routers.
For more information about the Control Bus see section 29.7. Typically you would send a control message asking to invoke a
particular JMX operation on a particular managed component (e.g., router). The two managed operations (methods) that are
specific to changing router resolution process are:
<itemizedlist>
<listitem>
<para><emphasis>public void setChannelMapping(String channelIdentifier, String channelName)</emphasis> -
will allow you to add new or modify existing mapping of <code>channel identifier</code> to <code>channel name</code></para>
</listitem>
<listitem>
<para><emphasis>public void removeChannelMapping(String channelIdentifier)</emphasis> -
will allow you to remove a particular channel mapping, thus disconnecting the relationship between
<code>channel identifier</code> and <code>channel name</code> </para>
</listitem>
</itemizedlist>
There are obviously other managed operations, so please refer to an <classname>AbstractMessageRouter</classname> for more detail
</para>
<para>
You can also use your favorite JMX client (e.g., JConsole) and use those operations (methods) to change
router configuration. For more information on Spring Integration management and monitoring please visit
section 29 of this manual.
</para>
</section>
</chapter>