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

INT-1552 doc polishing

Browse Source
This commit is contained in:
Mark Fisher
2010-11-22 15:46:11 -05:00
parent 5418f0d7f5
commit ee2ecf682f
1 changed files with 31 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
docs/src/reference/docbook/transformer.xml
View File

@@ -74,15 +74,15 @@
</para>
<para>
Just like Routers, Aggregators and other components, since Spring Integration 2.0 Transformers can also benefit from SpEL
http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html
Just like Routers, Aggregators and other components, as of Spring Integration 2.0 Transformers can also benefit from SpEL support
(http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html)
whenever transformation logic is relatively simple.
<programlisting language="xml"><![CDATA[<int:transformer input-channel="inChannel"
output-channel="outChannel"
expression="payload.toUpperCase() + '- [' + T(java.lang.System).currentTimeMillis() + ']'"/>]]></programlisting>
In the above configuration we are achieving a simple transformation of the <emphasis>payload</emphasis> with a simple SpEL
In the above configuration we are achieving a simple transformation of the <emphasis>payload</emphasis> with a simple SpEL
expression and without writing a custom transformer. Our <emphasis>payload</emphasis> (assuming String) will be
upper-cased and concatenated with the current timestamp with some simple formatting.
</para>
@@ -91,11 +91,13 @@
<emphasis>Common Transformers</emphasis>
</para>
<para>
There are a also a few Transformer implementations available out of the box. Because, it is fairly common
There are also a few Transformer implementations available out of the box. Because, it is fairly common
to use the <methodname>toString()</methodname> representation of an Object, Spring Integration provides an
<classname>ObjectToStringTransformer</classname> whose output is a Message with a String payload. That String
is the result of invoking the toString operation on the inbound Message's payload.
is the result of invoking the toString() operation on the inbound Message's payload.
<programlisting language="xml"><![CDATA[ <object-to-string-transformer input-channel="in" output-channel="out"/>]]></programlisting>
A potential example for this would be sending some arbitrary object to the 'outbound-channel-adapter' in the
<emphasis>file</emphasis> namespace. Whereas that Channel Adapter only supports String, byte-array, or
<classname>java.io.File</classname> payloads by default, adding this transformer immediately before the
@@ -109,7 +111,10 @@
</para>
<para>
If you need to serialize an Object to a byte array or deserialize a byte array back into an Object,
Spring Integration provides symmetrical serialization transformers.
Spring Integration provides symmetrical serialization transformers. These will use standard Java serialization
by default, but you can provide an implementation of Spring 3.0's Serializer or Deserializer strategies via the
'serializer' and 'deserializer' attributes, respectively.
<programlisting language="xml"><![CDATA[ <payload-serializing-transformer input-channel="objectsIn" output-channel="bytesOut"/>
<payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"/>]]></programlisting>
@@ -118,10 +123,10 @@
<emphasis>Object-to-Map Transformer</emphasis>
</para>
<para>
As added convenience, Spring Integration also provides <emphasis>Object-to-Map</emphasis> and <emphasis>Map-to-Object</emphasis> transformers which
utilize Spring Expression Language (SpEL) to serialize and de-serialize the object graphs. Object hierarchy is introspected
to the most primitive types (e.g., String, int etc.). The path to this type is described via SpEL, which becomes the <emphasis>key</emphasis>key in the
transformed Map with primitive type being the value.
Spring Integration also provides <emphasis>Object-to-Map</emphasis> and <emphasis>Map-to-Object</emphasis> transformers which
utilize the Spring Expression Language (SpEL) to serialize and de-serialize the object graphs. The object hierarchy is introspected
to the most primitive types (String, int, etc.). The path to this type is described via SpEL, which becomes the <emphasis>key</emphasis> in the
transformed Map. The primitive type becomes the value.
</para>
<para>
For example:
@@ -140,19 +145,19 @@ public class Child{
<code>{person.name=George, person.child.name=Jenna, person.child.nickNames[0]=Bimbo . . . etc}</code>
</para>
<para>
SpEL-based Map allows you to describe the object structure without sharing the actual types allowing
The SpEL-based Map allows you to describe the object structure without sharing the actual types allowing
you to restore/rebuild the object graph into a differently typed Object graph as long as you maintain the structure.
</para>
<para>
For example:
The above structure could be easily restored back to the following Object graph via Map-to-Object transformer:
<programlisting language="java"><![CDATA[public class Father{
The above structure could be easily restored back to the following Object graph via the Map-to-Object transformer:
<programlisting language="java"><![CDATA[public class Father {
    private Kid child;
    private String name; 
    // setters and getters are omitted
}
public class Kid{
public class Kid {
   private String name; 
   private List<String> nickNames;
   // setters and getters are omitted
@@ -175,14 +180,14 @@ public class Kid{
</para>
<note>
NOTE: 'ref' and 'type' attributes are mutually exclusive. You can only use either one.
Also, if using 'ref' attribute you must point to a 'prototype' scoped bean, otherwise
BeanCreationException will be thrown. 
NOTE: 'ref' and 'type' attributes are mutually exclusive. You can only use one.
Also, if using the 'ref' attribute, you must point to a 'prototype' scoped bean, otherwise
a BeanCreationException will be thrown. 
</note>
</section>
<section id="transformer-annotation">
<title>Configuring Transformer with Annotations</title>
<title>Configuring a Transformer with Annotations</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
@@ -202,24 +207,23 @@ Order generateOrder(String productId, @Header("customerName") String customer) {
</section>
</section>
<section id="header-filter">
<title>Header Filter</title>
Some time your transformation use case might be as simple as removing a few headers.
For this type of use cases Spring Integration provides <emphasis>Header Filter</emphasis> which allows you to specify which header should be
removed from the output Message.
Basically <emphasis>Header Filter</emphasis> is the opposite of <emphasis>Header Enricher</emphasis>
that is discussed in <xref linkend="header-enricher"/>
Some times your transformation use case might be as simple as removing a few headers.
For such a use case, Spring Integration provides a <emphasis>Header Filter</emphasis> which allows you to specify certain header names
that should be removed from the output Message (e.g. for security reasons or a value that was only needed temporarily).
Basically the <emphasis>Header Filter</emphasis> is the opposite of the <emphasis>Header Enricher</emphasis>.
The latter is discussed in <xref linkend="header-enricher"/>
<programlisting language="xml"><![CDATA[<int:header-filter input-channel="inputChannel"
output-channel="outputChannel" header-names="lastName, state"/>]]></programlisting>
As you can see, configuration of <emphasis>Header Filter</emphasis> is quite simple. It is a typical endpoint with input/output channels
and <code>header-names</code> attribute which allows you to specify the names of the headers (delimited by coma if multiple)
that need to be removed. So, in the above example headers with the name 'lastName' and 'state' will be removed.
As you can see, configuration of a <emphasis>Header Filter</emphasis> is quite simple. It is a typical endpoint with input/output channels
and a <code>header-names</code> attribute. That attribute accepts the names of the header(s) (delimited by commas if there are multiple)
that need to be removed. So, in the above example the headers named 'lastName' and 'state' will not be present on the outbound Message.
</section>
</section>