72 lines
4.7 KiB
XML
72 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>REPLY_CHANNEL</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 latter, then it will
|
|
be assumed that it is a Message payload, 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. Arguments may also have @Header or @Headers annotations as described in <xref linkend="annotations"/>
|
|
</para>
|
|
<note>
|
|
Since v1.0.3 of Spring Integration, the service method is not required 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 an
|
|
implementation could be a simple counter/monitor of messages deposited on the input channel.
|
|
</note>
|
|
<para>
|
|
Using a "ref" attribute is generally recommended if the custom Service Activator handler implementation can be reused
|
|
in other <code><service-activator></code> definitions. However if the custom Service Activator handler implementation
|
|
should be scoped to a single definition of the <code><service-activator></code>, you can use an inner bean definition:
|
|
<programlisting language="xml"><![CDATA[<service-activator id="exampleServiceActivator" input-channel="inChannel"
|
|
output-channel = "outChannel" method="foo">
|
|
<beans:bean class="org.foo.ExampleServiceActivator"/>
|
|
</service-activator>]]></programlisting>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Using both the "ref" attribute and an inner handler definition in the same <code><service-activator></code>
|
|
configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
</chapter> |