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

INT-2388 Update Gradle build

Browse Source 
This is a significant update to the build system, including the changes
listed below. README.md has been updated with instructions on the most
important day-to-day commands.

 - Eliminate buildSrc submodule

   In favor of using the new bundlor and docbook-reference plugins. The
   net effect is a large reduction in number of lines of build code.
   Common docbook resources, stylesheets, etc are stored directly in the
   docbook plugin.

   This means that --recursive is no longer required when cloning and
   there will never be a need to use `git submodule` commands. README
   files have been updated to reflect.

   Use of the new bundlor plugin also means the removal of template.mf
   files from the source tree in favor of an inline approach. See
   build.gradle for details. Bundlor 'import templates' are built up
   programmatically and kept physically close to gradle dependency
   declarations, leading to more convenience when changing these values
   and hopefully fewer errors / version inconsistencies over time.

   Certain tests depended on the presence of template.mf files, all of
   which have recently been removed from the source tree in favor of the
   new bundlor plugin which allows for inlining bundlor configuration
   within the Gradle build script. These tests now create temp files
   using the java.io.File API instead.

 - Upgrade to Gradle 1.0-milestone-6

   The m6 release is significantly faster when resolving dependencies
   and has a number of valuable new features over the earlier m3
   version. Review the release notes for Gradle 1.0-milestone-6 online
   for full details.

 - Switch to repo.springsource.org repository

   Previously the project build declared as many repositories as
   necessary to resolve all project dependencies.

   Now depending on a single 'virtual repository' defined within the
   SpringSource Artifactory instance at http://repo.springsource.org.
   Currently, the virtual repository in use is 'libs-milestone', which
   allows for the resolution of all "milestone-or-better" versions of
   all S2 and third-party dependencies.

   Should snapshot dependencies become required, this value may be
   changed from 'libs-milestone' to 'libs-snapshot'. To build only
   against GA releases, change the value to 'libs-release'.

 - New build plan(s)

   Spring Integration build plans have been updated to use the
   Artifactory Bamboo plugin and publish to repo.springsource.org.
   Build plans have names like 2.1.x to reflect the version under
   development, not necessarily the name of the branch, as this may
   change over time and across major releases.

 - Improve release process

   As mentioned above, Spring Integration will now use the Artifactory
   Bamboo plugin to publish releases and also use Artifactory's support
   for pushing builds directly into Maven Central via oss.sonatype.org.

   Generate poms that contain all necessary fields for onboarding at
   Maven central (scm, developers, organization, licenses, etc).

   Generate -source and -javadoc poms to comply with Maven Central
   onboarding rules (and for general good practice anyway).

   Generation of PGP signatures, sha1 and md5 checksums are all handled
   automatically by Artifactory. These are also requirements for
   automated entry into Maven Central.

 - Remove source-level pom generation

   Automatic generation of Maven poms suitable for use in building
   Spring Integration is no longer supported. Generation and
   publication of poms for the purpose of dependency management remains
   supported.

   Sonar support has to date depended on these poms, but will be
   switched over to use the Gradle Sonar plugin shortly.

 - Eliminate docs subproject

   Move docs/src to the root of the project and eliminate docs as a
   formal subproject. This simplifies the build in a number of ways,
   including removing the need for distinguishing between 'subprojects'
   and 'javaprojects' as well as allowing users to build both 'api' and
   'reference' docs without qualifying with a ':docs' prefix.

   Also rename the src/info directory to src/dist to better reflect that
   these files are packaged with the distribution. For example, the
   readme.txt there is really the distribution readme, distinct from the
   README.md at the root of the project which is for building from source,
   etc.
This commit is contained in:
Chris Beams
2011-11-08 14:38:53 -08:00
committed by Mark Fisher
parent ae0ecff886
commit f30da932e8
225 changed files with 811 additions and 7510 deletions
Download Patch File Download Diff File Expand all files Collapse all files

272
src/reference/docbook/transformer.xml Normal file
View File

