* Started writing up the VFS and the data types.

* Moved selectors into their own package.
* Added <is-empty> selector.


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271599 13f79535-47bb-0310-9956-ffa450edef68

proposal/myrmidon/docs/user.html

@@ -65,6 +65,70 @@ to use Ant 1.4.1 or later.  The default target builds the Myrmidon distribution
 into the <code>dist</code> directory.  The distribution is a ready-to-run
 installation of Myrmidon.
 </p>
+                                <p>There are a number features that are not built unless the appropriate optional Jar
+files are found in the <code>lib</code> directory:</p>
+                                  <table>
+              <tr>
+                  <td bgcolor="#039acc" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Feature
+        </font>
+  </td>
+                      <td bgcolor="#039acc" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Jar File
+        </font>
+  </td>
+                      <td bgcolor="#039acc" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Download From
+        </font>
+  </td>
+      </tr>
+                  <tr>
+                  <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          SMB VFS support (Samba, Windows shares)
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          jcifs.jar
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          <a href="http://jcifs.samba.org">jcifs.samba.org</a>
+        </font>
+  </td>
+      </tr>
+                  <tr>
+                  <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          FTP VFS support
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          netcomponents.jar
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          <a href="http://www.savarese.org/oro/software/NetComponents.html">www.savarese.org</a>
+        </font>
+  </td>
+      </tr>
+        </table>
                     </blockquote>
     </td></tr>
   </table>
@@ -731,6 +795,332 @@ attributes:</p>
   </table>
                     </blockquote>
     </td></tr>
