Major progress on Gradle port

Complete:
--------
- src/* documentation resources moved to 'docs' subproject

- docbook sources upgraded to Docbook 5

- formatted all docbook sources to strip tab characters and
  eliminate trailing whitespace

- all projects compile and test successfully

- all artifacts upload successfully to s3, static.sf.org, etc.

Remaining:
---------
- documentation L&F needs work. CSS, images, and highlighting aren't
  hooked up properly

- spring-integration-jdbc codegen bits in Maven POM need to be
  transcribed into gradle

- dependencies that were optional or provided scope in maven are
  currently 'compile' scope in Gradle.  Need to figure out support
  in Gradle to fix this.

- run through Eclipse classpath and project generation scenarios

- delete all Maven artifacts

.gitignore

@@ -1,16 +1,17 @@
+*.iml
+*.sw?
+*/src/main/java/META-INF
+.gradle
+.idea
+.settings
+.springBeans
+build
+derby.log
+integration-repo
 lib
 logs
-target
-.springBeans
-.settings
-spring-integration-samples/loanshark/application.log*
-integration-repo
-spring-integration-jms/activemq-data/
 si.java.hsp
-*/src/main/java/META-INF
+spring-integration-jms/activemq-data/
 spring-integration-parent/.project
-*.iml
-.idea
-derby.log
-.gradle
-build
+spring-integration-samples/loanshark/application.log*
+target

build.gradle

@@ -24,16 +24,21 @@
 // -----------------------------------------------------------------------------
 
 
+// -----------------------------------------------------------------------------
+// Configuration for the root project
+// -----------------------------------------------------------------------------
+apply from: "$rootDir/gradle/version.gradle"
+apply plugin: 'idea'
+
+// used for artifact names, building doc upload urls, etc.
+description = 'Spring Integration'
+abbreviation = 'INT'
+
 // -----------------------------------------------------------------------------
 // Configuration for all projects including this one (the root project)
 //
 // @see settings.gradle for list of all subprojects
 // -----------------------------------------------------------------------------
