INT-2261

added documentation for Resource Inbound Channel Adapter

  added resource.xml file

docs/src/reference/docbook/index.xml

@@ -140,6 +140,7 @@
       <xi:include href="./mail.xml"/>
       <xi:include href="./mongodb.xml"/>
       <xi:include href="./redis.xml"/>
+      <xi:include href="./resource.xml"/>
       <xi:include href="./rmi.xml"/>
       <xi:include href="./sftp.xml"/>
       <xi:include href="./stream.xml"/>

docs/src/reference/docbook/resource.xml

@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="resource"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Resource Support</title>
+
+  <section id="resource-intro">
+    <title>Introduction</title>
+    <para>
+      <emphasis>Resource Inbound Channel Adapter</emphasis> builds upon Spring's <classname>Resource</classname> abstraction to 
+      support greater flexibility across a variety of actual types of underlying resources, such as a file, a URL, 
+      or a class path resource. Therefore, it's similar to but more generic than the 
+      <emphasis>File Inbound Channel Adapter</emphasis>.
+    </para>
+  </section>
+
+  <section id="resource-inbound-channel-adapter">
+    <title>Resource Inbound Channel Adapter</title>
+    <para>
+    <emphasis>Resource Inbound Channel Adapter</emphasis> is a polling adapter that creates a <classname>Message</classname> 
+    with collection of <classname>Resource</classname> objects as payload
+    </para>
+    <para>
+    <classname>Resource</classname> objects are resolved based on the pattern specified using <code>pattern</code> attribute. 
+    The collection of the resolved <classname>Resource</classname> objects is than sent as a payload with an 
+    outgoing <classname>Message</classname>. That is one major difference that <emphasis>Resource Inbound Channel Adapter</emphasis> 
+    has with <emphasis>File Inbound Channel Adapter</emphasis> which buffers File objects and sends a single <classname>File</classname> object per 
+    <classname>Message</classname>.
+    </para>
+    <para>
+    Below is an example of very simple configuration which will find all files with 'property' 
+    extension in the <code>foo.bar</code> package available on the classpath and will send them as 
+    payload of a Message to <code>resultChannel</code>:
+    
+      <programlisting language="xml"><![CDATA[<int:resource-inbound-channel-adapter id="resourceAdapterDefault" channel="resultChannel" 
+               pattern="classpath:foo/bar/*.property">
+	<int:poller fixed-rate="1000"/>
+</int:resource-inbound-channel-adapter>]]></programlisting>
+    </para>
+    <para>
+      <emphasis>Resource Inbound Channel Adapter</emphasis> relies on 
+      <classname>org.springframework.core.io.support.ResourcePatternResolver</classname> to resolve provided pattern. 
+      It defaults to an instance of the current <classname>ApplicationContext</classname>. However you may provide your own 
+      instance of the <classname>ResourcePatternResolver</classname> using <code>pattern-resolver</code> attribute:
+      <programlisting language="xml"><![CDATA[<int:resource-inbound-channel-adapter id="resourceAdapter" channel="resultChannel" 
+               pattern="classpath:foo/bar/*.property" pattern-resolver="myPatternResolver">
+	<int:poller fixed-rate="1000"/>
+</int:resource-inbound-channel-adapter>
+
+<bean id="myPatternResolver" class="org.bar.MyPatternResolver"/>]]></programlisting>
+    </para>
+    <para>
+      There may be a use case where you might want to filter resources in addition to what was already 
+      resolved by the <classname>ResourcePatternResolver</classname>. For example, you may want to prevent resources 
+      that were resolved once to never appear in the collection of resolved resources ever again. On the other hand 
+      your resources might be updated rather often and you DO want them to be picked up again. In other words 
+      there is a valid use case for defining an additional filter as well as use no additional filtering at all. 
+      You can accomplish this by providing your own implementation of <classname>org.springframework.integration.util.CollectionFilter</classname> 
+      strategy:
+      <programlisting language="java"><![CDATA[public interface CollectionFilter<T> {
+
+	Collection<T> filter(Collection<T> unfilteredElements);
+
+}]]></programlisting>
+		
+		As you can see the <classname>CollectionFilter</classname> receives a collection of un-filtered <classname>Resource</classname>
+		 objects and returns a collection of filtered <classname>Resource</classname> objects.
+
+    </para>
+    <para>
+    The default implementation of <classname>CollectionFilter</classname> used by the <emphasis>Resource Inbound Channel Adapter</emphasis> 
+    is <classname>org.springframework.integration.util.AcceptOnceCollectionFilter</classname> which remembers the 
+    elements passed in the previous invocation in order to avoid returning those elements more than once.
+    </para>
+    <para>
+      To inject your own implementation of <classname>CollectionFilter</classname> use <code>filter</code> attribute.
+      <programlisting language="xml"><![CDATA[<int:resource-inbound-channel-adapter id="resourceAdapter" channel="resultChannel" 
+               pattern="classpath:foo/bar/*.property" filter="myFilter">
+	<int:poller fixed-rate="1000"/>
+</int:resource-inbound-channel-adapter>
+
+<bean id="myFilter" class="org.bar.MyFilter"/>]]></programlisting>
+
+    If you don't need any additional filtering and you want to disable default <classname>CollectionFilter</classname> strategy 
+    simply configure empty filter attribute (e.g., <code>filter=""</code>)
+    </para>
+  </section>
+
+</chapter>

docs/src/reference/docbook/whats-new.xml

@@ -92,6 +92,18 @@
             <para>
                 For further details please see <xref linkend="redis"/>.
             </para>
+        </section>
+        <section id="2.1-new-resource-support">
+            <title>Support for Spring's Resource abstraction</title>
+            <para>
+                As of version 2.1, we've introduced a new <emphasis>Resource Inbound Channel Adapter</emphasis> that builds upon 
+                Spring's Resource abstraction to support greater flexibility across a variety of actual types of 
+                underlying resources, such as a file, a URL, or a class path resource. Therefore, it's similar to but 
+                more generic than the <emphasis>File Inbound Channel Adapter</emphasis>.
+            </para>
+             <para>
+                For further details please see <xref linkend="resource-inbound-channel-adapter"/>.
+            </para>
         </section>
 		<section id="2.1-new-stored-proc-support">
 		    <title>Stored Procedure Components</title>