@@ -0,0 +1,272 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="transformer"
xmlns:xlink="http://www.w3.org/1999/xlink">
<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-config">
<title>Configuring Transformer</title>
<section id="transformer-namespace">
<title>Configuring Transformer with XML</title>
<para>
The &lt;transformer&gt; 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[<int: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 the custom transformer handler implementation can be reused in
other <code>&lt;transformer&gt;</code> definitions. However if the custom transformer handler implementation should
be scoped to a single definition of the <code>&lt;transformer&gt;</code>, you can define an inner bean definition:
<programlisting language="xml"><![CDATA[<int:transformer id="testTransformer" input-channel="inChannel" method="transform"
output-channel="outChannel">
<beans:bean class="org.foo.TestTransformer"/>
</transformer>]]></programlisting>
</para>
<note>
<para>
Using both the "ref" attribute and an inner handler definition in the same <code>&lt;transformer&gt;</code>
configuration is not allowed, as it creates an ambiguous condition and will result in an 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. It may also accept Message header values either individually or as a full
map by using the <code>@Header</code> and <code>@Headers</code> parameter annotations respectively. 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.
</para>
<para>
As of Spring Integration 2.0, a Message Transformer's transformation method can no longer return <code>null</code>.
Returning <code>null</code> will result in an exception since a Message Transformer should always be expected to
transform each source Message into a valid target Message. In other words, a Message Transformer should not be used
as a Message Filter since there is a dedicated &lt;filter&gt; option for that. However, if you do need this type of
behavior (where a component might return NULL and that should not be considered an error), a
<emphasis>service-activator</emphasis> could be used. Its <code>requires-reply</code> value is FALSE by default,
but that can be set to TRUE in order to have Exceptions thrown for NULL return values as with the transformer.
</para>
<para>
<emphasis>Transformers and Spring Expression Language (SpEL)</emphasis>
</para>
<para>
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
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>
<para>
<emphasis>Common Transformers</emphasis>
</para>
<para>
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.
<programlisting language="xml"><![CDATA[ <int: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
adapter will handle the necessary conversion. Of course, that works fine as long as the result of the
<methodname>toString()</methodname> call is what you want to be written to the File. Otherwise, you can
just provide a custom POJO-based Transformer via the generic 'transformer' element shown previously.
<tip>
When debugging, this transformer is not typically necessary since the 'logging-channel-adapter' is capable
of logging the Message payload. Refer to <xref linkend="channel-wiretap"/> for more detail.
</tip>
</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. 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[ <int:payload-serializing-transformer input-channel="objectsIn" output-channel="bytesOut"/>
<int:payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"/>]]></programlisting>
</para>
<para>
<emphasis>Object-to-Map Transformer</emphasis>
</para>
<para>
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:
<programlisting language="java"><![CDATA[public class Parent{
    private Child child;
    private String name; 
    // setters and getters are omitted
}
public class Child{
   private String name; 
   private List<String> nickNames;
   // setters and getters are omitted
}]]></programlisting>
... will be transformed to a Map which looks like this:
<code>{person.name=George, person.child.name=Jenna, person.child.nickNames[0]=Bimbo . . . etc}</code>
</para>
<para>
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 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 {
   private String name; 
   private List<String> nickNames;
   // setters and getters are omitted
}]]></programlisting>
</para>
<para>
To configure these transformers, Spring Integration provides namespace support
Object-to-Map:
<programlisting language="xml"><![CDATA[<int:object-to-map-transformer input-channel="directInput" output-channel="output"/>]]></programlisting>
Map-to-Object
<programlisting language="xml"><![CDATA[<int:map-to-object-transformer input-channel="input" 
                       output-channel="output" 
                        type="org.foo.Person"/>]]></programlisting>
or
<programlisting language="xml"><![CDATA[<int:map-to-object-transformer input-channel="inputA" 
                              output-channel="outputA" 
                              ref="person"/>
<bean id="person" class="org.foo.Person" scope="prototype"/>
]]></programlisting>
</para>
<note>
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>
<para>
<emphasis>JSON Transformers</emphasis>
</para>
<para>
<emphasis>Object to JSON</emphasis> and <emphasis>JSON to Object</emphasis> transformers are provided.
</para>
<para>
<programlisting language="xml"><![CDATA[<int:object-to-json-transformer input-channel="objectMapperInput"/>]]></programlisting>
<programlisting language="xml"><![CDATA[<int:json-to-object-transformer input-channel="objectMapperInput"
type="foo.MyDomainObject"/>]]></programlisting>
</para>
<para>
These use a vanilla Jackson ObjectMapper by default. If you wish to customize the ObjectMapper (for example,
to configure the 'ALLOW_COMMENTS' feature when parsing JSON), you can supply a reference to your custom ObjectMapper bean using
the object-mapper attribute.
</para>
<para>
<programlisting language="xml"><![CDATA[<int:json-to-object-transformer input-channel="objectMapperInput"
type="foo.MyDomainObject" object-mapper="customObjectMapper"/>]]></programlisting>
</para>
<para>
You may wish to consider using a FactoryBean or simple factory method to create the ObjectMapper with
the required characteristics.
</para>
<para>
<programlisting language="java"><![CDATA[public class ObjectMapperFactory {
public static ObjectMapper getMapper() {
ObjectMapper mapper = new ObjectMapper();
mapper.configure(JsonParser.Feature.ALLOW_COMMENTS, true);
return mapper;
}
}]]></programlisting>
</para>
<para>
<programlisting language="xml"><![CDATA[<bean id="customObjectMapper" class="foo.ObjectMapperFactory"
factory-method="getMapper"/>]]></programlisting>
</para>
</section>
<section id="transformer-annotation">
<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
exact same way as described above in the section describing the &lt;transformer&gt; 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 <xref linkend="annotations"/>
<programlisting language="java">@Transformer
Order generateOrder(String productId, @Header("customerName") String customer) {
return new Order(productId, customer);
}</programlisting>
</para>
</section>
</section>
<section id="header-filter">
<title>Header Filter</title>
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 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>