Merge pull request #228 from olegz/INT-2261

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,95 @@
+<?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>
+      The <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>
+    The <emphasis>Resource Inbound Channel Adapter</emphasis> is a polling adapter that creates a <classname>Message</classname> 
+    whose payload is a collection of <classname>Resource</classname> objects.
+    </para>
+    <para>
+    <classname>Resource</classname> objects are resolved based on the pattern specified using the <code>pattern</code> attribute. 
+    The collection of resolved <classname>Resource</classname> objects is then sent as a payload within a
+    <classname>Message</classname> to the adapter's channel. That is one major difference between <emphasis>Resource Inbound Channel Adapter</emphasis> 
+    and <emphasis>File Inbound Channel Adapter</emphasis>; the latter buffers File objects and sends a single <classname>File</classname> object per 
+    <classname>Message</classname>.
+    </para>
+    <para>
+    Below is an example of a very simple configuration which will find all files ending with the 'properties' 
+    extension in the <code>foo.bar</code> package available on the classpath and will send them as 
+    the payload of a Message to the channel named '<code>resultChannel</code>':
+    
+      <programlisting language="xml"><![CDATA[<int:resource-inbound-channel-adapter id="resourceAdapter"
+               channel="resultChannel" 
+               pattern="classpath:foo/bar/*.properties">
+    <int:poller fixed-rate="1000"/>
+</int:resource-inbound-channel-adapter>]]></programlisting>
+    </para>
+    <para>
+      The <emphasis>Resource Inbound Channel Adapter</emphasis> relies on the 
+      <classname>org.springframework.core.io.support.ResourcePatternResolver</classname> strategy interface to resolve the provided pattern. 
+      It defaults to an instance of the current <classname>ApplicationContext</classname>. However you may provide a reference to an instance
+      of your own implementation of <classname>ResourcePatternResolver</classname> using the <code>pattern-resolver</code> attribute:
+      <programlisting language="xml"><![CDATA[<int:resource-inbound-channel-adapter id="resourceAdapter"
+               channel="resultChannel" 
+               pattern="classpath:foo/bar/*.properties"
+               pattern-resolver="myPatternResolver">
+    <int:poller fixed-rate="1000"/>
+</int:resource-inbound-channel-adapter>
+
+<bean id="myPatternResolver" class="org.example.MyPatternResolver"/>]]></programlisting>
+    </para>
+    <para>
+      You may have a use case where you need to further filter the collection of resources 
+      resolved by the <classname>ResourcePatternResolver</classname>. For example, you may want to prevent resources 
+      that were resolved already from appearing in a collection of resolved resources ever again. On the other hand 
+      your resources might be updated rather often and you <emphasis>do</emphasis> want them to be picked up again.
+      In other words there is a valid use case for defining an additional filter as well as disabling filtering altogether. 
+      You can provide your own implementation of the <classname>org.springframework.integration.util.CollectionFilter</classname> 
+      strategy interface:
+      <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 elements
+		(which would be <classname>Resource</classname> objects in this case), and it returns a collection of
+		filtered elements of that same type.
+
+    </para>
+    <para>
+    If you are defining the adapter via XML but you do not specify a filter reference, a default implementation of
+    <classname>CollectionFilter</classname> will be used by the <emphasis>Resource Inbound Channel Adapter</emphasis>.
+    The implementation class of that default filter is <classname>org.springframework.integration.util.AcceptOnceCollectionFilter</classname>.
+    It 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> instead, use the <code>filter</code> attribute.
+      <programlisting language="xml"><![CDATA[<int:resource-inbound-channel-adapter id="resourceAdapter"
+               channel="resultChannel" 
+               pattern="classpath:foo/bar/*.properties"
+               filter="myFilter">
+    <int:poller fixed-rate="1000"/>
+</int:resource-inbound-channel-adapter>
+
+<bean id="myFilter" class="org.example.MyFilter"/>]]></programlisting>
+
+    If you don't need any filtering and want to disable even the default <classname>CollectionFilter</classname> strategy,
+    simply provide an empty value for the 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>