68 lines
4.7 KiB
XML
68 lines
4.7 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
<chapter id="service-activator">
|
|
<title>Service Activator</title>
|
|
|
|
<section id="service-activator-introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
The Service Activator is the endpoint type for connecting any Spring-managed Object to an input channel so that
|
|
it may play the role of a service. If the service produces output, it may also be connected to an output channel.
|
|
Alternatively, an output producing service may be located at the end of a processing pipeline or message flow in
|
|
which case, the inbound Message's "replyChannel" header can be used. This is the default behavior if no output
|
|
channel is defined, and as with most of the configuration options you'll see here, the same behavior actually
|
|
applies for most of the other components we have seen.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="service-activator-namespace">
|
|
<title>The <service-activator/> Element</title>
|
|
<para>
|
|
To create a Service Activator, use the 'service-activator' element with the 'input-channel' and 'ref' attributes:
|
|
<programlisting language="xml"><service-activator input-channel="exampleChannel" ref="exampleHandler"/></programlisting>
|
|
</para>
|
|
<para>
|
|
The configuration above assumes that "exampleHandler" either contains a single method annotated with the
|
|
@ServiceActivator annotation or that it contains only one public method at all. To delegate to an explicitly
|
|
defined method of any object, simply add the "method" attribute.
|
|
<programlisting language="xml"><service-activator input-channel="exampleChannel" ref="somePojo" method="someMethod"/></programlisting>
|
|
</para>
|
|
<para>
|
|
In either case, when the service method returns a non-null value, the endpoint will attempt to send the reply
|
|
message to an appropriate reply channel. To determine the reply channel, it will first check if an
|
|
"output-channel" was provided in the endpoint configuration:
|
|
<programlisting language="xml"><service-activator input-channel="exampleChannel" output-channel="replyChannel"
|
|
ref="somePojo" method="someMethod"/></programlisting>
|
|
If no "output-channel" is available, it will then check the Message's <literal>RETURN_ADDRESS</literal> header
|
|
value. If that value is available, it will then check its type. If it is a
|
|
<interfacename>MessageChannel</interfacename>, the reply message will be sent to that channel. If it is a
|
|
<classname>String</classname>, then the endpoint will attempt to resolve the channel name to a channel instance.
|
|
If the channel cannot be resolved, then a <classname>ChannelResolutionException</classname> will be thrown.
|
|
</para>
|
|
<para>
|
|
The argument in the service method could be either a Message or an arbitrary type. If the later one, then it will be assumed that it is a Payload source,
|
|
which will be extracted from the message and injected into such service method. This is generally the recommended approach as it follows and promotes
|
|
a POJO model when working with Spring Integration.
|
|
Since v1.0.3 of Spring Integration, the service method does not require to have an argument at all, which means you can now implement event-style Service Activators,
|
|
where all you care about is an invocation of the service method not worrying about the contents of the message. Think of it as a NULL JMS message. An example use-case for such implementation
|
|
could be a simple counter/monitor of messages deposited on the input channel.
|
|
</para>
|
|
<para>
|
|
Using a "ref" attribute is generally recommended if custom Service Activator handler implementation can be reused in other <code><service-activator></code> definitions. However
|
|
if custom Service Activator handler implementation has to be scoped to a concrete definition of the <code><service-activator></code>, starting with v1.0.3, Spring Integration supports
|
|
inner bean definitions for custom Service Activator handlers within the <code><service-activator></code> element:
|
|
<programlisting language="xml"><![CDATA[<service-activator id="testServiceActivator" input-channel="inChannel"
|
|
output-channel = "outChannel" method="foo">
|
|
<beans:bean class="org.foo.TestServiceActivator" /> \
|
|
</service-activator>]]></programlisting>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Using both "ref" attribute and inner handler definition in the same <code><service-activator></code> configuration
|
|
is not allowed, as it creates an ambiguous condition and will result in Exception being thrown
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
</chapter> |