commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nia...@apache.org
Subject svn commit: r463560 - in /jakarta/commons/proper/io/trunk/src: java/org/apache/commons/io/DirectoryWalker.java test/org/apache/commons/io/DirectoryWalkerTestCase.java
Date Fri, 13 Oct 2006 04:46:17 GMT
Author: niallp
Date: Thu Oct 12 21:46:16 2006
New Revision: 463560

URL: http://svn.apache.org/viewvc?view=rev&rev=463560
Log:
IO-86 - Update cancellation behaviour in DirectoryWalker to use a new CancelException, also
add IOException to "lifecycle" method definitions.

Modified:
    jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/DirectoryWalker.java
    jakarta/commons/proper/io/trunk/src/test/org/apache/commons/io/DirectoryWalkerTestCase.java

Modified: jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/DirectoryWalker.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/DirectoryWalker.java?view=diff&rev=463560&r1=463559&r2=463560
==============================================================================
--- jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/DirectoryWalker.java (original)
+++ jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/DirectoryWalker.java Thu
Oct 12 21:46:16 2006
@@ -18,6 +18,7 @@
 
 import java.io.File;
 import java.io.FileFilter;
+import java.io.IOException;
 import java.util.Collection;
 
 /**
@@ -28,8 +29,19 @@
  * limit the files and direcories visited.
  * Commons IO supplies many common filter implementations in the 
  * <a href="filefilter/package-summary.html"> filefilter</a> package.
+ * <p>
+ * The following sections describe:
+ *   <ul>
+ *      <li><a href="#example">1. Example Implementation</a> - example
+ *          <code>FileCleaner</code> implementation.</li>
+ *      <li><a href="#filter">2. Filter Example</a> - using 
+ *          {@link FileFilter}(s) with <code>DirectoryWalker</code>.</li>
+ *      <li><a href="#cancel">3. Cancellation</a> - how to implement cancellation
+ *          behaviour.</li>
+ *   </ul>
  *
- * <h3>Example Implementation</h3>
+ * <a name="example"></a>
+ * <h3>1. Example Implementation</h3>
  *
  * There are many possible extensions, for example, to delete all
  * files and '.svn' directories, and return a list of deleted files:
@@ -37,7 +49,7 @@
  *  public class FileCleaner extends DirectoryWalker {
  *
  *    public FileCleaner() {
- *      super(null, -1);
+ *      super();
  *    }
  *
  *    public List clean(File startDirectory) {
@@ -65,7 +77,8 @@
  *  }
  * </pre>
  *
- * <h3>Filter Example</h3>
+ * <a name="filter"></a>
+ * <h3>2. Filter Example</h3>
  *
  * If you wanted all directories which are not hidden
  * and files which end in ".txt" - you could build a composite filter
@@ -94,28 +107,49 @@
  *
  * </pre>
  *
- * <h3>Cancellation</h3>
+ * <a name="cancel"></a>
+ * <h3>3. Cancellation</h3>
  *
  * The DirectoryWalker contains some of the logic required for cancel processing.
  * Subclasses must complete the implementation.
- * This is for performance and to ensure you think about the multihreaded implications.
  * <p>
- * Before any processing occurs on each file or directory the
- * <code>isCancelled()</code> method is called. If it returns <code>true</code>
- * then <code>handleCancelled()<code> is called. This method can decide whether
- * to accept or ignore the cancellation. If it accepts it then all further
- * processing is skipped and the operation returns. If it rejects it then
- * processing continues on as before. This is useful if a group of files has
- * meaning and cancellation cannot occur in the middle of the group.
+ * What <code>DirectoryWalker</code> does provide for cancellation is:
+ * <ul>
+ *    <li>{@link CancelException} which can be thrown in any of the
+ *        <i>lifecycle</i> methods to stop processing.</li>
+ *    <li>The <code>walk()</code> method traps thrown {@link CancelException}
+ *        and calls the <code>handleCancelled()</code> method, providing
+ *        a place for custom cancel processing.</li>
+ * </ul>
+ * <p>
+ * Implementations need to provide:
+ * <ul>
+ *    <li>The decision logic on whether to cancel processing or not.</li>
+ *    <li>Constructing and throwing a {@link CancelException}.</li>
+ *    <li>Custom cancel processing in the <code>handleCancelled()</code>
method.
+ * </ul>
  * <p>
- * The default implementation of <code>isCancelled()</code> always
- * returns <code>false</code> and it is down to the implementation
- * to fully implement the <code>isCancelled()</code> behaviour.
+ * Two possible scenarios are envisaged for cancellation:
+ * <ul>
+ *    <li><a href="#external">3.1 External / Mult-threaded</a> - cancellation
being
+ *        decided/initiated by an external process.</li>
+ *    <li><a href="#internal">3.2 Internal</a> - cancellation being decided/initiated

+ *        from within a DirectoryWalker implementation.</li>
+ * </ul>
  * <p>
- * The following example uses the
+ * The following sections provide example implementations for these two different
+ * scenarios.
+ *
+ * <a name="external"></a>
+ * <h4>3.1 External / Mult-threaded</h4>
+ *
+ * This example provides a <code>cancel()</code> method for external processes
to
+ * indcate that processing must stop. Calling this method sets a
  * <a href="http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#36930">
- * volatile</a> keyword to (hopefully) ensure it will work properly in
- * a multi-threaded environment.
+ * volatile</a> flag to (hopefully) ensure it will work properly in
+ * a multi-threaded environment. In this implementation the flag is checked in two
+ * of the lifecycle methods using a convenience <code>checkIfCancelled()</code>
method
+ * which throws a {@link CancelException} if cancellation has been requested.
  *
  * <pre>
  *  public class FooDirectoryWalker extends DirectoryWalker {
@@ -126,13 +160,56 @@
  *        cancelled = true;
  *    }
  *
- *    public boolean isCancelled() {
- *        return cancelled;
+ *    protected boolean handleDirectory(File directory, int depth, Collection results) throws
IOException {
+ *        checkIfCancelled(directory, depth); // Cancel Check
+ *        return true;
+ *    }
+ *
+ *    protected void handleFile(File file, int depth, Collection results) throws IOException
{
+ *        checkIfCancelled(file, depth);  // Cancel Check
+ *        results.add(file);
+ *    }
+ *
+ *    private void checkIfCancelled(File file, int depth) throws CancelException {
+ *        if (cancelled) {
+ *            throw new CancelException(file, depth);
+ *        }
  *    }
  *
- *    protected boolean handleCancelled(File file, int depth, Collection results) {
- *       // implement any cancel processing here
- *       return true;  // accept cancellation
+ *    protected void handleCancelled(File startDirectory, Collection results, CancelException
cancel) {
+ *        // implement cancel processing here
+ *    }
+ *  }
+ * </pre>
+ *
+ * <a name="internal"></a>
+ * <h4>3.2 Internal</h4>
+ *
+ * This shows an example of how internal cancellation processing could be implemented.
+ * <b>Note</b> the decision logic and throwing a {@link CancelException} could
be implemented
+ * in any of the <i>lifecycle</i> methods. 
+ *
+ * <pre>
+ *  public class BarDirectoryWalker extends DirectoryWalker {
+ *
+ *    protected boolean handleDirectory(File directory, int depth, Collection results) throws
IOException {
+ *        // cancel if hidden directory
+ *        if (directory.isHidden()) {
+ *            throw new CancelException(file, depth);
+ *        }
+ *        return true;
+ *    }
+ *
+ *    protected void handleFile(File file, int depth, Collection results) throws IOException
{
+ *        // cancel if read-only file
+ *        if (!file.canWrite()) {
+ *            throw new CancelException(file, depth);
+ *        }
+ *        results.add(file);
+ *    }
+ *
+ *    protected void handleCancelled(File startDirectory, Collection results, CancelException
cancel) {
+ *        // implement cancel processing here
  *    }
  *  }
  * </pre>
@@ -183,16 +260,20 @@
      *
      * @param startDirectory  the directory to start from, not null
      * @param results  the collection of result objects, may be updated
-     * @return true if completed, false if cancelled
      * @throws NullPointerException if the start directory is null
+     * @throws IOException if an I/O Error occurs
      */