+  </table>
+        <table border="0" cellspacing="0" cellpadding="2" width="100%">
+    <tr><td bgcolor="#525D76">
+      <font color="#ffffff" face="arial,helvetica,sanserif">
+        <a name="Handling Files"><strong>Handling Files</strong></a>
+      </font>
+    </td></tr>
+    <tr><td>
+      <blockquote>
+                        <p>Myrmidon includes a Virtual File System (VFS), which allows files from
+different sources to be treated identically.  The VFS currently supports
+the following file types:</p>
+                                  <table>
+              <tr>
+                  <td bgcolor="#039acc" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          File System
+        </font>
+  </td>
+                      <td bgcolor="#039acc" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Description
+        </font>
+  </td>
+                      <td bgcolor="#039acc" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          URL Format
+        </font>
+  </td>
+      </tr>
+                  <tr>
+                  <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Local Files
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Files on the local file system.
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Three different formats are currently supported for local file names:
+            <ul>
+                <li><code>file://</code> <i>absolute-file-name</i></li>
+                <li>Absolute file names</li>
+                <li>Relative file names.  These are resolved relative to the
+                project's base directory.
+                </li>
+            </ul>
+        
+        </font>
+  </td>
+      </tr>
+                  <tr>
+                  <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Zip Files
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          The contents of Zip files (and Jar, War, and Ear files).
+        Currently, the VFS supports read-only access to Zip file contents,
+        and only for local Zip files.
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          <code>zip://</code> <i>zip-file-path</i> [<code>!</code><i>absolute-path</i>]
+        </font>
+  </td>
+      </tr>
+                  <tr>
+                  <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          FTP
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Files on an FTP server.
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          <code>ftp://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]
+        </font>
+  </td>
+      </tr>
+                  <tr>
+                  <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          SMB
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Files on a CFIS server, such as Samba or Windows shares.
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          <code>smb://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]
+        </font>
+  </td>
+      </tr>
+        </table>
+                                <p>Here are some example URLs:</p>
+                                <ul>
+    <li><code>build/classes</code></li>
+    <li><code>c:\program files\ant\bin</code></li>
+    <li><code>file://C:/program files/ant</code></li>
+    <li><code>zip://build/lib/ant.jar!/org/apache/tools</code></li>
+    <li><code>ftp://adam@somehost/pub/downloads</code></li>
+    <li><code>smb://password:adam@somehost/home/adam</code></li>
+</ul>
+                                <p>Currently, there are only a handful of VFS aware tasks.  This will grow
+as more tasks are ported to the new API, and data types.</p>
+                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
+    <tr><td bgcolor="#828DA6">
+      <font color="#ffffff" face="arial,helvetica,sanserif">
+        <a name="File Sets"><strong>File Sets</strong></a>
+      </font>
+    </td></tr>
+    <tr><td>
+      <blockquote>
+                        <p>A file set in Myrmidon is more general than Ant 1's concept of a file set.
+Firstly, there is more than one type of file set.  Secondly, they are VFS enabled.
+File sets are automatically converted to a <a href="#Paths">path</a>, and so
+can be used anywhere that a path can.</p>
+                                <h3><code>&lt;v-fileset&gt;</code></h3>
+                                <p>This is the equivalent of Ant 1's <code>&lt;fileset&gt;</code> (The name
+is temporary, it will be changed to <code>&lt;fileset&gt;</code> once more
+porting work as been completed).</p>
+                                <p>Rather than use a set of include and exclude patterns to choose the files
+that make up the file set, <code>&lt;v-fileset&gt;</code> takes zero or more
+<a href="#File Selectors">file selectors</a>.  File selectors can be used to
+select files based on any attribute of the file, rather than just the name.
+You can use <code>&lt;name&gt;</code> selectors to achieve the same result
+as using includes or excludes.</p>
+                                <p>A <code>&lt;v-fileset&gt;</code> element takes the following attributes:</p>
+                                  <table>
+              <tr>
+                  <td bgcolor="#039acc" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Attribute
+        </font>
+  </td>
+                      <td bgcolor="#039acc" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Description
+        </font>
+  </td>
+                      <td bgcolor="#039acc" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Default Value
+        </font>
+  </td>
+      </tr>
+                  <tr>
+                  <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          dir
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          The base directory for the file set.  This can be any URL that the
+        VFS supports.
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Required
+        </font>
+  </td>
+      </tr>
+        </table>
+                                <p>A <code>&lt;v-fileset&gt;</code> element takes any number of nested
+<a href="#File Selectors">file selector</a> elements.  To be included in the
+file set, a file must be selected by all the file selectors.  That is, the
+file selectors are implicitly AND-ed together.  If no file selector is provided,
+all the files and directories are included in the set.</p>
+                                <p>An example:</p>
+                                  <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+      <tr>
+        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#ffffff"><pre>
+
+&lt;v-fileset dir=&quot;src&quot;&gt;
+    &lt;name pattern=&quot;org/apache/tools/ant/**&quot;/&gt;
+    &lt;is-file/&gt;
+&lt;/v-fileset&gt;
+</pre></td>
+        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+    </table>
+  </div>
+                                <h3><code>&lt;flat-fileset&gt;</code></h3>
+                                <p>This file set takes a set of nested file sets and paths, and flattens them
+into a single directory.  It can be used as a way of converting a path into a
+file set.  It can also be used as a replacement for the <code>flatten</code>
+attribute for the copy and move tasks.</p>
+                                <p>A <code>&lt;flat-fileset&gt;</code> element takes no attributes, and a set
+of nested paths or file sets.</p>
+                                <p>An example:</p>
+                                  <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+      <tr>
+        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#ffffff"><pre>
+
+&lt;v-copy todir=&quot;dist/lib&quot;&gt;
+  &lt;flat-fileset&gt;
+    &lt;v-fileset dir=&quot;build/lib&quot;&gt;
+        &lt;basename pattern=&quot;*.jar&quot;/&gt;
+    &lt;v-fileset&gt;
+    &lt;v-path path=&quot;${classpath}&quot;/&gt;
+  &lt;/flat-fileset&gt;
+&lt;/v-copy&gt;
+</pre></td>
+        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+    </table>
+  </div>
+                    </blockquote>
+    </td></tr>
+  </table>
+                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
+    <tr><td bgcolor="#828DA6">
+      <font color="#ffffff" face="arial,helvetica,sanserif">
+        <a name="Paths"><strong>Paths</strong></a>
+      </font>
+    </td></tr>
+    <tr><td>
+      <blockquote>
+                        <p>Paths are an ordered list of files.</p>
+                                <h3><code>&lt;v-path&gt;</code></h3>
+                                <p>This is the equivalent of Ant 1's <code>&lt;path&gt;</code>.</p>
+                                <h3><code>&lt;filtered-path&gt;</code></h3>
+                                <p>A path that applies file selectors to a set of nested file sets and paths.</p>
+                    </blockquote>
+    </td></tr>
+  </table>
+                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
+    <tr><td bgcolor="#828DA6">
+      <font color="#ffffff" face="arial,helvetica,sanserif">
+        <a name="File Selectors"><strong>File Selectors</strong></a>
+      </font>
+    </td></tr>
+    <tr><td>
+      <blockquote>
+                        <p>File selectors are used to select files from file sets and paths.</p>
+                                <h3><code>&lt;and&gt;</code></h3>
+                                <p>Combines zero or more file selectors, using AND. An empty <code>&lt;and&gt;</code>
+selector accepts all files.</p>
+                                <h3><code>&lt;basename&gt;</code></h3>
+                                <p>Selects files whose base name matches an Ant 1 style pattern, or a regular
+expression.</p>
+                                <h3><code>&lt;exists&gt;</code></h3>
+                                <p>Selects files that exist.</p>
+                                <h3><code>&lt;is-empty&gt;</code></h3>
+                                <p>Selects empty folders, that is, folders that have no children.</p>
+                                <h3><code>&lt;is-folder&gt;</code></h3>
+                                <p>Selects folders, does not select regular files.</p>
+                                <h3><code>&lt;is-file&gt;</code></h3>
+                                <p>Selects regular files, does not select folders.</p>
+                                <h3><code>&lt;name&gt;</code></h3>
+                                <p>Selects files whose path in a file set matches an Ant 1 style pattern, or
+a regular expression.</p>
+                                <h3><code>&lt;not&gt;</code></h3>
+                                <p>Selects files that are not selected by a nested file selector.</p>
+                                <h3><code>&lt;or&gt;</code></h3>
+                                <p>Combines zero or more file selectors, using OR. An empty <code>&lt;or&gt;</code>
+selector accepts all files.</p>
+                                <h3><code>&lt;url&gt;</code></h3>
+                                <p>Selects files whose URL matches an Ant 1 style pattern, or a regular expression.</p>
+                    </blockquote>
+    </td></tr>
+  </table>
+                    </blockquote>
+    </td></tr>
   </table>
         <table border="0" cellspacing="0" cellpadding="2" width="100%">
     <tr><td bgcolor="#525D76">

proposal/myrmidon/src/java/org/apache/antlib/vfile/DefaultFileSet.java

@@ -15,6 +15,7 @@ import org.apache.avalon.excalibur.i18n.ResourceManager;
 import org.apache.avalon.excalibur.i18n.Resources;
 import org.apache.myrmidon.api.TaskContext;
 import org.apache.myrmidon.api.TaskException;
+import org.apache.antlib.vfile.selectors.AndFileSelector;
 
 /**
  * A file set, that contains those files under a directory that match

proposal/myrmidon/src/java/org/apache/antlib/vfile/FilteredFileList.java

@@ -11,6 +11,7 @@ import java.util.ArrayList;
 import org.apache.aut.vfs.FileObject;
 import org.apache.myrmidon.api.TaskContext;
 import org.apache.myrmidon.api.TaskException;
+import org.apache.antlib.vfile.selectors.AndFileSelector;
 
 /**
  * A file-list which filters another.

proposal/myrmidon/src/java/org/apache/antlib/vfile/SingletonFileList.java

@@ -16,8 +16,6 @@ import org.apache.myrmidon.api.TaskException;
  *
  * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
  *
- * @ant:data-type name="v-file"
- * @ant:type type="v-path" name="v-file"
  */
 public class SingletonFileList
     implements FileList

