DeferredFileOutputStream now clears and deletes its temporary storage by

default.

To get the old behavior back, call
org.apache.commons.io.output.DeferredFileOutputStream.Builder.setDeleteTempFileOnClose(false)

- Add DeferredFileOutputStream.Builder.setDeleteTempFileOnClose(boolean)
- Add PathUtils.clear[IfExists](Path)
- Add PathUtils.deleteIfExists(Path)
- Update generic type of RandomAccessFileMode.accept(Path, IOConsumer)
from IOConsumer<RandomAccessFile> to IOConsumer<IORandomAccessFile>
- Harden tests for NPEs on failures, happy path unchanged.

Author: garydgregory

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

@@ -19,6 +19,7 @@
 
 import java.io.File;
 import java.io.FileNotFoundException;
+import java.io.IOException;
 import java.io.RandomAccessFile;
 import java.util.Objects;
 
@@ -51,7 +52,7 @@ public IORandomAccessFile(final File file, final String mode) throws FileNotFoun
     /**
      * Constructs a new instance by calling {@link RandomAccessFile#RandomAccessFile(String, String)}.
      *
-     * @param name the file object.
+     * @param name the system-dependent file name.
      * @param mode the access mode, as described in {@link RandomAccessFile#RandomAccessFile(String, String)}.
      * @throws FileNotFoundException Thrown by {@link RandomAccessFile#RandomAccessFile(String, String)}.
      * @see RandomAccessFile#RandomAccessFile(String, String)
@@ -62,6 +63,26 @@ public IORandomAccessFile(final String name, final String mode) throws FileNotFo
         this.mode = mode;
     }
 
+    /**
+     * Clears the contents of this existing file by filling it with NUL ({@code 0)} bytes.
+     *
+     * @return {@code this} instance.
+     * @throws FileNotFoundException See {@link #IORandomAccessFile(File, String)}.
+     * @throws IOException           Thrown if an I/O error occurs.
+     */
+    public IORandomAccessFile clear() throws IOException {
+        final long length = length();
+        final byte[] zeroBuffer = IOUtils.byteArray();
+        long bytesWritten = 0;
+        while (bytesWritten < length) {
+            final long remaining = length - bytesWritten;
+            final int toWrite = (int) Math.min(zeroBuffer.length, remaining);
+            write(zeroBuffer, 0, toWrite);
+            bytesWritten += toWrite;
+        }
+        return this;
+    }
+
     /**
      * Gets the file passed to {@link #IORandomAccessFile(File, String)}.
      *
@@ -81,7 +102,7 @@ public String getMode() {
     }
 
     /**
-     * Returns the pathname string of this abstract pathname. This is just the string returned by the {@link File#toString()} method.
+     * Returns the path name string of this abstract pathname. This is just the string returned by the {@link File#toString()} method.
      *
      * @return The string form of the File's abstract pathname.
      * @see File#toString()
@@ -90,5 +111,4 @@ public String getMode() {
     public String toString() {
         return Objects.toString(file);
     }
-
 }

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

@@ -163,8 +163,8 @@ public static RandomAccessFileMode valueOfMode(final String mode) {
      * @throws IOException Thrown by the given function.
      * @since 2.18.0
      */