-
-apply from: "$rootDir/gradle/version.gradle"
-apply plugin: 'idea'
-
-
 allprojects {
     // group will translate to groupId during pom generation and deployment
     group = 'org.springframework.integration'
@@ -80,6 +85,11 @@ configure(javaprojects) {
     apply plugin: 'eclipse' // `gradle eclipse` to generate .classpath/.project
     apply plugin: 'idea' // `gradle idea` to generate .ipr/.iml
 
+    // set up dedicated directories for jars and source jars.
+    // this makes it easier when putting together the distribution
+    libsBinDir = new File(libsDir, 'bin')
+    libsSrcDir = new File(libsDir, 'src')
+
     // all core projects should be OSGi-compliant bundles
     // add the bundlor task to ensure proper manifests
     apply from: "$rootDir/gradle/bundlor.gradle"
@@ -405,7 +415,7 @@ project('spring-integration-xmpp') {
 apply plugin: 'base'
 
 // add tasks like 'distArchive'
-//apply from: "$rootDir/gradle/dist.gradle"
+apply from: "$rootDir/gradle/dist.gradle"
 
 // add tasks like 'snapshotDependencyCheck'
 apply from: "${rootDir}/gradle/checks.gradle"

docs/build.gradle

@@ -0,0 +1,231 @@
+/*
+ * Copyright 2002-2010 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+apply plugin: 'base'
+apply from: "$rootDir/gradle/docbook.gradle"
+
+description = "Spring Integration Documentation"
+
+task build(dependsOn: assemble) {
+    group = 'Build'
+    description = 'Builds reference and API documentation and archives'
+}
+
+
+/**
+ * Build aggregated JavaDoc HTML for all core project classes.  Result is
+ * suitable for packaging into a distribution zip or viewing directly with
+ * a browser.
+ *
+ * @author cbeams
+ * @author ltaylor
+ * @see http://gradle.org/0.9-rc-1/docs/javadoc/org/gradle/api/tasks/javadoc/Javadoc.html
+ */
+ task api(type: Javadoc) {
+    group = 'Documentation'
+    description = "Builds aggregated JavaDoc HTML for all core project classes."
+
+    // this task is a bit ugly to configure. it was a user contribution, and
+    // Hans tells me it's on the roadmap to redesign it.
+    srcDir = file("${projectDir}/src/api")
+    destinationDir = file("${buildDir}/api")
+    tmpDir = file("${buildDir}/api-work")
+    optionsFile = file("${tmpDir}/apidocs/javadoc.options")
+    options.stylesheetFile = file("${srcDir}/spring-javadoc.css")
+    options.links = ["http://static.springframework.org/spring/docs/3.0.x/javadoc-api"]
+    options.overview = "${srcDir}/overview.html"
+    options.docFilesSubDirs = true
+    title = "Spring Integration ${version} API"
+
+    // collect all the sources that will be included in the javadoc output
+    source javaprojects.collect {project ->
+        project.sourceSets.main.allJava
+    }
+
+    // collect all main classpaths to be able to resolve @see refs, etc.
+    // this collection also determines the set of projects that this
+    // task dependsOn, thus the runtimeClasspath is used to ensure all
+    // projects are included, not just *dependencies* of all classes.
+    // this is awkward and took me a while to figure out.
+    classpath = files(javaprojects.collect {project ->
+        project.sourceSets.main.runtimeClasspath
+    })
+
+    // copy the images from the doc-files dir over to the target
+    doLast { task ->
+        copy {
+            from file("${task.srcDir}/doc-files")
+            into file("${task.destinationDir}/doc-files")
+        }
+    }
+}
+
+/**
+ * Expand ${...} variables within docbook sources. This is a workaround
+ * accomodating the fact that the current docbook plugin has no way of
+ * parameterizing and replacing normal XML entities.
+ *
+ * Note that this task represents an implementation detail and it is
+ * unfortunate that it pollutes the listing of available tasks, e.g.
+ * during `gradle -t`. It's a good example of the need for 'task visibility' -
+ * a feature not yet implemented, but on the Gradle roadmap.
+ *
+ * @author Chris Beams
+ * @see http://jira.codehaus.org/browse/GRADLE-1026
+ */
+task preprocessDocbookSources {
+    description = 'Expands ${...} variables within docbook sources.'
+
+    doLast {
+        docbookSrcDir = file('src/reference/docbook')
+        docbookBuildDir = file('build/reference-work')
+
+        // copy everything but index.xml
+        copy {
+            into(docbookBuildDir)
+            from(docbookSrcDir) { exclude '**/index.xml' }
+        }
+        // copy index.xml and expand ${...} variables along the way
+        // e.g.: ${version} needs to be replaced in the header
+        copy {
+            into(docbookBuildDir)
+            from(docbookSrcDir) { include '**/index.xml' }
+            expand(version: "$version")
+        }
+    }
+}
+
+// -----------------------------------------------------------------------------
+// Configure the three docbook* tasks that are added to the project by the
+// 'docbook' plugin.
+// -----------------------------------------------------------------------------
+task reference(dependsOn: [docbookHtml, docbookHtmlSingle, docbookPdf]) {
+    group = 'Documentation'
+    description = 'Generates all HTML and PDF reference documentation.'
+}
+
+[docbookHtml, docbookPdf, docbookHtmlSingle]*.sourceFileName = 'index.xml';
+[docbookHtml, docbookHtmlSingle, docbookPdf]*.dependsOn preprocessDocbookSources
+
+docbookHtml.stylesheet = file('src/reference/xsl/html-custom.xsl')
+docbookHtmlSingle.stylesheet = file('src/reference/xsl/html-single-custom.xsl')
+docbookPdf.stylesheet = file('src/reference/xsl/pdf-custom.xsl')
+def imagesDir = file('src/reference/docbook/images');
+docbookPdf.admonGraphicsPath = "${imagesDir}/"
+
+
+/**
+ *
+ * @see http://www.gradle.org/0.9-preview-3/docs/userguide/userguide_single.html#sec:copying_files
+ * @see http://www.gradle.org/0.9-preview-3/docs/javadoc/org/gradle/api/file/CopySpec.html
+ */
+docsSpec = copySpec {
+    into("${version}") {
+        from('src/info/changelog.txt')
+    }
+
+    into("${version}/api") {
+        from(api.destinationDir)
+    }
+
+    into("${version}/reference") {
+        from("${buildDir}/reference")
+    }
+
+    // copy images and css into respective html dirs
+    ['html', 'htmlsingle'].each { dir ->
+        into("${version}/reference/${dir}/images") {
+            from "src/docbook/images"
+        }
+        into("${version}/reference/${dir}/css") {
+            from "src/resources/css"
+        }
+    }
+}
+
+task archive(type: Zip, dependsOn: [api, reference]) {
+    group = "Documentation"
+    description = "Create a zip archive of reference and API documentation."
+
+    baseName = rootProject.name + '-docs'
+
+    // drop it right in the root of the build dir for simplicity
+    destinationDir = buildDir
+
+    // use the copy spec above to specify the contents of the zip
+    with docsSpec
+}
+
+configurations { archives }
+artifacts { archives archive }
+
+configurations { scpAntTask }
+dependencies {
+    scpAntTask("org.apache.ant:ant-jsch:1.8.1")
+}
+
+checkForProps(taskPath: project.path + ':uploadArchives', requiredProps: ['sshHost', 'sshUsername'])
+
+uploadArchives {
+    def sshHost = project.properties.sshHost
+    def sshUsername = project.properties.sshUsername
+    def remoteSiteDir = '/var/www/domains/springframework.org/static/htdocs/' + rootProject.name
+    def docUrl = "http://${sshHost}/${rootProject.name}/docs/${version}"
+    def remoteDocsDir = "${remoteSiteDir}/docs/"
+    def fqRemoteDir = "${sshUsername}@${sshHost}:${remoteDocsDir}"
+
+    group = 'Buildmaster'
+    description = "Uploads and unpacks documentation archive" + (sshHost ? " to ${docUrl}" : ": Host is not specified")
+
+    uploadDescriptor = false
+
+    repositories {
+        add(new org.apache.ivy.plugins.resolver.SshResolver()) {
+            name = 'sshHost: ' + sshHost // used for debugging
+            host = sshHost
+            user = sshUsername
+            if (project.hasProperty('remoteSiteDir')) {
+                keyFile = sshPrivateKey as File
+            }
+            addArtifactPattern "${remoteDocsDir}/${archive.archiveName}"
+        }
+    }
+
+    configurations { scpAntTask }
+    dependencies { scpAntTask 'org.apache.ant:ant-jsch:1.8.1' }
+
+    doFirst {
+        println "Uploading: ${archive.archivePath} to ${fqRemoteDir}"
+    }
+
+    doLast {
+        project.ant {
+            taskdef(name: 'sshexec',
+                    classname: 'org.apache.tools.ant.taskdefs.optional.ssh.SSHExec',
+                    classpath: configurations.scpAntTask.asPath)
+
+            // copy the archive, unpack it, then delete it
+            def unpackCommand = "cd ${remoteDocsDir} && unzip ${archive.archiveName}"
+            def deleteCommand = "rm ${remoteDocsDir}/${archive.archiveName}"
+
+            println "sshexec ${unpackCommand}"
+            sshexec(host: sshHost, username: sshUsername, keyfile: sshPrivateKey, command: unpackCommand)
+            println "sshexec ${deleteCommand}"
+            sshexec(host: sshHost, username: sshUsername, keyfile: sshPrivateKey, command: deleteCommand)
+            println "UPLOAD SUCCESSFUL - validate by visiting ${docUrl}"
+        }
+    }
+}

docs/src/reference/docbook/aggregator.xml

@@ -0,0 +1,625 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="aggregator"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Aggregator</title>
+
+  <section id="aggregator-introduction">
+    <title>Introduction</title>
+
+    <para>Basically a mirror-image of the Splitter, the Aggregator is a type
+    of Message Handler that receives multiple Messages and combines them into
+    a single Message. In fact, Aggregators are often downstream consumers in a
+    pipeline that includes a Splitter.</para>
+
+    <para>Technically, the Aggregator is more complex than a Splitter, because
+    it is required to maintain state (the Messages to be aggregated), to
+    decide when the complete group of Messages is available. In order to do
+    this it requires a MessageStore</para>
+  </section>
+
+  <section id="aggregator-functionality">
+    <title>Functionality</title>
+
+    <para>The Aggregator combines a group of related messages, by correlating
+    and storing them, until the group is deemed complete. At that point, the
+    Aggregator will create a single message by processing the whole group, and
+    will send that aggregated message as output.</para>
+
+    <para>An main aspect of implementing an Aggregator is providing the logic
+    that has to be executed when the aggregation (creation of a single message
+    out of many) takes place. The other two aspects are correlation and
+    release</para>
+
+    <para>In Spring Integration, the grouping of the messages for aggregation
+    (correlation) is done by default based on their CORRELATION_ID message
+    header (i.e. the messages with the same CORRELATION_ID will be grouped
+    together). However, this can be customized, and the users can opt for
+    other ways of specifying how the messages should be grouped together, by
+    using a CorrelationStrategy (see below).</para>
+
+    <para>To determine whether or not a group of messages may be processed, a
+    ReleaseStrategy is consulted. The default release strategy for aggregator
+    will release groups that have all messages from the sequence, but this can
+    be entirely customized</para>
+  </section>
+
+  <section id="aggregator-api">
+    <title>Programming model</title>
+
+    <para>The Aggregation API consists of a number of classes:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>The interface <code>MessageGroupProcessor</code> and related
+        base class <code>AbstractAggregatingMessageGroupProcessor</code> and
+        its subclass
+        <code>MethodInvokingAggregatingMessageGroupProcessor</code></para>
+      </listitem>
+
+      <listitem>
+        <para>The <code>ReleaseStrategy</code> interface and its default
+        implementation <code>SequenceSizeReleaseStrategy</code></para>
+      </listitem>
+
+      <listitem>
+        <para>The <code>CorrelationStrategy</code> interface and its default
+        implementation <code>HeaderAttributeCorrelationStrategy</code></para>
+      </listitem>
+    </itemizedlist>
+
+    <section>
+       
+
+      <title>CorrelatingMessageHandler</title>
+
+       
+
+      <para>The <code>CorrelatingMessageHandler</code> is a
+      <code>MessageHandler</code> implementation, encapsulating the common
+      functionalities of an Aggregator (and other correlating use cases),
+      which are: <itemizedlist>
+          <listitem>
+            <para>correlating messages into a group to be aggregated</para>
+          </listitem>
+
+          <listitem>
+            <para>maintaining those messages in a MessageStore until the group
+            may be released</para>
+          </listitem>
+
+          <listitem>
+            <para>deciding when the group is in fact may be released</para>
+          </listitem>
+
+          <listitem>
+            <para>processing the released group into a single aggregated
+            message</para>
+          </listitem>
+
+          <listitem>
+            <para>recognizing and responding to an expired group</para>
+          </listitem>
+        </itemizedlist> The responsibility of deciding how the messages should
+      be grouped together is delegated to a <code>CorrelationStrategy</code>
+      instance. The responsibility of deciding whether the message group can
+      be released is delegated to a <code>ReleaseStrategy</code>
+      instance.</para>
+
+       
+
+      <para>Here is a brief highlight of the base
+      <code>AbstractAggregatingMessageGroupProcessor</code> (the
+      responsibility of implementing the aggregateMessages method is left to
+      the developer):</para>
+
+       
+
+      <programlisting language="java"><![CDATA[public abstract class AbstractAggregatingMessageGroupProcessor
+              implements MessageGroupProcessor {
+
+    protected Map<String, Object> aggregateHeaders(MessageGroup group) {
+  ....
+    }
+
+  	protected abstract Object aggregatePayloads(MessageGroup group);
+
+}]]></programlisting>
+
+       The CorrelationStrategy is owned by the 
+
+      <code>CorrelatingMessageHandler</code>
+
+       and it has a default value based on the correlation ID message header: 
+
+      <programlisting language="java"><![CDATA[private volatile CorrelationStrategy correlationStrategy =
+          new HeaderAttributeCorrelationStrategy(MessageHeaders.CORRELATION_ID);]]></programlisting>
+
+       
+
+      <para>When appropriate, the simplest option is the
+      <code>DefaultAggregatingMessageGroupProcessor</code>. It creates a
+      single Message whose payload is a List of the payloads received for a
+      given group. It uses the default <code>CorrelationStrategy</code> and
+      <code>CompletionStrategy</code> as shown above. This works well for
+      simple Scatter Gather implementations with either a Splitter, Publish
+      Subscribe Channel, or Recipient List Router upstream.</para>
+
+       
+
+      <note>
+        <para>When using a Publish Subscribe Channel or Recipient List Router
+        in this type of scenario, be sure to enable the flag to
+        <emphasis>apply-sequence</emphasis>. That will add the necessary
+        headers (correlation id, sequence number and sequence size). That
+        behavior is enabled by default for Splitters in Spring Integration,
+        but it is not enabled for the Publish Subscribe Channel or Recipient
+        List Router because those components may be used in a variety of
+        contexts where those headers are not necessary.</para>
+      </note>
+
+       
+
+      <para>When implementing a specific aggregator object for an application,
+      a developer can extend
+      <code>AbstractAggregatingMessageGroupProcessor</code> and implement the
+      <code>aggregatePayloads</code> method. However, there are better suited
+      (which reads, less coupled to the API) solutions for implementing the
+      aggregation logic, which can be configured easily either through XML or
+      through annotations.</para>
+
+       
+
+      <para>In general, any ordinary Java class (i.e. POJO) can implement the
+      aggregation algorithm. For doing so, it must provide a method that
+      accepts as an argument a single java.util.List (parametrized lists are
+      supported as well). This method will be invoked for aggregating
+      messages, as follows:</para>
+
+       
+
+      <itemizedlist>
+        <listitem>
+          <para>if the argument is a parametrized java.util.List, and the
+          parameter type is assignable to Message, then the whole list of
+          messages accumulated for aggregation will be sent to the
+          aggregator</para>
+        </listitem>
+
+        <listitem>
+          <para>if the argument is a non-parametrized java.util.List or the
+          parameter type is not assignable to Message, then the method will
+          receive the payloads of the accumulated messages</para>
+        </listitem>
+
+        <listitem>
+          <para>if the return type is not assignable to Message, then it will
+          be treated as the payload for a Message that will be created
+          automatically by the framework.</para>
+        </listitem>
+      </itemizedlist>
+
+       
+
+      <note>
+        <para>In the interest of code simplicity, and promoting best practices
+        such as low coupling, testability, etc., the preferred way of
+        implementing the aggregation logic is through a POJO, and using the
+        XML or annotation support for setting it up in the application.</para>
+      </note>
+
+       
+    </section>
+
+    <section>
+      <title>ReleaseStrategy</title>
+
+      <para>The <code>ReleaseStrategy</code> interface is defined as
+      follows:</para>
+
+      <programlisting language="java"><![CDATA[public interface ReleaseStrategy {
+
+  boolean canRelease(MessageGroup messages);
+
+}]]></programlisting>
+
+      <para>In general, any ordinary Java class (i.e. POJO) can implement the
+      completion decision mechanism. For doing so, it must provide a method
+      that accepts as an argument a single java.util.List (parametrized lists
+      are supported as well), and returns a boolean value. This method will be
+      invoked after the arrival of a new message, to decide whether the group
+      is complete or not, as follows:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>if the argument is a parametrized java.util.List, and the
+          parameter type is assignable to Message, then the whole list of
+          messages accumulated in the group will be sent to the method</para>
+        </listitem>
+
+        <listitem>
+          <para>if the argument is a non-parametrized java.util.List or the
+          parameter type is not assignable to Message, then the method will
+          receive the payloads of the accumulated messages</para>
+        </listitem>
+
+        <listitem>
+          <para>the method must return true if the message group is ready for
+          aggregation, and false otherwise.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>When the group is released for aggregation, all its unmarked
+      messages are processed and then marked so they will not be processed
+      again. If the group is also complete (i.e. if all messages from a
+      sequence have arrived or if there is no sequence defined) then the group
+      is removed from the message store. Partial sequences can be released, in
+      which case the next time the <code>ReleaseStrategy</code> is called it
+      will be presented with a group containing marked messages (already
+      processed) and unmarked messages (a potential new partial
+      sequence)</para>
+
+      <para>Spring Integration provides an out-of-the box implementation for
+      <code>ReleaseStrategy</code>, the
+      <code>SequenceSizerReleaseStrategy</code>. This implementation uses the
+      SEQUENCE_NUMBER and SEQUENCE_SIZE of the arriving messages for deciding
+      when a message group is complete and ready to be aggregated. As shown
+      above, it is also the default strategy.</para>
+    </section>
+
+    <section>
+      <title>CorrelationStrategy</title>
+
+      <para>The <code>CorrelationStrategy</code> interface is defined as
+      follows:</para>
+
+      <programlisting language="java"><![CDATA[public interface CorrelationStrategy {
+
+  Object getCorrelationKey(Message<?> message);
+
+}]]></programlisting>
+
+      <para>The method shall return an Object which represents the correlation
+      key used for grouping messages together. The key must satisfy the
+      criteria used for a key in a Map with respect to the implementation of
+      equals() and hashCode().</para>
+
+      <para>In general, any ordinary Java class (i.e. POJO) can implement the
+      correlation decision mechanism, and the rules for mapping a message to a
+      method's argument (or arguments) are the same as for a
+      <code>ServiceActivator</code> (including support for @Header
+      annotations). The method must return a value, and the value must not be
+      <code>null</code>.</para>
+
+      <para>Spring Integration provides an out-of-the box implementation for
+      <code>CorrelationStrategy</code>, the
+      <code>HeaderAttributeCorrelationStrategy</code>. This implementation
+      returns the value of one of the message headers (whose name is specified
+      by a constructor argument) as the correlation key. By default, the
+      correlation strategy is a HeaderAttributeCorrelationStrategy returning
+      the value of the CORRELATION_ID header attribute.</para>
+    </section>
+  </section>
+
+  <section id="aggregator-xml">
+    <title>Configuring an Aggregator with XML</title>
+
+    <para>Spring Integration supports the configuration of an aggregator via
+    XML through the &lt;aggregator/&gt; element. Below you can see an example
+    of an aggregator with all optional parameters defined.</para>
+
+    <programlisting lang="xml"><![CDATA[<channel id="inputChannel"/>
+
+<aggregator id="completelyDefinedAggregator" ]]><co id="aggxml1" /><![CDATA[
+    input-channel="inputChannel" ]]><co id="aggxml2" /><![CDATA[
+    output-channel="outputChannel"  ]]><co id="aggxml3" /><![CDATA[
+    discard-channel="discardChannel"  ]]><co id="aggxml4" /><![CDATA[
+    ref="aggregatorBean" ]]><co id="aggxml5" /><![CDATA[
+    method="add" ]]><co id="aggxml6" /><![CDATA[
+    release-strategy="releaseStrategyBean"  ]]><co id="aggxml7" /><![CDATA[
+    release-strategy-method="canRelease" ]]><co id="aggxml8" /><![CDATA[
+    correlation-strategy="correlationStrategyBean" ]]><co
+        id="aggxmlCorrelationStrategy" /><![CDATA[
+    correlation-strategy-method="groupNumbersByLastDigit" ]]><co
+        id="aggxmlCorrelationStrategyMethod" /><![CDATA[
+    message-store="messageStore" ]]><co id="aggxml11-co" linkends="aggxml11" /><![CDATA[
+    send-partial-result-on-expiry="true" ]]><co id="aggxml9" /><![CDATA[
+    send-timeout="86420000" ]]><co id="aggxml10" /><![CDATA[ /> 
+
+<channel id="outputChannel"/>
+
+<bean id="aggregatorBean" class="sample.PojoAggregator"/>
+
+<bean id="releaseStrategyBean" class="sample.PojoReleaseStrategy"/>
+
+<bean id="correlationStrategyBean" class="sample.PojoCorrelationStrategy"/>]]></programlisting>
+
+    <calloutlist>
+      <callout arearefs="aggxml1">
+        <para>The id of the aggregator is
+        <emphasis>optional</emphasis>.</para>
+      </callout>
+
+      <callout arearefs="aggxml2">
+        <para>The input channel of the aggregator.
+        <emphasis>Required</emphasis>.</para>
+      </callout>
+
+      <callout arearefs="aggxml3">
+        <para>The channel where the aggregator will send the aggregation
+        results. <emphasis>Optional (because incoming messages can specify a
+        reply channel themselves)</emphasis>.</para>
+      </callout>
+
+      <callout arearefs="aggxml4">
+        <para>The channel where the aggregator will send the messages that
+        timed out (if <code>send-partial-results-on-timeout</code> is
+        <emphasis>false</emphasis>). <emphasis>Optional</emphasis>.</para>
+      </callout>
+
+      <callout arearefs="aggxml5">
+        <para>A reference to a bean defined in the application context. The
+        bean must implement the aggregation logic as described above.
+        <emphasis>Required</emphasis>.</para>
+      </callout>
+
+      <callout arearefs="aggxml6">
+        <para>A method defined on the bean referenced by <code>ref</code>,
+        <emphasis>that implements the message aggregation
+        algorithm.</emphasis> <emphasis>Optional, with restrictions (see
+        above).</emphasis></para>
+      </callout>
+
+      <callout arearefs="aggxml7">
+        <para>A reference to a bean that implements the decision algorithm as
+        to whether a given message group is complete. The bean can be an
+        implementation of the CompletionStrategy interface or a POJO. In the
+        latter case the completion-strategy-method attribute must be defined
+        as well. <emphasis>Optional (by default, the aggregator will use
+        sequence size) </emphasis>.</para>
+      </callout>
+
+      <callout arearefs="aggxml8">
+        <para>A method defined on the bean referenced by
+        <code>release-strategy</code>, <emphasis>that implements the
+        completion decision algorithm.</emphasis> <emphasis>Optional, with
+        restrictions (requires <code>completion-strategy</code> to be
+        present).</emphasis></para>
+      </callout>
+
+      <callout arearefs="aggxmlCorrelationStrategy">
+        <para>A reference to a bean that implements the correlation strategy.
+        The bean can be an implementation of the CorrelationStrategy interface
+        or a POJO. In the latter case the correlation-strategy-method
+        attribute must be defined as well. <emphasis>Optional (by default, the
+        aggregator will use the correlation id header attribute)
+        </emphasis>.</para>
+      </callout>
+
+      <callout arearefs="aggxmlCorrelationStrategyMethod">
+        <para>A method defined on the bean referenced by
+        <code>correlation-strategy</code>, <emphasis>that implements the
+        correlation key algorithm.</emphasis> <emphasis>Optional, with
+        restrictions (requires <code>correlation-strategy</code> to be
+        present).</emphasis></para>
+      </callout>
+
+      <callout arearefs="aggxml11-co" id="aggxml11">
+        <para>A reference to a <code>MessageGroupStore</code> that can be used
+        to store groups of messages under their correlation key until they are
+        complete. <emphasis>Optional</emphasis> with default a volatile
+        in-memory store.</para>
+      </callout>
+
+      <callout arch="" arearefs="aggxml9">
+        <para>Whether upon the expiration of the message group, the aggregator
+        will try to aggregate the messages that have already arrived.
+        <emphasis>Optional (false by default)</emphasis>.</para>
+      </callout>
+
+      <callout arearefs="aggxml10">
+        <para>The timeout for sending the aggregated messages to the output or
+        reply channel. <emphasis>Optional</emphasis>.</para>
+      </callout>
+    </calloutlist>
+
+    <para>Using a "ref" attribute is generally recommended if a custom
+    aggregator handler implementation can be reused in other
+    <code>&lt;aggregator&gt;</code> definitions. However if a custom
+    aggregator handler implementation should be scoped to a concrete
+    definition of the <code>&lt;aggregator&gt;</code>, you can use an inner
+    bean definition (starting with version 1.0.3) for custom aggregator
+    handlers within the <code>&lt;aggregator&gt;</code> element:
+    <programlisting language="xml"><![CDATA[<aggregator input-channel="input" method="sum" output-channel="output">
+    <beans:bean class="org.foo.ExampleAggregator"/>
+</aggregator>]]></programlisting></para>
+
+    <note>
+      <para>Using both a "ref" attribute and an inner bean definition in the
+      same <code>&lt;aggregator&gt;</code> configuration is not allowed, as it
+      creates an ambiguous condition. In such cases, an Exception will be
+      thrown.</para>
+    </note>
+
+    <para>An example implementation of the aggregator bean looks as
+    follows:</para>
+
+    <programlisting language="java"><![CDATA[public class PojoAggregator {
+
+  public Long add(List<Long> results) {
+    long total = 0l;
+    for (long partialResult: results) {
+      total += partialResult;
+    }
+    return total;
+  }
+
+}]]></programlisting>
+
+    <para>An implementation of the completion strategy bean for the example
+    above may be as follows:</para>
+
+    <para><programlisting language="java"><![CDATA[public class PojoReleaseStrategy {
+...
+  public boolean canRelease(List<Long> numbers) {
+    int sum = 0;
+    for (long number: numbers) {
+      sum += number;
+    }
+    return sum >= maxValue;
+  }
+}]]></programlisting> <note>
+        <para>Wherever it makes sense, the release strategy method and the
+        aggregator method can be combined in a single bean.</para>
+      </note></para>
+
+    <para>An implementation of the correlation strategy bean for the example
+    above may be as follows:</para>
+
+    <para><programlisting language="java"><![CDATA[public class PojoCorrelationStrategy {
+...
+  public Long groupNumbersByLastDigit(Long number) {
+    return number % 10;
+  }
+}]]></programlisting></para>
+
+    <para>For example, this aggregator would group numbers by some criterion
+    (in our case the remainder after dividing by 10) and will hold the group
+    until the sum of the numbers which represents the payload exceeds a
+    certain value.</para>
+
+    <note>
+      <para>Wherever it makes sense, the release strategy method, correlation
+      strategy method and the aggregator method can be combined in a single
+      bean (all of them or any two).</para>
+    </note>
+  </section>
+
+  <section>
+    <title id="reaper">Managing State in an Aggregator:
+    MessageGroupStore</title>
+
+    <para>Aggregator (and some other patterns in Spring Integration) is a
+    stateful pattern that requires decisions to be made based on a group of
+    messages that have arrived over a period of time, all with the same
+    correlation key. The design of the interfaces in the stateful patterns
+    (e.g. <classname>ReleaseStrategy</classname>) is driven by the principle
+    that the components (framework and user) should be to remain stateless.
+    All state is carried by the <classname>MessageGroup</classname> and its
+    management is delegated to the
+    <classname>MessageGroupStore</classname>.</para>
+
+    <para>The <classname>MessageGroupStore</classname> accumulates state
+    information in <classname>MessageGroups</classname>, potentially forever.
+    So to prevent stale state from hanging around, and for volatile stores to
+    provide a hook for cleaning up when the application shots down, the
+    <classname>MessageGroupStore</classname> allows the user to register
+    callbacks to apply to <classname>MessageGroups</classname> when they
+    expire. The interface is very straighforward:</para>
+
+    <programlisting><![CDATA[public interface MessageGroupCallback {
+
+  void execute(MessageGroupStore messageGroupStore, MessageGroup group);
+
+}]]></programlisting>
+
+    <para>The callback has access directly to the store and the message group
+    so it can manage the persistent state (e.g. by removing the group from the
+    store entirely).</para>
+
+    <para>The MessageGroupStore maintains a list of these callbacks which it
+    applies when asked to all messages whose timestamp is earlier than a time
+    supplied as a parameter:</para>
+
+    <programlisting><![CDATA[public interface MessageGroupStore {
+   void registerMessageGroupExpiryCallback(MessageGroupCallback callback);
+   int expireMessageGroups(long timeout);
+}]]></programlisting>
+
+    <para>The expireMessageGroups method can be called with a timeout value:
+    any message older than the current time minus this value wiull be expired,
+    and have the callbacks applied. Thus it is the user of the store that
+    defines what is meant by message group "expiry".</para>
+
+    <para>As a convenience for users, Spring Integration provides a wrapper
+    for the message expiry in the form of a
+    <classname>MessageGroupStoreReaper</classname>:</para>
+
+    <programlisting><![CDATA[<bean id="reaper" class="org...MessageGroupStoreReaper">
+  <property name="messageGroupStore" ref="messageStore"/>
+  <property name="timeout" value="10"/>
+</bean>
+
+<task:scheduled-tasks scheduler="scheduler">	
+  <task:scheduled ref="reaper" method="run" fixed-rate="10000"/>
+</task:scheduled-tasks>]]></programlisting>
+
+    <para>The reaper is a Runnable, and all that is happening is that the
+    message group store's expire method is being called in the sample above
+    once every 10 seconds. In addition to the reaper, the expiry callbacks are
+    invoked when the application shuts down via a lifecycle callback in the
+    <classname>CorrelatingMessageHandler</classname>.</para>
+
+    <para>The <classname>CorrelatingMessageHandler</classname> registers its
+    own expiry callback, and this is the link with the boolean flag
+    <code>send-partial-result-on-expiry</code> in the XML configuration of the
+    aggregator. If the flag is set to true, then when the expiry callback is
+    invoked then any unmarked messages in groups that are not yet released can
+    be sent on to the downstream channel.</para>
+  </section>
+
+  <section id="aggregator-annotations">
+    <title>Configuring an Aggregator with Annotations</title>
+
+    <para>An aggregator configured using annotations can look like
+    this.</para>
+
+    <programlisting language="java"><![CDATA[public class Waiter {
+  ... 
+
+  @Aggregator ]]><co id="aggann" /><![CDATA[ 
+  public Delivery aggregatingMethod(List<OrderItem> items) {
+    ...
+  }
+
+  @ReleaseStrategy ]]><co id="agganncs" /><![CDATA[
+  public boolean releaseChecker(List<Message<?>> messages) {
+    ...
+  }
+
+  @CorrelationStrategy ]]><co id="agganncorrs" /><![CDATA[
+  public String correlateBy(OrderItem item) {
+    ...
+  }
+
+}]]></programlisting>
+
+    <calloutlist>
+      <callout arearefs="aggann">
+        <para>An annotation indicating that this method shall be used as an
+        aggregator. Must be specified if this class will be used as an
+        aggregator.</para>
+      </callout>
+
+      <callout arearefs="agganncs">
+        <para id="aggann2">An annotation indicating that this method shall be
+        used as the release strategy of an aggregator. If not present on any
+        method, the aggregator will use the
+        SequenceSizeCompletionStrategy.</para>
+      </callout>
+
+      <callout arearefs="agganncorrs">
+        <para id="agann3">An annotation indicating that this method shall be
+        used as the correlation strategy of an aggregator. If no correlation
+        strategy is indicated, the aggregator will use the
+        HeaderAttributeCorrelationStrategy based on CORRELATION_ID.</para>
+      </callout>
+    </calloutlist>
+
+    <para>All of the configuration options provided by the xml element are
+    also available for the @Aggregator annotation.</para>
+
+    <para>The aggregator can be either referenced explicitly from XML or, if
+    the @MessageEndpoint is defined on the class, detected automatically
+    through classpath scanning.</para>
+  </section>
+</chapter>

docs/src/reference/docbook/bridge.xml

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="bridge"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Messaging Bridge</title>
+
+  <section id="bridge-introduction">
+    <title>Introduction</title>
+    <para>
+      A Messaging Bridge is a relatively trivial endpoint that simply connects two Message Channels or Channel
+      Adapters. For example, you may want to connect a <interfacename>PollableChannel</interfacename> to a
+      <interfacename>SubscribableChannel</interfacename> so that the subscribing endpoints do not have to worry
+      about any polling configuration. Instead, the Messaging Bridge provides the polling configuration.
+    </para>
+    <para>
+      By providing an intermediary poller between two channels, a Messaging Bridge can be used to throttle inbound
+      Messages. The poller's trigger will determine the rate at which messages arrive on the second channel, and the
+      poller's "maxMessagesPerPoll" property will enforce a limit on the throughput.
+    </para>
+    <para>
+      Another valid use for a Messaging Bridge is to connect two different systems. In such a scenario, Spring 
+      Integration's role would be limited to making the connection between these systems and managing a poller
+      if necessary. It is probably more common to have at least a <emphasis>Transformer</emphasis> between the
+      two systems to translate between their formats, and in that case, the channels would be provided as the
+      'input-channel' and 'output-channel' of a Transformer endpoint. If data format translation is not required,
+      the Messaging Bridge may indeed be sufficient.
+    </para>
+  </section>
+
+  <section id="bridge-namespace">
+    <title>The &lt;bridge&gt; Element</title>
+    <para>
+      The &lt;bridge&gt; element is used to create a Messaging Bridge between two Message Channels or Channel Adapters.
+      Simply provide the "input-channel" and "output-channel" attributes:
+      <programlisting language="xml"><![CDATA[ <bridge input-channel="input" output-channel="output"/>]]></programlisting>
+      As mentioned above, a common use case for the Messaging Bridge is to connect a
+      <interfacename>PollableChannel</interfacename> to a <interfacename>SubscribableChannel</interfacename>, and when
+      performing this role, the Messaging Bridge may also serve as a throttler:
+      <programlisting language="xml"><![CDATA[ <bridge input-channel="pollable" output-channel="subscribable">
+     <poller max-messages-per-poll="10" fixed-rate="5000"/>
+ </bridge>]]></programlisting>
+    </para>
+    <para>
+      Connecting Channel Adapters is just as easy. Here is a simple echo example between the "stdin" and "stdout"
+      adapters from Spring Integration's "stream" namespace.
+      <programlisting language="xml"><![CDATA[ <stream:stdin-channel-adapter id="stdin"/>
+
+ <stream:stdout-channel-adapter id="stdout"/>
+
+ <bridge id="echo" input-channel="stdin" output-channel="stdout"/>]]></programlisting>
+      Of course, the configuration would be similar for other (potentially more useful) Channel Adapter bridges, such
+      as File to JMS, or Mail to File. The various Channel Adapters will be discussed in upcoming chapters.
+    </para>
+    <note>
+      <para>If no 'output-channel' is defined on a bridge, the reply channel provided by the inbound Message will
+      be used, if available. If neither output or reply channel is available, an Exception will be thrown.</para>
+    </note>
+  </section>
+
+</chapter>

docs/src/reference/docbook/chain.xml

@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="chain"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Message Handler Chain</title>
+
+  <section id="chain-introduction">
+    <title>Introduction</title>
+    <para>
+      The <classname>MessageHandlerChain</classname> is an implementation of
+      <interfacename>MessageHandler</interfacename> that can be configured as a single Message Endpoint while
+      actually delegating to a chain of other handlers, such as Filters, Transformers, Splitters, and so on.
+      This can lead to a much simpler configuration when several handlers need to be connected in a fixed, linear
+      progression. For example, it is fairly common to provide a Transformer before other components. Similarly, when
+      providing a <emphasis>Filter</emphasis> before some other component in a chain, you are essentially creating a
+      <ulink url="http://www.eaipatterns.com/MessageSelector.html">Selective Consumer</ulink>. In either case, the
+      chain only requires a single input-channel and a single output-channel as opposed to the configuration of
+      channels for each individual component.
+      <tip>
+        Spring Integration's <emphasis>Filter</emphasis> provides a boolean property 'throwExceptionOnRejection'. When
+        providing multiple Selective Consumers on the same point-to-point channel with different acceptance criteria,
+        this value should be set to 'true' (the default is false) so that the dispatcher will know that the Message was
+        rejected and as a result will attempt to pass the Message on to other subscribers. If the Exception were not
+        thrown, then it would appear to the dispatcher as if the Message had been passed on successfully even though
+        the Filter had <emphasis>dropped</emphasis> the Message to prevent further processing.
+      </tip>
+    </para>
+    <para>
+    The handler chain simplifies configuration while internally maintaining the same degree of loose coupling between
+    components, and it is trivial to modify the configuration if at some point a non-linear arrangement is required.
+    </para>
+    <para>
+    Internally, the chain will be expanded into a linear setup of the listed endpoints, separated by direct channels.
+    The reply channel header will not be taken into account within the chain: only after the last handler is invoked
+    will the resulting message be forwarded on to the reply channel or the chain's output channel. Because of this
+    setup all handlers except the last require a <methodname>setOutputChannel</methodname> implementation. The last
+    handler only needs an output channel if the outputChannel on the MessageHandlerChain is set.
+    <note>
+      <para>
+        As with other endpoints, the output-channel is optional. If there is a reply Message at the end of the
+        chain, the output-channel takes precedence, but if not available, the chain handler will check for a
+        reply channel header on the inbound Message.
+      </para>
+    </note>
+    </para>
+    <para>
+    In most cases there is no need to implement MessageHandlers yourself. The next section will focus on namespace
+    support for the chain element. Most Spring Integration endpoints, like Service Activators and Transformers, are
+    suitable for use within a <classname>MessageHandlerChain</classname>.
+    </para>
+  </section>
+
+  <section id="chain-namespace">
+    <title>The &lt;chain&gt; Element</title>
+    <para>
+      The &lt;chain&gt; element provides an 'input-channel' attribute, and if the last element in the chain is capable
+      of producing reply messages (optional), it also supports an 'output-channel' attribute. The sub-elements are then
+      filters, transformers, splitters, and service-activators. The last element may also be a router.
+      <programlisting language="xml"><![CDATA[ <chain input-channel="input" output-channel="output">
+     <filter ref="someSelector" throw-exception-on-rejection="true"/>
+     <header-enricher error-channel="customErrorChannel">
+         <header name="foo" value="bar"/>
+     </header-enricher>
+     <service-activator ref="someService" method="someMethod"/>
+ </chain>]]></programlisting>
+    </para>
+  <para>
+    The &lt;header-enricher&gt; element used in the above example will set a message header with name "foo" and
+    value "bar" on the message. A header enricher is a specialization of Transformer that touches only header
+    values. You could obtain the same result by implementing a MessageHandler that did the header modifications
+    and wiring that as a bean.
+  </para>
+
+  <para>
+  Some time you need to make a nested call to another chain from within the chain and then come
+  back and continue execution within the original chain.
+    To accomplish this you can utilize Messaging Gateway by including light-configuration via &lt;gateway&gt; element.
+    For example:
+    <programlisting language="xml"><![CDATA[   <si:chain id="main-chain" input-channel="inputA" output-channel="inputB">
+    <si:header-enricher>
+      <si:header name="name" value="Many" />
+    </si:header-enricher>
+    <si:service-activator>
+      <bean class="org.foo.SampleService" />
+    </si:service-activator>
+    <si:gateway request-channel="inputC"/>  
+  </si:chain>
+  <si:chain id="nested-chain-a" input-channel="inputC">
+    <si:header-enricher>
+      <si:header name="name" value="Moe" />
+    </si:header-enricher>
+    <si:gateway request-channel="inputD"/> 
+    <si:service-activator>
+      <bean class="org.foo.SampleService" />
+    </si:service-activator>
+  </si:chain>
+  <si:chain id="nested-chain-b" input-channel="inputD">
+    <si:header-enricher>
+      <si:header name="name" value="Jack" />
+    </si:header-enricher>
+    <si:service-activator>
+      <bean class="org.foo.SampleService" />
+    </si:service-activator>
+  </si:chain>]]></programlisting>
+
+In the above example the <emphasis>nested-chain-a</emphasis> will be called at the end of <emphasis>main-chain</emphasis> processing by the 'gateway' element
+configured there. While in <emphasis>nested-chain-a</emphasis> a call to a <emphasis>nested-chain-b</emphasis> will be made after header enrichment and then it will
+come back to finish execution in <emphasis>nested-chain-b</emphasis> finally getting back to the <emphasis>main-chain</emphasis>.
+When light version of &lt;gateway&gt; element is defined in the chain SI will construct an instance <classname>SimpleMessagingGateway</classname>
+ (no need to provide 'service-interface' configuration) which will take the message in its current state and will place it on the channel defined via 'request-channel' attribute.
+ Upon processing <classname>Message</classname> will be returned to the gateway and continue its journey within the current chain.
+  </para>
+  </section>
+
+</chapter>

docs/src/reference/docbook/channel-adapter.xml

@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="channel-adapter">
+  <title>Channel Adapter</title>
+  <para>
+    A Channel Adapter is a Message Endpoint that enables connecting a single sender or receiver to a Message Channel.
+    Spring Integration provides a number of adapters out of the box to support various transports, such as JMS, File,
+    HTTP, Web Services, and Mail. Those will be discussed in upcoming chapters of this reference guide. However, this
+    chapter focuses on the simple but flexible Method-invoking Channel Adapter support. There are both inbound and
+    outbound adapters, and each may be configured with XML elements provided in the core namespace.
+  </para>
+
+  <section id="channel-adapter-namespace-inbound">
+    <title>The &lt;inbound-channel-adapter&gt; element</title>
+    <para>
+      An "inbound-channel-adapter" element can invoke any method on a Spring-managed Object and send a non-null return
+      value to a <interfacename>MessageChannel</interfacename> after converting it to a <classname>Message</classname>.
+      When the adapter's subscription is activated, a poller will attempt to receive messages from the source. The
+      poller will be scheduled with the <interfacename>TaskScheduler</interfacename> according to the provided
+      configuration. To configure the polling interval or cron expression for an individual channel-adapter,
+      provide a 'poller' element with either an 'interval-trigger' (in milliseconds) or 'cron-trigger'
+      sub-element.
+      <programlisting language="xml"><![CDATA[<inbound-channel-adapter ref="source1" method="method1" channel="channel1">
+    <poller fixed-rate="5000"/>
+</inbound-channel-adapter>
+
+<inbound-channel-adapter ref="source2" method="method2" channel="channel2">
+    <poller cron="30 * 9-17 * * MON-FRI"/>
+</channel-adapter>]]></programlisting>
+    </para>
+    <note>
+      <para>
+        If no poller is provided, then a single default poller must be registered within the context.
+        See <xref linkend="endpoint-namespace"/> for more detail.
+      </para>
+    </note>
+  </section>
+
+  <section id="channel-adapter-namespace-outbound">
+    <title>The &lt;outbound-channel-adapter/&gt; element</title>
+    <para>
+      An "outbound-channel-adapter" element can also connect a <interfacename>MessageChannel</interfacename> to any POJO consumer
+      method that should be invoked with the payload of Messages sent to that channel.
+      <programlisting language="xml"><![CDATA[<outbound-channel-adapter channel="channel1" ref="target1" method="method1"/>]]></programlisting>
+      If the channel being adapted is a <interfacename>PollableChannel</interfacename>, provide a poller sub-element:
+        <programlisting language="xml"><![CDATA[<outbound-channel-adapter channel="channel2" ref="target2" method="method2">
+    ]]><emphasis><![CDATA[<poller fixed-rate="3000"/>
+]]></emphasis><![CDATA[
+</outbound-channel-adapter>
+<beans:bean id="target1" class="org.bar.Foo"/>
+]]></programlisting>
+    </para>
+    <para>
+      Using a "ref" attribute is generally recommended if the POJO consumer implementation can be reused
+      in other <code>&lt;outbound-channel-adapter&gt;</code> definitions. However if the consumer implementation
+      should be scoped to a single definition of the <code>&lt;outbound-channel-adapter&gt;</code>, you can define it as inner bean:
+        <programlisting language="xml"><![CDATA[<outbound-channel-adapter channel="channel2" method="method2">
+        <beans:bean class="org.bar.Foo"/>
+    ]]><![CDATA[
+</outbound-channel-adapter>
+]]></programlisting>
+    </para>
+    <note>
+    <para>
+    Using both the "ref" attribute and an inner handler definition in the same <code>&lt;outbound-channel-adapter&gt;</code>
+    configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
+    </para>
+    </note>
+    <para>
+      Any Channel Adapter can be created without a "channel" reference in which case it will implicitly create an
+      instance of <classname>DirectChannel</classname>. The created channel's name will match the "id" attribute
+      of the &lt;inbound-channel-adapter/&gt; or &lt;outbound-channel-adapter&gtl; element. Therefore, if the "channel"
+      is not provided, the "id" is required.
+    </para>
+  </section>
+
+</chapter>

docs/src/reference/docbook/channel.xml

@@ -0,0 +1,602 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="channel"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Message Channels</title>
+  <para>
+    While the <interfacename>Message</interfacename> plays the crucial role of encapsulating data, it is the
+    <interfacename>MessageChannel</interfacename> that decouples message producers from message consumers.
+  </para>
+
+  <section id="channel-interfaces">
+    <title>The MessageChannel Interface</title>
+    <para>
+      Spring Integration's top-level <interfacename>MessageChannel</interfacename> interface is defined as follows.
+      <programlisting language="java"><![CDATA[public interface MessageChannel {
+
+    String getName();
+
+    boolean send(Message message);
+
+    boolean send(Message message, long timeout);
+}]]></programlisting>
+      When sending a message, the return value will be <emphasis>true</emphasis> if the message is sent successfully.
+      If the send call times out or is interrupted, then it will return <emphasis>false</emphasis>.
+    </para>
+
+    <section id="channel-interfaces-pollablechannel">
+      <title>PollableChannel</title>
+      <para>
+        Since Message Channels may or may not buffer Messages (as discussed in the overview), there are two
+        sub-interfaces defining the buffering (pollable) and non-buffering (subscribable) channel behavior. Here is the
+        definition of <interfacename>PollableChannel</interfacename>.
+        <programlisting language="java">public interface PollableChannel extends MessageChannel {
+
+    Message&lt;?&gt; receive();
+
+    Message&lt;?&gt; receive(long timeout);
+
+    List&lt;Message&lt;?&gt;&gt; clear();
+
+    List&lt;Message&lt;?&gt;&gt; purge(MessageSelector selector);
+
+}</programlisting>
+        Similar to the send methods, when receiving a message, the return value will be <emphasis>null</emphasis> in the
+        case of a timeout or interrupt.
+      </para>
+    </section>
+
+    <section id="channel-interfaces-subscribablechannel">
+      <title>SubscribableChannel</title>
+      <para>
+        The <interfacename>SubscribableChannel</interfacename> base interface is implemented by channels that send
+        Messages directly to their subscribed <interfacename>MessageHandler</interfacename>s. Therefore, they do not
+        provide receive methods for polling, but instead define methods for managing those subscribers:
+        <programlisting language="java">public interface SubscribableChannel extends MessageChannel {
+
+    boolean subscribe(MessageHandler handler);
+
+    boolean unsubscribe(MessageHandler handler);
+
+}</programlisting>
+      </para>
+    </section>
+  </section>
+
+  <section id="channel-implementations">
+    <title>Message Channel Implementations</title>
+    <para>
+      Spring Integration provides several different Message Channel implementations. Each is briefly described in the
+      sections below.
+    </para>
+    <section id="channel-implementations-publishsubscribechannel">
+      <title>PublishSubscribeChannel</title>
+      <para>
+        The <classname>PublishSubscribeChannel</classname> implementation broadcasts any Message
+        sent to it to all of its subscribed handlers. This is most often used for sending
+        <emphasis>Event Messages</emphasis> whose primary role is notification as opposed to
+        <emphasis>Document Messages</emphasis> which are generally intended to be processed by
+        a single handler. Note that the <classname>PublishSubscribeChannel</classname> is
+        intended for sending only. Since it broadcasts to its subscribers directly when its
+        <methodname>send(Message)</methodname> method is invoked, consumers cannot poll for
+        Messages (it does not implement <interfacename>PollableChannel</interfacename> and
+        therefore has no <methodname>receive()</methodname> method). Instead, any subscriber
+        must be a <interfacename>MessageHandler</interfacename> itself, and the subscriber's
+        <methodname>handleMessage(Message)</methodname> method will be invoked in turn.
+      </para>
+    </section>
+    <section id="channel-implementations-queuechannel">
+      <title>QueueChannel</title>
+      <para>
+        The <classname>QueueChannel</classname> implementation wraps a queue. Unlike the
+        <classname>PublishSubscribeChannel</classname>, the <classname>QueueChannel</classname> has point-to-point
+        semantics. In other words, even if the channel has multiple consumers, only one of them should receive any
+        Message sent to that channel. It provides a default no-argument constructor (providing an essentially unbounded
+        capacity of <code>Integer.MAX_VALUE</code>) as well as a constructor that accepts the queue capacity:
+        <programlisting language="java">public QueueChannel(int capacity)</programlisting>
+        A channel that has not reached its capacity limit will store messages in its internal queue, and the
+        <methodname>send()</methodname> method will return immediately even if no receiver is ready to handle the
+        message. If the queue has reached capacity, then the sender will block until room is available. Or, if using
+        the send call that accepts a timeout, it will block until either room is available or the timeout period
+        elapses, whichever occurs first. Likewise, a receive call will return immediately if a message is available
+        on the queue, but if the queue is empty, then a receive call may block until either a message is available
+        or the timeout elapses. In either case, it is possible to force an immediate return regardless of the
+        queue's state by passing a timeout value of 0. Note however, that calls to the no-arg versions of
+        <methodname>send()</methodname> and <methodname>receive()</methodname> will block indefinitely.
+      </para>
+    </section>
+    <section id="channel-implementations-prioritychannel">
+      <title>PriorityChannel</title>
+      <para>
+        Whereas the <classname>QueueChannel</classname> enforces first-in/first-out (FIFO) ordering, the
+        <classname>PriorityChannel</classname> is an alternative implementation that allows for messages
+        to be ordered within the channel based upon a priority. By default the priority is determined by the
+        '<literal>priority</literal>' header within each message. However, for custom priority determination
+        logic, a comparator of type <classname>Comparator&lt;Message&lt;?&gt;&gt;</classname> can be provided
+        to the <classname>PriorityChannel</classname>'s constructor.
+      </para>
+    </section>
+    <section id="channel-implementations-rendezvouschannel">
+      <title>RendezvousChannel</title>
+      <para>
+        The <classname>RendezvousChannel</classname> enables a "direct-handoff" scenario where a sender will block
+        until another party invokes the channel's <methodname>receive()</methodname> method or vice-versa. Internally,
+        this implementation is quite similar to the <classname>QueueChannel</classname> except that it uses a
+        <classname>SynchronousQueue</classname> (a zero-capacity implementation of
+        <interfacename>BlockingQueue</interfacename>). This works well in situations where the sender and receiver are
+        operating in different threads but simply dropping the message in a queue asynchronously is not appropriate.
+        In other words, with a <classname>RendezvousChannel</classname> at least the sender knows that some receiver
+        has accepted the message, whereas with a <classname>QueueChannel</classname>, the message would have been
+        stored to the internal queue and potentially never received.
+      </para>
+      <tip>
+        <para>
+          Keep in mind that all of these queue-based channels are storing messages in-memory only. When persistence
+          is required, you can either invoke a database operation within a handler or use Spring Integration's
+          support for JMS-based Channel Adapters. The latter option allows you to take advantage of any JMS provider's
+          implementation for message persistence, and it will be discussed in <xref linkend="jms"/>. However, when
+          buffering in a queue is not necessary, the simplest approach is to rely upon the
+          <classname>DirectChannel</classname> discussed next.
+        </para>
+      </tip>
+      <para>
+        The <classname>RendezvousChannel</classname> is also useful for implementing request-reply
+        operations. The sender can create a temporary, anonymous instance of <classname>RendezvousChannel</classname>
+        which it then sets as the 'replyChannel' header when building a Message. After sending that Message, the sender
+        can immediately call receive (optionally providing a timeout value) in order to block while waiting for a reply
+        Message. This is very similar to the implementation used internally by many of Spring Integration's
+        request-reply components.
+      </para>
+    </section>
+    <section id="channel-implementations-directchannel">
+      <title>DirectChannel</title>
+      <para>
+        The <classname>DirectChannel</classname> has point-to-point semantics but otherwise is more similar to the
+        <classname>PublishSubscribeChannel</classname> than any of the queue-based channel implementations described
+        above. It implements the <interfacename>SubscribableChannel</interfacename> interface instead of the
+        <interfacename>PollableChannel</interfacename> interface, so it dispatches Messages directly to a subscriber.
+        As a point-to-point channel, however, it differs from the <classname>PublishSubscribeChannel</classname> in
+        that it will only send each Message to a <emphasis>single</emphasis> subscribed
+        <classname>MessageHandler</classname>.
+      </para>
+      <para>
+        In addition to being the simplest point-to-point channel option, one of its most important features is that
+        it enables a single thread to perform the operations on "both sides" of the channel. For example, if a handler
+        is subscribed to a <classname>DirectChannel</classname>, then sending a Message to that channel will trigger
+        invocation of that handler's <methodname>handleMessage(Message)</methodname> method <emphasis>directly in the
+        sender's thread</emphasis>, before the send() method invocation can return.
+      </para>
+      <para>
+        The key motivation for providing a channel implementation with this behavior is to support transactions that
+        must span across the channel while still benefiting from the abstraction and loose coupling that the channel
+        provides. If the send call is invoked within the scope of a transaction, then the outcome of the handler's
+        invocation (e.g. updating a database record) will play a role in determining the ultimate result of that
+        transaction (commit or rollback).
+        <note>
+          Since the <classname>DirectChannel</classname> is the simplest option and does not add any additional
+          overhead that would be required for scheduling and managing the threads of a poller, it is the default
+          channel type within Spring Integration. The general idea is to define the channels for an application and
+          then to consider which of those need to provide buffering or to throttle input, and then modify those to
+          be queue-based <interfacename>PollableChannels</interfacename>. Likewise, if a channel needs to broadcast
+          messages, it should not be a <classname>DirectChannel</classname> but rather a
+          <classname>PublishSubscribeChannel</classname>. Below you will see how each of these can be configured.
+        </note>
+      </para>
+      <para>
+        The <classname>DirectChannel</classname> internally delegates to a Message Dispatcher to invoke its
+        subscribed Message Handlers, and that dispatcher can have a load-balancing strategy. The load-balancer
+        determines how invocations will be ordered in the case that there are multiple handlers subscribed to the
+        same channel. When using the namespace support described below, the default strategy is
+        "round-robin" which essentially load-balances across the handlers in rotation.
+        <note>
+          The "round-robin" strategy is currently the only implementation available out-of-the-box in Spring
+          Integration. Other strategy implementations may be added in future versions.
+        </note>
+      </para>
+      <para>
+        The load-balancer also works in combination with a boolean <emphasis>failover</emphasis> property.
+        If the "failover" value is true (the default), then the dispatcher will fall back to any subsequent
+        handlers as necessary when preceding handlers throw Exceptions. The order is determined by an optional
+        order value defined on the handlers themselves or, if no such value exists, the order in which the
+        handlers are subscribed.
+      </para>
+      <para>
+        If a certain situation requires that the dispatcher always try to invoke the first handler, then
+        fallback in the same fixed order sequence every time an error occurs, no load-balancing strategy should
+        be provided. In other words, the dispatcher still supports the failover boolean property even when no
+        load-balancing is enabled. Without load-balancing, however, the invocation of handlers will always begin
+        with the first according to their order. For example, this approach works well when there is a clear
+        definition of primary, secondary, tertiary, and so on. When using the namespace support, the "order"
+        attribute on any endpoint will determine that order.
+      </para>
+      <note>
+          Keep in mind that load-balancing and failover only apply when a channel has more than one
+          subscribed Message Handler. When using the namespace support, this means that more than one
+          endpoint shares the same channel reference in the "input-channel" attribute.
+       </note>
+    </section>
+    <section id="executor-channel">
+      <title>ExecutorChannel</title>
+      <para>
+        The <classname>ExecutorChannel</classname> is a point-to-point channel that supports
+        the same dispatcher configuration as <classname>DirectChannel</classname> (load-balancing strategy
+        and the failover boolean property). The key difference between these two dispatching channel types
+        is that the <classname>ExecutorChannel</classname> delegates to an instance of
+        <interfacename>TaskExecutor</interfacename> to perform the dispatch. This means that the send method
+        typically will not block, but it also means that the handler invocation may not occur in the sender's
+        thread. It therefore <emphasis>does not support transactions spanning the sender and receiving
+        handler</emphasis>.
+        <tip>
+        Note that there are occasions where the sender may block. For example, when using a
+        TaskExecutor with a rejection-policy that throttles back on the client (such as the
+          <code>ThreadPoolExecutor.CallerRunsPolicy</code>), the sender's thread will execute
+          the method directly anytime the thread pool is at its maximum capacity and the
+          executor's work queue is full. Since that situation would only occur in a non-predictable
+          way, that obviously cannot be relied upon for transactions.
+        </tip>
+      </para>
+    </section>
+    <section id="channel-implementations-threadlocalchannel">
+      <title>ThreadLocalChannel</title>
+      <para>
+        The final channel implementation type is <classname>ThreadLocalChannel</classname>. This channel also delegates
+        to a queue internally, but the queue is bound to the current thread. That way the thread that sends to the
+        channel will later be able to receive those same Messages, but no other thread would be able to access them.
+        While probably the least common type of channel, this is useful for situations where
+        <classname>DirectChannels</classname> are being used to enforce a single thread of operation but any reply
+        Messages should be sent to a "terminal" channel. If that terminal channel is a
+        <classname>ThreadLocalChannel</classname>, the original sending thread can collect its replies from it.
+      </para>
+    </section>
+  </section>
+
+  <section id="channel-interceptors">
+    <title>Channel Interceptors</title>
+    <para>
+      One of the advantages of a messaging architecture is the ability to provide common behavior and capture
+      meaningful information about the messages passing through the system in a non-invasive way. Since the
+      <interfacename>Messages</interfacename> are being sent to and received from
+      <interfacename>MessageChannels</interfacename>, those channels provide an opportunity for intercepting
+      the send and receive operations. The <interfacename>ChannelInterceptor</interfacename> strategy interface
+      provides methods for each of those operations:
+      <programlisting language="java"><![CDATA[public interface ChannelInterceptor {
+
+    Message<?> preSend(Message<?> message, MessageChannel channel);
+
+    void postSend(Message<?> message, MessageChannel channel, boolean sent);
+
+    boolean preReceive(MessageChannel channel);
+
+    Message<?> postReceive(Message<?> message, MessageChannel channel);
+}]]></programlisting>
+      After implementing the interface, registering the interceptor with a channel is just a matter of calling:
+      <programlisting language="java">channel.addInterceptor(someChannelInterceptor);</programlisting>
+      The methods that return a Message instance can be used for transforming the Message or can return 'null'
+      to prevent further processing (of course, any of the methods can throw a RuntimeException). Also, the
+      <methodname>preReceive</methodname> method can return '<literal>false</literal>' to prevent the receive
+      operation from proceeding.
+      <note>
+        Keep in mind that <methodname>receive()</methodname> calls are only relevant for
+        <interfacename>PollableChannels</interfacename>. In fact the
+        <interfacename>SubscribableChannel</interfacename> interface does not even define a
+        <methodname>receive()</methodname> method. The reason for this is that when a Message is sent to a
+        <interfacename>SubscribableChannel</interfacename> it will be sent directly to one or more subscribers
+        depending on the type of channel (e.g. a PublishSubscribeChannel sends to all of its subscribers). Therefore,
+        the <methodname>preReceive(..)</methodname> and <methodname>postReceive(..)</methodname> interceptor methods
+        are only invoked when the interceptor is applied to a <interfacename>PollableChannel</interfacename>.
+      </note>
+      Spring Integration also provides an implementation of the
+      <ulink url="http://eaipatterns.com/WireTap.html">Wire Tap</ulink> pattern.
+      It is a simple interceptor that sends the Message to another channel without otherwise altering the
+      existing flow. It can be very useful for debugging and monitoring. An example is shown in
+      <xref linkend="channel-wiretap"/>.
+    </para>
+    <para>
+      Because it is rarely necessary to implement all of the interceptor methods, a
+      <classname>ChannelInterceptorAdapter</classname> class is also available for sub-classing. It provides no-op
+      methods (the <literal>void</literal> method is empty, the <classname>Message</classname> returning methods
+      return the Message as-is, and the <literal>boolean</literal> method returns <literal>true</literal>).
+      Therefore, it is often easiest to extend that class and just implement the method(s) that you need as in the
+      following example.
+      <programlisting language="java"><![CDATA[public class CountingChannelInterceptor extends ChannelInterceptorAdapter {
+
+    private final AtomicInteger sendCount = new AtomicInteger();
+
+    @Override
+    public Message<?> preSend(Message<?> message, MessageChannel channel) {
+        sendCount.incrementAndGet();
+        return message;
+    }
+}]]></programlisting>
+      <tip>
+        The order of invocation for the interceptor methods depends on the type of channel. As described above,
+        the queue-based channels are the only ones where the receive method is intercepted in the first place.
+        Additionally, the relationship between send and receive interception depends on the timing of separate
+        sender and receiver threads. For example, if a receiver is already blocked while waiting for a message
+        the order could be: preSend, preReceive, postReceive, postSend. However, if a receiver polls after the
+        sender has placed a message on the channel and already returned, the order would be: preSend, postSend,
+        (some-time-elapses) preReceive, postReceive. The time that elapses in such a case depends on a number
+        of factors and is therefore generally unpredictable (in fact, the receive may never happen!).
+        Obviously, the type of queue also plays a role (e.g. rendezvous vs. priority). The bottom line is that
+        you cannot rely on the order beyond the fact that preSend will precede postSend and preReceive will
+        precede postReceive.
+      </tip>
+    </para>
+  </section>
+
+  <section id="channel-template">
+    <title>MessagingTemplate</title>
+    <para>
+      As you will see when the endpoints and their various configuration options are introduced, Spring Integration
+      provides a foundation for messaging components that enables non-invasive invocation of your application code
+      <emphasis>from the messaging system</emphasis>. However, sometimes it is necessary to invoke the messaging system
+      <emphasis>from your application code</emphasis>. For convenience when implementing such use-cases, Spring
+      Integration provides a <classname>MessagingTemplate</classname> that supports a variety of operations across
+      the Message Channels, including request/reply scenarios. For example, it is possible to send a request
+      and wait for a reply.
+      <programlisting language="java">MessagingTemplate template = new MessagingTemplate();
+
+Message reply = template.sendAndReceive(new StringMessage("test"), someChannel);</programlisting>
+      In that example, a temporary anonymous channel would be created internally by the template. The
+      'sendTimeout' and 'receiveTimeout' properties may also be set on the template, and other exchange
+      types are also supported.
+      <programlisting language="java"><![CDATA[public boolean send(final Message<?> message, final MessageChannel channel) { ... }
+
+public Message<?> sendAndReceive(final Message<?> request, final MessageChannel channel) { .. }
+
+public Message<?> receive(final PollableChannel<?> channel) { ... }]]></programlisting>
+    </para>
+    <note>
+      <para>
+        A less invasive approach that allows you to invoke simple interfaces with payload and/or header
+        values instead of Message instances is described in <xref linkend="gateway-proxy"/>.
+      </para>
+    </note>
+  </section>
+
+  <section id="channel-configuration">
+    <title>Configuring Message Channels</title>
+    <para>
+      To create a Message Channel instance, you can use the 'channel' element:
+      <programlisting language="xml">&lt;channel id="exampleChannel"/&gt;</programlisting>
+    </para>
+    <para>
+      The default channel type is <emphasis>Point to Point</emphasis>. To create a
+      <emphasis>Publish Subscribe</emphasis> channel, use the "publish-subscribe-channel" element:
+      <programlisting language="xml">&lt;publish-subscribe-channel id="exampleChannel"/&gt;</programlisting>
+    </para>
+    <para>
+      To create a <ulink url="http://www.eaipatterns.com/DatatypeChannel.html">Datatype Channel</ulink> that only
+      accepts messages containing a certain payload type, provide the fully-qualified class name in the
+      channel element's <literal>datatype</literal> attribute:
+      <programlisting language="xml"><![CDATA[<channel id="numberChannel" datatype="java.lang.Number"/>]]></programlisting>
+      Note that the type check passes for any type that is <emphasis>assignable</emphasis> to the channel's
+      datatype. In other words, the "numberChannel" above would accept messages whose payload is
+      <classname>java.lang.Integer</classname> or <classname>java.lang.Double</classname>. Multiple types can be
+      provided as a comma-delimited list:
+      <programlisting language="xml"><![CDATA[<channel id="stringOrNumberChannel" datatype="java.lang.String,java.lang.Number"/>]]></programlisting>
+    </para>
+    <para>
+      When using the "channel" element without any sub-elements, it will create a <classname>DirectChannel</classname>
+      instance (a <interfacename>SubscribableChannel</interfacename>).
+    </para>
+    <para>
+      However, you can alternatively provide a variety of "queue" sub-elements to create any of
+      the pollable channel types (as described in
+      <xref linkend="channel-implementations"/>). Examples of each are shown below.
+    </para>
+    <section id="channel-configuration-directchannel">
+      <title>DirectChannel Configuration</title>
+      <para>
+        As mentioned above, <classname>DirectChannel</classname> is the default type.
+        <programlisting language="xml"><![CDATA[<channel id="directChannel"/>]]></programlisting>
+      </para>
+      <para>
+        A default channel will have a <emphasis>round-robin</emphasis> load-balancer and will also have
+        failover enabled (See the discussion in <xref linkend="channel-implementations-directchannel"/>
+        for more detail). To disable one or both of these, add a &lt;dispatcher/&gt; sub-element and
+        configure the attributes:
+        <programlisting language="xml"><![CDATA[<channel id="failFastChannel">
+    <dispatcher failover="false"/>
+</channel>
+
+<channel id="channelWithFixedOrderSequenceFailover">
+    <dispatcher load-balancer="none"/>
+</channel>
+]]></programlisting>
+      </para>
+    </section>
+    <section id="channel-configuration-queuechannel">
+      <title>QueueChannel Configuration</title>
+      <para>
+        To create a <classname>QueueChannel</classname>, use the "queue" sub-element.
+        You may specify the channel's capacity:
+        <programlisting language="xml">&lt;channel id="queueChannel"&gt;
+    &lt;queue capacity="25"/&gt;
+&lt;/channel&gt;</programlisting>
+        <note>
+          If you do not provide a value for the 'capacity' attribute on this &lt;queue/&gt; sub-element,
+          the resulting queue will be unbounded. To avoid issues such as OutOfMemoryErrors, it is highly
+          recommended to set an explicit value for a bounded queue.
+        </note>
+      </para>
+    </section>
+    <section id="channel-configuration-pubsubchannel">
+      <title>PublishSubscribeChannel Configuration</title>
+      <para>
+        To create a <classname>PublishSubscribeChannel</classname>, use the "publish-subscribe-channel" element.
+        When using this element, you can also specify the "task-executor" used for publishing
+        Messages (if none is specified it simply publishes in the sender's thread):
+        <programlisting language="xml">&lt;publish-subscribe-channel id="pubsubChannel" task-executor="someExecutor"/&gt;</programlisting>
+        If you are providing a <emphasis>Resequencer</emphasis> or <emphasis>Aggregator</emphasis> downstream
+        from a <classname>PublishSubscribeChannel</classname>, then you can set the 'apply-sequence' property
+        on the channel to <code>true</code>. That will indicate that the channel should set the sequence-size
+        and sequence-number Message headers as well as the correlation id prior to passing the Messages along.
+        For example, if there are 5 subscribers, the sequence-size would be set to 5, and the Messages would
+        have sequence-number header values ranging from 1 to 5.
+        <programlisting language="xml">&lt;publish-subscribe-channel id="pubsubChannel" apply-sequence="true"/&gt;</programlisting>
+        <note>
+          The 'apply-sequence' value is <code>false</code> by default so that a Publish Subscribe Channel
+          can send the exact same Message instances to multiple outbound channels. Since Spring Integration
+          enforces immutability of the payload and header references, the channel creates new Message
+          instances with the same payload reference but different header values when the flag is set to
+          <code>true</code>.
+        </note>
+      </para>
+    </section>
+    <section id="channel-configuration-executorchannel">
+      <title>ExecutorChannel</title>
+      <para>
+        To create an <classname>ExecutorChannel</classname>, add the &lt;dispatcher&gt; sub-element along
+        with a 'task-executor' attribute. Its value can reference any <interfacename>TaskExecutor</interfacename>
+        within the context. For example, this enables configuration of a thread-pool for dispatching messages
+        to subscribed handlers. As mentioned above, this does break the "single-threaded" execution context
+        between sender and receiver so that any active transaction context will not be shared by the invocation
+        of the handler (i.e. the handler may throw an Exception, but the send invocation has already returned
+        successfully).
+        <programlisting language="xml"><![CDATA[<channel id="executorChannel">
+    <dispatcher task-executor="someExecutor"/>
+</channel>]]></programlisting>
+      </para>
+      <note>
+        The "load-balancer" and "failover" options are also both available on the dispatcher sub-element
+        as described above in <xref linkend="channel-configuration-directchannel"/>. The same defaults
+        apply as well. So, the channel will have a round-robin load-balancing strategy with failover
+        enabled unless explicit configuration is provided for one or both of those attributes.
+        <programlisting language="xml"><![CDATA[<channel id="executorChannelWithoutFailover">
+    <dispatcher task-executor="someExecutor" failover="false"/>
+</channel>]]></programlisting>
+      </note>
+    </section>
+    <section id="channel-configuration-prioritychannel">
+      <title>PriorityChannel Configuration</title>
+      <para>
+        To create a <classname>PriorityChannel</classname>, use the "priority-queue" sub-element:
+        <programlisting language="xml"><![CDATA[<channel id="priorityChannel">
+    <priority-queue capacity="20"/>
+</channel>]]></programlisting>
+        By default, the channel will consult the <classname>MessagePriority</classname> header of the
+        message. However, a custom <interfacename>Comparator</interfacename> reference may be
+        provided instead. Also, note that the <classname>PriorityChannel</classname> (like the other types)
+        does support the "datatype" attribute. As with the QueueChannel, it also supports a "capacity" attribute.
+        The following example demonstrates all of these:
+        <programlisting language="xml"><![CDATA[<channel id="priorityChannel" datatype="example.Widget">
+    <priority-queue comparator="widgetComparator"
+                    capacity="10"/>
+</channel>
+]]></programlisting>
+      </para>
+    </section>
+    <section id="channel-configuration-rendezvouschannel">
+      <title>RendezvousChannel Configuration</title>
+      <para>
+        A <classname>RendezvousChannel</classname> is created when the queue sub-element is
+        a &lt;rendezvous-queue&gt;. It does not provide any additional configuration options to
+        those described above, and its queue does not accept any capacity value since it is a
+        0-capacity direct handoff queue.
+        <programlisting language="xml"><![CDATA[<channel id="rendezvousChannel"/>
+    <rendezvous-queue/>
+</channel>
+]]></programlisting>
+      </para>
+    </section>
+    <section id="channel-configuration-threadlocalchannel">
+      <title>ThreadLocalChannel Configuration</title>
+      <para>
+        The <classname>ThreadLocalChannel</classname> does not provide any additional configuration options.
+        <programlisting language="xml"><![CDATA[<thread-local-channel id="threadLocalChannel"/>]]></programlisting>
+      </para>
+    </section>
+
+    <section id="channel-configuration-interceptors">
+    <title>Channel Interceptor Configuration</title>
+      <para>
+        Message channels may also have interceptors as described in <xref linkend="channel-interceptors"/>. The
+        &lt;interceptors&gt; sub-element can be added within &lt;channel&gt; (or the more specific element
+        types). Provide the "ref" attribute to reference any Spring-managed object that implements the
+        <interfacename>ChannelInterceptor</interfacename> interface:
+        <programlisting language="xml"><![CDATA[<channel id="exampleChannel">
+    ]]><emphasis><![CDATA[<interceptors>
+        <ref bean="trafficMonitoringInterceptor"/>
+    </interceptors>]]></emphasis><![CDATA[
+</channel>]]></programlisting>
+        In general, it is a good idea to define the interceptor implementations in a separate location since they
+        usually provide common behavior that can be reused across multiple channels.
+      </para>
+    </section>
+
+    <section id="global-channel-configuration-interceptors">
+    <title>Global Channel Interceptor Configuration</title>
+      <para>
+        Channel Interceptors allow you for a clean and concise way of applying cross-cutting behavior per individual channel.
+        But what if the same behavior should be applied on multiple channels, configuring the same set of interceptors for
+        each channel <emphasis>would not be</emphasis> the most efficient way. The better way would be to configure interceptors globally and apply
+        them on multiple channels in one shot. Spring Integration provides capabilities to configure <emphasis>Global Interceptors</emphasis>
+        and apply them on multiple channels.
+    Look at the example below:
+        <programlisting language="xml"><![CDATA[<int:channel-interceptor pattern="input*, bar*, foo" order="3">
+    <bean class="foo.barSampleInterceptor"/>
+</int:channel-interceptor>]]></programlisting>
+    or
+    <programlisting language="xml"><![CDATA[<int:channel-interceptor ref="myInterceptor" pattern="input*, bar*, foo" order="3"/>
+
+<bean id="myInterceptor" class="foo.barSampleInterceptor"/>]]></programlisting>
+        &lt;channel-interceptor&gt; element allows you to define a global interceptor which will be applied on all
+        channels that match patterns defined via <emphasis>pattern</emphasis> attribute. In the above case the global interceptor will be applied on
+        'foo' channel and all other channels that begin with 'bar' and 'input'.
+        The <emphasis>order</emphasis> attribute allows you to manage the place where this interceptor will be injected.
+        For example, channel 'inputChannel' could have individual interceptors configured locally (see below):
+        <programlisting language="xml"><![CDATA[<int:channel id="inputChannel"> 
+  <int:interceptors>
+    <int:wire-tap channel="logger"/> 
+  </int:interceptors>
+</int:channel>]]></programlisting>
+  The reasonable question would be how global interceptor will be injected in relation to other interceptors
+  configured locally or through other global interceptor definitions? Current implementation provides
+  a very simple and clever mechanism of handling this. Positive number in the <emphasis>order</emphasis> attribute will ensure interceptor injection
+  after existing interceptors and negative number will ensure that such interceptors injected before.
+  This means that in the above example global interceptor will be injected <emphasis>AFTER</emphasis> (since its order is greater then 0)
+  'wire-tap' interceptor configured locally. If there was another global interceptor with matching <emphasis>pattern</emphasis> their
+  order would be determined based on who's got the higher or lower value in <emphasis>order</emphasis> attribute.
+  To inject global interceptor <emphasis>BEFORE</emphasis> the existing interceptors use negative value for the <emphasis>order</emphasis> attribute.
+      </para>
+      <note>
+      Note that <emphasis>order</emphasis> and <emphasis>pattern</emphasis> attributes are optional. The default value for <emphasis>order</emphasis>
+      will be 0 and for <emphasis>pattern</emphasis> is '*'
+      </note>
+    </section>
+
+    <section id="channel-wiretap">
+    <title>Wire Tap</title>
+      <para>
+    As mentioned above, Spring Integration provides a simple <emphasis>Wire Tap</emphasis> interceptor out of
+    the box. You can configure a <emphasis>Wire Tap</emphasis> on any channel within an 'interceptors' element.
+        This is especially useful for debugging, and can be used in conjunction with Spring Integration's logging
+    Channel Adapter as follows: <programlisting language="xml"><![CDATA[ <channel id="in">
+     <interceptors>
+         <wire-tap channel="logger"/>
+     </interceptors>
+ </channel>
+
+ <logging-channel-adapter id="logger" level="DEBUG"/>]]></programlisting>
+        <tip>
+      The 'logging-channel-adapter' also accepts a boolean attribute: <emphasis>'log-full-message'</emphasis>.
+      That is <emphasis>false</emphasis> by default so that only the payload is logged. Setting that to
+      <emphasis>true</emphasis> enables logging of all headers in addition to the payload.
+      </tip>
+      </para>
+  </section>
+
+    <note>
+      <para>
+        If namespace support is enabled, there are also two special channels defined within the context by default:
+        <code>errorChannel</code> and <code>nullChannel</code>. The 'nullChannel' acts like <code>/dev/null</code>,
+        simply logging any Message sent to it at DEBUG level and returning immediately. Any time you face channel
+        resolution errors for a reply that you don't care about, you can set the affected component's 'output-channel'
+        to reference 'nullChannel' (the name 'nullChannel' is reserved within the context). The 'errorChannel' is
+        used internally for sending error messages, and it can be overridden with a custom configuration. It is
+        discussed in greater detail in <xref linkend="namespace-errorhandler"/>.
+      </para>
+    </note>
+  </section>
+
+</chapter>

docs/src/reference/docbook/configuration.xml

@@ -0,0 +1,463 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="configuration"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Configuration</title>
+  <section id="configuration-introduction">
+    <title>Introduction</title>
+    <para>
+      Spring Integration offers a number of configuration options. Which option you choose depends upon your particular
+      needs and at what level you prefer to work. As with the Spring framework in general, it is also possible to mix
+      and match the various techniques according to the particular problem at hand. For example, you may choose the
+      XSD-based namespace for the majority of configuration combined with a handful of objects that are configured with
+      annotations. As much as possible, the two provide consistent naming. XML elements defined by the XSD schema will
+      match the names of annotations, and the attributes of those XML elements will match the names of annotation
+      properties. Direct usage of the API is of course always an option, but we expect that most users will choose one
+      of the higher-level options, or a combination of the namespace-based and annotation-driven configuration.
+    </para>
+  </section>
+
+  <section id="configuration-namespace">
+    <title>Namespace Support</title>
+    <para>
+      Spring Integration components can be configured with XML elements that map directly to the terminology and
+      concepts of enterprise integration. In many cases, the element names match those of the
+      <ulink url="http://www.eaipatterns.com">Enterprise Integration Patterns</ulink>.
+    </para>
+    <para>
+      To enable Spring Integration's core namespace support within your Spring configuration files, add the following
+      namespace reference and schema mapping in your top-level 'beans' element:
+      <programlisting language="xml"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans"
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       ]]><emphasis>xmlns:integration="http://www.springframework.org/schema/integration"</emphasis><![CDATA[
+       xsi:schemaLocation="http://www.springframework.org/schema/beans
+           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
+           ]]><emphasis>http://www.springframework.org/schema/integration
+           http://www.springframework.org/schema/integration/spring-integration-2.0.xsd"</emphasis>&gt;</programlisting>
+    </para>
+    <para>
+      You can choose any name after "xmlns:"; <emphasis>integration</emphasis> is used here for clarity, but you might
+      prefer a shorter abbreviation. Of course if you are using an XML-editor or IDE support, then the availability of
+      auto-completion may convince you to keep the longer name for clarity. Alternatively, you can create configuration
+      files that use the Spring Integration schema as the primary namespace:
+      <programlisting language="xml"><emphasis>&lt;beans:beans xmlns="http://www.springframework.org/schema/integration"</emphasis><![CDATA[
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       ]]><emphasis>xmlns:beans="http://www.springframework.org/schema/beans"</emphasis><![CDATA[
+       xsi:schemaLocation="http://www.springframework.org/schema/beans
+           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
+           http://www.springframework.org/schema/integration
+           http://www.springframework.org/schema/integration/spring-integration-2.0.xsd">]]></programlisting>
+    </para>
+    <para>
+      When using this alternative, no prefix is necessary for the Spring Integration elements. On the other hand, if
+      you want to define a generic Spring "bean" within the same configuration file, then a prefix would be required
+      for the bean element (&lt;beans:bean ... /&gt;). Since it is generally a good idea to modularize the
+      configuration files themselves based on responsibility and/or architectural layer, you may find it appropriate to
+      use the latter approach in the integration-focused configuration files, since generic beans are seldom necessary
+      within those same files. For purposes of this documentation, we will assume the "integration" namespace is
+      primary.
+    </para>
+    <para>
+      Many other namespaces are provided within the Spring Integration distribution. In fact, each adapter type (JMS,
+      File, etc.) that provides namespace support defines its elements within a separate schema. In order to use these
+      elements, simply add the necessary namespaces with an "xmlns" entry and the corresponding "schemaLocation" mapping.
+      For example, the following root element shows several of these namespace declarations:
+      <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns:integration="http://www.springframework.org/schema/integration"
+    xmlns:file="http://www.springframework.org/schema/integration/file"
+    xmlns:jms="http://www.springframework.org/schema/integration/jms"
+    xmlns:mail="http://www.springframework.org/schema/integration/mail"
+    xmlns:rmi="http://www.springframework.org/schema/integration/rmi"
+    xmlns:ws="http://www.springframework.org/schema/integration/ws"
+    xsi:schemaLocation="http://www.springframework.org/schema/beans
+            http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
+            http://www.springframework.org/schema/integration
+            http://www.springframework.org/schema/integration/spring-integration-2.0.xsd
+            http://www.springframework.org/schema/integration/file
+            http://www.springframework.org/schema/integration/file/spring-integration-file-2.0.xsd
+            http://www.springframework.org/schema/integration/jms
+            http://www.springframework.org/schema/integration/jms/spring-integration-jms-2.0.xsd
+            http://www.springframework.org/schema/integration/mail
+            http://www.springframework.org/schema/integration/mail/spring-integration-mail-2.0.xsd
+            http://www.springframework.org/schema/integration/rmi
+            http://www.springframework.org/schema/integration/rmi/spring-integration-rmi-2.0.xsd
+            http://www.springframework.org/schema/integration/ws
+            http://www.springframework.org/schema/integration/ws/spring-integration-ws-2.0.xsd">
+ ...
+</beans>]]></programlisting>
+      The reference manual provides specific examples of the various elements in their corresponding chapters. Here, the
+      main thing to recognize is the consistency of the naming for each namespace URI and schema location.
+    </para>
+  </section>
+
+  <section id="namespace-taskscheduler">
+    <title>Configuring the Task Scheduler</title>
+    <para>
+      In Spring Integration, the ApplicationContext plays the central role of a Message Bus, and there are only a
+      couple configuration options to be aware of. First, you may want to control the central TaskScheduler instance.
+      You can do so by providing a single bean with the name "taskScheduler". This is also defined as a constant:
+      <programlisting><![CDATA[ IntegrationContextUtils.TASK_SCHEDULER_BEAN_NAME ]]></programlisting>
+      By default Spring Integration uses the <classname>SimpleTaskScheduler</classname> implementation. That in turn
+      just delegates to any instance of Spring's <interfacename>TaskExecutor</interfacename> abstraction. Therefore,
+      it's rather trivial to supply your own configuration. The "taskScheduler" bean is then responsible for managing
+      all pollers. The TaskScheduler will startup automatically by default. If you provide your own instance of
+      SimpleTaskScheduler however, you can set the 'autoStartup' property to <emphasis>false</emphasis> instead.
+    </para>
+    <para>
+      When Polling Consumers provide an explicit task-executor reference in their configuration, the invocation of
+      the handler methods will happen within that executor's thread pool and not the main scheduler pool. However,
+      when no task-executor is provided for an endpoint's poller, it will be invoked by one of the main scheduler's
+      threads.
+      <note>
+         An endpoint is a <emphasis>Polling Consumer</emphasis> if its input channel is one of the queue-based
+         (i.e. pollable) channels. On the other hand, <emphasis>Event Driven Consumers</emphasis> are those whose
+         input channels have dispatchers instead of queues (i.e. they are subscribable). Such endpoints have no
+         poller configuration since their handlers will be invoked directly.
+      </note>
+      <para>
+        The next section will describe what happens if Exceptions occur within the asynchronous invocations.
+      </para>
+    </para>
+  </section>
+
+  <section id="namespace-errorhandler">
+    <title>Error Handling</title>
+    <para>
+      As described in the overview at the very beginning of this manual, one of the main motivations behind a
+      Message-oriented framework like Spring Integration is to promote loose-coupling between components. The
+      Message Channel plays an important role in that producers and consumers do not have to know about each
+      other. However, the advantages also have some drawbacks. Some things become more complicated in a very
+      loosely coupled environment, and one example is error handling.
+    </para>
+    <para>
+      When sending a Message to a channel, the component that ultimately handles that Message may or may not
+      be operating within the same thread as the sender. If using a simple default DirectChannel (with the
+      &lt;channel&gt; element that has no &lt;queue&gt; sub-element and no 'task-executor' attribute), the
+      Message-handling will occur in the same thread as the Message-sending. In that case, if an Exception
+      is thrown, it can be caught by the sender (or it may propagate past the sender if it is an uncaught
+      RuntimeException). So far, everything is fine. This is the same behavior as an Exception-throwing
+      operation in a normal call stack. However, when adding the asynchronous aspect, things become much
+      more complicated. For instance, if the 'channel' element <emphasis>does</emphasis> provide a 'queue'
+      sub-element, then the component that handles the Message <emphasis>will</emphasis> be operating in a
+      different thread than the sender. The sender may have dropped the Message into the channel and moved
+      on to other things. There is no way for the Exception to be thrown directly back to that sender using
+      standard Exception throwing techniques. Instead, to handle errors for asynchronous processes requires
+      an asynchronous error-handling mechanism as well.
+    </para>
+    <para>
+      Spring Integration supports error handling for its components by publishing errors to a Message Channel.
+      Specifically, the Exception will become the payload of a Spring Integration Message. That Message will
+      then be sent to a Message Channel that is resolved in a way that is similar to the 'replyChannel'
+      resolution. First, if the request Message being handled at the time the Exception occurred contains
+      an 'errorChannel' header (the header name is defined in the constant: MessageHeaders.ERROR_CHANNEL),
+      the ErrorMessage will be sent to that channel. Otherwise, the error handler will send to a "global"
+      channel whose bean name is "errorChannel" (this is also defined as a constant:
+      IntegrationContextUtils.ERROR_CHANNEL_BEAN_NAME).
+    </para>
+    <para>
+      Whenever relying on Spring Integration's XML namespace support, a default "errorChannel" bean will be
+      created behind the scenes. However, you can just as easily define your own if you want to control the
+      settings.
+      <programlisting language="xml"><![CDATA[ <channel id="errorChannel">
+     <queue capacity="500"/>
+ </channel>]]></programlisting>
+      <note>
+        The default "errorChannel" is a PublishSubscribeChannel.
+      </note>
+    </para>
+    <para>
+      The most important thing to understand here is that the messaging-based error handling will only apply
+      to Exceptions that are thrown by a Spring Integration task that is executing within a TaskExecutor.
+      This does <emphasis>not</emphasis> apply to Exceptions thrown by a handler that is operating within
+      the same thread as the sender (e.g. through a DirectChannel as described above).
+    </para>
+    <note>
+      When Exceptions occur in a scheduled poller task's execution, those exceptions will be wrapped in
+      <classname>ErrorMessages</classname> and sent to the 'errorChannel' as well.
+    </note>
+    <para>
+      To enable global error handling, simply register a handler on that channel. For example, you can configure
+      Spring Integration's <classname>ErrorMessageExceptionTypeRouter</classname> as the handler of an endpoint
+      that is subscribed to the 'errorChannel'. That router can then spread the error messages across multiple
+      channels based on <classname>Exception</classname> type.
+    </para>
+  </section>
+
+  <section id="annotations">
+    <title>Annotation Support</title>
+    <para>
+      In addition to the XML namespace support for configuring Message Endpoints, it is also possible to use
+      annotations. First, Spring Integration provides the class-level <interfacename>@MessageEndpoint</interfacename>
+      as a <emphasis>stereotype</emphasis> annotation meaning that is itself annotated with Spring's @Component
+      annotation and therefore is recognized automatically as a bean definition when using Spring component-scanning.
+    </para>
+    <para>
+      Even more importantly are the various Method-level annotations that indicate the annotated method is capable of
+      handling a message. The following example demonstrates both:
+      <programlisting language="java">@MessageEndpoint
+public class FooService {
+
+    @ServiceActivator
+    public void processMessage(Message message) {
+        ...
+    }
+}</programlisting>
+    </para>
+    <para>
+      Exactly what it means for the method to "handle" the Message depends on the particular annotation. The following
+      are available with Spring Integration, and the behavior of each is described in its own chapter or section within
+      this reference: @Transformer, @Router, @Splitter, @Aggregator, @ServiceActivator, and @ChannelAdapter.
+    </para>
+    <note>
+      The @MessageEndpoint is not required if using XML configuration in combination with annotations. If you want to
+      configure a POJO reference from the "ref" attribute of a &lt;service-activator/&gt; element, it is sufficient to
+      provide the method-level annotations. In that case, the annotation prevents ambiguity even when no "method"
+      attribute exists on the &lt;service-activator/&gt; element.
+    </note>
+    <para>
+      In most cases, the annotated handler method should not require the <classname>Message</classname> type as its
+      parameter. Instead, the method parameter type can match the message's payload type.
+      <programlisting language="java">public class FooService {
+
+    @ServiceActivator
+    public void bar(<emphasis>Foo foo</emphasis>) {
+        ...
+    }
+
+}</programlisting>
+    </para>
+    <para>
+      When the method parameter should be mapped from a value in the <classname>MessageHeaders</classname>, another
+      option is to use the parameter-level <interfacename>@Header</interfacename> annotation. In general, methods
+      annotated with the Spring Integration annotations can either accept the <classname>Message</classname> itself, the
+      message payload, or a header value (with @Header) as the parameter. In fact, the method can accept a combination,
+      such as:
+      <programlisting language="java">public class FooService {
+
+    @ServiceActivator
+    public void bar(String payload, @Header("x") int valueX, @Header("y") int valueY) {
+        ...
+    }
+
+}</programlisting>
+      There is also a @Headers annotation that provides all of the Message headers as a Map:
+      <programlisting language="java">public class FooService {
+
+    @ServiceActivator
+    public void bar(String payload, @Headers Map&lt;String, Object&gt; headerMap) {
+        ...
+    }
+
+}</programlisting>
+    </para>
+    <para>
+      For several of these annotations, when a Message-handling method returns a non-null value, the endpoint will
+      attempt to send a reply. This is consistent across both configuration options (namespace and annotations) in
+      that such an endpoint's output channel will be used if available, and the REPLY_CHANNEL message header value
+      will be used as a fallback.
+    </para>
+    <tip>
+      The combination of output channels on endpoints and the reply channel message header enables a pipeline approach
+      where multiple components have an output channel, and the final component simply allows the reply message to be
+      forwarded to the reply channel as specified in the original request message. In other words, the final component
+      depends on the information provided by the original sender and can dynamically support any number of clients as a
+      result. This is an example of <ulink url="http://eaipatterns.com/ReturnAddress.html">Return Address</ulink>.
+  </tip>
+    <para>
+      In addition to the examples shown here, these annotations also support inputChannel and outputChannel properties.
+      <programlisting language="java">public class FooService {
+
+    @ServiceActivator(inputChannel="input", outputChannel="output")
+    public void bar(String payload, @Headers Map&lt;String, Object&gt; headerMap) {
+        ...
+    }
+
+}</programlisting>
+      That provides a pure annotation-driven alternative to the XML configuration. However, it is generally recommended
+      to use XML for the endpoints, since it is easier to keep track of the overall configuration in a single, external
+      location (and besides the namespace-based XML configuration is not very verbose). If you do prefer to provide
+      channels with the annotations however, you just need to enable a SI Annotations BeanPostProcessor. The following element should
+      be added: <programlisting language="xml"><![CDATA[ <int:annotation-config/> ]]></programlisting>
+      <note>
+        When configuring the "inputChannel" and "outputChannel" with annotations, the "inputChannel"
+        <emphasis>must</emphasis> be a reference to a <interfacename>SubscribableChannel</interfacename> instance.
+        Otherwise, it would be necessary to also provide the full poller configuration via annotations, and those
+        settings (e.g. the trigger for scheduling the poller) should be externalized rather than hard-coded within
+        an annotation. If the input channel that you want to receive Messages from is indeed a
+        <interfacename>PollableChannel</interfacename> instance, one option to consider is the Messaging Bridge.
+        Spring Integration's "bridge" element can be used to connect a PollableChannel directly to a
+        SubscribableChannel. Then, the polling metadata is externally configured, but the annotation option is
+        still available. For more detail see <xref linkend="bridge"/>.
+      </note>
+    </para>
+  </section>
+
+  <section id="message-mapping-rules">
+    <title>Message Mapping rules and conventions</title>
+    <para>Spring Integration implements a flexible facility to map Messages to Methods and their arguments without
+    providing extra configuration by relying on some default rules as well as defining certain conventions.
+  </para>
+  <section id="sample-scenarios">
+      <title>Simple Scenarios</title>
+
+      <para>
+      <emphasis>Single un-annotated parameter (object or primitive) which is not a Map/Properties with non-void return type;</emphasis>
+      </para>
+      <programlisting language="java">public String foo(Object o);</programlisting>
+      <para>Details:</para>
+      <para>Input parameter is Message Payload. If parameter type is not compatible with Message Payload an
+      attempt will be made to convert it using Conversion Service provided by Spring 3.0. The return value
+      will be incorporated as a Payload of the returned Message</para>
+
+      <para>
+      <emphasis>Single un-annotated parameter (object or primitive) which is not a Map/Properties with Message return type;</emphasis>
+      </para>
+      <programlisting language="java">public Message  foo(Object o);</programlisting>
+      <para>Details:</para>
+      <para>Input parameter is Message Payload. If parameter type is not compatible with Message Payload an attempt
+      will be made to convert it using Conversion Service provided by Spring 3.0. The return value is a newly constructed
+      Message that will be sent to the next destination.</para>
+
+      <para>
+      <emphasis>Single parameter which is a Message or its subclass with arbitrary object/primitive return type;  </emphasis>
+      </para>
+      <programlisting language="java">public int foo(Message  msg);</programlisting>
+      <para>Details:</para>
+      <para>Input parameter is Message itself. The return value will become a payload of the
+      Message that will be sent to the next destination.</para>
+
+      <para>
+      <emphasis>Single parameter which is a Message or its subclass with Message or its subclass as a return type;</emphasis>
+      </para>
+      <programlisting language="java">public Message foo(Message msg);</programlisting>
+      <para>Details:</para>
+      <para>Input parameter is Message itself. The return value is a newly constructed Message that will be sent to the next destination.</para>
+
+      <para>
+      <emphasis>Single parameter which is of type Map or Properties with Message as a return type;</emphasis>
+      </para>
+      <programlisting language="java">public Message foo(Map m);</programlisting>
+      <para>Details:</para>
+      <para>This one is a bit interesting. Although at first it might seem like an easy mapping straight to Message Headers,
+      the preference is always given to a Message Payload. This means that if Message Payload is of type Map, this input argument will
+      represent Message Payload. However if Message Payload is not of type Map, then no conversion via Conversion Service will be
+      attempted and the input argument will be mapped to Message Headers.</para>
+
+      <para>
+      <emphasis>Two parameters where one of them is arbitrary non-Map/Properties type object/primitive and another is Map/Properties type object (regardless of the return)</emphasis>
+      </para>
+      <programlisting language="java">public Message foo(Map h, &lt;T&gt; t);</programlisting>
+      <para>Details:</para>
+      <para>This combination contains two input parameters where one of them is of type Map. Naturally the non-Map parameters (regardless of the order) will
+      be mapped to a Message Payload and the Map/Properties (regardless of the order) will be mapped to  Message Headers giving you a nice POJO way
+      of interacting with Message structure.</para>
+
+      <para>
+      <emphasis>No parameters (regardless of the return)</emphasis>
+      </para>
+      <programlisting language="java">public String foo();</programlisting>
+      <para>Details:</para>
+      <para>This Message Handler method will be invoked based on the Message sent to the input channel this handler is hooked up to,
+      however no Message data will be mapped, thus making Message act as event/trigger to invoke such handlerThe output will be
+      mapped according to the rules above</para>
+
+      <para>
+      <emphasis>No parameters, void return</emphasis>
+      </para>
+      <programlisting language="java">public void foo();</programlisting>
+      <para>Details:</para>
+      <para>Same as above, but no output </para>
+
+      <para>
+      <emphasis>Annotation based mappings</emphasis>
+      </para>
+      <para>Annotation based mapping is the safest and least ambiguous approach to map Messages to Methods. There wil be many pointers to annotation
+      based mapping throughout this manual, however here are couple of examples:
+      </para>
+
+      <programlisting language="java">public String foo(@Payload String s,  @Header("foo") String b) </programlisting>
+      <para>Very simple and explicite way of mapping Messages to method. As you'll see later on without annotation this signature
+      would result in the ambiguous condition, however by explicitly mapping first argument to a Message Payload and second argument to
+      a value of the 'foo' Message Header we have avoided ambiguity.</para>
+
+      <programlisting language="java">public String foo(@Payload String s,  @RequestParam("foo") String b) </programlisting>
+      <para>Looks almost identical to the previous example, however @RequestMapping or any other non-SI mapping annotation
+      is irrelevant  and therefore will be ignored leaving the second parameter unmapped. And although the second parameters could
+      easily be mapped to a Payload, there can only be one Payload, therefore this method becomes ambiguous. </para>
+
+      <programlisting language="java">public String foo(String s,  @Header("foo") String b) </programlisting>
+      <para>The same as above. The only difference is that the first argument will be mapped to Message Payload implicitly.</para>
+
+      <programlisting language="java">public String foo(@Headers Map m,  @Header("foo")Map f, @Header("bar") String bar)</programlisting>
+      <para>Yet another signature that would definitely be treated as ambiguous because it has more then 2 arguments,
+      plus two of them are Maps, however with annotation-based mapping ambiguity is easily avoided. In this example
+      the first argument is mapped to all the Message Headers, while second and third argument map to the values of Message Headers 'foo' and 'bar'.</para>
+  </section>
+
+  <section id="complex-scenarios">
+      <title>Complex Scenarios</title>
+
+      <para><emphasis>Multiple parameters:</emphasis> </para>
+      <para>Multiple parameters could create a lot of ambiguity with regards to determining the appropriate mappings. The general advice is to annotate your method parameters with @Payload and/or @Header/@Headers
+Below are some of the examples of ambiguous conditions which result in exception being raised.
+      </para>
+      <programlisting language="java">public String foo(String s, int i)</programlisting>
+      <para> - the two parameters are equal in weight, therefore no way to determine which one is a payload and what to do with another.</para>
+
+      <programlisting language="java">public String foo(String s, Map m, String b) </programlisting>
+      <para> - almost the same as above. Although Map could be easily mapped to Message Headers, there is no way to determine what to do with two Strings.</para>
+
+      <programlisting language="java">public String foo(Map m, Map f)</programlisting>
+      <para> - although one might argue that one Map could be mapped to Message Payload and another one to Message Headers, it would be unreasonable to rely on the order (e.g., first is Payload, second Headers)</para>
+
+      <para>
+        <tip>Basically any method signature with more then one method argument which is not (Map, &lt;T&gt;) and those parameters are not annotated will result in the ambiguous condition thus triggering an exception.</tip>
+      </para>
+      <para>
+      <emphasis>Multiple methods:</emphasis>
+      </para>
+      <para>Message Handlers with multiple methods are mapped based on the same rules that are described above, however some scenarios might still look confusing.</para>
+
+      <para><emphasis>Multiple methods (same or different name) with legal (mappable) signatures:</emphasis> </para>
+
+      <programlisting language="java">public class Foo{
+  public String foo(String str, Map m);
+
+  public String foo(Map m)
+}</programlisting>
+      <para>As you can see, the Message could be mapped to either method. The first method would be invoked where Message Payload
+      could be mapped to 'str'  and Message Headers could be mapped to 'm'. The second method could easily also be a candidate where
+      only Message Headers are mapped to 'm'. To make meters worse both methods have the same name which at first might look very
+      ambiguous considering the following configuration:</para>
+      <programlisting language="xml"><![CDATA[<si:service-activator input-channel="input" output-channel="output" method="foo">
+  <bean class="org.bar.Foo"/>
+</si:service-activator>]]></programlisting>
+      <para>At this point it would be important to understand Spring Integration mapping Conventions where at the very core,
+      mappings are based on Payload first and everything else next. In other words the method whose argument could be mapped
+      to a Payload will take precedence over all other methods.</para>
+
+      <para>On the other hand let's look at slightly different example:</para>
+      <programlisting language="java">public class Foo{
+  public String foo(String str, Map m);
+
+  public String foo(String str)
+}</programlisting>
+
+      <para>If you look at it you can probably see a truly an ambiguous condition. In this example since both methods have signatures that
+      could be mapped to a Message Payload. They also have the same name. Such handler will trigger an exception.
+However if method names were different you could influence the mapping with 'method' attribute (see below):</para>
+      <programlisting language="java">public class Foo{
+  public String foo(String str, Map m);
+
+  public String bar(String str)
+}</programlisting>
+      <programlisting language="xml"><![CDATA[<si:service-activator input-channel="input" output-channel="output" method="bar">
+  <bean class="org.bar.Foo"/>
+</si:service-activator>]]></programlisting>
+
+      <para>Now there is no ambiguity since the configuration explicitly maps to 'bar' method which has no name conflicts.</para>
+  </section>
+  </section>
+
+</appendix>

docs/src/reference/docbook/delayer.xml

@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="delayer"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Delayer</title>
+
+  <section id="delayer-introduction">
+    <title>Introduction</title>
+    <para>
+      A Delayer is a simple endpoint that allows a Message flow to be delayed by a certain interval. When
+      a Message is delayed, the original sender will not block. Instead, the delayed Messages will be
+      scheduled with an instance of <interfacename>java.util.concurrent.ScheduledExecutorService</interfacename>
+      to be sent to the output channel after the delay has passed. This approach is scalable even for
+      rather long delays, since it does not result in a large number of blocked sender Threads. On the
+      contrary, in the typical case a thread pool will be used for the actual execution of releasing the
+      Messages. Below you will find several examples of configuring a Delayer.
+    </para>
+  </section>
+
+  <section id="delayer-namespace">
+    <title>The &lt;delayer&gt; Element</title>
+    <para>
+      The &lt;delayer&gt; element is used to delay the Message flow between two Message Channels.
+      As with the other endpoints, you can provide the "input-channel" and "output-channel" attributes,
+      but the delayer also requires at least the 'default-delay' attribute with the number of milliseconds
+      that each Message should be delayed.
+      <programlisting language="xml"><![CDATA[ <delayer input-channel="input" default-delay="3000" output-channel="output"/>]]></programlisting>
+      If you need per-Message determination of the delay, then you can also provide the name of a header
+      within the 'delay-header-name' attribute:
+      <programlisting language="xml"><![CDATA[ <delayer input-channel="input" output-channel="output"
+          default-delay="3000" delay-header-name="delay"/>]]></programlisting>
+      In the example above the 3 second delay would only apply in the case that the header value is
+      not present for a given inbound Message. If you only want to apply a delay to Messages that have
+      an explicit header value, then you can set the 'default-delay' to 0. For any Message that has a
+      delay of 0 (or less), the Message will be sent directly. In fact, if there is not a positive delay
+      value for a Message, it will be sent to the output channel on the calling Thread.
+      <tip>
+        The delay handler actually supports header values that represent an interval in milliseconds (any
+        Object whose <methodname>toString()</methodname> method produces a value that can be parsed into a
+        Long) as well as <classname>java.util.Date</classname> instances representing an absolute time.
+        In the former case, the milliseconds will be counted from the current time (e.g. a value of 5000
+        would delay the Message for at least 5 seconds from the time it is received by the Delayer). In
+        the latter case, with an actual Date instance, the Message will not be released until that Date
+        occurs. In either case, a value that equates to a non-positive delay, or a Date in the past, will
+        not result in any delay. Instead, it will be sent directly to the output channel in the original
+        sender's Thread.
+      </tip>
+    </para>
+    <para>
+      The delayer delegates to an instance of Spring's <interfacename>TaskScheduler</interfacename> abstraction.
+      The default scheduler is a <classname>ThreadPoolTaskScheduler</classname> instance with a pool size of 1.
+      If you want to delegate to a different scheduler, you can provide a reference through the delayer element's
+      'scheduler' attribute:
+      <programlisting language="xml"><![CDATA[ <delayer input-channel="input" output-channel="output"
+          default-delay="0" delay-header-name="delay"
+          scheduler="exampleTaskScheduler"/>
+
+ <task:scheduler id="exampleTaskScheduler" pool-size="3"/>]]></programlisting>
+    </para>
+  </section>
+
+</chapter>

docs/src/reference/docbook/endpoint.xml

@@ -0,0 +1,349 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="endpoint"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Message Endpoints</title>
+  <para>
+    The first part of this chapter covers some background theory and reveals quite a bit about the underlying API
+    that drives Spring Integration's various messaging components. This information can be helpful if you want to
+    really understand what's going on behind the scenes. However, if you want to get up and running with the
+    simplified namespace-based configuration of the various elements, feel free to skip ahead to
+    <xref linkend="endpoint-namespace"/> for now.
+  </para>
+  <para>
+    As mentioned in the overview, Message Endpoints are responsible for connecting the various messaging components to
+    channels. Over the next several chapters, you will see a number of different components that consume Messages. Some
+    of these are also capable of sending reply Messages. Sending Messages is quite straightforward. As shown above in
+    <xref linkend="channel"/>, it's easy to <emphasis>send</emphasis> a Message to a Message Channel. However,
+    receiving is a bit more complicated. The main reason is that there are two types of consumers:
+    <ulink url="http://www.eaipatterns.com/PollingConsumer.html">Polling Consumers</ulink> and
+    <ulink url="http://www.eaipatterns.com/EventDrivenConsumer.html">Event Driven Consumers</ulink>.
+  </para>
+  <para>
+    Of the two, Event Driven Consumers are much simpler. Without any need to manage and schedule a separate poller
+    thread, they are essentially just listeners with a callback method. When connecting to one of Spring Integration's
+    subscribable Message Channels, this simple option works great. However, when connecting to a buffering, pollable
+    Message Channel, some component has to schedule and manage the polling thread(s). Spring Integration provides
+    two different endpoint implementations to accommodate these two types of consumers. Therefore, the consumers
+    themselves can simply implement the callback interface. When polling is required, the endpoint acts as a
+    "container" for the consumer instance. The benefit is similar to that of using a container for hosting
+    Message Driven Beans, but since these consumers are simply Spring-managed Objects running within an 
+    ApplicationContext, it more closely resembles Spring's own MessageListener containers.
+  </para>
+
+  <section id="endpoint-handler">
+    <title>Message Handler</title>
+    <para>
+      Spring Integration's <interfacename>MessageHandler</interfacename> interface is implemented by many of the
+      components within the framework. In other words, this is not part of the public API, and a developer would not
+      typically implement <interfacename>MessageHandler</interfacename> directly. Nevertheless, it is used by a Message
+      Consumer for actually handling the consumed Messages, and so being aware of this strategy interface does help in
+      terms of understanding the overall role of a consumer. The interface is defined as follows:
+      <programlisting language="java">public interface MessageHandler {
+
+    void handleMessage(Message&lt;?&gt; message);
+
+}</programlisting>
+      Despite its simplicity, this provides the foundation for most of the components that will be covered in the
+      following chapters (Routers, Transformers, Splitters, Aggregators, Service Activators, etc). Those components
+      each perform very different functionality with the Messages they handle, but the requirements for actually
+      receiving a Message are the same, and the choice between polling and event-driven behavior is also the same.
+      Spring Integration provides two endpoint implementations that "host" these callback-based handlers and allow
+      them to be connected to Message Channels.
+    </para>
+  </section>
+
+  <section id="endpoint-eventdrivenconsumer">
+    <title>Event Driven Consumer</title>
+    <para>
+      Because it is the simpler of the two, we will cover the Event Driven Consumer endpoint first. You may recall that
+      the <interfacename>SubscribableChannel</interfacename> interface provides a <methodname>subscribe()</methodname>
+      method and that the method accepts a <interfacename>MessageHandler</interfacename> parameter (as shown in
+      <xref linkend="channel-interfaces-subscribablechannel"/>):
+      <programlisting language="java">
+subscribableChannel.subscribe(messageHandler);
+</programlisting>
+      Since a handler that is subscribed to a channel does not have to actively poll that channel, this is an
+      Event Driven Consumer, and the implementation provided by Spring Integration accepts a
+      a <interfacename>SubscribableChannel</interfacename> and a <interfacename>MessageHandler</interfacename>:
+      <programlisting language="java">SubscribableChannel channel = (SubscribableChannel) context.getBean("subscribableChannel");
+
+EventDrivenConsumer consumer = new EventDrivenConsumer(channel, exampleHandler);</programlisting>
+    </para>
+  </section>
+
+  <section id="endpoint-pollingconsumer">
+    <title>Polling Consumer</title>
+    <para>
+      Spring Integration also provides a <classname>PollingConsumer</classname>, and it can be instantiated in
+      the same way except that the channel must implement <interfacename>PollableChannel</interfacename>:
+      <programlisting language="java">PollableChannel channel = (PollableChannel) context.getBean("pollableChannel");
+
+PollingConsumer consumer = new PollingConsumer(channel, exampleHandler);</programlisting>
+    </para>
+    <para>
+      There are many other configuration options for the Polling Consumer. For example, the trigger is a required property:
+      <programlisting language="java">
+PollingConsumer consumer = new PollingConsumer(channel, handler);
+
+consumer.setTrigger(new IntervalTrigger(30, TimeUnit.SECONDS));</programlisting>
+      Spring Integration currently provides two implementations of the <interfacename>Trigger</interfacename>
+      interface: <classname>IntervalTrigger</classname> and <classname>CronTrigger</classname>. The
+      <classname>IntervalTrigger</classname> is typically defined with a simple interval (in milliseconds), but
+      also supports an 'initialDelay' property and a boolean 'fixedRate' property (the default is false, i.e.
+      fixed delay):
+      <programlisting language="java">IntervalTrigger trigger = new IntervalTrigger(1000);
+trigger.setInitialDelay(5000);
+trigger.setFixedRate(true);</programlisting>
+      The <classname>CronTrigger</classname> simply requires a valid cron expression (see the Javadoc for details):
+      <programlisting language="java">CronTrigger trigger = new CronTrigger("*/10 * * * * MON-FRI");</programlisting>
+    </para>
+    <para>
+      In addition to the trigger, several other polling-related configuration properties may be specified:
+      <programlisting language="java">
+PollingConsumer consumer = new PollingConsumer(channel, handler);
+
+consumer.setMaxMessagesPerPoll(10);
+
+consumer.setReceiveTimeout(5000);</programlisting>
+    </para>
+    <para>
+      The 'maxMessagesPerPoll' property specifies the maximum number of messages to receive within a given poll
+      operation. This means that the poller will continue calling receive() <emphasis>without waiting</emphasis>
+      until either <code>null</code> is returned or that max is reached. For example, if a poller has a 10 second
+      interval trigger and a 'maxMessagesPerPoll' setting of 25, and it is polling a channel that has 100 messages
+      in its queue, all 100 messages can be retrieved within 40 seconds. It grabs 25, waits 10 seconds, grabs the
+      next 25, and so on.
+    </para>
+    <para>
+      The 'receiveTimeout' property specifies the amount of time the poller should wait if no messages are
+      available when it invokes the receive operation. For example, consider two options that seem similar on
+      the surface but are actually quite different: the first has an interval trigger of 5 seconds and a receive
+      timeout of 50 milliseconds while the second has an interval trigger of 50 milliseconds and a receive timeout
+      of 5 seconds. The first one may receive a message up to 4950 milliseconds later than it arrived on the channel
+      (if that message arrived immediately after one of its poll calls returned). On the other hand, the second
+      configuration will never miss a message by more than 50 milliseconds. The difference is that the second
+      option requires a thread to wait, but as a result it is able to respond much more quickly to arriving messages.
+      This technique, known as "long polling", can be used to emulate event-driven behavior on a polled source.
+    </para>
+    <para>
+      A Polling Consumer may also delegate to a Spring <interfacename>TaskExecutor</interfacename>, and it can
+      be configured to participate in Spring-managed transactions. The following example shows the configuration of both:
+      <programlisting language="java">
+PollingConsumer consumer = new PollingConsumer(channel, handler);
+
+TaskExecutor taskExecutor = (TaskExecutor) context.getBean("exampleExecutor");
+consumer.setTaskExecutor(taskExecutor);
+
+PlatformTransactionManager txManager = (PlatformTransationManager) context.getBean("exampleTxManager");
+consumer.setTransactionManager(txManager);</programlisting>
+      The examples above show dependency lookups, but keep in mind that these consumers will most often be configured
+      as Spring <emphasis>bean definitions</emphasis>. In fact, Spring Integration also provides a
+      <interfacename>FactoryBean</interfacename> that creates the appropriate consumer type based on the type of
+      channel, and there is full XML namespace support to even further hide those details. The namespace-based
+      configuration will be featured as each component type is introduced.
+      <note>
+		Many of the <interfacename>MessageHandler</interfacename> implementations are also capable of generating reply
+        Messages. As mentioned above, sending Messages is trivial when compared to the Message reception. Nevertheless,
+        <emphasis>when</emphasis> and <emphasis>how many</emphasis> reply Messages are sent depends on the handler
+        type. For example, an <emphasis>Aggregator</emphasis> waits for a number of Messages to arrive and is often
+        configured as a downstream consumer for a <emphasis>Splitter</emphasis> which may generate multiple
+        replies for each Message it handles. When using the namespace configuration, you do not strictly need to know
+        all of the details, but it still might be worth knowing that several of these components share a common base
+        class, the <classname>AbstractReplyProducingMessageHandler</classname>, and it provides a
+        <methodname>setOutputChannel(..)</methodname> method.
+      </note>
+    </para>
+  </section>
+
+  <section id="endpoint-namespace">
+    <title>Namespace Support</title>
+    <para>
+      Throughout the reference manual, you will see specific configuration examples for endpoint elements, such as
+      router, transformer, service-activator, and so on. Most of these will support an "input-channel" attribute and
+      many will support an "output-channel" attribute. After being parsed, these endpoint elements produce an instance
+      of either the <classname>PollingConsumer</classname> or the
+      <classname>EventDrivenConsumer</classname> depending on the type of the "input-channel" that is
+      referenced: <interfacename>PollableChannel</interfacename> or <interfacename>SubscribableChannel</interfacename>
+      respectively. When the channel is pollable, then the polling behavior is determined based on the endpoint
+      element's "poller" sub-element and its attributes. For example, a simple interval-based poller with a 1-second interval would be
+      configured like this: <programlisting language="xml"><![CDATA[ <transformer input-channel="pollable"
+              ref="transformer"
+              output-channel="output">
+     <poller fixed-rate="1000"/>
+</transformer>]]></programlisting>
+	  As an alternative to 'fixed-rate' you cna also use 'fixed-delay' attribute.
+	  </para>
+	  <para>
+      For a poller based on a Cron expression, use the "cron" attribute instead:
+      <programlisting language="xml"><![CDATA[ <transformer input-channel="pollable"
+              ref="transformer"
+              output-channel="output">
+     <poller cron="*/10 * * * * MON-FRI"/>
+ </transformer>]]></programlisting>
+    </para>
+    <para>
+      If the input channel is a <interfacename>PollableChannel</interfacename>, then the poller configuration is
+      required. Specifically, as mentioned above, the 'trigger' is a required property of the PollingConsumer class.
+      Therefore, if you omit the "poller" sub-element for a Polling Consumer endpoint's configuration, an Exception
+      may be thrown. The exception will also be thrown if you attempt to configure a poller on the element that is 
+      connected to a non-pollable channel.
+     </para>
+     <para> 
+      It is also possible to create top-level pollers in which case only a "ref" is required:
+      <programlisting language="xml"><![CDATA[ <poller id="weekdayPoller" cron="*/10 * * * * MON-FRI"/>
+   
+ <transformer input-channel="pollable"
+              ref="transformer"
+              output-channel="output">
+    <poller ref="weekdayPoller"/>
+ </transformer>]]></programlisting>
+      In fact, to simplify the configuration, you can define a global default poller. A single top-level poller within
+      an ApplicationContext may have the <code>default</code> attribute with a value of "true". In that case, any
+      endpoint with a PollableChannel for its input-channel that is defined within the same ApplicationContext and has
+      no explicitly configured 'poller' sub-element will use that default.
+      <programlisting language="xml"><![CDATA[ <poller id="defaultPoller" default="true" max-messages-per-poll="5" fixed-rate="3000"/>
+    
+ <!-- No <poller/> sub-element is necessary since there is a default -->
+ <transformer input-channel="pollable"
+              ref="transformer"
+              output-channel="output"/>]]></programlisting>
+    </para>
+    <para>
+      Spring Integration also provides transaction support for the pollers so that each receive-and-forward
+      operation can be performed as an atomic unit-of-work. To configure transactions for a poller, simply add the
+      &lt;transactional/&gt; sub-element. The attributes for this element should be familiar to anyone who has
+      experience with Spring's Transaction management:
+      <programlisting language="xml"><![CDATA[<poller fixed-delay="1000">
+    <transactional transaction-manager="txManager"
+                   propagation="REQUIRED"
+                   isolation="REPEATABLE_READ"
+                   timeout="10000"
+                   read-only="false"/>
+</poller>]]></programlisting> 
+
+	</para>
+	<para>
+	<emphasis>AOP Advice chains</emphasis>
+	</para>
+	<para>
+	Since Spring transaction support depends on the Proxy mechanism  with <classname>TransactionInterceptor</classname> (AOP Advice) handling transactional 
+	behavior of the message flow initiated by the poler, some times there is a need to provide extra Advice(s) to handle other 
+	cross cutting behavior associated with the poller. For that poller defines an 'advice-chain' element allowing you to add 
+	more advices - class that  implements <classname>MethodInterceptor</classname> interface.. 
+	<programlisting language="xml"><![CDATA[<service-activator id="advicedSa" input-channel="goodInputWithAdvice" ref="testBean"
+		method="good" output-channel="output">
+	<poller max-messages-per-poll="1" fixed-rate="10000">
+		<transactional transaction-manager="txManager" />
+		 <advice-chain>
+			<ref bean="adviceA" />
+			<beans:bean class="org.bar.SampleAdvice"/>
+		</advice-chain>
+	</poller>
+</service-activator>]]></programlisting> 
+For more information on how to implement MethodInterceptor please refer to AOP sections of Spring 
+reference manual (section 7 and 8). Advice chain can also be applied on the poller that does not have 
+any transaction configuration essentially allowing you to enhance the behavior of the message flow initiated by the poller.
+    </para>
+    <para>
+      The polling threads may be executed by any instance of Spring's <interfacename>TaskExecutor</interfacename>
+      abstraction. This enables concurrency for an endpoint or group of endpoints. As of Spring 3.0, there is a "task"
+      namespace in the core Spring Framework, and its &lt;executor/&gt; element supports the creation of a simple thread
+      pool executor. That element accepts attributes for common concurrency settings such as pool-size and queue-capacity.
+      Configuring a thread-pooling executor can make a substantial difference in how the endpoint performs under load. These
+      settings are available per-endpoint since the performance of an endpoint is one of the major factors to consider
+      (the other major factor being the expected volume on the channel to which the endpoint subscribes). To enable
+      concurrency for a polling endpoint that is configured with the XML namespace support, provide the 'task-executor'
+      reference on its &lt;poller/&gt; element and then provide one or more of the properties shown below:
+      <programlisting language="xml"><![CDATA[ <poller task-executor="pool" fixed-rate="1000"/>
+    
+ <task:executor id="pool"
+                pool-size="5-25"
+                queue-capacity="20"
+                keep-alive="120"/>]]></programlisting>
+      If no 'task-executor' is provided, the consumer's handler will be invoked in the caller's thread. Note that the
+      "caller" is usually the default <interfacename>TaskScheduler</interfacename>
+      (see <xref linkend="namespace-taskscheduler"/>). Also, keep in mind that the 'task-executor' attribute can
+      provide a reference to any implementation of Spring's <interfacename>TaskExecutor</interfacename> interface by
+      specifying the bean name. The "executor" element above is simply provided for convenience.
+    </para>
+     <para>
+    	As mentioned in the background section for Polling Consumers above, you can also configure a Polling Consumer
+        in such a way as to emulate event-driven behavior. With a long receive-timeout and a short interval-trigger,
+        you can ensure a very timely reaction to arriving messages even on a polled message source. Note that this
+        will only apply to sources that have a blocking wait call with a timeout. For example, the File poller does
+        not block, each receive() call returns immediately and either contains new files or not. Therefore, even if
+        a poller contains a long receive-timeout, that value would never be usable in such a scenario. On the other
+        hand when using Spring Integration's own queue-based channels, the timeout value does have a chance to
+        participate. The following example demonstrates how a Polling Consumer will receive Messages nearly
+        instantaneously.
+      <programlisting language="xml"><![CDATA[ <service-activator input-channel="someQueueChannel"
+        output-channel="output">  
+     <poller receive-timeout="30000" fixed-rate="10"/>
+        
+ </service-activator>]]></programlisting>
+      Using this approach does not carry much overhead since internally it is nothing more then a timed-wait thread
+      which does not require nearly as much CPU resource usage as a thrashing, infinite while loop for example.
+    </para>
+  </section>
+  
+  <section id="payload-type-conversion">
+    <title>Payload Type Conversion</title>
+    <para>
+      Throughout the reference manual, you will also see specific configuration and implementation examples of various endpoints 
+      which can accept a Message or any arbitrary Object as an input parameter. In the case of an Object, such parameter will 
+      be mapped to a Message payload or part of the payload or header (when using Spring Expression Language). However there 
+      are times when the type of input parameter of the endpoint method does not match the type of the payload or its part. 
+      In this scenario we need to perform type conversion. Spring Integration provides a convenient way for registering type 
+      converters (using Spring 3.x ConversionService) within its own instance of the conversion service bean named <emphasis>integrationConversionService</emphasis>
+      which is automatically created as soon as the first converter is defined.
+
+      To register such converter all you need is to implement <interfacename> org.springframework.core.convert.converter.Converter</interfacename> and register via 
+      cionvinient namespace support:
+      <programlisting language="xml"><![CDATA[ <int:converter ref="sampleConverter"/>
+
+	<bean id="sampleConverter" class="foo.bar.TestConverter"/>]]></programlisting>
+      
+      or
+      <programlisting language="xml"><![CDATA[ <int:converter>
+		<bean class="org.springframework.integration.config.xml.ConverterParserTests$TestConverter3"/>
+	</int:converter>]]></programlisting>
+     </para>
+  </section>
+  <section id="async-polling">
+    <title>Asynchronous polling</title>
+     <para>
+     If you want the polling to be asynchronous, Poller can optionaly specify 'task-executor' attribute 
+     pointing to an existing instance of <classname>TaskExecutor</classname> bean 
+     (Spring 3.0 provides a convinient namespaces configuration via the <code>task</code> namespace). However, there are certain things 
+     you must understand when configuring Poller with TaskExecutor. 
+     </para>
+     <para>
+     The problem is that there are two configurations in place. The <emphasis>Poller</emphasis> and the <emphasis>TaskExecutor</emphasis> 
+     and they both have to be in tune with each other otherwise you might end up creating an artificial memory leak. 
+     </para>
+     <para>
+     Let's look at the following configuration provided by one of the users on the Spring's 
+     forums (http://forum.springsource.org/showthread.php?t=94519):
+
+      <programlisting language="xml"><![CDATA[<int:service-activator input-channel="publishChannel" ref="myService">
+		<int:poller receive-timeout="5000" task-executor="taskExecutor" fixed-rate="50"/>
+</si:service-activator>
+	
+<task:executor id="taskExecutor" pool-size="20" queue-capacity="20"/>]]></programlisting>
+      
+	The above configuration demonstrates one of those out of tune configurations.
+     </para>
+     <para>
+     The poller keeps scheduling new tasks even though all the threads are blocked waiting for either a new message to arrive, 
+     or the timeout to expire. Given that there are 20 threads executing tasks with a 5 second timeout, they will be executed 
+     at a rate of 4 per second (5000/20 = 250ms). But, new tasks are being scheduled at a rate of 20 per second, so the internal 
+     queue in the task executor will grow at a rate of 16 per second (while the process is idle), so we essentially have a memory leak.
+     </para>
+     <para>
+     One of the ways to handle this is to set <code>queue-capacity</code> attribute of Task Executor to 0. You can also manage it by specifying what to do 
+     with messages that can not be queued up by setting <code>rejection-policy</code> attribute of Task Executor (e.g., DISCARD). In other 
+     words there are certain details you must understand with regard to configuring the TaskExecutor. Please refer 
+     to - <emphasis>Section 25 - Task Execution and Scheduling</emphasis> of Spring reference manual.
+     </para>
+  </section>
+</chapter>

docs/src/reference/docbook/event.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="applicationevent"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Spring ApplicationEvent Support</title>
+
+  <para>
+    Spring Integration provides support for inbound and outbound <classname>ApplicationEvents</classname>
+    as defined by the underlying Spring Framework. For more information about the events and listeners,
+    refer to the  <ulink url="http://static.springsource.org/spring/docs/2.5.x/reference/beans.html#context-functionality-events">Spring Reference Manual</ulink>.
+  </para>
+
+  <section id="applicationevent-inbound">
+    <title>Receiving Spring ApplicationEvents</title>
+  <para>
+    To receive events and send them to a channel, simply define an instance of Spring Integration's
+    <classname>ApplicationEventListeningChannelAdapter</classname>. This class is an implementation of
+    Spring's <interfacename>ApplicationListener</interfacename> interface. By default it will pass all
+    received events as Spring Integration Messages. To limit based on the type of event, configure the
+    list of event types that you want to receive with the 'eventTypes' property.
+  </para>
+  <para>
+  For convenience namespace support was provided to configure <classname>ApplicationEventListeningChannelAdapter</classname> via <emphasis>inbound-channel-adapter</emphasis>
+    <programlisting language="xml"><![CDATA[<int-event:inbound-channel-adapter channel="input" event-types="foo.bar.FooApplicationEvent, foo.bar.BarApplicationEvent"/>
+
+<int:publish-subscribe-channel id="sampleEventChannel"/>]]></programlisting>
+In the above sample, all Application Context events that are of type specified by the 'event-types' (optional) attribute will be
+delivered as Spring Integration Messages to 'sampleEventChannel'.
+  </para>
+
+
+  </section>
+
+  <section id="applicationevent-outbound">
+  <title>Sending Spring ApplicationEvents</title>
+  <para>
+    To send Spring <classname>ApplicationEvents</classname>, create an instance of the
+    <classname>ApplicationEventPublishingMessageHandler</classname> and register it within an endpoint.
+    This implementation of the <interfacename>MessageHandler</interfacename> interface also implements
+    Spring's <interfacename>ApplicationEventPublisherAware</interfacename> interface and thus acts as a
+    bridge between Spring Integration Messages and <classname>ApplicationEvents</classname>.
+  </para>
+  <para>
+  For convenience namespace support was provided to configure <classname>ApplicationEventPublishingMessageHandler</classname> via <emphasis>outbound-channel-adapter</emphasis> element
+    <programlisting language="xml"><![CDATA[<int:channel id="input"/>
+
+<int-event:outbound-channel-adapter channel="input"/>]]></programlisting>
+If you are using PollableChannel (e.g., Queue), you can also provide <emphasis>poller</emphasis> as sub-element of <emphasis>outbound-channel-adapter</emphasis>, optionally providing <emphasis>task-executor</emphasis>
+<programlisting language="xml"><![CDATA[<int:channel id="input">
+  <int:queue/>
+</int:channel>
+
+<int-event:outbound-channel-adapter channel="input">
+  <int:poller max-messages-per-poll="1" task-executor="executor" fixed-rate="100"/>
+</int-event:outbound-channel-adapter>
+
+<task:executor id="executor" pool-size="5"/>]]></programlisting>
+
+In the above sample, all messages sent to an 'input' channel will be published as ApplicationEvents to Spring Application sContext
+  </para>
+  </section>
+
+</chapter>

docs/src/reference/docbook/file.xml

@@ -0,0 +1,228 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="files"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>File Support</title>
+
+  <section id="file-intro">
+    <title>Introduction</title>
+    <para>
+      Spring Integration's File support extends the Spring Integration Core with
+      a dedicated vocabulary to deal with reading, writing, and transforming files.
+      It provides a namespace that enables elements defining Channel Adapters dedicated
+      to files and support for Transformers that can read file contents into strings or
+      byte arrays.
+      </para>
+    <para>
+      This section will explain the workings of <classname>FileReadingMessageSource</classname>
+      and <classname>FileWritingMessageHandler</classname> and how to configure them as
+      <emphasis>beans</emphasis>. Also the support for dealing with files through file specific
+      implementations of <interfacename>Transformer</interfacename> will be discussed. Finally the
+      file specific namespace will be explained.
+    </para>
+  </section>
+
+  <section id="file-reading">
+    <title>Reading Files</title>
+    <para>
+      A <classname>FileReadingMessageSource</classname> can be used to consume files from the filesystem.
+      This is an implementation of <interfacename>MessageSource</interfacename> that creates messages from
+      a file system directory. <programlisting language="xml"><![CDATA[<bean id="pollableFileSource"
+      class="org.springframework.integration.file.FileReadingMessageSource"
+        p:inputDirectory="file:${input.directory}"/>]]></programlisting>
+    </para>
+    <para>
+      To prevent creating messages for certain files, you may supply a
+      <interfacename>FileListFilter</interfacename>. By default, an
+      <classname>AcceptOnceFileListFilter</classname> is used. This filter
+      ensures files are picked up only once from the directory.
+      <programlisting language="xml"><![CDATA[<bean id="pollableFileSource"
+      class="org.springframework.integration.file.FileReadingMessageSource"
+        p:inputDirectory="file:${input.directory}"
+        p:filter-ref="customFilterBean"/>]]></programlisting>
+    </para>
+    <para>
+      A common problem with reading files is that a file may be detected before
+      it is ready. The default <classname>AcceptOnceFileListFilter</classname>
+      does not prevent this. In most cases, this can be prevented if the
+      file-writing process renames each file as soon as it is ready for
+      reading. A pattern-matching filter that accepts only files that are
+      ready (e.g. based on a known suffix), composed with the default
+      <classname>AcceptOnceFileListFilter</classname> allows for this.
+      The <classname>CompositeFileListFilter</classname> enables the
+      composition.
+      <programlisting language="xml"><![CDATA[<bean id="pollableFileSource"
+      class="org.springframework.integration.file.FileReadingMessageSource"
+        p:inputDirectory="file:${input.directory}"
+        p:filter-ref="compositeFilter"/>
+<bean id="compositeFilter" class="org.springframework.integration.file.filters.CompositeFileListFilter">
+    <constructor-arg>
+        <list>
+            <bean class="org.springframework.integration.file.filters.AcceptOnceFileListFilter" />
+            <bean class="org.springframework.integration.file.filters.PatternMatchingFileListFilter">
+                <constructor-arg value="^test.*$"/>
+            </bean>
+        </list>
+    </constructor-arg>
+</bean>]]></programlisting>
+    </para>
+    <para>
+      The configuration can be simplified using the file specific namespace. To do
+      this use the following template.
+      <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:integration="http://www.springframework.org/schema/integration"
+  xmlns:file="http://www.springframework.org/schema/integration/file"
+  xsi:schemaLocation="http://www.springframework.org/schema/beans
+      http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
+      http://www.springframework.org/schema/integration
+      http://www.springframework.org/schema/integration/spring-integration-2.0.xsd
+      http://www.springframework.org/schema/integration/file
+      http://www.springframework.org/schema/integration/file/spring-integration-file-2.0.xsd">
+</beans>]]></programlisting>
+      Within this namespace you can reduce the FileReadingMessageSource and wrap
+      it in an inbound Channel Adapter like this:
+      <programlisting language="xml"><![CDATA[ <file:inbound-channel-adapter id="filesIn"
+       directory="file:${input.directory}" prevent-duplicates="true"/>
+
+ <file:inbound-channel-adapter id="filesIn"
+        directory="file:${input.directory}"
+        filter="customFilterBean" />
+
+ <file:inbound-channel-adapter id="filesIn"
+        directory="file:${input.directory}"
+        filename-pattern="test*" />               ]]></programlisting>
+      The first channel adapter is relying on the default filter that just prevents
+      duplication, the second is using a custom filter, and the third is using the
+      <emphasis>filename-pattern</emphasis> attribute to add a <classname>AntPathMatcher</classname>
+      based filter to the <classname>FileReadingMessageSource</classname>.
+      The <emphasis>file-name-pattern</emphasis> and <emphasis>filter</emphasis> attributes are mutually exclusive, but
+      you can use a <classname>CompositeFileListFilter</classname> to use any combination of filters, including a
+      pattern based filter to fit your particular needs.
+    </para>
+        <para>
+            When multiple processes are reading from the same directory it can be desirable to lock files to prevent
+            them from being picked up concurrently. To do this you can use a <interfacename>FileLocker</interfacename>.
+            There is a java.nio based implementation available out of the box, but it is also possible to implement your
+            own locking scheme. The nio locker can be injected as follows
+            <programlisting><![CDATA[ <file:inbound-channel-adapter id="filesIn"
+       directory="file:${input.directory}" prevent-duplicates="true">
+    <file:nio-locker/>
+  </file:inbound-channel-adapter>]]>
+            </programlisting>
+            A custom locker you can configure like this:
+             <programlisting><![CDATA[ <file:inbound-channel-adapter id="filesIn"
+       directory="file:${input.directory}" prevent-duplicates="true">
+    <file:locker ref="customLocker"/>
+  </file:inbound-channel-adapter>]]>
+            </programlisting>
+        </para>
+        <para>
+            When filtering and locking files is not enough it might be needed to control the way files are listed entirely. To
+            implement this type of requirement you can use an implementation of <interfacename>DirectoryScanner</interfacename>.
+            This scanner allows you to determine entirely what files are listed each poll. This is also the interface
+            that Spring Integration uses internally to wire FileListFilters FileLocker to the FileReadingMessageSource.
+            A custom DirectoryScanner can be injected into the &lt;file:inbound-channel-adapter/&gt; on the <code>scanner</code>
+            attribute.
+            <programlisting><![CDATA[ <file:inbound-channel-adapter id="filesIn"
+       directory="file:${input.directory}" prevent-duplicates="true" scanner="customDirectoryScanner"/>]]>
+            </programlisting>
+            This gives you full freedom to choose the ordering, listing and locking strategies.
+        </para>
+  </section>
+
+  <section id="file-writing">
+    <title>Writing files</title>
+    <para>
+      To write messages to the file system you can use a
+      <classname>FileWritingMessageHandler</classname>. This class can deal with
+      File, String, or byte array payloads. In its simplest form the
+      <classname>FileWritingMessageHandler </classname> only requires a
+      destination directory for writing the files. The name of the file to be
+      written is determined by the handler's <classname>FileNameGenerator</classname>.
+      The default implementation looks for a Message header whose key matches
+      the constant defined as <code>FileHeaders.FILENAME</code>.
+    </para>
+    <para>
+      Additionally, you can configure the encoding and the charset that
+      will be used in case of a String payload.
+    </para>
+    <para>
+      To make things easier you can configure the FileWritingMessageHandler as
+      part of an outbound channel adapter using the namespace.
+      <programlisting language="xml"><![CDATA[ <file:outbound-channel-adapter id="filesOut" directory="file:${input.directory.property}"/>]]></programlisting>
+    </para>
+    <para>
+    The namespace based configuration also supports a <code>delete-source-files</code> attribute.
+    If set to <code>true</code>, it will trigger deletion of the original source files after writing
+    to a destination. The default value for that flag is <code>false</code>.
+    <programlisting language="xml"><![CDATA[ <file:outbound-channel-adapter id="filesOut"
+             directory="file:${output.directory}"
+             delete-source-files="true"/>]]></programlisting>
+    <note>
+      <para>
+        The <code>delete-source-files</code> attribute will only have an effect if the inbound
+        Message has a File payload or if the <classname>FileHeaders.ORIGINAL_FILE</classname> header
+        value contains either the source File instance or a String representing the original file path.
+      </para>
+    </note>
+    </para>
+    <para>
+      In cases where you want to continue processing messages based on the written File you can use
+      the <code>outbound-gateway</code> instead. It plays a very similar role as the
+      <code>outbound-channel-adapter</code>. However after writing the File, it will also send it
+      to the reply channel as the payload of a Message.
+    <programlisting language="xml"><![CDATA[ <file:outbound-gateway id="mover" request-channel="moveInput"
+            reply-channel="output"
+            directory="${output.directory}"
+            delete-source-files="true"/>]]></programlisting>
+    </para>
+    <note>
+      The 'outbound-gateway' works well in cases where you want to first move a File and then send it
+      through a processing pipeline. In such cases, you may connect the file namespace's
+      'inbound-channel-adapter' element to the 'outbound-gateway' and then connect that gateway's
+      reply-channel to the beginning of the pipeline.
+    </note>
+    <para>
+      If you have more elaborate requirements or need to support additional payload types as input
+      to be converted to file content you could extend the FileWritingMessageHandler, but a much
+      better option is to rely on a <classname>Transformer</classname>.
+    </para>
+  </section>
+
+  <section id="file-transforming">
+    <title>File Transformers</title>
+    <para>
+      To transform data read from the file system to objects and the other way around you need
+      to do some work. Contrary to <classname>FileReadingMessageSource</classname> and to a
+      lesser extent <classname>FileWritingMessageHandler</classname>, it is very likely that you
+      will need your own mechanism to get the job done. For this you can implement the
+      <interfacename>Transformer</interfacename> interface. Or extend the
+      <classname>AbstractFilePayloadTransformer</classname> for inbound messages. Some obvious
+      implementations have been provided.
+    </para>
+    <para>
+      <classname>FileToByteArrayTransformer</classname> transforms Files into byte[]s using
+      Spring's <classname>FileCopyUtils</classname>. It is often better to use a sequence of
+      transformers than to put all transformations in a single class. In that case the File to
+      byte[] conversion might be a logical first step.
+    </para>
+    <para>
+      <classname>FileToStringTransformer</classname> will convert Files to Strings as the name
+      suggests. If nothing else, this can be useful for debugging (consider using with a Wire Tap).
+    </para>
+    <para>
+      To configure File specific transformers you can use the appropriate elements from the file namespace.
+      <programlisting language="xml"><![CDATA[ <file-to-bytes-transformer input-channel="input" output-channel="output"
+             delete-files="true"/>
+
+ <file:file-to-string-transformer input-channel="input" output-channel="output
+             delete-files="true" charset="UTF-8"/>]]></programlisting>
+      The <emphasis>delete-files</emphasis> option signals to the transformer that it should delete
+      the inbound File after the transformation is complete. This is in no way a replacement for using the
+      <classname>AcceptOnceFileListFilter</classname> when the FileReadingMessageSource is being used in a
+      multi-threaded environment (e.g. Spring Integration in general).
+    </para>
+  </section>
+
+</chapter>

docs/src/reference/docbook/filter.xml

@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="filter"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Filter</title>
+
+  <section id="filter-introduction">
+    <title>Introduction</title>
+    <para>
+      Message Filters are used to decide whether a Message should be passed along or dropped based on some criteria
+      such as a Message Header value or even content within the Message itself. Therefore, a Message Filter is similar
+      to a router, except that for each Message received from the filter's input channel, that same Message may or may
+      not be sent to the filter's output channel. Unlike the router, it makes no decision regarding
+      <emphasis>which</emphasis> Message Channel to send to but only decides <emphasis>whether</emphasis> to send.
+      <note>
+        As you will see momentarily, the Filter does also support a discard channel, so in certain cases it
+        <emphasis>can</emphasis> play the role of a very simple router (or "switch") based on a boolean condition.
+      </note>
+    </para>
+    <para>
+      In Spring Integration, a Message Filter may be configured as a Message Endpoint that delegates to some
+      implementation of the <interfacename>MessageSelector</interfacename> interface. That interface is itself quite
+      simple: <programlisting language="java"><![CDATA[ public interface MessageSelector {
+
+     boolean accept(Message<?> message);
+
+ }]]></programlisting>
+      The <classname>MessageFilter</classname> constructor accepts a selector instance:
+      <programlisting language="java"><![CDATA[ MessageFilter filter = new MessageFilter(someSelector);]]></programlisting>
+    </para>
+      In combination with the namespace and SpEL very powerful filters can be configured with very little java code.
+  </section>
+
+  <section id="filter-namespace">
+    <title>The &lt;filter&gt; Element</title>
+    <para>
+    The &lt;filter&gt; element is used to create a Message-selecting endpoint. In addition to "input-channel"
+      and "output-channel" attributes, it requires a "ref". The "ref" may point to a MessageSelector implementation:
+      <programlisting language="xml"><![CDATA[ <filter input-channel="input" ref="selector" output-channel="output"/>
+
+ <bean id="selector" class="example.MessageSelectorImpl"/>]]></programlisting>
+    </para>
+    <para>
+      Alternatively, the "method" attribute can be added at which point the "ref" may refer to any object.
+      The referenced method may expect either the <interfacename>Message</interfacename> type or the payload type of
+      inbound Messages. The return value of the method must be a boolean value. Any time the method returns 'true',
+      the Message <emphasis>will</emphasis> be passed along to the output-channel.
+      <programlisting language="xml"><![CDATA[ <filter input-channel="input" output-channel="output"
+         ref="exampleObject" method="someBooleanReturningMethod"/>
+
+ <bean id="exampleObject" class="example.SomeObject"/>]]></programlisting>
+    </para>
+    <para>
+      If the selector or adapted POJO method returns <code>false</code>, there are a few settings that control the
+      fate of the rejected Message. By default (if configured like the example above), the rejected Messages will
+      be silently dropped. If rejection should instead indicate an error condition, then set the
+      'throw-exception-on-rejection' flag to <code>true</code>:
+      <programlisting language="xml"><![CDATA[ <filter input-channel="input" ref="selector"
+      output-channel="output" throw-exception-on-rejection="true"/> ]]></programlisting>
+    If you want the rejected messages to go to a specific channel, provide that reference as the 'discard-channel':
+      <programlisting language="xml"><![CDATA[ <filter input-channel="input" ref="selector"
+      output-channel="output" discard-channel="rejectedMessages"/> ]]></programlisting>
+    </para>
+    <note>
+      A common usage for Message Filters is in conjunction with a Publish Subscribe Channel. Many filter endpoints may
+      be subscribed to the same channel, and they decide whether or not to pass the Message for the next endpoint which
+      could be any of the supported types (e.g. Service Activator). This provides a <emphasis>reactive</emphasis>
+      alternative to the more <emphasis>proactive</emphasis> approach of using a Message Router with a single
+      Point-to-Point input channel and multiple output channels.
+    </note>
+  <para>
+      Using a "ref" attribute is generally recommended if the custom filter implementation can be reused in other
+      <code>&lt;filter&gt;</code> definitions. However if the custom filter implementation should be scoped to a
+      single <code>&lt;filter&gt;</code> element, provide an inner bean definition:
+<programlisting language="xml"><![CDATA[<filter method="someMethod" input-channel="inChannel" output-channel="outChannel">
+  <beans:bean class="org.foo.MyCustomFilter"/>
+</filter>]]></programlisting>
+    </para>
+    <note>
+      <para>
+        Using both the "ref" attribute and an inner handler definition in the same <code>&lt;filter&gt;</code> configuration
+        is not allowed, as it creates an ambiguous condition, and it will therefore result in an Exception being thrown.
+      </para>
+    </note>
+    <para>
+      With the introduction of SpEL Spring Integration has added the <code>expression</code> attribute to the filter
+      element. It can be used to avoid Java entirely for simple filters.
+      <programlisting language="xml">
+        <![CDATA[  <filter input-channel="input" expression="payload.equals(nonsense)"/>]]>
+      </programlisting>
+      The string passed as the expression attribute will be evaluated as a SpEL expression in the context of the message.
+      If it is needed to include the result of an expression in the scope of the application context you can use the
+      #{} notation as defined in the SpEL reference documentation
+      <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html#expressions-beandef">
+        SpEL reference documentation
+      </ulink>.
+      <programlisting language="xml">
+        <![CDATA[  <filter input-channel="input" expression="payload.matches(#{filterPatterns.nonsensePattern})"/>]]>
+      </programlisting>
+      If the Expression itself needs to be dynamic, then an 'expression' sub-element may be used. That provides a level of
+      indirection for resolving the Expression by its key from an ExpressionSource. That is a strategy interface that you
+      can implement directly, or you can rely upon a version available in Spring Integration that loads Expressions from
+      a "resource bundle" and can check for modifications after a given number of seconds. All of this is demonstrated in
+      the following configuration sample where the Expression could be reloaded within one minute if the underlying file
+      had been modified. If the ExpressionSource bean is named "expressionSource", then it is not necessary to provide the
+      "source" attribute on the &lt;expression&gt; element, but in this case it's shown for completeness.
+      <programlisting language="xml">
+        <![CDATA[  <filter input-channel="input" output-channel="output">
+      <expression key="filterPatterns.example" source="myExpressions"/>
+  </filter>
+
+  <beans:bean id="myExpressions" id="myExpressions"
+          class="org.springframework.integration.expression.ReloadableResourceBundleExpressionSource">
+      <beans:property name="basename" value="config/integration/expressions"/>
+      <beans:property name="cacheSeconds" value="60"/>
+  </beans:bean>
+]]></programlisting>
+
+    Then, the 'config/integration/expressions.properties' file (or any more specific version with a locale extension
+    to be resolved in the typical way that resource-bundles are loaded) would contain a key/value pair:
+  <programlisting language="xml">
+        <![CDATA[  filterPatterns.example=payload > 100
+]]></programlisting>
+
+    <note>All of the examples that use "expression" as an attribute or sub-element can also be applied within
+      transformer, router, splitter, service-activator, and header-enricher elements. Of course, the semantics/role
+      of the given component type would affect the interpretation of the evaluation result in the same way that the
+      return or a method-invocation would be interpreted. For example, an expression can return Strings that are
+      to be treated as Message Channel names by a router component.</note>
+    </para>
+  </section>
+</chapter>

docs/src/reference/docbook/gateway.xml

@@ -0,0 +1,254 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="gateway"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Inbound Messaging Gateways</title>
+
+  <section id="gateway-proxy">
+    <title>GatewayProxyFactoryBean</title>
+    <para>
+      Working with Objects instead of Messages is an improvement. However, it would be even better to have no
+      dependency on the Spring Integration API at all - including the gateway class. For that reason, Spring
+      Integration also provides a <classname>GatewayProxyFactoryBean</classname> that generates a proxy for
+      any interface and internally invokes the gateway methods shown above. Namespace support is also
+      provided as demonstrated by the following example.
+      <programlisting language="xml"><![CDATA[<gateway id="fooService"
+         service-interface="org.example.FooService"
+         default-request-channel="requestChannel"
+         default-reply-channel="replyChannel"/>]]></programlisting>
+      Then, the "fooService" can be injected into other beans, and the code that invokes the methods on that
+      proxied instance of the FooService interface has no awareness of the Spring Integration API. The general
+      approach is similar to that of Spring Remoting (RMI, HttpInvoker, etc.). See the "Samples" Appendix for
+      an example that uses this "gateway" element (in the Cafe demo).
+  </para>
+    <para>
+      The reason that the attributes on the 'gateway' element are named 'default-request-channel' and
+      'default-reply-channel' is that you may also provide per-method channel references by using the
+      @Gateway annotation.
+      <programlisting language="java"><![CDATA[ public interface Cafe {
+
+     @Gateway(requestChannel="orders")
+     void placeOrder(Order order);
+
+ }]]></programlisting>
+   ... as well as <code>method</code> sub element if yuo prefer XML configuration (see next paragraph)
+    </para>
+    <para>
+      It is also possible to pass values to be interpreted as Message headers on the Message
+      that is created and sent to the request channel by using the @Header annotation:
+    <programlisting language="java"><![CDATA[ public interface FileWriter {
+
+     @Gateway(requestChannel="filesOut")
+     void write(byte[] content, @Header(FileHeaders.FILENAME) String filename);
+
+ }]]></programlisting>
+    </para>
+
+    <para>
+    If you prefer XML way of configuring Gateway methods, you can provide <emphasis>method</emphasis> sub-elements
+    to the gateway configuration (see below)
+     <programlisting language="xml"><![CDATA[<si:gateway id="myGateway" service-interface="org.foo.bar.TestGateway"
+      default-request-channel="inputC">
+  <si:method name="echo" request-channel="inputA" reply-timeout="2" request-timeout="200"/>
+      <si:method name="echoUpperCase" request-channel="inputB"/>
+      <si:method name="echoViaDefault"/>
+</si:gateway>]]></programlisting>
+    </para>
+    <para>
+      You can also provide individual headers per method invocation via XML.
+      This could be very useful if the headers you want to set are static in nature and you don't want
+      to embed them in the gateway's method signature via <classname>@Header</classname> annotations.
+      For example, in the Loan Broker example we want to influence how aggregation of the Loan quotes
+      will be done based on what type of request was initiated (single quote or all quotes). Determining the
+      type of the request by evaluating what gateway method was invoked, although possible would
+      violate the separation of concerns paradigm (method is a java artifact),  but expressing your
+      intention (meta information) via Message headers is natural in a Messaging architecture.
+
+      <programlisting language="xml"><![CDATA[<int:gateway id="loanBrokerGateway"
+         service-interface="org.springframework.integration.loanbroker.LoanBrokerGateway">
+  <int:method name="getLoanQuote" request-channel="loanBrokerPreProcessingChannel">
+    <int:header name="RESPONSE_TYPE" value="BEST"/>
+  </int:method>
+  <int:method name="getAllLoanQuotes" request-channel="loanBrokerPreProcessingChannel">
+    <int:header name="RESPONSE_TYPE" value="ALL"/>
+  </int:method>
+</int:gateway>]]></programlisting>
+  In the above case you can clearly see how a different header value will be set for the 'RESPONSE_TYPE'
+  header based on the gateway's method.
+    </para>
+    <para>
+    As with anything else, Gateway invocation might result in errors.
+    By default any error that has occurred downstream will be re-thrown as a MessagingExeption (RuntimeException)
+    upon the Gateway's method invocation. However there are times when you may want to treat an Exception as a valid reply,
+    by mapping it to a Message. To accomplish this our Gateway provides support for Exception mappers via the
+    <emphasis>exception-mapper</emphasis> attribute.
+    </para>
+    <para>
+<programlisting language="xml"><![CDATA[<si:gateway id="sampleGateway"
+    default-request-channel="gatewayChannel"
+    service-interface="foo.bar.SimpleGateway"
+    exception-mapper="exceptionMapper"/>
+
+<bean id="exceptionMapper" class="foo.bar.SampleExceptionMapper"/>
+
+        ]]></programlisting>
+
+  <emphasis>foo.bar.SampleExceptionMapper</emphasis> is the implementation of
+  <emphasis>org.springframework.integration.message.InboundMessageMapper</emphasis> which only defines one method: <code>toMessage(Object object)</code>.
+<programlisting language="java"><![CDATA[public static class SampleExceptionMapper implements InboundMessageMapper<Throwable>{
+  public Message<?> toMessage(Throwable object) throws Exception {
+    MessageHandlingException ex = (MessageHandlingException) object;
+    return MessageBuilder.withPayload("Error happened in message: " +
+                ex.getFailedMessage().getPayload()).build();
+  }
+
+}
+        ]]></programlisting>
+
+     </para>
+     <para>
+       <important>
+       Exposing messaging system via POJO Gateway is obviously a great benefit, but it does come at the price so there
+       are certain things you must be aware of.
+
+            We want our Java method to return as quick as possible and not hang for infinite amount of time until they can
+            return (void , exception or return value). When regular methods are used as a proxies in front of the Messaging
+            system we have to take into account the asynchronous nature of the Messaging Systems. This means that there might
+            be a chance that a Message hat was initiated by a Gateway could be dropped by a Filter, thus never reaching a
+            component that is responsible to produce a reply. Some Service Activator method might result in the Exception,
+            thus resulting in no-reply (as we don't generate Null messages).So as you can see there are multiple scenarios
+            where reply message might not be coming which is perfectly natural in messaging systems. However think about the
+            implication on the gateway method.  The Gateway's method input arguments  were incorporated into a Message and
+            sent downstream. The reply Message would be converted to a return value of the Gateway's method. So you can see
+            how ugly it could get if you can not guarantee that for each Gateway call there will alway be a reply Message.
+            Basically your Gateway method will never return and will hang infinitely. (work in progress!!!!)
+One of the ways of handling this situation is via AsyncGateway (explained later in this section). Another way of handling it is to explicitly set the reply-timeout attribute. This way gateway will not hang for more then the time that was specified by the reply-timout and will return 'null'. 
+       </important>
+     </para>
+  </section>
+  <section id="async-gateway">
+    <title>Asynchronous Gateway</title>
+    <para>
+      As a pattern the Messaging Gateway is a very nice way to hide messaging-specific code while still exposing the full capabilities of the
+      messaging system. And <classname>GatewayProxyFactoryBean</classname> provides a convenient way to expose a Proxy over a service-interface
+      thus giving you a POJO-based access to a messaging system (based on objects in your own domain, or primitives/Strings, etc).  But when a
+      gateway is exposed via simple POJO methods which return values it does imply that for each Request message (generated when the method is invoked)
+      there must be a Reply message (generated when the method has returned). Since Messaging systems naturally are asynchronous you may not always be
+      able to guarantee the contract where <emphasis>"for each request there will always be be a reply"</emphasis>. 
+      With Spring Integration 2.0 we are introducing support for an <emphasis>Asynchronous Gateway</emphasis> which is a convenient way to initiate
+      flows where you may not know if a reply is expected or how long will it take for it to arrive.
+      </para>
+      <para>
+      A natural way to handle these types of scenarios in Java would be relying upon <emphasis>java.util.concurrent.Future</emphasis> instances, and
+      that is exactly what Spring Integration uses to support an <emphasis>Asynchronous Gateway</emphasis>.
+      </para>
+      <para>
+    From the XML configuration, there is nothing different and you still define <emphasis>Asynchronous Gateway</emphasis> the same way as a regular Gateway.
+      <programlisting language="xml"><![CDATA[<int:gateway id="mathService" 
+     service-interface="org.springframework.integration.sample.gateway.futures.MathServiceGateway"
+     default-request-channel="requestChannel"/>]]></programlisting>
+      However the Gateway Interface (service-interface) is a bit different.
+
+      <programlisting language="java">public interface MathServiceGateway {
+  Future&lt;Integer&gt; multiplyByTwo(int i);
+}</programlisting>
+    </para>
+    <para>
+    As you can see from the example above the return type for the gateway method is <classname>Future</classname>. When
+    <classname>GatewayProxyFactoryBean</classname> sees that the
+    return type of the gateway method is <classname>Future</classname>, it immediately switches to the async mode by utilizing
+    an <classname>AsyncTaskExecutor</classname>. That is all. The call to a method always returns immediately with <classname>Future</classname>
+    encapsulating  the interaction with the framework.
+    Now you can interact with the <classname>Future</classname> at your own pace to get the result, timeout, get the exception etc...
+    <programlisting language="java">MathServiceGateway mathService = ac.getBean("mathService", MathServiceGateway.class);
+Future&lt;Integer&gt; result = mathService.multiplyByTwo(number);
+// do something else here since the reply might take a moment
+int finalResult =  result.get(1000, TimeUnit.SECONDS);</programlisting>
+For a more detailed example, please refer to the <emphasis>async-gateway</emphasis> sample distributed within the Spring Integration samples.
+    </para>
+
+  </section>
+  <section>
+    <title>Gateway behavior when no response is coming</title>
+    <para>
+    As it was explained earlier, Gateway provides a convenient way of interacting with Messaging system via POJO method
+    invocations, but realizing that a typical method invocation, which is generally expected to always return (even with Exception),
+    might not always map one-to-one to message exchanges (e.g., reply message might not be coming which is equivalent to
+    method not returning), it is important to go over several scenarios especially in the Sync Gateway case and understand
+    what the default behavior of the Gateway and how to deal with these scenarios to make Sync Gateway behavior more
+    predictable regardless of the outcome of the message flow that was initialed from such Gateway.
+    </para>
+    <para>
+    There are certain attributes that could be configured to make Sync Gateway behavior more predictable,
+    but some of them might not always work as you might have expected. One of them is <emphasis>reply-timeout</emphasis>.
+    So, lets look at the <emphasis>reply-timeout</emphasis> attribute and see how it can/can't influence the behavior
+    of the Sync Gateway in various scenarios. We will look at single-theraded scenario
+    (all components downstream are connected via Direct Channel) and multi-theraded scenarios
+    (e.g., somewhere downstream you may have Pollable or Executor Channel which breaks single-thread boundary)
+    </para>
+    <para>
+    <emphasis>Long running process downstream</emphasis>
+    </para>
+    <para>
+    <emphasis>Sync Gateway - single-threaded</emphasis>.
+  If a component downstream is still running (e.g., infinite loop or a very slow service), then setting <emphasis>reply-timeout</emphasis>
+  has no effect and Gateway method call will not return until such downstream service exits (e.g., return or exception).
+    <emphasis>Sync Gateway - multi-threaded</emphasis>.
+  If a component downstream is still running (e.g., infinite loop or a very slow service), in a multi-threaded message
+  flow setting <emphasis>reply-timeout</emphasis> will have an effect by allowing gateway method invocation to
+  return once the timeout has been reached, since <classname>GatewayProxyFactoryBean</classname>  will simply
+  poll on the reply channel waiting for a message untill the timeout expires. However it could result in the 'null' return
+  from the Gateway method if the timeout has been reached before the actual reply was produced. It is also important to understand that
+  the reply message (if produced) will be sent to a reply channel after Gateway method invocation might have returned, so you must be aware of that
+  and design your flow with this in mind.
+    </para>
+    <para>
+    <emphasis>Downstream component returns 'null'</emphasis>
+    </para>
+    <para>
+    <emphasis>Sync Gateway - single-threaded</emphasis>.
+  If a component downstream returns 'null' and no <emphasis>reply-timeout</emphasis> has been configured, the Gateway
+  method call will hang indefinitely unless: a) <emphasis>reply-timeout</emphasis> has been configured or b)
+  <emphasis>requires-reply</emphasis> attribute has been set on the downstream component (e.g., service-activator)
+  that might return 'null'. In this case, the exception will be thrown and propagated to the Gateway.
+  <emphasis>Sync Gateway - multi-threaded</emphasis>. Behavior is the same as above.
+    </para>
+    <para>
+    <emphasis>Downstream component return signature is 'void' while Gateway method signature is non-void</emphasis>
+    </para>
+    <para>
+    <emphasis>Sync Gateway - single-threaded</emphasis>.
+  If a component downstream returns 'void' and no <emphasis>reply-timeout</emphasis> has been configured,
+  the Gateway method call will hang indefinitely unless <emphasis>reply-timeout</emphasis> has been configured 
+  <emphasis>Sync Gateway - multi-threaded</emphasis> Behavior is the same as above.
+    </para>
+    <para>
+    <emphasis>Downstream component results in Runtime Exception (regardless of the method signature)</emphasis>
+    </para>
+    <para>
+    <emphasis>Sync Gateway - single-threaded</emphasis>.
+  If a component downstream throws a Runtime Exception, such exception will be propagated via Error Message back to
+  the gateway and re-thrown.
+  <emphasis>Sync Gateway - multi-threaded</emphasis> Behavior is the same as above.
+    </para>
+    <para>
+      <important>
+    It is also important to understand that by default <emphasis>reply-timout</emphasis> is unbounded which means that
+    if not explicitly set there are several scenarios (described above) where your Gateway method invocation might
+    hang indefinitely, so make sure you analyze your flow and if there is even a remote possibility of one of these
+    scenarios to occur, set the <emphasis>reply-timout</emphasis> attribute to a 'safe' value or better off
+    set  the <emphasis>requires-reply</emphasis>  attribute of the downstream component to 'true' to ensure a timely response.
+    But also, realize that there are some scenarios (see the very first one)
+    where <emphasis>reply-timout</emphasis> will not help which means it is also important to analyze your message
+    flow and decide when to use Sync Gateway vs Async Gateway where Gateway method invocation is always guaranteed
+    to return while giving you a more granular control over the results of the invocation via Java Futures.
+    <para>
+    Also, when dealing with Router you should remember that seeting <emphasis>resolution-required</emphasis> attribute to 'true'
+    will result in the exception thrown by the router if it can not resolve a particular chanel. And when dealing with the filter
+    you can also set <emphasis>throw-exception-on-rejection</emphasis> attribute. Both of these will help to ensure a timely response
+    from the Gateway method invocation.
+    </para>
+      </important>
+    </para>
+  </section>
+
+</chapter>