proposal/myrmidon/src/java/org/apache/antlib/vfile/AbstractNameFileSelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/AbstractNameFileSelector.java

@@ -5,7 +5,7 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import org.apache.aut.vfs.FileObject;
 import org.apache.myrmidon.api.TaskContext;
@@ -17,6 +17,7 @@ import org.apache.oro.text.regex.Perl5Compiler;
 import org.apache.oro.text.regex.Perl5Matcher;
 import org.apache.avalon.excalibur.i18n.ResourceManager;
 import org.apache.avalon.excalibur.i18n.Resources;
+import org.apache.antlib.vfile.FileSelector;
 
 /**
  * An abstract file selector that selects files based on name.

proposal/myrmidon/src/java/org/apache/antlib/vfile/AndFileSelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/AndFileSelector.java

@@ -5,12 +5,13 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import java.util.ArrayList;
 import org.apache.aut.vfs.FileObject;
 import org.apache.myrmidon.api.TaskContext;
 import org.apache.myrmidon.api.TaskException;
+import org.apache.antlib.vfile.FileSelector;
 
 /**
  * A file selector that performs an AND of nested selectors.  Performs

proposal/myrmidon/src/java/org/apache/antlib/vfile/BaseNameFileSelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/BaseNameFileSelector.java

@@ -5,9 +5,10 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import org.apache.aut.vfs.FileObject;
+import org.apache.antlib.vfile.selectors.AbstractNameFileSelector;
 
 /**
  * A file selector that selects files based on their base-name.

proposal/myrmidon/src/java/org/apache/antlib/vfile/ExistenceFileSelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/ExistenceFileSelector.java

@@ -5,12 +5,13 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import org.apache.aut.vfs.FileObject;
 import org.apache.aut.vfs.FileSystemException;
 import org.apache.myrmidon.api.TaskContext;
 import org.apache.myrmidon.api.TaskException;
+import org.apache.antlib.vfile.FileSelector;
 
 /**
  * A file selector that only selects files that exist.

proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/IsEmptyFolderSelector.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (C) The Apache Software Foundation. All rights reserved.
+ *
+ * This software is published under the terms of the Apache Software License
+ * version 1.1, a copy of which has been included  with this distribution in
+ * the LICENSE.txt file.
+ */
+package org.apache.antlib.vfile.selectors;
+
+import org.apache.antlib.vfile.FileSelector;
+import org.apache.aut.vfs.FileObject;
+import org.apache.aut.vfs.FileType;
+import org.apache.aut.vfs.FileSystemException;
+import org.apache.myrmidon.api.TaskContext;
+import org.apache.myrmidon.api.TaskException;
+
+/**
+ * A file selector that selects empty directories.
+ *
+ * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
+ * @version $Revision$ $Date$
+ *
+ * @ant:data-type name="is-empty-folder-selector"
+ * @ant:type type="v-file-selector" name="is-empty"
+ */
+public class IsEmptyFolderSelector
+    implements FileSelector
+{
+    /**
+     * Accepts a file.
+     */
+    public boolean accept( final FileObject file,
+                           final String path,
+                           final TaskContext context )
+        throws TaskException
+    {
+        try
+        {
+            return ( file.exists()
+                     && file.getType() == FileType.FOLDER
+                     && file.getChildren().length == 0 );
+        }
+        catch( FileSystemException e )
+        {
+            throw new TaskException( e.getMessage(), e );
+        }
+    }
+}

