From 7f005382b6516b3fa53a54bfa3f4bbfe4b2b573e Mon Sep 17 00:00:00 2001
From: Sarankumar Baskar <sbaskar@redhat.com>
Date: Fri, 12 Jun 2026 10:27:44 +0530
Subject: [PATCH 1/2] [IO-438] Clarify IOUtils.closeQuietly() Javadocs Remove
 examples that quietly close output streams after copy operations, and
 document when close failures should not be ignored.

---
 .../java/org/apache/commons/io/IOUtils.java   | 29 ++++---------------
 1 file changed, 5 insertions(+), 24 deletions(-)

diff --git a/src/main/java/org/apache/commons/io/IOUtils.java b/src/main/java/org/apache/commons/io/IOUtils.java
index d4b9af073d0..ba4ac61e03b 100644
--- a/src/main/java/org/apache/commons/io/IOUtils.java
+++ b/src/main/java/org/apache/commons/io/IOUtils.java
@@ -778,7 +778,11 @@ private static void closeQ(final Closeable closeable) {
     /**
      * Closes a {@link Closeable} unconditionally.
      * <p>
-     * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in finally blocks.
+     * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in cleanup code when reporting a close failure is not
+     * necessary or useful.
+     * <p>
+     * Do not use this method to close output streams or writers when close failures must be reported. Closing an output stream or writer may flush buffered data,
+     * and ignoring a close failure can hide that data was not fully written.
      * <p>
      * Example code:
      * </p>
@@ -796,18 +800,6 @@ private static void closeQ(final Closeable closeable) {
      * }
      * </pre>
      * <p>
-     * Closing all streams:
-     * </p>
-     *
-     * <pre>
-     * try {
-     *     return IOUtils.copy(inputStream, outputStream);
-     * } finally {
-     *     IOUtils.closeQuietly(inputStream);
-     *     IOUtils.closeQuietly(outputStream);
-     * }
-     * </pre>
-     * <p>
      * Also consider using a try-with-resources statement where appropriate.
      * </p>
      *
@@ -848,17 +840,6 @@ public static void closeQuietly(final Closeable closeable) {
      * }
      * </pre>
      * <p>
-     * Closing all streams:
-     * </p>
-     *
-     * <pre>
-     * try {
-     *     return IOUtils.copy(inputStream, outputStream);
-     * } finally {
-     *     IOUtils.closeQuietly(inputStream, outputStream);
-     * }
-     * </pre>
-     * <p>
      * Also consider using a try-with-resources statement where appropriate.
      * </p>
      *

From fe21bcfe0234769edb2db7dad84e7fd5d885aee5 Mon Sep 17 00:00:00 2001
From: Sarankumar Baskar <sbaskar@redhat.com>
Date: Fri, 12 Jun 2026 17:50:32 +0530
Subject: [PATCH 2/2] [IO-438] Clarify IOUtils.closeQuietly() Javadocs, and
 added examples Show output streams being closed normally before falling back
 to closeQuietly() for cleanup.

---
 .../java/org/apache/commons/io/IOUtils.java   | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/main/java/org/apache/commons/io/IOUtils.java b/src/main/java/org/apache/commons/io/IOUtils.java
index ba4ac61e03b..0debd25897e 100644
--- a/src/main/java/org/apache/commons/io/IOUtils.java
+++ b/src/main/java/org/apache/commons/io/IOUtils.java
@@ -800,6 +800,20 @@ private static void closeQ(final Closeable closeable) {
      * }
      * </pre>
      * <p>
+     * Closing all streams:
+     * </p>
+     *
+     * <pre>
+     * try {
+     *     IOUtils.copy(inputStream, outputStream);
+     *     outputStream.close(); // close errors are handled
+     *     outputStream = null;
+     * } finally {
+     *     IOUtils.closeQuietly(inputStream);
+     *     IOUtils.closeQuietly(outputStream); // only if normal close was skipped
+     * }
+     * </pre>
+     * <p>
      * Also consider using a try-with-resources statement where appropriate.
      * </p>
      *
@@ -840,6 +854,19 @@ public static void closeQuietly(final Closeable closeable) {
      * }
      * </pre>
      * <p>
+     * Closing all streams:
+     * </p>
+     *
+     * <pre>
+     * try {
+     *     IOUtils.copy(inputStream, outputStream);
+     *     outputStream.close(); // close errors are handled
+     *     outputStream = null;
+     * } finally {
+     *     IOUtils.closeQuietly(inputStream, outputStream); // only closes outputStream if normal close was skipped
+     * }
+     * </pre>
+     * <p>
      * Also consider using a try-with-resources statement where appropriate.
      * </p>
      *