Merge remote-tracking branch 'upstream/master'

Author: garydgregory

.github/workflows/codeql-analysis.yml

@@ -63,7 +63,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@c6f931105cb2c34c8f901cc885ba1e2e259cf745 # v4.34.0
+      uses: github/codeql-action/init@38697555549f1db7851b81482ff19f1fa5c4fedc # v4.34.1
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -74,7 +74,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@c6f931105cb2c34c8f901cc885ba1e2e259cf745 # v4.34.0
+      uses: github/codeql-action/autobuild@38697555549f1db7851b81482ff19f1fa5c4fedc # v4.34.1
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -88,4 +88,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@c6f931105cb2c34c8f901cc885ba1e2e259cf745 # v4.34.0
+      uses: github/codeql-action/analyze@38697555549f1db7851b81482ff19f1fa5c4fedc # v4.34.1

.github/workflows/scorecards-analysis.yml

@@ -66,6 +66,6 @@ jobs:
           retention-days: 5
 
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@c6f931105cb2c34c8f901cc885ba1e2e259cf745 # v4.34.0
+        uses: github/codeql-action/upload-sarif@38697555549f1db7851b81482ff19f1fa5c4fedc # v4.34.1
         with:
           sarif_file: results.sarif

src/changes/changes.xml

@@ -66,6 +66,8 @@ The <action> type attribute can be add,update,fix,remove.
       <action type="fix" dev="ggregory" due-to="Gary Gregory">AbstractStreamBuilder.setOpenOptions(OpenOption...) now makes a defensive copy of its input array.</action>
       <action type="fix" dev="ggregory" due-to="Peter De Maeyer, Gary Gregory" issue="IO-885">Path visits follow links #832.</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">BOMInputStream fail-fast and tracks its ByteOrderMark as a final #835.</action>
+      <action type="fix" dev="ggregory" due-to="Gary Gregory">Refactor UnixLineEndingInputStream and WindowsLineEndingInputStream for duplication.</action>
+      <action type="fix" dev="ggregory" due-to="Peter De Maeyer, Gary Gregory" issue="IO-857">[Javadoc] PathUtils.cleanDirectory() methods vs FileUtils.</action>
       <!-- ADD -->
       <action type="add" dev="ggregory" due-to="Gary Gregory, Piotr P. Karwasz">Add and use IOUtils.closeQuietlySuppress(Closeable, Throwable) #818.</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">Add ProxyWriter.setReference(Writer).</action>

src/main/java/org/apache/commons/io/file/PathUtils.java

