Merge branch 'master' of https://ggregory@gitbox.apache.org/repos/asf/commons-io.git

Author: garydgregory

src/changes/changes.xml

@@ -103,6 +103,8 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="fix"                due-to="Elliotte Rusty Harold, Gary Gregory">Clarify and correct EndianUtils and SwappedDataInputStream API doc #566.</action>
       <action dev="ggregory" type="fix"                due-to="Elliotte Rusty Harold">Add characterization test for copying a symlinked directory #570.</action>
       <action dev="ggregory" type="fix"                due-to="Gary Gregory">RandomAccessFileInputStream.builder().get() now throws ISE instead of NPE.</action>
+      <action dev="ggregory" type="fix" issue="IO-845" due-to="Elliotte Rusty Harold">Test links to targets outside the source directory #571.</action>
+      <action dev="ggregory" type="fix"                due-to="Elliotte Rusty Harold">Focus Javadoc on current version rather than past versions #573, #574.</action>
       <!-- Add -->
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add and use PathUtils.getFileName(Path, Function&lt;Path, R&gt;).</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add and use PathUtils.getFileNameString().</action>

src/main/java/org/apache/commons/io/DirectoryWalker.java

@@ -186,11 +186,11 @@
  *
  * <p>
  * This example provides a public {@code cancel()} method that can be called by another thread to stop the
- * processing. A typical example use-case would be a cancel button on a GUI. Calling this method sets a
- * <a href="https://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#36930"> volatile</a> flag to ensure
- * it will work properly in a multi-threaded environment. The flag is returned by the {@code handleIsCancelled()}
- * method, which will cause the walk to stop immediately. The {@code handleCancelled()} method will be the next,
- * and last, callback method received once cancellation has occurred.
+ * processing. A typical example use-case is a cancel button on a GUI. Calling this method sets a
+ * <a href='https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#d5e12277'>(@code volatile}</a>
+ * flag to ensure it works properly in a multi-threaded environment.
+ * The flag is returned by the {@code handleIsCancelled()} method, which causes the walk to stop
+ * immediately. The {@code handleCancelled()} method will be the next, and last, callback method received once cancellation has occurred.
  * </p>
  *
  * <pre>

src/main/java/org/apache/commons/io/FileSystemUtils.java

