[IO-435] Document thrown IllegalArgumentException in FileUtils. Thanks to Dominik Stadler.

netomi · netomi · commit def9299707ed · 2014-07-16T21:15:39.000Z
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/io/trunk@1611192 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/pom.xml b/pom.xml
@@ -204,6 +204,9 @@ file comparators, endian transformation classes, and much more.
     <contributor>
       <name>Ian Springer</name>
     </contributor>
+    <contributor>
+      <name>Dominik Stadler</name>
+    </contributor>
     <contributor>
       <name>Masato Tezuka</name>
     </contributor>
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -47,6 +47,11 @@ The <action> type attribute can be add,update,fix,remove.
   <body>
     <!-- The release date is the date RC is cut -->
     <release version="2.5" date="2014-??-??" description="New features and bug fixes.">
+      <action issue="IO-435" dev="tn" type="fix" due-to="Dominik Stadler">
+         Document that FileUtils.deleteDirectory, directoryContains and cleanDirectory
+         may throw an IllegalArgumentException in case the passed directory does not
+         exist or is not a directory. 
+      </action>
       <action issue="IO-426" dev="ggregory" type="add">
          Add API IOUtils.closeQuietly(Closeable...)
       </action>
diff --git a/src/main/java/org/apache/commons/io/FileUtils.java b/src/main/java/org/apache/commons/io/FileUtils.java
@@ -1557,6 +1557,7 @@ public static void copyToFile(final InputStream source, final File destination)
      *
      * @param directory  directory to delete
      * @throws IOException in case deletion is unsuccessful
+     * @throws IllegalArgumentException if {@code directory} does not exist or is not a directory
      */
     public static void deleteDirectory(final File directory) throws IOException {
         if (!directory.exists()) {
@@ -1628,6 +1629,8 @@ public static boolean deleteQuietly(final File file) {
      * @return true is the candidate leaf is under by the specified composite. False otherwise.
      * @throws IOException
      *             if an IO error occurs while checking the files.
+     * @throws IllegalArgumentException
+     *             if {@code directory} is null or not a directory.
      * @since 2.2
      * @see FilenameUtils#directoryContains(String, String)
      */
@@ -1662,6 +1665,7 @@ public static boolean directoryContains(final File directory, final File child)
      *
      * @param directory directory to clean
      * @throws IOException in case cleaning is unsuccessful
+     * @throws IllegalArgumentException if {@code directory} does not exist or is not a directory
      */
     public static void cleanDirectory(final File directory) throws IOException {
         if (!directory.exists()) {
diff --git a/src/test/java/org/apache/commons/io/FileUtilsTestCase.java b/src/test/java/org/apache/commons/io/FileUtilsTestCase.java
@@ -2185,6 +2185,15 @@ public void testChecksumDouble() throws Exception {
         assertEquals(expectedValue, resultValue);
     }
 
+    public void testDeleteDirectoryWithNonDirectory() throws Exception {
+        try {
+            FileUtils.deleteDirectory(testFile1);
+            fail();
+        } catch (final IllegalArgumentException ex) {
+            // expected
+        }
+    }
+
     public void testDeleteQuietlyForNull() {
         try {
             FileUtils.deleteQuietly(null);