-    protected boolean walk(File startDirectory, Collection results) {
-        handleStart(startDirectory, results);
-        if (walk(startDirectory, 0, results) == false) {
-            return false;  // cancelled
+    protected void walk(File startDirectory, Collection results) throws IOException {
+        if (startDirectory == null) {
+            throw new NullPointerException("Start Directory is null");
+        }
+        try {
+            handleStart(startDirectory, results);
+            walk(startDirectory, 0, results);
+            handleEnd(results);
+        } catch(CancelException cancel) {
+            handleCancelled(startDirectory, results, cancel);
         }
-        handleEnd(results);
-        return true;
     }
 
     /**
@@ -201,12 +282,9 @@
      * @param directory  the directory to examine, not null
      * @param depth  the directory level (starting directory = 0)
      * @param results  the collection of result objects, may be updated
-     * @return false if cancelled
+     * @throws IOException if an I/O Error occurs
      */
-    private boolean walk(File directory, int depth, Collection results) {
-        if (isCancelled() && handleCancelled(directory, depth, results)) {
-            return false;  // cancelled
-        }
+    private void walk(File directory, int depth, Collection results) throws IOException {
         if (handleDirectory(directory, depth, results)) {
             handleDirectoryStart(directory, depth, results);
             int childDepth = depth + 1;
@@ -217,13 +295,8 @@
                 } else {
                     for (int i = 0; i < files.length; i++) {
                         if (files[i].isDirectory()) {
-                            if (walk(files[i], childDepth, results) == false) {
-                                return false;  // cancelled
-                            }
+                            walk(files[i], childDepth, results);
                         } else {
-                            if (isCancelled() && handleCancelled(files[i], childDepth,
results)) {
-                                return false;  // cancelled
-                            }
                             handleFile(files[i], childDepth, results);
                         }
                     }
@@ -231,7 +304,6 @@
             }
             handleDirectoryEnd(directory, depth, results);
         }
-        return true;
     }
 
     //-----------------------------------------------------------------------
@@ -242,8 +314,9 @@
      *
      * @param startDirectory  the directory to start from
      * @param results  the collection of result objects, may be updated
+     * @throws IOException if an I/O Error occurs
      */
-    protected void handleStart(File startDirectory, Collection results) {
+    protected void handleStart(File startDirectory, Collection results) throws IOException
{
         // do nothing - overridable by subclass
     }
 
@@ -260,8 +333,9 @@
      * @param depth  the current directory level (starting directory = 0)
      * @param results  the collection of result objects, may be updated
      * @return true to process this directory, false to skip this directory
+     * @throws IOException if an I/O Error occurs
      */
-    protected boolean handleDirectory(File directory, int depth, Collection results) {
+    protected boolean handleDirectory(File directory, int depth, Collection results) throws
IOException {
         // do nothing - overridable by subclass
         return true;  // process directory
     }
@@ -274,8 +348,9 @@
      * @param directory  the current directory being processed
      * @param depth  the current directory level (starting directory = 0)
      * @param results  the collection of result objects, may be updated
+     * @throws IOException if an I/O Error occurs
      */
-    protected void handleDirectoryStart(File directory, int depth, Collection results) {
+    protected void handleDirectoryStart(File directory, int depth, Collection results) throws
IOException {
         // do nothing - overridable by subclass
     }
 
@@ -287,8 +362,9 @@
      * @param file  the current file being processed
      * @param depth  the current directory level (starting directory = 0)
      * @param results  the collection of result objects, may be updated
+     * @throws IOException if an I/O Error occurs
      */
-    protected void handleFile(File file, int depth, Collection results) {
+    protected void handleFile(File file, int depth, Collection results) throws IOException
{
         // do nothing - overridable by subclass
     }
 
@@ -300,8 +376,9 @@
      * @param directory  the restricted directory
      * @param depth  the current directory level (starting directory = 0)
      * @param results  the collection of result objects, may be updated
+     * @throws IOException if an I/O Error occurs
      */
-    protected void handleRestricted(File directory, int depth, Collection results) {
+    protected void handleRestricted(File directory, int depth, Collection results) throws
IOException  {
         // do nothing - overridable by subclass
     }
 
@@ -313,8 +390,9 @@
      * @param directory  the directory being processed
      * @param depth  the current directory level (starting directory = 0)
      * @param results  the collection of result objects, may be updated
+     * @throws IOException if an I/O Error occurs
      */
-    protected void handleDirectoryEnd(File directory, int depth, Collection results) {
+    protected void handleDirectoryEnd(File directory, int depth, Collection results) throws
IOException {
         // do nothing - overridable by subclass
     }
 
@@ -324,51 +402,80 @@
      * This implementation does nothing.
      *
      * @param results  the collection of result objects, may be updated
+     * @throws IOException if an I/O Error occurs
      */
-    protected void handleEnd(Collection results) {
+    protected void handleEnd(Collection results) throws IOException {
         // do nothing - overridable by subclass
     }
 
-    //-----------------------------------------------------------------------
-    /**
-     * Indicates whether the operation has been cancelled or not.
-     * <p>
-     * This implementation always returns <code>false</code>.
-     *
-     * @return true if the operation has been cancelled
-     */
-    protected boolean isCancelled() {
-        return false;
-    }
-
     /**
      * Overridable callback method invoked when the operation is cancelled.
      * <p>
-     * This method returns a boolean to indicate if the cancellation is being
-     * accepted or rejected. This could be useful if you need to finish processing
-     * all the files in a directory before accepting the cancellation request.
-     * For example, this only accepts the cancel when the current directory is complete:
-     * <pre>
-     * protected boolean handleCancelled(File file, int depth, Collection results) {
-     *   return file.isDirectory();
-     * }
-     * </pre>
-     * If you return true, then the whole operation is cancelled and no more event
-     * methods will be called.
-     * <p>
-     * If you return false, then normal processing will continue until the next time
-     * the <code>isCancelled()</code> method returns false.
-     * <p>
-     * This implementation returns true, accepting the cancellation.
+     * This implementation just re-throws the {@link CancelException}.
      *
-     * @param file  the file about to be processed which may be a file or a directory
-     * @param depth  the current directory level (starting directory = 0)
+     * @param startDirectory  the directory to start from
      * @param results  the collection of result objects, may be updated
-     * @return true to accept the cancellation, false to reject it
-     */
-    protected boolean handleCancelled(File file, int depth, Collection results) {
-        // do nothing - overridable by subclass
-        return true;  // accept cancellation
+     * @param cancel The exception throw to cancel further processing
+     * containing details at the point of cancellation. 
+     * @throws IOException if an I/O Error occurs
+     */
+    protected void handleCancelled(File startDirectory, Collection results,
+                       CancelException cancel) throws IOException {
+        // re-throw exception - overridable by subclass
+        throw cancel;
     }
 
+    /**
+     * CancelException is thrown in DirectoryWalker to cancel the current
+     * processing.
+     */
+    public static class CancelException extends IOException {
+
+        private File file;
+        private int depth = -1;
+
+        /**
+         * Constructs a <code>CancelException</code> with
+         * the file and depth when cancellation occurred.
+         *
+         * @param file The file when the operation was cancelled
+         * @param depth The depth when the operation was cancelled
+         */
+        public CancelException(File file, int depth) {
+            this("Operation Cancelled", file, depth);
+        }
+
+        /**
+         * Constructs a <code>CancelException</code> with
+         * an appropriate message and the file and depth when
+         * cancellation occurred.
+         *
+         * @param message The detail message.
+         * @param file The file when the operation was cancelled
+         * @param depth The depth when the operation was cancelled
+         */
+        public CancelException(String message, File file, int depth) {
+            super(message);
+            this.file = file;
+            this.depth = depth;
+        }
+
+        /**
+         * Return the file when the operation was cancelled.
+         *
+         * @return The file when the operation was cancelled
+         */
+        public File getFile() {
+            return file;
+        }
+
+        /**
+         * Return the depth when the operation was cancelled.
+         *
+         * @return The depth when the operation was cancelled
+         */
+        public int getDepth() {
+            return depth;
+        }
+    }
 }

Modified: jakarta/commons/proper/io/trunk/src/test/org/apache/commons/io/DirectoryWalkerTestCase.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/io/trunk/src/test/org/apache/commons/io/DirectoryWalkerTestCase.java?view=diff&rev=463560&r1=463559&r2=463560
==============================================================================
--- jakarta/commons/proper/io/trunk/src/test/org/apache/commons/io/DirectoryWalkerTestCase.java
(original)
+++ jakarta/commons/proper/io/trunk/src/test/org/apache/commons/io/DirectoryWalkerTestCase.java
Thu Oct 12 21:46:16 2006
@@ -18,6 +18,7 @@
 
 import java.io.File;
 import java.io.FileFilter;
+import java.io.IOException;
 import java.util.List;
 import java.util.ArrayList;
 import java.util.Collection;
@@ -209,14 +210,41 @@
      * Test Cancel
      */
     public void testCancel() {
-        List results = new TestCancelWalker(2, true).find(javaDir);
-        assertEquals(2, results.size());
-        
-        results = new TestCancelWalker(3, true).find(javaDir);
-        assertEquals(3, results.size());
-        
-        results = new TestCancelWalker(3, false).find(javaDir);
-        assertEquals(6, results.size());
+        String cancelName = null;
+
+        // Cancel on a file
+        try {
+            cancelName = "DirectoryWalker.java";
+            List results = new TestCancelWalker(cancelName, false).find(javaDir);
+            fail("CancelException not thrown for '" + cancelName + "'");
+        } catch (DirectoryWalker.CancelException cancel) {
+            assertEquals("File:  " + cancelName,   cancelName, cancel.getFile().getName());
+            assertEquals("Depth: " + cancelName,  5, cancel.getDepth());
+        } catch(IOException ex) {
+            fail("IOException: " + cancelName + " " + ex);
+        }
+
+        // Cancel on a directory
+        try {
+            cancelName = "commons";
+            List results = new TestCancelWalker(cancelName, false).find(javaDir);
+            fail("CancelException not thrown for '" + cancelName + "'");
+        } catch (DirectoryWalker.CancelException cancel) {
+            assertEquals("File:  " + cancelName,   cancelName, cancel.getFile().getName());
+            assertEquals("Depth: " + cancelName,  3, cancel.getDepth());
+        } catch(IOException ex) {
+            fail("IOException: " + cancelName + " " + ex);
+        }
+
+        // Suppress CancelException (use same file name as preceeding test)
+        try {
+            List results = new TestCancelWalker(cancelName, true).find(javaDir);
+            File lastFile = (File)results.get(results.size() - 1);
+            assertEquals("Suppress:  " + cancelName,   cancelName, lastFile.getName());
+        } catch(IOException ex) {
+            fail("Suppress threw " + ex);
+        }
+
     }
 
     // ------------ Test DirectoryWalker implementation --------------------------
@@ -234,7 +262,11 @@
         /** find files. */
         protected List find(File startDirectory) {
            List results = new ArrayList();
-           Assert.assertEquals(true, walk(startDirectory, results));
+           try {
+               walk(startDirectory, results);
+           } catch(IOException ex) {
+               Assert.fail(ex.toString());
+           }
            return results;
         }
 
@@ -274,74 +306,44 @@
      * applying a file filter.
      */
     static class TestCancelWalker extends DirectoryWalker {
-        private boolean cancelled;
-        private int count;
-        private boolean accept;
+        private String cancelFileName;
+        private boolean suppressCancel;
 
-        TestCancelWalker(int count, boolean accept) {
+        TestCancelWalker(String cancelFileName,boolean suppressCancel) {
             super();
-            this.count = count;
-            this.accept = accept;
+            this.cancelFileName = cancelFileName;
+            this.suppressCancel = suppressCancel;
         }
 
         /** find files. */
-        public List find(File startDirectory) {
+        protected List find(File startDirectory) throws IOException {
            List results = new ArrayList();
-           Assert.assertEquals(false, walk(startDirectory, results));
+           walk(startDirectory, results);
            return results;
         }
 
-        /** Return cancelled flag. */
-        protected boolean isCancelled() {
-            return cancelled;
-        }
-
-        /** Handles a directory start. */
-        protected void handleDirectoryStart(File directory, int depth, Collection results)
{
-            if (accept) {
-                Assert.assertEquals(false, cancelled);
-            }
-        }
-
         /** Handles a directory end by adding the File to the result set. */
-        protected void handleDirectoryEnd(File directory, int depth, Collection results)
{
-            if (accept) {
-                Assert.assertEquals(false, cancelled);
-            }
+        protected void handleDirectoryEnd(File directory, int depth, Collection results)
throws IOException {
             results.add(directory);
-            cancelled = (results.size() >= count);
+            if (cancelFileName.equals(directory.getName())) {
+                throw new CancelException(directory, depth);
+            }
         }
 
         /** Handles a file by adding the File to the result set. */
-        protected void handleFile(File file, int depth, Collection results) {
-            if (accept) {
-                Assert.assertEquals(false, cancelled);
-            }
+        protected void handleFile(File file, int depth, Collection results) throws IOException
{
             results.add(file);
-            cancelled = (results.size() >= count);
-        }
-
-        /** Handles start. */
-        protected void handleStart(File directory, Collection results) {
-            if (accept) {
-                Assert.assertEquals(false, cancelled);
-            }
-        }
-
-        /** Handles end. */
-        protected void handleEnd(Collection results) {
-            if (accept) {
-                Assert.assertEquals(false, cancelled);
+            if (cancelFileName.equals(file.getName())) {
+                throw new CancelException(file, depth);
             }
         }
 
-        /** Handles end. */
-        protected boolean handleCancelled(File file, int depth, Collection results) {
-            Assert.assertEquals(true, cancelled);
-            if (accept) {
-                return true;
+        /** Handles Cancel. */
+        protected void handleCancelled(File startDirectory, Collection results,
+                       CancelException cancel) throws IOException {
+            if (!suppressCancel) {
+                super.handleCancelled(startDirectory, results, cancel);
             }
-            return (results.size() >= (count * 2));
         }
     }
 



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message