docs/src/reference/docbook/groovy.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="groovy"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Groovy support</title>
+  <para>
+  With Spring Integration 2.0 we've added Groovy support allowing you to use Groovy scripting language to provide
+  integration and business logic  for various integration components similar to the way Spring Expression Language (SpEL)
+  is use to implement routing, transformation and other integration concerns.
+
+    For more information about Groovy please refer to Groovy documentation which you can find here: http://groovy.codehaus.org/
+  </para>
+
+  <section id="groovy-config">
+    <title>Groovy configuration</title>
+    <para>
+      Depending on the complexity of your integration requirements Groovy scripts could be provided inline as CDATA in XML
+      configuration or as a reference to a file containing Groovy script.
+
+      To enable Groovy support Spring Integration defines <classname>GroovyScriptExecutingMessageProcessor</classname> which will
+      create a groovy Binding object identifying Message Payload as <code>payload</code> variable and Message Headers as
+      <code>headers</code> variable. All that is left for you to do is write script that uses these variables.
+      Below are couple of sample configurations:
+      </para>
+
+      <para>
+      <emphasis>Filter</emphasis>
+      <programlisting language="xml">&lt;filter input-channel="referencedScriptInput"&gt;
+   &lt;groovy:script location="some/path/to/groovy/file/GroovyFilterTests.groovy"/&gt;
+&lt;/filter&gt;
+
+&lt;filter input-channel="inlineScriptInput"&gt;
+     &lt;groovy:script&gt;&lt;![CDATA[
+     return payload == 'good'
+   ]]&gt;&lt;/groovy:script&gt;
+&lt;/filter&gt;</programlisting>
+You see that script could be included inline or via <code>location</code> attribute using the groovy namespace sport. 
+    </para>
+
+    <para>
+    Other supported elements are <emphasis>router, service-activator, transformer, splitter</emphasis>
+    </para>
+
+    <para>
+    Another interesting aspect of using Groovy support is framework's ability to update (reload) scripts 
+    without restarting the Application Context.
+    To accomplish this all you need is specify <code>refresh-check-delay</code> attribute on <emphasis>script</emphasis>
+    element. The reason for this attribute is to make reloading of  the script more efficient. 
+
+    <programlisting language="xml"><![CDATA[<groovy:script location="..." refresh-check-delay="5000"/>]]></programlisting>
+
+    In the above example for the next 5 seconds after you update the script you'll still be using the old script and
+    after 5 seconds the context will be updated with the new script. This is a good example where  'near real time'
+    is acceptable.
+
+     <programlisting language="xml"><![CDATA[<groovy:script location="..." refresh-check-delay="0"/>]]></programlisting>
+
+     In the above example the context will be updated with the new script every time the script is modified. Basically this is the example of the
+     'real-time' and might not be the most efficient way.
+
+     <programlisting language="xml"><![CDATA[<groovy:script location="..." refresh-check-delay="-1"/>]]></programlisting>
+
+
+    Any negative number value means the script will never be refreshed after initial initialization of application context.
+    DEFAULT BEHAVIOR
+
+    <important>Inline defined script can not be reloaded.</important>
+
+    </para>
+
+  </section>
+
+</chapter>