@@ -281,7 +281,10 @@ private static AccumulatorPathVisitor accumulate(final Path directory, final int
     }
 
     /**
-     * Cleans a directory by only deleting files, including in subdirectories, but without deleting the directories.
+     * Cleans a directory by only deleting files, including in subdirectories, without deleting directories.
+     * <p>
+     * This leaves a directory empty of files but the directory and any subdirectories remain.
+     * </p>
      *
      * @param directory directory to clean.
      * @return The visitation path counters.
@@ -292,7 +295,10 @@ public static PathCounters cleanDirectory(final Path directory) throws IOExcepti
     }
 
     /**
-     * Cleans a directory by only deleting files, including in subdirectories, but without deleting the directories.
+     * Cleans a directory by only deleting files, including in subdirectories, without deleting directories.
+     * <p>
+     * This leaves a directory empty of files but the directory and any subdirectories remain.
+     * </p>
      *
      * @param directory     directory to clean.
      * @param deleteOptions How to handle deletion.

src/main/java/org/apache/commons/io/input/AbstractLineEndingInputStream.java

@@ -0,0 +1,67 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.io.input;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+/**
+ * Abstracts {@link UnixLineEndingInputStream} and {@link WindowsLineEndingInputStream} to reduce duplication.
+ */
+abstract class AbstractLineEndingInputStream extends InputStream {
+
+    boolean atEos;
+
+    boolean atSlashCr;
+
+    boolean atSlashLf;
+
+    final InputStream in;
+
+    final boolean lineFeedAtEos;
+
+    /**
+     * Constructs an input stream that filters another stream
+     *
+     * @param inputStream   The input stream to wrap.
+     * @param lineFeedAtEos true to ensure that the file ends with LF.
+     */
+    AbstractLineEndingInputStream(final InputStream inputStream, final boolean lineFeedAtEos) {
+        this.in = inputStream;
+        this.lineFeedAtEos = lineFeedAtEos;
+    }
+
+    /**
+     * Closes the stream. Also closes the underlying stream.
+     *
+     * @throws IOException If an I/O error occurs.
+     */
+    @Override
+    public void close() throws IOException {
+        super.close();
+        in.close();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public synchronized void mark(final int readLimit) {
+        throw UnsupportedOperationExceptions.mark();
+    }
+}

src/main/java/org/apache/commons/io/input/Input.java

@@ -26,7 +26,7 @@
 final class Input {
 
     /**
-     * Throws an IOException on false input.
+     * Throws an {@link IOException} on false input.
      *
      * @param isOpen whether an input is open or not.
      * @throws IOException if {@code isOpen} is false indicating an input is closed.
@@ -38,7 +38,7 @@ static void checkOpen(final boolean isOpen) throws IOException {
     }
 
     /**
-     * Converts an InterruptedException to an InterruptedIOException.
+     * Converts an {@link InterruptedException} to an {@link InterruptedIOException}.
      * <p>
      * The cause of the returned InterruptedIOException is set to the original.
      * </p>

src/main/java/org/apache/commons/io/input/UnixLineEndingInputStream.java

@@ -28,38 +28,16 @@
  *
  * @since 2.5
  */
-public class UnixLineEndingInputStream extends InputStream {
-
-    private boolean atEos;
-
-    private boolean atSlashCr;
-
-    private boolean atSlashLf;
-
-    private final InputStream in;
-
-    private final boolean lineFeedAtEndOfFile;
+public class UnixLineEndingInputStream extends AbstractLineEndingInputStream {
 
     /**
      * Constructs an input stream that filters another stream
      *
      * @param inputStream                        The input stream to wrap.
-     * @param ensureLineFeedAtEndOfFile true to ensure that the file ends with LF.
-     */
-    public UnixLineEndingInputStream(final InputStream inputStream, final boolean ensureLineFeedAtEndOfFile) {
-        this.in = inputStream;
-        this.lineFeedAtEndOfFile = ensureLineFeedAtEndOfFile;
-    }
-
-    /**
-     * Closes the stream. Also closes the underlying stream.
-     *
-     * @throws IOException If an I/O error occurs.
+     * @param lineFeedAtEos true to ensure that the file ends with LF.
      */
-    @Override
-    public void close() throws IOException {
-        super.close();
-        in.close();
+    public UnixLineEndingInputStream(final InputStream inputStream, final boolean lineFeedAtEos) {
+        super(inputStream, lineFeedAtEos);
     }
 
     /**
@@ -69,7 +47,7 @@ public void close() throws IOException {
      * @return The next char to output to the stream.
      */
     private int handleEos(final boolean previousWasSlashCr) {
-        if (previousWasSlashCr || !lineFeedAtEndOfFile) {
+        if (previousWasSlashCr || !lineFeedAtEos) {
             return EOF;
         }
         if (!atSlashLf) {
@@ -79,14 +57,6 @@ private int handleEos(final boolean previousWasSlashCr) {
         return EOF;
     }
 
-    /**
-     * {@inheritDoc}
-     */
-    @Override
-    public synchronized void mark(final int readLimit) {
-        throw UnsupportedOperationExceptions.mark();
-    }
-
     /**
      * {@inheritDoc}
      */
@@ -96,7 +66,7 @@ public synchronized int read() throws IOException {
         if (atEos) {
             return handleEos(previousWasSlashR);
         }
-        final int target = readWithUpdate();
+        final int target = readUpdate();
         if (atEos) {
             return handleEos(previousWasSlashR);
         }
@@ -117,7 +87,7 @@ public synchronized int read() throws IOException {
      * @return the next int read from the target stream.
      * @throws IOException If an I/O error occurs.
      */
-    private int readWithUpdate() throws IOException {
+    private int readUpdate() throws IOException {
         final int target = this.in.read();
         atEos = target == EOF;
         if (atEos) {

src/main/java/org/apache/commons/io/input/WindowsLineEndingInputStream.java

@@ -28,40 +28,18 @@
  *
  * @since 2.5
  */
-public class WindowsLineEndingInputStream extends InputStream {
-
-    private boolean atEos;
-
-    private boolean atSlashCr;
-
-    private boolean atSlashLf;
-
-    private final InputStream in;
+public class WindowsLineEndingInputStream extends AbstractLineEndingInputStream {
 
     private boolean injectSlashLf;
 
-    private final boolean lineFeedAtEos;
-
     /**
      * Constructs an input stream that filters another stream.
      *
      * @param in                        The input stream to wrap.
      * @param lineFeedAtEos true to ensure that the stream ends with CRLF.
      */
     public WindowsLineEndingInputStream(final InputStream in, final boolean lineFeedAtEos) {
-        this.in = in;
-        this.lineFeedAtEos = lineFeedAtEos;
-    }
-
-    /**
-     * Closes the stream. Also closes the underlying stream.
-     *
-     * @throws IOException If an I/O error occurs.
-     */
-    @Override
-    public void close() throws IOException {
-        super.close();
-        in.close();
+        super(in, lineFeedAtEos);
     }
 
     /**
@@ -85,14 +63,6 @@ private int handleEos() {
         return EOF;
     }
 
-    /**
-     * {@inheritDoc}
-     */
-    @Override
-    public synchronized void mark(final int readLimit) {
-        throw UnsupportedOperationExceptions.mark();
-    }
-
     /**
      * {@inheritDoc}
      */

src/test/java/org/apache/commons/io/FileUtilsCleanDirectoryTest.java

@@ -68,66 +68,57 @@ private boolean chmod(final File file, final int mode, final boolean recurse) th
     void testCleanDirectoryToForceDelete() throws Exception {
         final File file = new File(tempDirFile, "restricted");
         FileUtils.touch(file);
-
         // 300 = owner: WE.
         // 500 = owner: RE.
         // 700 = owner: RWE.
         assumeTrue(chmod(tempDirFile, 700, false));
-
         // cleanDirectory calls forceDelete
         FileUtils.cleanDirectory(tempDirFile);
+        assertTrue(tempDirFile.exists());
     }
 
     @Test
     void testCleanEmpty() throws Exception {
         assertEquals(0, tempDirFile.list().length);
-
         FileUtils.cleanDirectory(tempDirFile);
-
+        assertTrue(tempDirFile.exists());
         assertEquals(0, tempDirFile.list().length);
     }
 
     @Test
     void testDeletesNested() throws Exception {
         final File nested = new File(tempDirFile, "nested");
-
         assertTrue(nested.mkdirs());
-
         FileUtils.touch(new File(nested, "file"));
-
         assertEquals(1, tempDirFile.list().length);
-
         FileUtils.cleanDirectory(tempDirFile);
-
+        assertTrue(tempDirFile.exists());
         assertEquals(0, tempDirFile.list().length);
     }
 
     @Test
     void testDeletesRegular() throws Exception {
         FileUtils.touch(new File(tempDirFile, "regular"));
         FileUtils.touch(new File(tempDirFile, ".hidden"));
-
         assertEquals(2, tempDirFile.list().length);
-
         FileUtils.cleanDirectory(tempDirFile);
-
+        assertTrue(tempDirFile.exists());
         assertEquals(0, tempDirFile.list().length);
     }
 
     @DisabledOnOs(OS.WINDOWS)
     @Test
     void testThrowsOnNullList() throws Exception {
-        // test won't work if we can't restrict permissions on the
-        // directory, so skip it.
+        // test won't work if we can't restrict permissions on the directory, so skip it.
         assumeTrue(chmod(tempDirFile, 0, false));
-
         try {
             // cleanDirectory calls forceDelete
             final IOException e = assertThrows(IOException.class, () -> FileUtils.cleanDirectory(tempDirFile));
             assertEquals("Unknown I/O error listing contents of directory: " + tempDirFile.getAbsolutePath(), e.getMessage());
         } finally {
             chmod(tempDirFile, 755, false);
         }
+        assertTrue(tempDirFile.exists());
     }
 
 }

src/test/java/org/apache/commons/io/FileUtilsCleanSymlinksTest.java

@@ -82,6 +82,7 @@ void testCleanDirWithASymlinkDir() throws Exception {
 
         // assert contents of the real directory were removed including the symlink
         FileUtils.cleanDirectory(realOuter);
+        assertTrue(realOuter.exists());
         assertEquals(0, realOuter.list().length);
 
         // ensure that the contents of the symlink were NOT removed.
@@ -121,6 +122,7 @@ void testCleanDirWithParentSymlinks() throws Exception {
         // assert contents of the real directory were removed including the symlink
         // should clean the contents of this but not recurse into other links
         FileUtils.cleanDirectory(symlinkParentDirectory);
+        assertTrue(symlinkParentDirectory.exists());
         assertEquals(0, symlinkParentDirectory.list().length);
         assertEquals(0, realParent.list().length);
 
@@ -155,6 +157,7 @@ void testCleanDirWithSymlinkFile() throws Exception {
 
         // assert contents of the real directory were removed including the symlink
         FileUtils.cleanDirectory(realOuter);
+        assertTrue(realOuter.exists());
         assertEquals(0, realOuter.list().length);
 
         // ensure that the contents of the symlink were NOT removed.
@@ -256,6 +259,7 @@ void testStillClearsIfGivenDirectoryIsASymlink() throws Exception {
         assertTrue(setupSymlink(randomDirectory, symlinkDirectory));
 
         FileUtils.cleanDirectory(symlinkDirectory);
+        assertTrue(symlinkDirectory.exists());
         assertEquals(0, symlinkDirectory.list().length);
         assertEquals(0, randomDirectory.list().length);
     }