-    public void accept(final Path file, final IOConsumer<RandomAccessFile> consumer) throws IOException {
-        try (RandomAccessFile raf = create(file)) {
+    public void accept(final Path file, final IOConsumer<IORandomAccessFile> consumer) throws IOException {
+        try (IORandomAccessFile raf = new IORandomAccessFile(file.toFile(), mode)) {
             consumer.accept(raf);
         }
     }
@@ -282,7 +282,7 @@ public boolean implies(final RandomAccessFileMode other) {
     /**
      * Constructs a random access file to read from, and optionally to write to, the file specified by the {@link File} argument.
      *
-     * @param name the file object.
+     * @param name the system-dependent file name.
      * @return a random access file.
      * @throws FileNotFoundException See {@link IORandomAccessFile#IORandomAccessFile(File, String)}.
      * @since 2.18.0

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

@@ -18,6 +18,7 @@
 package org.apache.commons.io.file;
 
 import java.io.File;
+import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
@@ -75,6 +76,7 @@
 import org.apache.commons.io.Charsets;
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.FilenameUtils;
+import org.apache.commons.io.IORandomAccessFile;
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.io.RandomAccessFileMode;
 import org.apache.commons.io.RandomAccessFiles;
@@ -310,6 +312,33 @@ public static PathCounters cleanDirectory(final Path directory, final DeleteOpti
         return visitFileTree(new CleaningPathVisitor(Counters.longPathCounters(), deleteOptions), directory).getPathCounters();
     }
 
+    /**
+     * Clears the contents at an existing Path by filling it with NUL ({@code 0)} bytes.
+     *
+     * @param path The target path to an existing file.
+     * @return The given path.
+     * @throws FileNotFoundException See {@link IORandomAccessFile#IORandomAccessFile(File, String)}.
+     * @throws IOException Thrown writing to the Path.
+     * @since 2.23.0
+     */
+    public static Path clear(final Path path) throws IOException {
+        RandomAccessFileMode.READ_WRITE.accept(path, IORandomAccessFile::clear);
+        return path;
+    }
+
+    /**
+     * Clears the contents at a Path by filling it with NUL ({@code 0)} bytes.
+     *
+     * @param path The target path, may not exist, may be null.
+     * @return The given path.
+     * @throws FileNotFoundException See {@link IORandomAccessFile#IORandomAccessFile(File, String)}.
+     * @throws IOException Thrown writing to the Path.
+     * @since 2.23.0
+     */
+    public static Path clearIfExists(final Path path) throws IOException {
+        return exists(path) ? clear(path) : path;
+    }
+
     /**
      * Compares the given {@link Path}'s last modified time to the given file time.
      *
@@ -698,6 +727,18 @@ public static PathCounters deleteFile(final Path file, final LinkOption[] linkOp
         return pathCounts;
     }
 
+    /**
+     * A null-safe version of {@link Files#deleteIfExists(Path)}.
+     *
+     * @param path The path to the file to delete, may be {@code null}.
+     * @return Same as {@link Files#deleteIfExists(Path)} if {@code path} is non-null, false otherwise.
+     * @throws IOException Same as {@link Files#deleteIfExists(Path)}.
+     * @since 2.23.0
+     */
+    public static boolean deleteIfExists(final Path path) throws IOException {
+        return path != null && Files.deleteIfExists(path);
+    }
+
     /**
      * Delegates to {@link File#deleteOnExit()}.
      *

src/main/java/org/apache/commons/io/output/DeferredFileOutputStream.java

@@ -30,13 +30,13 @@
 
 /**
  * An output stream which will retain data in memory until a specified threshold is reached, and only then commit it to disk. If the stream is closed before the
- * threshold is reached, the data will not be written to disk at all.
+ * threshold is reached, the data will not be written to disk.
  * <p>
- * To build an instance, use {@link Builder}.
+ * To build an instance, use the {@link Builder builder}.
  * </p>
  * <p>
- * The caller is responsible for deleting the output file ({@link #getFile()}, {@link #getPath()}) created by a DeferredFileOutputStream when the caller only
- * configured a prefix.
+ * A temporary file created <em>only</em> when a prefix is configured (via {@link Builder#setPrefix(String)}) and is deleted automatically when {@link #close()}
+ * is called.
  * </p>
  * <p>
  * The caller is responsible for deleting the output file passed to a constructor or builder through {@link Builder#setOutputFile(File)} or
@@ -82,6 +82,7 @@ public static class Builder extends AbstractStreamBuilder<DeferredFileOutputStre
         private String prefix;
         private String suffix;
         private Path directory;
+        private boolean deleteTempFileOnClose = true;
 
         /**
          * Constructs a new builder of {@link DeferredFileOutputStream}.
@@ -113,6 +114,24 @@ public DeferredFileOutputStream get() {
             return new DeferredFileOutputStream(this);
         }
 
+        /**
+         * Sets whether to delete the temporary file when {@link DeferredFileOutputStream#close()} is called.
+         * <p>
+         * This only applies when a temporary file is created internally via a prefix/suffix configuration (i.e.,
+         * {@link #setPrefix(String)} is used). It has no effect when an explicit output file is provided via
+         * {@link #setOutputFile(File)} or {@link #setOutputFile(Path)}.
+         * </p>
+         *
+         * @param deleteTempFileOnClose {@code true} to delete the temporary file on close (default), {@code false} to
+         *                              keep it (the caller is then responsible for deleting it).
+         * @return {@code this} instance.
+         * @since 2.23.0
+         */
+        public Builder setDeleteTempFileOnClose(final boolean deleteTempFileOnClose) {
+            this.deleteTempFileOnClose = deleteTempFileOnClose;
+            return this;
+        }
+
         /**
          * Sets the temporary file directory.
          *
@@ -254,17 +273,29 @@ private static Path toPath(final Path file, final Supplier<Path> defaultPathSupp
      */
     private boolean closed;
 
+    /**
+     * True when the output file was created internally as a temporary file by {@link #thresholdReached()}.
+     * Such a file is deleted automatically when {@link #close()} is called (subject to {@link #deleteTempFileOnClose}).
+     */
+    private boolean tempFile;
+
+    /**
+     * Controls whether a temporary file created internally is deleted when {@link #close()} is called.
+     */
+    private final boolean deleteTempFileOnClose;
+
     /**
      * Constructs an instance of this class which will trigger an event at the specified threshold, and save data either to a file beyond that point.
      *
-     * @param builder         The construction data source.
+     * @param builder The construction data source.
      */
     private DeferredFileOutputStream(final Builder builder) {
         super(builder.threshold);
         this.outputPath = toPath(builder.outputFile, null);
         this.prefix = builder.prefix;
         this.suffix = builder.suffix;
         this.directory = toPath(builder.directory, PathUtils::getTempDirectory);
+        this.deleteTempFileOnClose = builder.deleteTempFileOnClose;
         this.memoryOutputStream = new ByteArrayOutputStream(checkBufferSize(builder.getBufferSize()));
         this.currentOutputStream = memoryOutputStream;
     }
@@ -300,6 +331,7 @@ private DeferredFileOutputStream(final int threshold, final File outputFile, fin
         this.prefix = prefix;
         this.suffix = suffix;
         this.directory = toPath(directory, PathUtils::getTempDirectory);
+        this.deleteTempFileOnClose = true;
         this.memoryOutputStream = new ByteArrayOutputStream(checkBufferSize(initialBufferSize));
         this.currentOutputStream = memoryOutputStream;
     }
@@ -351,14 +383,22 @@ public DeferredFileOutputStream(final int threshold, final String prefix, final
     }
 
     /**
-     * Closes underlying output stream, and mark this as closed
+     * Closes underlying output stream, and marks this as closed. If the output was directed to a temporary file created
+     * internally via a prefix/suffix configuration, and {@link Builder#setDeleteTempFileOnClose(boolean)} is
+     * {@code true} (the default), that file is deleted.
      *
      * @throws IOException if an error occurs.
      */
     @Override
     public void close() throws IOException {
-        super.close();
-        closed = true;
+        try {
+            super.close();
+        } finally {
+            closed = true;
+            if (tempFile && deleteTempFileOnClose && outputPath != null) {
+                PathUtils.deleteIfExists(PathUtils.clearIfExists(outputPath));
+            }
+        }
     }
 
     /**
@@ -436,6 +476,7 @@ public boolean isInMemory() {
     protected void thresholdReached() throws IOException {
         if (prefix != null) {
             outputPath = Files.createTempFile(directory, prefix, suffix);
+            tempFile = true;
         }
         PathUtils.createParentDirectories(outputPath, null, PathUtils.EMPTY_FILE_ATTRIBUTE_ARRAY);
         final OutputStream fos = Files.newOutputStream(outputPath);

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

@@ -2988,7 +2988,7 @@ void testSizeOfDirectory() throws Exception {
             // Different result value depending on the Java version and operating system, but should not throw an exception or loop infinitely.
             FileUtils.sizeOfDirectory(file);
         } finally {
-            Files.deleteIfExists(linkPath);
+            PathUtils.deleteIfExists(linkPath);
         }
     }
 
@@ -3030,7 +3030,7 @@ void testSizeOfDirectoryAsBigInteger() throws Exception {
             assertDelete(true, nonEmptyFile);
             assertDelete(false, file);
         } finally {
-            Files.deleteIfExists(linkPath);
+            PathUtils.deleteIfExists(linkPath);
         }
     }
 

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

@@ -50,7 +50,7 @@ class FilenameUtilsTest {
     private static final boolean WINDOWS = File.separatorChar == '\\';
 
     @TempDir
-    public Path temporaryFolder;
+    Path temporaryFolder;
 
     private Path testFile1;
     private Path testFile2;
@@ -59,42 +59,33 @@ class FilenameUtilsTest {
     private int testFile2Size;
 
     @BeforeEach
-    public void setUp() throws Exception {
+    void setUp() throws Exception {
         testFile1 = Files.createTempFile(temporaryFolder, "test", "1");
         testFile2 = Files.createTempFile(temporaryFolder, "test", "2");
-
         testFile1Size = (int) Files.size(testFile1);
         testFile2Size = (int) Files.size(testFile2);
         if (!Files.exists(testFile1.getParent())) {
-            throw new IOException("Cannot create file " + testFile1
-                    + " as the parent directory does not exist");
+            throw new IOException("Cannot create file " + testFile1 + " as the parent directory does not exist");
         }
-        try (BufferedOutputStream output3 =
-                new BufferedOutputStream(Files.newOutputStream(testFile1))) {
+        try (BufferedOutputStream output3 = new BufferedOutputStream(Files.newOutputStream(testFile1))) {
             TestUtils.generateTestData(output3, testFile1Size);
         }
         if (!Files.exists(testFile2.getParent())) {
-            throw new IOException("Cannot create file " + testFile2
-                    + " as the parent directory does not exist");
+            throw new IOException("Cannot create file " + testFile2 + " as the parent directory does not exist");
         }
-        try (BufferedOutputStream output2 =
-                new BufferedOutputStream(Files.newOutputStream(testFile2))) {
+        try (BufferedOutputStream output2 = new BufferedOutputStream(Files.newOutputStream(testFile2))) {
             TestUtils.generateTestData(output2, testFile2Size);
         }
         if (!Files.exists(testFile1.getParent())) {
-            throw new IOException("Cannot create file " + testFile1
-                    + " as the parent directory does not exist");
+            throw new IOException("Cannot create file " + testFile1 + " as the parent directory does not exist");
         }
-        try (BufferedOutputStream output1 =
-                new BufferedOutputStream(Files.newOutputStream(testFile1))) {
+        try (BufferedOutputStream output1 = new BufferedOutputStream(Files.newOutputStream(testFile1))) {
             TestUtils.generateTestData(output1, testFile1Size);
         }
         if (!Files.exists(testFile2.getParent())) {
-            throw new IOException("Cannot create file " + testFile2
-                    + " as the parent directory does not exist");
+            throw new IOException("Cannot create file " + testFile2 + " as the parent directory does not exist");
         }
-        try (BufferedOutputStream output =
-                new BufferedOutputStream(Files.newOutputStream(testFile2))) {
+        try (BufferedOutputStream output = new BufferedOutputStream(Files.newOutputStream(testFile2))) {
             TestUtils.generateTestData(output, testFile2Size);
         }
     }

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

@@ -17,10 +17,13 @@
 
 package org.apache.commons.io;
 
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
 
 import java.io.File;
 import java.io.IOException;
+import java.nio.file.Files;
 
 import org.apache.commons.io.build.AbstractOriginTest;
 import org.junit.jupiter.api.Test;
@@ -40,6 +43,32 @@ private File newFileFixture() throws IOException {
         return file;
     }
 
+    /**
+     * Tests {@link IORandomAccessFile#clear()} by writing known non-zero bytes to the file, calling {@code clear()},
+     * and verifying that every byte in the file is {@code 0}.
+     *
+     * @throws IOException Thrown on a test failure.
+     */
+    @Test
+    void testClear() throws IOException {
+        final File file = newFileFixture();
+        final byte[] originalData = { 1, 2, 3, 4, 5, 6, 7, 8 };
+        // Write non-zero data into the file first
+        Files.write(file.toPath(), originalData);
+        try (IORandomAccessFile raf = new IORandomAccessFile(file, "rw")) {
+            assertEquals(originalData.length, raf.length());
+            // clear() should overwrite every byte with 0 and return 'this'
+            @SuppressWarnings("resource")
+            final IORandomAccessFile echoRaf = raf.clear();
+            assertSame(raf, echoRaf);
+            // Seek back to the start and read the contents
+            raf.seek(0);
+            final byte[] result = new byte[originalData.length];
+            raf.readFully(result);
+            assertArrayEquals(new byte[originalData.length], result, "All bytes should be 0 after clear()");
+        }
+    }
+
     @ParameterizedTest
     @EnumSource(RandomAccessFileMode.class)
     void testFile(final RandomAccessFileMode mode) throws IOException {