92 lines
5.2 KiB
XML
92 lines
5.2 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="transformer">
|
|
<title>Transformer</title>
|
|
|
|
<section id="transformer-introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
Message Transformers play a very important role in enabling the loose-coupling of Message Producers and Message
|
|
Consumers. Rather than requiring every Message-producing component to know what type is expected by the next
|
|
consumer, Transformers can be added between those components. Generic transformers, such as one that converts a
|
|
String to an XML Document, are also highly reusable.
|
|
</para>
|
|
<para>
|
|
For some systems, it may be best to provide a
|
|
<ulink url="http://www.eaipatterns.com/CanonicalDataModel.html">Canonical Data Model</ulink>, but Spring
|
|
Integration's general philosophy is not to require any particular format. Rather, for maximum flexibility, Spring
|
|
Integration aims to provide the simplest possible model for extension. As with the other endpoint types, the use
|
|
of declarative configuration in XML and/or Annotations enables simple POJOs to be adapted for the role of Message
|
|
Transformers. These configuration options will be described below.
|
|
<note>
|
|
For the same reason of maximizing flexibility, Spring does not require XML-based Message payloads.
|
|
Nevertheless, the framework does provide some convenient Transformers for dealing with XML-based payloads if
|
|
that is indeed the right choice for your application. For more information on those transformers, see
|
|
<xref linkend="xml"/>.
|
|
</note>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="transformer-namespace">
|
|
<title>The <transformer> Element</title>
|
|
<para>
|
|
The <transformer> element is used to create a Message-transforming endpoint. In addition to "input-channel"
|
|
and "output-channel" attributes, it requires a "ref". The "ref" may either point to an Object that contains the
|
|
@Transformer annotation on a single method (see below) or it may be combined with an explicit method name value
|
|
provided via the "method" attribute.
|
|
<programlisting language="xml"><![CDATA[<transformer id="testTransformer" ref="testTransformerBean" input-channel="inChannel"
|
|
method="transform" output-channel="outChannel"/>
|
|
<beans:bean id="testTransformerBean" class="org.foo.TestTransformer" />]]></programlisting>
|
|
</para>
|
|
<para>
|
|
Using a "ref" attribute is generally recommended if custom transformer handler implementation can be reused in other <code><transformer></code> definitions. However
|
|
if custom transformer handler implementation has to be scoped to a concrete definition of the <code><transformer></code>, starting with v1.0.3, Spring Integration supports
|
|
inner bean definitions for custom transformer handlers within the <code><transformer></code> element:
|
|
<programlisting language="xml"><![CDATA[<transformer id="testTransformer" input-channel="inChannel" method="transform"
|
|
output-channel="outChannel">
|
|
<beans:bean class="org.foo.TestTransformer"/>
|
|
</transformer>]]></programlisting>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Using both "ref" attribute and inner handler definition in the same <code><transformer></code> configuration
|
|
is not allowed, as it creates an ambiguous condition and will result in Exception being thrown
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
The method that is used for transformation may expect either the <interfacename>Message</interfacename> type or
|
|
the payload type of inbound Messages. The return value of the method can be any type. If the return value is
|
|
itself a <interfacename>Message</interfacename>, that will be passed along to the transformer's output channel.
|
|
If the return value is <emphasis>null</emphasis>, then no reply Message will be sent (effectively the same
|
|
behavior as a Message Filter). Otherwise, the return value will be sent as the payload of a Message.
|
|
</para>
|
|
<note>
|
|
<para>Using both "ref" attribute and inner handler definition in the same <code><router></code> configuration is not
|
|
allowed, as it creates an ambiguous condition and will result in Exception being thrown</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section id="transformer-annotation">
|
|
<title>The @Transformer Annotation</title>
|
|
<para>
|
|
The <interfacename>@Transformer</interfacename> annotation can also be added to methods that expect either the
|
|
<interfacename>Message</interfacename> type or the message payload type. The return value will be handled in the
|
|
exact same way as described above in the section describing the <transformer> element.
|
|
<programlisting language="java">@Transformer
|
|
Order generateOrder(String productId) {
|
|
return new Order(productId);
|
|
}</programlisting>
|
|
</para>
|
|
<para>
|
|
Transformer methods may also accept the @Header and @Headers annotations that is documented in section <xref linkend="annotations"/>
|
|
<programlisting language="java">@Transformer
|
|
Order generateOrder(String productId, @Header("customerName") String customer) {
|
|
return new Order(productId, customer);
|
|
}</programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
</chapter> |