@@ -473,11 +473,10 @@ List<String> performCommand(final String[] cmdAttribs, final int max, final Dura
         //
         // This method does what it can to avoid the 'Too many open files' error
         // based on trial and error and these links:
-        // https://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4784692
-        // https://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4801027
-        // https://forum.java.sun.com/thread.jspa?threadID=533029&messageID=2572018
-        // however, it's still not perfect as the JDK support is so poor
-        // (see commons-exec or Ant for a better multithreaded multi-OS solution)
+        // https://bugs.java.com/bugdatabase/view_bug.do?bug_id=4784692
+        // https://bugs.java.com/bugdatabase/view_bug.do?bug_id=4801027
+        // However, it's still not perfect as the JDK support is so poor.
+        // (See commons-exec or Ant for a better multithreaded multi-OS solution.)
         //
         final Process proc = openProcess(cmdAttribs);
         final Thread monitor = ThreadMonitor.start(timeout);

src/main/java/org/apache/commons/io/FileUtils.java

@@ -1184,7 +1184,7 @@ static String decodeUrl(final String url) {
                             i += 3;
                         } while (i < n && url.charAt(i) == '%');
                         continue;
-                    } catch (final RuntimeException ignored) {
+                    } catch (final IndexOutOfBoundsException | NumberFormatException ignored) {
                         // malformed percent-encoded octet, fall through and
                         // append characters literally
                     } finally {
@@ -2690,8 +2690,7 @@ public static String readFileToString(final File file, final Charset charsetName
      * @throws NullPointerException if file is {@code null}.
      * @throws IOException if an I/O error occurs, including when the file does not exist, is a directory rather than a
      *         regular file, or for some other reason why the file cannot be opened for reading.
-     * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
-     * .UnsupportedEncodingException} in version 2.2 if the named charset is unavailable.
+     * @throws java.nio.charset.UnsupportedCharsetException if the named charset is unavailable.
      * @since 2.3
      */
     public static String readFileToString(final File file, final String charsetName) throws IOException {
@@ -2740,8 +2739,7 @@ public static List<String> readLines(final File file, final Charset charset) thr
      * @throws NullPointerException if file is {@code null}.
      * @throws IOException if an I/O error occurs, including when the file does not exist, is a directory rather than a
      *         regular file, or for some other reason why the file cannot be opened for reading.
-     * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
-     * .UnsupportedEncodingException} in version 2.2 if the named charset is unavailable.
+     * @throws java.nio.charset.UnsupportedCharsetException if the named charset is unavailable.
      * @since 1.1
      */
     public static List<String> readLines(final File file, final String charsetName) throws IOException {
@@ -3058,11 +3056,8 @@ private static String[] toSuffixes(final String... extensions) {
 
     /**
      * Implements behavior similar to the Unix "touch" utility. Creates a new file with size 0, or, if the file exists, just
-     * updates the file's modified time.
-     * <p>
-     * NOTE: As from v1.3, this method throws an IOException if the last modified date of the file cannot be set. Also, as
-     * from v1.3 this method creates parent directories if they do not exist.
-     * </p>
+     * updates the file's modified time. This method throws an IOException if the last modified date
+     * of the file cannot be set. It creates parent directories if they do not exist.
      *
      * @param file the File to touch.
      * @throws NullPointerException if the parameter is {@code null}.
@@ -3211,8 +3206,7 @@ public static void write(final File file, final CharSequence data, final String
      * @param append   if {@code true}, then the data will be added to the
      *                 end of the file rather than overwriting
      * @throws IOException                 in case of an I/O error
-     * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
-     * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported by the VM
+     * @throws java.nio.charset.UnsupportedCharsetException if the encoding is not supported by the VM
      * @since 2.1
      */
     public static void write(final File file, final CharSequence data, final String charsetName, final boolean append) throws IOException {
@@ -3223,10 +3217,7 @@ public static void write(final File file, final CharSequence data, final String
 
     /**
      * Writes a byte array to a file creating the file if it does not exist.
-     * <p>
-     * NOTE: As from v1.3, the parent directories of the file will be created
-     * if they do not exist.
-     * </p>
+     * The parent directories of the file will be created if they do not exist.
      *
      * @param file the file to write to
      * @param data the content to write to the file
@@ -3353,10 +3344,7 @@ public static void writeLines(final File file, final Collection<?> lines, final
      * Writes the {@code toString()} value of each item in a collection to
      * the specified {@link File} line by line.
      * The specified character encoding and the default line ending will be used.
-     * <p>
-     * NOTE: As from v1.3, the parent directories of the file will be created
-     * if they do not exist.
-     * </p>
+     * The parent directories of the file will be created if they do not exist.
      *
      * @param file     the file to write to
      * @param charsetName the name of the requested charset, {@code null} means platform default
@@ -3391,10 +3379,7 @@ public static void writeLines(final File file, final String charsetName, final C
      * Writes the {@code toString()} value of each item in a collection to
      * the specified {@link File} line by line.
      * The specified character encoding and the line ending will be used.
-     * <p>
-     * NOTE: As from v1.3, the parent directories of the file will be created
-     * if they do not exist.
-     * </p>
+     * The parent directories of the file will be created if they do not exist.
      *
      * @param file       the file to write to
      * @param charsetName   the name of the requested charset, {@code null} means platform default
@@ -3461,10 +3446,7 @@ public static void writeStringToFile(final File file, final String data, final b
 
     /**
      * Writes a String to a file creating the file if it does not exist.
-     * <p>
-     * NOTE: As from v1.3, the parent directories of the file will be created
-     * if they do not exist.
-     * </p>
+     * The parent directories of the file will be created if they do not exist.
      *
      * @param file     the file to write
      * @param data     the content to write to the file
@@ -3478,7 +3460,8 @@ public static void writeStringToFile(final File file, final String data, final C
     }
 
     /**
-     * Writes a String to a file creating the file if it does not exist.
+     * Writes a String to a file, creating the file if it does not exist.
+     * The parent directories of the file are created if they do not exist.
      *
      * @param file     the file to write
      * @param data     the content to write to the file
@@ -3495,11 +3478,8 @@ public static void writeStringToFile(final File file, final String data, final C
     }
 
     /**
-     * Writes a String to a file creating the file if it does not exist.
-     * <p>
-     * NOTE: As from v1.3, the parent directories of the file will be created
-     * if they do not exist.
-     * </p>
+     * Writes a String to a file, creating the file if it does not exist.
+     * The parent directories of the file are created if they do not exist.
      *
      * @param file     the file to write
      * @param data     the content to write to the file
@@ -3512,16 +3492,16 @@ public static void writeStringToFile(final File file, final String data, final S
     }
 
     /**
-     * Writes a String to a file creating the file if it does not exist.
+     * Writes a String to a file, creating the file if it does not exist.
+     * The parent directories of the file are created if they do not exist.
      *
      * @param file     the file to write
      * @param data     the content to write to the file
      * @param charsetName the name of the requested charset, {@code null} means platform default
      * @param append   if {@code true}, then the String will be added to the
      *                 end of the file rather than overwriting
      * @throws IOException                 in case of an I/O error
-     * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
-     * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported by the VM
+     * @throws java.nio.charset.UnsupportedCharsetException if the encoding is not supported by the VM
      * @since 2.1
      */
     public static void writeStringToFile(final File file, final String data, final String charsetName, final boolean append) throws IOException {