docs/src/reference/docbook/http.xml

@@ -0,0 +1,210 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="http"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>HTTP Support</title>
+
+  <section id="http-intro">
+    <title>Introduction</title>
+    <para>
+      The HTTP support allows for the execution of HTTP requests and the processing of inbound HTTP requests.  Because interaction over HTTP is always synchronous, even if all that is returned is a 200 status code, the HTTP support consists of two gateway implementations:
+   <classname>HttpInboundEndpoint</classname> and <classname>HttpRequestExecutingMessageHandler</classname>.
+    </para>
+   </section>
+
+  <section id="http-inbound">
+    <title>Http Inbound Gateway</title>
+    <para>
+    To receive messages over HTTP you need to use an HTTP inbound Channel Adapter or Gateway.  In common with the HttpInvoker
+  support the HTTP inbound adapters need to be deployed within a servlet container.  The easiest way to do this is to provide a servlet
+  definition in <emphasis>web.xml</emphasis>, see
+  <xref linkend="httpinvoker-inbound"/> for further details.  Below is an example bean definition for a simple HTTP inbound endpoint.
+    <programlisting language="xml"><![CDATA[<bean id="httpInbound" class="org.springframework.integration.http.HttpRequestHandlingMessagingGateway">
+  <property name="requestChannel" ref="httpRequestChannel" />
+  <property name="replyChannel" ref="httpReplyChannel" />
+</bean>]]></programlisting>
+  The <classname>HttpRequestHandlingMessagingGateway</classname> accepts a list of <interfacename>HttpMessageConverter</interfacename> instances or else
+  relies on a default list. The converters allow
+  customization of the mapping from <interfacename>HttpServletRequest</interfacename> to <interfacename>Message</interfacename>. The default converters
+  encapsulate simple strategies, which for
+  example will create a String message for a <emphasis>POST</emphasis> request where the content type starts with "text", see the Javadoc for
+  full details.
+      </para>
+      <para>Starting with this release MultiPart File support was implemented. If the request has been wrapped as a
+    <emphasis>MultipartHttpServletRequest</emphasis>, when using the default converters, that request will be converted
+    to a Message payload that is a MultiValueMap containing values that may be byte arrays, Strings, or instances of
+    Spring's <interfacename>MultipartFile</interfacename> depending on the content type of the individual parts.
+    <note>
+    The HTTP inbound Endpoint will locate a MultipartResolver in the context if one exists with the bean name
+    "multipartResolver" (the same name expected by Spring's DispatcherServlet). If it does in fact locate that
+    bean, then the support for MultipartFiles will be enabled on the inbound request mapper. Otherwise, it will
+    fail when trying to map a multipart-file request to a Spring Integration Message. For more on Spring's
+    support for MultipartResolvers, refer to the <ulink url="http://static.springsource.org/spring/docs/2.5.x/reference/mvc.html#mvc-multipart">Spring Reference Manual</ulink>.
+      </note>
+      </para>
+      <para>
+    In sending a response to the client there are a number of ways to customize the behavior of the gateway.  By default the gateway will
+  simply acknowledge that the request was received by sending a 200 status code back.  It is possible to customize this response by providing a
+  'viewName' to be resolved by the Spring MVC <interfacename>ViewResolver</interfacename>.
+        In the case that the gateway should expect a reply to the <interfacename>Message</interfacename> then setting the <property>expectReply</property> flag
+    (constructor argument) will cause
+  the gateway to wait for a reply <interfacename>Message</interfacename> before creating an HTTP response.  Below is an example of a gateway
+  configured to serve as a Spring MVC Controller with a view name. Because of the constructor arg value of TRUE, it wait for a reply.  This also shows
+  how to customize the HTTP methods accepted by the gateway, which
+  are <emphasis>POST</emphasis> and <emphasis>GET</emphasis> by default.
+  <programlisting language="xml"><![CDATA[<bean id="httpInbound" class="org.springframework.integration.http.HttpRequestHandlingController">
+  <constructor-arg value="true" /> <!-- indicates that a reply is expected -->
+  <property name="requestChannel" ref="httpRequestChannel" />
+  <property name="replyChannel" ref="httpReplyChannel" />
+  <property name="viewName" value="jsonView" />
+  <property name="supportedMethodNames" >
+    <list>
+      <value>GET</value>
+      <value>DELETE</value>
+    </list>
+  </property>
+  <property name="expectReply" value="true" />
+</bean>]]></programlisting>
+  The reply message will be available in the Model map. The key that is used
+  for that map entry by default is 'reply', but this can be overridden by setting the
+  'replyKey' property on the endpoint's configuration.
+     </para>
+  </section>
+
+  <section id="http-outbound">
+    <title>Http Outbound Gateway</title>
+
+  <para>
+    To configure the <classname>HttpRequestExecutingMessageHandler</classname> write a bean definition like this:
+    <programlisting language="xml"><![CDATA[<bean id="httpOutbound" class="org.springframework.integration.http.HttpRequestExecutingMessageHandler" >
+  <constructor-arg value="http://localhost:8080/example" />
+  <property name="outputChannel" ref="responseChannel" />
+</bean>]]></programlisting>
+    This bean definition will execute HTTP requests by delegating to a <classname>RestTemplate</classname>. That template in turn delegates
+    to a list of HttpMessageConverters to generate the HTTP request body from the Message payload. You can configure those converters as well
+    as the ClientHttpRequestFactory instance to use:
+    <programlisting language="xml"><![CDATA[<bean id="httpOutbound" class="org.springframework.integration.http.HttpRequestExecutingMessageHandler" >
+  <constructor-arg value="http://localhost:8080/example" />
+  <property name="outputChannel" ref="responseChannel" />
+  <property name="messageConverters" ref="messageConverterList" />
+  <property name="requestFactory" ref="customRequestFactory" />
+</bean>]]></programlisting>
+By default the HTTP request will be generated using an instance of <classname>SimpleClientHttpRequestFactory</classname> which uses the JDK
+  <classname>HttpURLConnection</classname>.  Use of the Apache Commons HTTP Client is also supported through the provided
+  <classname>CommonsClientHttpRequestFactory</classname> which can be injected as shown above.
+    </para>
+  </section>
+
+  <section id="http-namespace">
+    <title>HTTP Namespace Support</title>
+  <para>
+    Spring Integration provides an "http" namespace and schema definition. To include it in your
+    configuration, simply provide the following URI within a namespace declaration:
+    'http://www.springframework.org/schema/integration/http'. The schema location should then map to
+    'http://www.springframework.org/schema/integration/http/spring-integration-http.xsd'.
+  </para>
+    <para>
+    To configure an inbound http channel adapter which is an instance of <classname>HttpInboundEndpoint</classname> configured
+    not to expect a response.
+    <programlisting language="xml"><![CDATA[ <http:inbound-channel-adapter id="httpChannelAdapter" channel="requests" supported-methods="PUT, DELETE"/>]]></programlisting>
+    </para>
+    <para>
+    To configure an inbound http gateway which expects a response.
+    <programlisting language="xml"><![CDATA[ <http:inbound-gateway id="inboundGateway" request-channel="requests" reply-channel="responses"/>]]></programlisting>
+    </para>
+    <para>
+    To configure the outbound gateway you can use the namespace support as well. The following code snippet shows the different configuration options for an outbound Http gateway. Most importantly, notice that the 'http-method' and 'expected-response-type' are provided. Those are two of the most commonly configured values. The
+    default http-method is POST, and the default response type is <emphasis>null</emphasis>. With a null response type, the payload of the reply Message would only
+    contain the status code (e.g. 200) as long as it's a successful status (non-successful status codes will throw Exceptions). If you are expecting a different
+    type, such as a <classname>String</classname>, then provide that fully-qualified class name as shown below.
+    <programlisting language="xml"><![CDATA[<http:outbound-gateway id="example"
+    request-channel="requests"
+    url="http://localhost/test"
+    http-method="POST"
+    extract-request-payload="false"
+    expected-response-type="java.lang.String"
+    charset="UTF-8"
+    request-factory="requestFactory"
+    request-timeout="1234"
+    reply-channel="replies"/>]]></programlisting>
+    </para>
+  <para>If your outbound adapter is to be used in a unidirectional way, then you can use an outbound-channel-adapter instead. This means that
+    a successful response will simply execute without sending any Messages to a reply channel. In the case of any non-successful response
+    status code, it will throw an exception. The configuration looks very similar to the gateway:
+    <programlisting language="xml"><![CDATA[<http:outbound-channel-adapter id="example"
+      url="http://localhost/example"
+      http-method="GET"
+      channel="requests"
+      charset="UTF-8"
+      extract-payload="false"
+      expected-response-type="java.lang.String"
+      request-factory="someRequestFactory"
+      order="3"
+      auto-startup="false"/>]]></programlisting>
+  </para>
+  </section>
+  <section id="http-samples">
+    <title>HTTP Samples</title>
+  <section id="multipart-rest-inbound">
+    <title>Multipart HTTP request - RestTemplate (client) and Http Inbound Gateway (server)</title>
+    <para>
+      This example demonstrates how simple it is to send a Multipart HTTP request via Spring's RestTemplate and receive it by Spring Integration HTTP Inbound Adapter.
+All we are doing is creating <classname>MultiValueMap</classname> and populating it with multi-part data. <classname>RestTemplate</classname> will take care of the rest
+by converting it to <classname>MultipartHttpServletRequest</classname>  
+THis particular client will send a multipart Http Request which contains the name of the company as well as the image file with company logo.
+    <programlisting language="java"><![CDATA[RestTemplate template = new RestTemplate();
+String uri = "http://localhost:8080/multipart-http/inboundAdapter.htm";
+Resource s2logo = 
+   new ClassPathResource("org/springframework/integration/samples/multipart/spring09_logo.png");
+MultiValueMap map = new LinkedMultiValueMap();
+map.add("company", "SpringSource");
+map.add("company-logo", s2logo);
+HttpHeaders headers = new HttpHeaders();
+headers.setContentType(new MediaType("multipart", "form-data"));
+HttpEntity request = new HttpEntity(map, headers);
+ResponseEntity<?> httpResponse = template.exchange(uri, HttpMethod.POST, request, null);]]></programlisting>
+</para>
+<para>
+That is all for the client.
+</para>
+<para>
+On the server side we have the following configuration:
+<programlisting language="xml"><![CDATA[<int-http:inbound-channel-adapter id="httpInboundAdapter"
+  channel="receiveChannel"
+  name="/inboundAdapter.htm"
+  supported-methods="GET, POST" />
+
+<int:channel id="receiveChannel"/>
+
+<int:service-activator input-channel="receiveChannel">
+  <bean class="org.springframework.integration.samples.multipart.MultipartReceiever"/>
+</int:service-activator>
+
+<bean id="multipartResolver"
+    class="org.springframework.web.multipart.commons.CommonsMultipartResolver"/>
+]]></programlisting>
+</para>
+<para>
+The 'httpInboundAdapter' will receive the request, convert it to a <classname>Message</classname> with a payload as <classname>LinkedMultiValueMap</classname> which
+we are parsing in the 'multipartReceiver' service-activator;
+<programlisting language="java"><![CDATA[public void recieve(LinkedMultiValueMap<String, Object> multipartRequest){
+  System.out.println("### Successfully recieved multipart request ###");
+  for (String elementName : multipartRequest.keySet()) {
+    if (elementName.equals("company")){
+      System.out.println("\t" + elementName + " - " +
+        ((String[]) multipartRequest.getFirst("company"))[0]);
+    } else if (elementName.equals("company-logo")){
+      System.out.println("\t" + elementName + " - as UploadedMultipartFile: " +
+        ((UploadedMultipartFile) multipartRequest.getFirst("company-logo")).getOriginalFilename());
+    }
+  }
+}
+
+]]></programlisting>
+You should see the following output:
+<programlisting language="xml"><![CDATA[### Successfully recieved multipart request ###
+   company - SpringSource
+   company-logo - as UploadedMultipartFile: spring09_logo.png]]></programlisting>
+</para>
+  </section>
+  </section>
+</chapter>

docs/src/reference/docbook/httpinvoker.xml

@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="httpinvoker"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>HttpInvoker Support</title>
+
+  <section id="httpinvoker-intro">
+    <title>Introduction</title>
+    <para>
+      HttpInvoker is a Spring-specific remoting option that essentially enables Remote Procedure Calls (RPC) over HTTP.
+      In order to accomplish this, an outbound representation of a method invocation is serialized using standard Java
+      serialization and then passed within an HTTP POST request. After being invoked on the target system, the method's
+      return value is then serialized and written to the HTTP response. There are two main requirements. First, you
+      must be using Spring on both sides since the marshalling to and from HTTP requests and responses is handled by
+      the client-side invoker and server-side exporter. Second, the Objects that you are passing must implement
+      <interfacename>Serializable</interfacename> and be available on both the client and server.
+    </para>
+    <para>
+      While traditional RPC provides <emphasis>physical</emphasis> decoupling, it does not offer nearly the same degree
+      of <emphasis>logical</emphasis> decoupling as a messaging-based system. In other words, both participants in an
+      RPC-based invocation must be aware of a specific interface and specific argument types. Interestingly, in Spring
+      Integration, the "parameter" being sent is a Spring Integration Message, and the interface is an internal detail
+      of Spring Integration's implementation. Therefore, the RPC mechanism is being used as a
+      <emphasis>transport</emphasis> so that from the end user's perspective, it is not necessary to consider the
+      interface and argument types. It's just another adapter to enable messaging between two systems.
+    </para>
+  </section>
+
+  <section id="httpinvoker-inbound">
+    <title>HttpInvoker Inbound Gateway</title>
+    <para>
+    To receive messages over http you can use an <classname>HttpInvokerInboundGateway</classname>. Here is an
+    example bean definition:
+    <programlisting language="xml"><![CDATA[<bean id="inboundGateway"
+      class="org.springframework.integration.httpinvoker.HttpInvokerInboundGateway">
+    <property name="requestChannel" ref="requestChannel"/>
+    <property name="replyChannel" ref="replyChannel"/>
+    <property name="requestTimeout" value="30000"/>
+    <property name="replyTimeout" value="10000"/>
+</bean>]]></programlisting>
+    Because the inbound gateway must be able to receive HTTP requests, it must be configured within a Servlet
+    container. The easiest way to do this is to provide a servlet definition in <emphasis>web.xml</emphasis>:
+    <programlisting language="xml"><![CDATA[<servlet>
+    <servlet-name>inboundGateway</servlet-name>
+    <servlet-class>org.springframework.web.context.support.HttpRequestHandlerServlet</servlet-class>
+</servlet>]]></programlisting>
+    Notice that the servlet name matches the bean name.
+    <note>
+      If you are running within a Spring MVC application and using the BeanNameHandlerMapping, then the servlet
+      definition is not necessary. In that case, the bean name for your gateway can be matched against the URL
+      path just like a Spring MVC Controller bean.
+    </note>
+    </para>
+  </section>
+
+  <section id="httpinvoker-outbound">
+    <title>HttpInvoker Outbound Gateway</title>
+    <para>
+  </para>
+  <para>
+    To configure the <classname>HttpInvokerOutboundGateway</classname> write a bean definition like this:
+    <programlisting language="xml"><![CDATA[<bean id="outboundGateway"
+      class="org.springframework.integration.httpinvoker.HttpInvokerOutboundGateway">
+    <property name="replyChannel" ref="replyChannel"/>
+</bean>]]></programlisting>
+    The outbound gateway is a <interfacename>MessageHandler</interfacename> and can therefore be registered with
+    either a <classname>PollingConsumer</classname> or <classname>EventDrivenConsumer</classname>.
+    The URL must match that defined by an inbound HttpInvoker Gateway as described in the previous section.
+    </para>
+  </section>
+
+  <section id="httpinvoker-namespace">
+    <title>HttpInvoker Namespace Support</title>
+  <para>
+    Spring Integration provides an "httpinvoker" namespace and schema definition. To include it in your
+    configuration, simply provide the following URI within a namespace declaration:
+    'http://www.springframework.org/schema/integration/httpinvoker'. The schema location should then map to
+    'http://www.springframework.org/schema/integration/httpinvoker/spring-integration-httpinvoker-2.0.xsd'.
+  </para>
+    <para>
+    To configure the inbound gateway you can choose to use the namespace support for it. The following code snippet shows the different configuration options that are supported.
+    <programlisting language="xml"><![CDATA[<httpinvoker:inbound-gateway id="inboundGateway"
+                             request-channel="requestChannel"
+                             request-timeout="10000"
+                             expect-reply="false"
+                             reply-timeout="30000"/>]]></programlisting>
+    <note>
+      A 'reply-channel' may also be provided, but it is recommended to rely on the temporary anonymous channel
+      that will be created automatically for handling replies.
+    </note>
+    </para>
+    <para>
+    To configure the outbound gateway you can use the namespace support as well. The following code snippet shows the different configuration for an outbound HttpInvoker gateway. Only the 'url' and 'request-channel' are required.
+    <programlisting language="xml"><![CDATA[<httpinvoker:outbound-gateway id="outboundGateway"
+                              url="http://localhost:8080/example"
+                              request-channel="requestChannel"
+                              request-timeout="5000"
+                              reply-channel="replyChannel"
+                              reply-timeout="10000"/>]]></programlisting>
+    </para>
+  </section>
+</chapter>

docs/src/reference/docbook/images/callouts/1.svg

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M10.428,10.411h0.56c3.78,0,4.788-1.96,4.872-3.444h3.22v19.88h-3.92V13.154h-4.732V10.411z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/10.svg

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.815,10.758h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76v17.04h-3.36V13.11H3.815V10.758z"/>
+		<path style="fill:#FFFFFF;" d="M22.175,7.806c4.009,0,5.904,2.76,5.904,8.736c0,5.975-1.896,8.76-5.904,8.76
+			c-4.008,0-5.904-2.785-5.904-8.76C16.271,10.566,18.167,7.806,22.175,7.806z M22.175,22.613c1.921,0,2.448-1.68,2.448-6.071
+			c0-4.393-0.527-6.049-2.448-6.049c-1.92,0-2.448,1.656-2.448,6.049C19.727,20.934,20.255,22.613,22.175,22.613z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/11.svg

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M5.209,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H5.209V10.412z"/>
+		<path style="fill:#FFFFFF;" d="M18.553,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.359V12.764h-4.056V10.412z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/12.svg

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M4.813,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H4.813V10.412z"/>
+		<path style="fill:#FFFFFF;" d="M17.316,13.484c0-5.545,4.056-6.024,5.568-6.024c3.265,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.553,5.544c-2.256,1.584-3.432,2.353-3.815,3.145h7.392V24.5h-11.64c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.353-2.424c-2.352,0-2.423,1.944-2.447,3.192H17.316z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/13.svg

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.813,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H3.813V10.412z"/>
+		<path style="fill:#FFFFFF;" d="M20.611,14.636h0.529c1.008,0,2.855-0.096,2.855-2.304c0-0.624-0.288-2.185-2.137-2.185
+			c-2.303,0-2.303,2.185-2.303,2.784h-3.12c0-3.191,1.8-5.472,5.64-5.472c2.279,0,5.279,1.152,5.279,4.752
+			c0,1.728-1.08,2.808-2.039,3.24V15.5c0.6,0.168,2.568,1.056,2.568,3.96c0,3.216-2.377,5.496-5.809,5.496
+			c-1.607,0-5.928-0.36-5.928-5.688h3.288l-0.024,0.024c0,0.912,0.24,2.976,2.496,2.976c1.344,0,2.52-0.911,2.52-2.808
+			c0-2.328-2.256-2.424-3.816-2.424V14.636z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/14.svg

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M4.146,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H4.146V10.412z"/>
+		<path style="fill:#FFFFFF;" d="M28.457,20.732h-1.896V24.5h-3.36v-3.768h-6.72v-2.904L22.746,7.46h3.815v10.656h1.896V20.732z
+			 M23.201,18.116c0-4.128,0.072-6.792,0.072-7.32h-0.048l-4.272,7.32H23.201z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/15.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.479,11.079h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76v17.04h-3.36V13.43H3.479V11.079z"/>
+		<path style="fill:#FFFFFF;" d="M19.342,14.943c0.625-0.433,1.392-0.937,3.048-0.937c2.279,0,5.16,1.584,5.16,5.496
+			c0,2.328-1.176,6.121-6.192,6.121c-2.664,0-5.376-1.584-5.544-5.016h3.36c0.144,1.391,0.888,2.326,2.376,2.326
+			c1.607,0,2.544-1.367,2.544-3.191c0-1.512-0.72-3.047-2.496-3.047c-0.456,0-1.608,0.023-2.256,1.223l-3-0.143l1.176-9.361h9.36
+			v2.832h-6.937L19.342,14.943z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/16.svg

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.813,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H3.813V10.412z"/>
+		<path style="fill:#FFFFFF;" d="M24.309,11.78c-0.097-0.96-0.721-1.633-1.969-1.633c-2.184,0-2.688,2.496-2.808,4.704L19.58,14.9
+			c0.456-0.624,1.296-1.416,3.191-1.416c3.529,0,5.209,2.712,5.209,5.256c0,3.72-2.28,6.216-5.568,6.216
+			c-5.16,0-6.168-4.32-6.168-8.568c0-3.24,0.432-8.928,6.336-8.928c0.695,0,2.641,0.264,3.48,1.104
+			c0.936,0.912,1.271,1.416,1.584,3.217H24.309z M22.172,16.172c-1.271,0-2.568,0.792-2.568,2.928c0,1.849,1.056,3.168,2.664,3.168
+			c1.225,0,2.353-0.936,2.353-3.239C24.62,16.868,23.229,16.172,22.172,16.172z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/17.svg

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.479,11.079h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76v17.04h-3.36V13.43H3.479V11.079z"/>
+		<path style="fill:#FFFFFF;" d="M27.838,11.006c-1.631,1.776-5.807,6.816-6.215,14.16h-3.457c0.36-6.816,4.632-12.24,6.072-13.776
+			h-8.472l0.072-2.976h12V11.006z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/18.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M4.813,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H4.813V10.412z"/>
+		<path style="fill:#FFFFFF;" d="M23.172,24.956c-4.392,0-5.904-2.856-5.904-5.185c0-0.863,0-3.119,2.592-4.319
+			c-1.344-0.672-2.064-1.752-2.064-3.336c0-2.904,2.328-4.656,5.304-4.656c3.528,0,5.4,2.088,5.4,4.44
+			c0,1.464-0.6,2.712-1.968,3.432c1.632,0.815,2.544,1.896,2.544,4.104C29.076,21.596,27.684,24.956,23.172,24.956z M23.124,16.916
+			c-1.224,0-2.4,0.792-2.4,2.64c0,1.632,0.936,2.712,2.472,2.712c1.752,0,2.424-1.512,2.424-2.688
+			C25.62,18.38,24.996,16.916,23.124,16.916z M25.284,12.26c0-1.296-0.888-2.112-1.968-2.112c-1.512,0-2.305,0.864-2.305,2.112
+			c0,1.008,0.744,2.112,2.185,2.112C24.516,14.372,25.284,13.484,25.284,12.26z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/19.svg

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M4.146,10.746h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76v17.041h-3.36V13.097H4.146V10.746z"/>
+		<path style="fill:#FFFFFF;" d="M20.225,20.898v0.023c0.192,1.176,0.936,1.68,1.968,1.68c1.392,0,2.783-1.176,2.808-4.752
+			l-0.048-0.049c-0.768,1.152-2.088,1.441-3.24,1.441c-3.264,0-5.16-2.473-5.16-5.329c0-4.176,2.472-6.12,5.808-6.12
+			c5.904,0,6,6.36,6,8.76c0,6.601-3.12,8.736-6.192,8.736c-2.904,0-4.992-1.68-5.28-4.391H20.225z M22.434,16.553
+			c1.176,0,2.472-0.84,2.472-2.855c0-1.944-0.841-3.145-2.568-3.145c-0.864,0-2.424,0.433-2.424,2.88
+			C19.913,16.001,21.161,16.553,22.434,16.553z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/2.svg

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M9.668,12.328c0-6.469,4.732-7.028,6.496-7.028c3.808,0,6.833,2.24,6.833,6.271
+			c0,3.416-2.213,5.152-4.145,6.469c-2.632,1.848-4.004,2.744-4.452,3.668h8.624v3.472H9.444c0.14-2.324,0.308-4.76,4.62-7.896
+			c3.584-2.604,5.012-3.612,5.012-5.853c0-1.315-0.84-2.828-2.744-2.828c-2.744,0-2.828,2.269-2.856,3.725H9.668z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/20.svg

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/>
+		<path style="fill:#FFFFFF;" d="M23.172,7.46c4.008,0,5.904,2.76,5.904,8.736c0,5.976-1.896,8.76-5.904,8.76
+			s-5.904-2.784-5.904-8.76C17.268,10.22,19.164,7.46,23.172,7.46z M23.172,22.268c1.92,0,2.448-1.68,2.448-6.071
+			c0-4.393-0.528-6.049-2.448-6.049s-2.448,1.656-2.448,6.049C20.724,20.588,21.252,22.268,23.172,22.268z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/21.svg

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M5.306,13.151c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392v2.976H5.114c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H5.306z"/>
+		<path style="fill:#FFFFFF;" d="M19.49,10.079h0.48c3.239,0,4.104-1.681,4.176-2.952h2.761v17.04h-3.361V12.431H19.49V10.079z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/22.svg

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/>
+		<path style="fill:#FFFFFF;" d="M17.316,13.484c0-5.545,4.056-6.024,5.568-6.024c3.265,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.553,5.544c-2.256,1.584-3.432,2.353-3.815,3.145h7.392V24.5h-11.64c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.353-2.424c-2.352,0-2.423,1.944-2.447,3.192H17.316z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/23.svg

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/>
+		<path style="fill:#FFFFFF;" d="M21.612,14.636h0.528c1.008,0,2.855-0.096,2.855-2.304c0-0.624-0.287-2.185-2.136-2.185
+			c-2.304,0-2.304,2.185-2.304,2.784h-3.12c0-3.191,1.8-5.472,5.64-5.472c2.28,0,5.28,1.152,5.28,4.752
+			c0,1.728-1.08,2.808-2.04,3.24V15.5c0.6,0.168,2.568,1.056,2.568,3.96c0,3.216-2.377,5.496-5.809,5.496
+			c-1.607,0-5.928-0.36-5.928-5.688h3.288l-0.024,0.024c0,0.912,0.24,2.976,2.496,2.976c1.344,0,2.521-0.911,2.521-2.808
+			c0-2.328-2.257-2.424-3.816-2.424V14.636z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/24.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M4.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H4.78c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H4.972z"/>
+		<path style="fill:#FFFFFF;" d="M30.124,20.732h-1.896V24.5h-3.36v-3.768h-6.72v-2.904L24.412,7.46h3.816v10.656h1.896V20.732z
+			 M24.868,18.116c0-4.128,0.071-6.792,0.071-7.32h-0.047l-4.272,7.32H24.868z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/25.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/>
+		<path style="fill:#FFFFFF;" d="M20.676,14.276c0.624-0.433,1.393-0.937,3.049-0.937c2.279,0,5.16,1.584,5.16,5.496
+			c0,2.328-1.177,6.12-6.193,6.12c-2.664,0-5.375-1.584-5.543-5.016h3.36c0.144,1.392,0.889,2.327,2.376,2.327
+			c1.608,0,2.544-1.367,2.544-3.191c0-1.513-0.72-3.048-2.496-3.048c-0.455,0-1.607,0.023-2.256,1.224l-3-0.144l1.176-9.36h9.36
+			v2.832h-6.937L20.676,14.276z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/26.svg

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/>
+		<path style="fill:#FFFFFF;" d="M25.309,11.78c-0.097-0.96-0.721-1.633-1.969-1.633c-2.184,0-2.688,2.496-2.808,4.704L20.58,14.9
+			c0.456-0.624,1.296-1.416,3.191-1.416c3.529,0,5.209,2.712,5.209,5.256c0,3.72-2.28,6.216-5.568,6.216
+			c-5.16,0-6.168-4.32-6.168-8.568c0-3.24,0.432-8.928,6.336-8.928c0.695,0,2.641,0.264,3.48,1.104
+			c0.936,0.912,1.271,1.416,1.584,3.217H25.309z M23.172,16.172c-1.271,0-2.568,0.792-2.568,2.928c0,1.849,1.056,3.168,2.664,3.168
+			c1.225,0,2.353-0.936,2.353-3.239C25.62,16.868,24.229,16.172,23.172,16.172z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/27.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/>
+		<path style="fill:#FFFFFF;" d="M29.172,10.34c-1.632,1.776-5.808,6.816-6.216,14.16H19.5c0.36-6.816,4.632-12.24,6.072-13.776
+			H17.1l0.072-2.976h12V10.34z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/28.svg

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/>
+		<path style="fill:#FFFFFF;" d="M23.172,24.956c-4.392,0-5.904-2.856-5.904-5.185c0-0.863,0-3.119,2.592-4.319
+			c-1.344-0.672-2.064-1.752-2.064-3.336c0-2.904,2.328-4.656,5.304-4.656c3.528,0,5.4,2.088,5.4,4.44
+			c0,1.464-0.6,2.712-1.968,3.432c1.632,0.815,2.544,1.896,2.544,4.104C29.076,21.596,27.684,24.956,23.172,24.956z M23.124,16.916
+			c-1.224,0-2.4,0.792-2.4,2.64c0,1.632,0.936,2.712,2.472,2.712c1.752,0,2.424-1.512,2.424-2.688
+			C25.62,18.38,24.996,16.916,23.124,16.916z M25.284,12.26c0-1.296-0.888-2.112-1.968-2.112c-1.512,0-2.305,0.864-2.305,2.112
+			c0,1.008,0.744,2.112,2.185,2.112C24.516,14.372,25.284,13.484,25.284,12.26z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/29.svg

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376
+			c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768
+			c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/>
+		<path style="fill:#FFFFFF;" d="M20.893,20.564v0.023c0.191,1.176,0.936,1.68,1.967,1.68c1.393,0,2.785-1.176,2.809-4.752
+			l-0.048-0.048c-0.769,1.152-2.088,1.44-3.24,1.44c-3.264,0-5.16-2.473-5.16-5.328c0-4.176,2.472-6.12,5.807-6.12
+			c5.904,0,6.001,6.36,6.001,8.76c0,6.601-3.12,8.736-6.192,8.736c-2.904,0-4.992-1.68-5.28-4.392H20.893z M23.1,16.22
+			c1.176,0,2.473-0.84,2.473-2.855c0-1.944-0.84-3.145-2.568-3.145c-0.863,0-2.424,0.433-2.424,2.88
+			C20.58,15.668,21.828,16.22,23.1,16.22z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/3.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M15.127,14.005h0.616c1.176,0,3.332-0.112,3.332-2.688c0-0.728-0.336-2.548-2.492-2.548
+			c-2.688,0-2.688,2.548-2.688,3.248h-3.64c0-3.724,2.1-6.384,6.58-6.384c2.66,0,6.16,1.344,6.16,5.544
+			c0,2.016-1.261,3.276-2.38,3.78v0.056c0.699,0.196,2.996,1.232,2.996,4.62c0,3.752-2.772,6.412-6.776,6.412
+			c-1.876,0-6.916-0.42-6.916-6.636h3.836l-0.028,0.027c0,1.064,0.28,3.473,2.912,3.473c1.568,0,2.94-1.064,2.94-3.276
+			c0-2.716-2.632-2.828-4.452-2.828V14.005z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/30.svg

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M8.268,14.636h0.528c1.008,0,2.856-0.096,2.856-2.304c0-0.624-0.288-2.185-2.136-2.185
+			c-2.304,0-2.304,2.185-2.304,2.784h-3.12c0-3.191,1.8-5.472,5.64-5.472c2.28,0,5.28,1.152,5.28,4.752
+			c0,1.728-1.08,2.808-2.04,3.24V15.5c0.6,0.168,2.568,1.056,2.568,3.96c0,3.216-2.376,5.496-5.808,5.496
+			c-1.608,0-5.928-0.36-5.928-5.688h3.288l-0.024,0.024c0,0.912,0.24,2.976,2.496,2.976c1.344,0,2.52-0.911,2.52-2.808
+			c0-2.328-2.256-2.424-3.816-2.424V14.636z"/>
+		<path style="fill:#FFFFFF;" d="M23.172,7.46c4.008,0,5.904,2.76,5.904,8.736c0,5.976-1.896,8.76-5.904,8.76
+			s-5.904-2.784-5.904-8.76C17.268,10.22,19.164,7.46,23.172,7.46z M23.172,22.268c1.92,0,2.448-1.68,2.448-6.071
+			c0-4.393-0.528-6.049-2.448-6.049s-2.448,1.656-2.448,6.049C20.724,20.588,21.252,22.268,23.172,22.268z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/4.svg

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M21.891,20.784h-2.212v4.396h-3.92v-4.396h-7.84v-3.389L15.227,5.3h4.452v12.432h2.212V20.784z
+			 M15.759,17.731c0-4.815,0.084-7.924,0.084-8.54h-0.056l-4.984,8.54H15.759z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/5.svg

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M14.035,14.252c0.728-0.504,1.624-1.092,3.556-1.092c2.66,0,6.02,1.848,6.02,6.411
+			c0,2.717-1.372,7.141-7.224,7.141c-3.108,0-6.272-1.849-6.468-5.853h3.92c0.168,1.624,1.036,2.717,2.772,2.717
+			c1.876,0,2.968-1.597,2.968-3.725c0-1.764-0.839-3.556-2.912-3.556c-0.532,0-1.876,0.028-2.632,1.428l-3.5-0.168l1.372-10.92
+			h10.919v3.304h-8.092L14.035,14.252z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/6.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M19.106,10.673c-0.112-1.12-0.84-1.904-2.296-1.904c-2.548,0-3.136,2.912-3.276,5.488l0.056,0.056
+			c0.532-0.728,1.512-1.651,3.724-1.651c4.116,0,6.077,3.164,6.077,6.131c0,4.34-2.66,7.252-6.497,7.252
+			c-6.02,0-7.196-5.039-7.196-9.996c0-3.78,0.504-10.416,7.392-10.416c0.812,0,3.08,0.308,4.061,1.288
+			c1.092,1.063,1.483,1.652,1.848,3.752H19.106z M16.614,15.797c-1.484,0-2.996,0.924-2.996,3.416c0,2.156,1.232,3.697,3.108,3.697
+			c1.428,0,2.745-1.094,2.745-3.781C19.471,16.609,17.846,15.797,16.614,15.797z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/7.svg

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M24.28,9.66c-1.904,2.071-6.776,7.951-7.252,16.52h-4.032c0.42-7.952,5.404-14.28,7.084-16.072
+			h-9.884l0.084-3.472h14V9.66z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/8.svg

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M16.28,26.712c-5.124,0-6.888-3.332-6.888-6.048c0-1.009,0-3.641,3.024-5.04
+			c-1.568-0.784-2.408-2.044-2.408-3.893c0-3.388,2.716-5.432,6.188-5.432c4.116,0,6.3,2.436,6.3,5.18
+			c0,1.708-0.7,3.164-2.296,4.004c1.903,0.952,2.968,2.212,2.968,4.788C23.168,22.792,21.544,26.712,16.28,26.712z M16.224,17.332
+			c-1.428,0-2.8,0.924-2.8,3.08c0,1.903,1.092,3.164,2.884,3.164c2.043,0,2.829-1.765,2.829-3.137
+			C19.137,19.04,18.408,17.332,16.224,17.332z M18.744,11.899c0-1.512-1.036-2.464-2.296-2.464c-1.764,0-2.688,1.008-2.688,2.464
+			c0,1.177,0.868,2.464,2.548,2.464C17.848,14.363,18.744,13.328,18.744,11.899z"/>
+	</g>
+</g>
+</svg>

docs/src/reference/docbook/images/callouts/9.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448)  -->
+<!DOCTYPE svg [
+	<!ENTITY ns_svg "http://www.w3.org/2000/svg">
+	<!ENTITY ns_xlink "http://www.w3.org/1999/xlink">
+]>
+<svg  version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33"
+	 style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve">
+<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/>
+<g>
+	<g style="enable-background:new    ;">
+		<path style="fill:#FFFFFF;" d="M13.953,21.921v0.027c0.224,1.372,1.092,1.961,2.296,1.961c1.624,0,3.248-1.372,3.276-5.545
+			l-0.057-0.056c-0.896,1.344-2.436,1.68-3.78,1.68c-3.808,0-6.02-2.884-6.02-6.216c0-4.872,2.884-7.14,6.776-7.14
+			c6.888,0,7,7.42,7,10.22c0,7.7-3.641,10.192-7.224,10.192c-3.388,0-5.824-1.96-6.16-5.124H13.953z M16.529,16.853
+			c1.372,0,2.884-0.979,2.884-3.332c0-2.268-0.98-3.668-2.996-3.668c-1.008,0-2.828,0.504-2.828,3.36
+			C13.589,16.209,15.045,16.853,16.529,16.853z"/>
+	</g>
+</g>
+</svg>