proposal/myrmidon/src/java/org/apache/antlib/vfile/IsFileSelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/IsFileSelector.java

@@ -5,13 +5,14 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import org.apache.aut.vfs.FileObject;
 import org.apache.aut.vfs.FileSystemException;
 import org.apache.aut.vfs.FileType;
 import org.apache.myrmidon.api.TaskContext;
 import org.apache.myrmidon.api.TaskException;
+import org.apache.antlib.vfile.FileSelector;
 
 /**
  * A file selector which only selects files, not folders.

proposal/myrmidon/src/java/org/apache/antlib/vfile/IsDirectorySelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/IsFolderSelector.java

@@ -5,13 +5,14 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import org.apache.aut.vfs.FileObject;
 import org.apache.aut.vfs.FileSystemException;
 import org.apache.aut.vfs.FileType;
 import org.apache.myrmidon.api.TaskContext;
 import org.apache.myrmidon.api.TaskException;
+import org.apache.antlib.vfile.FileSelector;
 
 /**
  * A file selector which only selects folders, not files.
@@ -22,7 +23,7 @@ import org.apache.myrmidon.api.TaskException;
  * @ant:data-type name="is-folder-selector"
  * @ant:type type="v-file-selector" name="is-folder"
  */
-public class IsDirectorySelector
+public class IsFolderSelector
     implements FileSelector
 {
     /**

proposal/myrmidon/src/java/org/apache/antlib/vfile/NameFileSelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/NameFileSelector.java

@@ -5,9 +5,10 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import org.apache.aut.vfs.FileObject;
+import org.apache.antlib.vfile.selectors.AbstractNameFileSelector;
 
 /**
  * A file selector that selects files based on their name.

proposal/myrmidon/src/java/org/apache/antlib/vfile/NotFileSelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/NotFileSelector.java

@@ -5,11 +5,12 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import org.apache.aut.vfs.FileObject;
 import org.apache.myrmidon.api.TaskContext;
 import org.apache.myrmidon.api.TaskException;
+import org.apache.antlib.vfile.FileSelector;
 
 /**
  * A file selector that negates a nested file selector.

proposal/myrmidon/src/java/org/apache/antlib/vfile/OrFileSelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/OrFileSelector.java

@@ -5,12 +5,13 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import java.util.ArrayList;
 import org.apache.aut.vfs.FileObject;
 import org.apache.myrmidon.api.TaskContext;
 import org.apache.myrmidon.api.TaskException;
+import org.apache.antlib.vfile.FileSelector;
 
 /**
  * A file selector that performs an OR of nested selectors.  Performs

proposal/myrmidon/src/java/org/apache/antlib/vfile/UrlFileSelector.java → proposal/myrmidon/src/java/org/apache/antlib/vfile/selectors/UrlFileSelector.java

@@ -5,9 +5,10 @@
  * version 1.1, a copy of which has been included  with this distribution in
  * the LICENSE.txt file.
  */
-package org.apache.antlib.vfile;
+package org.apache.antlib.vfile.selectors;
 
 import org.apache.aut.vfs.FileObject;
+import org.apache.antlib.vfile.selectors.AbstractNameFileSelector;
 
 /**
  * A file selector that selects files based on their URL.

proposal/myrmidon/src/xdocs/user.xml

@@ -24,6 +24,23 @@ into the <code>dist</code> directory.  The distribution is a ready-to-run
 installation of Myrmidon.
 </p>
 
+<p>There are a number features that are not built unless the appropriate optional Jar
+files are found in the <code>lib</code> directory:</p>
+
+<table>
+    <tr><th>Feature</th><th>Jar File</th><th>Download From</th></tr>
+    <tr>
+        <td>SMB VFS support (Samba, Windows shares)</td>
+        <td>jcifs.jar</td>
+        <td><a href="http://jcifs.samba.org">jcifs.samba.org</a></td>
+    </tr>
+    <tr>
+        <td>FTP VFS support</td>
+        <td>netcomponents.jar</td>
+        <td><a href="http://www.savarese.org/oro/software/NetComponents.html">www.savarese.org</a></td>
+    </tr>
+</table>
+
 </section>
 
 <section name="Running Myrmidon">
@@ -291,6 +308,199 @@ attributes:</p>
 
 </section>
 
+<section name="Handling Files">
+
+<p>Myrmidon includes a Virtual File System (VFS), which allows files from
+different sources to be treated identically.  The VFS currently supports
+the following file types:</p>
+
+<table>
+    <tr><th>File System</th><th>Description</th><th>URL Format</th></tr>
+    <tr>
+        <td>Local Files</td>
+        <td>Files on the local file system.</td>
+        <td>Three different formats are currently supported for local file names:
+            <ul>
+                <li><code>file://</code> <i>absolute-file-name</i></li>
+                <li>Absolute file names</li>
+                <li>Relative file names.  These are resolved relative to the
+                project's base directory.
+                </li>
+            </ul>
+        </td>
+    </tr>
+    <tr>
+        <td>Zip Files</td>
+        <td>The contents of Zip files (and Jar, War, and Ear files).
+        Currently, the VFS supports read-only access to Zip file contents,
+        and only for local Zip files.</td>
+        <td><code>zip://</code> <i>zip-file-path</i> [<code>!</code><i>absolute-path</i>]</td>
+    </tr>
+    <tr>
+        <td>FTP</td>
+        <td>Files on an FTP server.</td>
+        <td><code>ftp://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]</td>
+    </tr>
+    <tr>
+        <td>SMB</td>
+        <td>Files on a CFIS server, such as Samba or Windows shares.</td>
+        <td><code>smb://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]</td>
+    </tr>
+</table>
+
+<p>Here are some example URLs:</p>
+
+<ul>
+    <li><code>build/classes</code></li>
+    <li><code>c:\program files\ant\bin</code></li>
+    <li><code>file://C:/program files/ant</code></li>
+    <li><code>zip://build/lib/ant.jar!/org/apache/tools</code></li>
+    <li><code>ftp://adam@somehost/pub/downloads</code></li>
+    <li><code>smb://password:adam@somehost/home/adam</code></li>
+</ul>
+
+<p>Currently, there are only a handful of VFS aware tasks.  This will grow
+as more tasks are ported to the new API, and data types.</p>
+
+<subsection name="File Sets">
+
+<p>A file set in Myrmidon is more general than Ant 1's concept of a file set.
+Firstly, there is more than one type of file set.  Secondly, they are VFS enabled.
+File sets are automatically converted to a <a href="#Paths">path</a>, and so
+can be used anywhere that a path can.</p>
+
+<h3><code>&lt;v-fileset&gt;</code></h3>
+
+<p>This is the equivalent of Ant 1's <code>&lt;fileset&gt;</code> (The name
+is temporary, it will be changed to <code>&lt;fileset&gt;</code> once more
+porting work as been completed).</p>
+
+<p>Rather than use a set of include and exclude patterns to choose the files
+that make up the file set, <code>&lt;v-fileset&gt;</code> takes zero or more
+<a href="#File Selectors">file selectors</a>.  File selectors can be used to
+select files based on any attribute of the file, rather than just the name.
+You can use <code>&lt;name&gt;</code> selectors to achieve the same result
+as using includes or excludes.</p>
+
+<p>A <code>&lt;v-fileset&gt;</code> element takes the following attributes:</p>
+
+<table>
+    <tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr>
+    <tr>
+        <td>dir</td>
+        <td>The base directory for the file set.  This can be any URL that the
+        VFS supports.</td>
+        <td>Required</td>
+    </tr>
+</table>
+
+<p>A <code>&lt;v-fileset&gt;</code> element takes any number of nested
+<a href="#File Selectors">file selector</a> elements.  To be included in the
+file set, a file must be selected by all the file selectors.  That is, the
+file selectors are implicitly AND-ed together.  If no file selector is provided,
+all the files and directories are included in the set.</p>
+
+<p>An example:</p>
+
+<source><![CDATA[
+
+<v-fileset dir="src">
+    <name pattern="org/apache/tools/ant/**"/>
+    <is-file/>
+</v-fileset>
+]]></source>
+
+<h3><code>&lt;flat-fileset&gt;</code></h3>
+
+<p>This file set takes a set of nested file sets and paths, and flattens them
+into a single directory.  It can be used as a way of converting a path into a
+file set.  It can also be used as a replacement for the <code>flatten</code>
+attribute for the copy and move tasks.</p>
+
+<p>A <code>&lt;flat-fileset&gt;</code> element takes no attributes, and a set
+of nested paths or file sets.</p>
+
+<p>An example:</p>
+
+<source><![CDATA[
+
+<v-copy todir="dist/lib">
+  <flat-fileset>
+    <v-fileset dir="build/lib">
+        <basename pattern="*.jar"/>
+    <v-fileset>
+    <v-path path="${classpath}"/>
+  </flat-fileset>
+</v-copy>
+]]></source>
+
+</subsection>
+
+<subsection name="Paths">
+
+<p>Paths are an ordered list of files.</p>
+
+<h3><code>&lt;v-path&gt;</code></h3>
+
+<p>This is the equivalent of Ant 1's <code>&lt;path&gt;</code>.</p>
+
+<h3><code>&lt;filtered-path&gt;</code></h3>
+
+<p>A path that applies file selectors to a set of nested file sets and paths.</p>
+
+</subsection>
+
+<subsection name="File Selectors">
+
+<p>File selectors are used to select files from file sets and paths.</p>
+
+<h3><code>&lt;and&gt;</code></h3>
+
+<p>Combines zero or more file selectors, using AND. An empty <code>&lt;and&gt;</code>
+selector accepts all files.</p>
+
+<h3><code>&lt;basename&gt;</code></h3>
+
+<p>Selects files whose base name matches an Ant 1 style pattern, or a regular
+expression.</p>
+
+<h3><code>&lt;exists&gt;</code></h3>
+
+<p>Selects files that exist.</p>
+
+<h3><code>&lt;is-empty&gt;</code></h3>
+
+<p>Selects empty folders, that is, folders that have no children.</p>
+
+<h3><code>&lt;is-folder&gt;</code></h3>
+
+<p>Selects folders, does not select regular files.</p>
+
+<h3><code>&lt;is-file&gt;</code></h3>
+
+<p>Selects regular files, does not select folders.</p>
+
+<h3><code>&lt;name&gt;</code></h3>
+
+<p>Selects files whose path in a file set matches an Ant 1 style pattern, or
+a regular expression.</p>
+
+<h3><code>&lt;not&gt;</code></h3>
+
+<p>Selects files that are not selected by a nested file selector.</p>
+
+<h3><code>&lt;or&gt;</code></h3>
+
+<p>Combines zero or more file selectors, using OR. An empty <code>&lt;or&gt;</code>
+selector accepts all files.</p>
+
+<h3><code>&lt;url&gt;</code></h3>
+
+<p>Selects files whose URL matches an Ant 1 style pattern, or a regular expression.</p>
+
+</subsection>
+
+</section>
 <section name="Tasks">
 
 <p>