GROOVY-11902: minor groovy-nio improvements

paulk-asert · paulk-asert · commit fead705f2c92 · 2026-04-04T23:47:53.000+11:00
diff --git a/build.gradle b/build.gradle
@@ -109,6 +109,7 @@ dependencies {
     }
 
     testImplementation projects.groovyAnt
+    testImplementation projects.groovyNio
     testImplementation projects.groovyXml
     testImplementation projects.groovyJson
     testImplementation projects.groovyTest
diff --git a/src/spec/doc/_working-with-io.adoc b/src/spec/doc/_working-with-io.adoc
@@ -88,6 +88,17 @@ makes it very easy actually:
 include::../test/gdk/WorkingWithIOSpecTest.groovy[tags=file_bytes,indent=0]
 ----
 
+Groovy also provides asynchronous variants for reading and writing files via the `groovy-nio` module.
+These return a `CompletableFuture`, making them composable and easy to use with async frameworks.
+
+[source,groovy]
+----
+include::../test/gdk/WorkingWithIOSpecTest.groovy[tags=async_read,indent=0]
+----
+
+Similarly, `path.bytesAsync` returns a `CompletableFuture<byte[]>`, and
+`path.writeAsync(text)` writes content asynchronously.
+
 Working with I/O is not limited to dealing with files. In fact, a lot of operations rely on input/output streams,
 hence why Groovy adds a lot of support methods to those, as you can see in the
 http://docs.groovy-lang.org/latest/html/groovy-jdk/java/io/InputStream.html[documentation].
diff --git a/src/spec/test/gdk/WorkingWithIOSpecTest.groovy b/src/spec/test/gdk/WorkingWithIOSpecTest.groovy
@@ -79,6 +79,17 @@ Le bruit de l'eau.''')
             // tag::file_bytes[]
             byte[] contents = file.bytes
             // end::file_bytes[]
+
+            // tag::async_read[]
+            def path = file.toPath()
+            def future = path.textAsync           // returns CompletableFuture<String>
+            // end::async_read[]
+            /*
+            // tag::async_read[]
+            println future.get()                  // blocks until content is available
+            // end::async_read[]
+            */
+            println future.get(5, java.util.concurrent.TimeUnit.SECONDS)
         }
     }
 
diff --git a/subprojects/groovy-nio/src/main/java/org/apache/groovy/nio/extensions/NioExtensions.java b/subprojects/groovy-nio/src/main/java/org/apache/groovy/nio/extensions/NioExtensions.java
@@ -56,18 +56,23 @@
 import java.io.Reader;
 import java.io.Writer;
 import java.net.URI;
+import java.nio.ByteBuffer;
+import java.nio.channels.AsynchronousFileChannel;
+import java.nio.channels.CompletionHandler;
 import java.nio.charset.Charset;
 import java.nio.file.DirectoryStream;
 import java.nio.file.Files;
 import java.nio.file.LinkOption;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.nio.file.attribute.FileAttribute;
+import java.nio.file.StandardOpenOption;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.CompletableFuture;
 import java.util.regex.Pattern;
 
 import static java.lang.Boolean.FALSE;
@@ -2036,4 +2041,251 @@ public static <T> T withCloseable(Closeable self, @ClosureParams(value = SimpleT
         return IOGroovyMethods.withCloseable(self, action);
     }
 
+    // -------------------------------------------------------------------------
+    // Asynchronous file I/O extensions
+    // -------------------------------------------------------------------------
+
+    /**
+     * Asynchronously read the content of the Path and return it as a String
+     * using the platform's default charset.
+     * <p>
+     * Uses {@link AsynchronousFileChannel} internally, making the I/O
+     * non-blocking. The returned {@link CompletableFuture} completes
+     * when the entire file has been read.
+     *
+     * <pre class="groovyTestCase">
+     * import java.nio.file.Files
+     * def path = Files.createTempFile('test', '.txt')
+     * path.text = 'Hello async'
+     * assert path.textAsync.get() == 'Hello async'
+     * Files.delete(path)
+     * </pre>
+     *
+     * @param self the file whose content we want to read
+     * @return a CompletableFuture that completes with the file content as a String
+     * @since 6.0.0
+     */
+    public static CompletableFuture<String> getTextAsync(Path self) {
+        return getTextAsync(self, Charset.defaultCharset().name());
+    }
+
+    /**
+     * Asynchronously read the content of the Path and return it as a String
+     * using the specified charset.
+     *
+     * <pre class="groovyTestCase">
+     * import java.nio.file.Files
+     * def path = Files.createTempFile('test', '.txt')
+     * path.text = 'Hello async'
+     * assert path.getTextAsync('UTF-8').get() == 'Hello async'
+     * Files.delete(path)
+     * </pre>
+     *
+     * @param self    the file whose content we want to read
+     * @param charset the charset used to decode the file content
+     * @return a CompletableFuture that completes with the file content as a String
+     * @since 6.0.0
+     */
+    public static CompletableFuture<String> getTextAsync(Path self, String charset) {
+        return getBytesAsync(self).thenApply(bytes -> new String(bytes, Charset.forName(charset)));
+    }
+
+    /**
+     * Asynchronously read the content of the Path and return it as a byte array.
+     * <p>
+     * Uses {@link AsynchronousFileChannel} internally. The entire file content
+     * is read into a byte array.
+     *
+     * <pre class="groovyTestCase">
+     * import java.nio.file.Files
+     * def path = Files.createTempFile('test', '.txt')
+     * path.bytes = [72, 105] as byte[]
+     * assert path.bytesAsync.get() == [72, 105] as byte[]
+     * Files.delete(path)
+     * </pre>
+     *
+     * @param self the file whose content we want to read
+     * @return a CompletableFuture that completes with the file content as a byte array
+     * @since 6.0.0
+     */
+    public static CompletableFuture<byte[]> getBytesAsync(Path self) {
+        CompletableFuture<byte[]> result = new CompletableFuture<>();
+        AsynchronousFileChannel channel = null;
+        try {
+            channel = AsynchronousFileChannel.open(self, StandardOpenOption.READ);
+            long size = channel.size();
+            if (size > Integer.MAX_VALUE) {
+                channel.close();
+                result.completeExceptionally(new IOException("File too large to read into a single byte array: " + size + " bytes"));
+                return result;
+            }
+            ByteBuffer buf = ByteBuffer.allocate((int) size);
+            readFully(channel, buf, 0, result);
+        } catch (IOException | RuntimeException e) {
+            if (channel != null) {
+                try {
+                    channel.close();
+                } catch (IOException ignored) {
+                }
+            }
+            result.completeExceptionally(e);
+        }
+        return result;
+    }
+
+    private static void readFully(AsynchronousFileChannel channel, ByteBuffer buf,
+                                  long position, CompletableFuture<byte[]> result) {
+        channel.read(buf, position, null, new CompletionHandler<Integer, Void>() {
+            @Override
+            public void completed(Integer bytesRead, Void attachment) {
+                if (bytesRead == -1 || !buf.hasRemaining()) {
+                    try {
+                        channel.close();
+                    } catch (IOException e) {
+                        result.completeExceptionally(e);
+                        return;
+                    }
+                    buf.flip();
+                    byte[] bytes = new byte[buf.remaining()];
+                    buf.get(bytes);
+                    result.complete(bytes);
+                } else {
+                    readFully(channel, buf, position + bytesRead, result);
+                }
+            }
+
+            @Override
+            public void failed(Throwable exc, Void attachment) {
+                try {
+                    channel.close();
+                } catch (IOException ignored) {
+                }
+                result.completeExceptionally(exc);
+            }
+        });
+    }
+
+    /**
+     * Asynchronously write the String content to the Path using the
+     * platform's default charset.
+     *
+     * <pre class="groovyTestCase">
+     * import java.nio.file.Files
+     * def path = Files.createTempFile('test', '.txt')
+     * path.writeAsync('Hello async').get()
+     * assert path.text == 'Hello async'
+     * Files.delete(path)
+     * </pre>
+     *
+     * @param self the file to write to
+     * @param text the text to write
+     * @return a CompletableFuture that completes when the write is finished
+     * @since 6.0.0
+     */
+    public static CompletableFuture<Void> writeAsync(Path self, String text) {
+        return writeAsync(self, text, Charset.defaultCharset().name());
+    }
+
+    /**
+     * Asynchronously write the String content to the Path using the
+     * specified charset.
+     *
+     * <pre class="groovyTestCase">
+     * import java.nio.file.Files
+     * def path = Files.createTempFile('test', '.txt')
+     * path.writeAsync('Hello async', 'UTF-8').get()
+     * assert path.text == 'Hello async'
+     * Files.delete(path)
+     * </pre>
+     *
+     * @param self    the file to write to
+     * @param text    the text to write
+     * @param charset the charset used to encode the text
+     * @return a CompletableFuture that completes when the write is finished
+     * @since 6.0.0
+     */
+    public static CompletableFuture<Void> writeAsync(Path self, String text, String charset) {
+        try {
+            return writeBytesAsync(self, text.getBytes(Charset.forName(charset)));
+        } catch (RuntimeException e) {
+            CompletableFuture<Void> result = new CompletableFuture<>();
+            result.completeExceptionally(e);
+            return result;
+        }
+    }
+
+    /**
+     * Asynchronously write the byte array to the Path, creating the file
+     * if it doesn't exist and truncating it if it does.
+     *
+     * <pre class="groovyTestCase">
+     * import java.nio.file.Files
+     * def path = Files.createTempFile('test', '.txt')
+     * path.writeBytesAsync([72, 105] as byte[]).get()
+     * assert path.bytes == [72, 105] as byte[]
+     * Files.delete(path)
+     * </pre>
+     *
+     * @param self  the file to write to
+     * @param bytes the byte array to write
+     * @return a CompletableFuture that completes when the write is finished
+     * @since 6.0.0
+     */
+    public static CompletableFuture<Void> writeBytesAsync(Path self, byte[] bytes) {
+        CompletableFuture<Void> result = new CompletableFuture<>();
+        AsynchronousFileChannel channel = null;
+        try {
+            channel = AsynchronousFileChannel.open(self,
+                    StandardOpenOption.WRITE, StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);
+            ByteBuffer buf = ByteBuffer.wrap(bytes);
+            writeFully(channel, buf, 0, result);
+        } catch (IOException | RuntimeException e) {
+            if (channel != null) {
+                try {
+                    channel.close();
+                } catch (IOException ignored) {
+                }
+            }
+            result.completeExceptionally(e);
+        }
+        return result;
+    }
+
+    private static void writeFully(AsynchronousFileChannel channel, ByteBuffer buf,
+                                   long position, CompletableFuture<Void> result) {
+        channel.write(buf, position, null, new CompletionHandler<Integer, Void>() {
+            @Override
+            public void completed(Integer bytesWritten, Void attachment) {
+                if (buf.hasRemaining()) {
+                    if (bytesWritten <= 0) {
+                        try {
+                            channel.close();
+                        } catch (IOException ignored) {
+                        }
+                        result.completeExceptionally(new IOException("Async write made no progress"));
+                        return;
+                    }
+                    writeFully(channel, buf, position + bytesWritten, result);
+                } else {
+                    try {
+                        channel.close();
+                    } catch (IOException e) {
+                        result.completeExceptionally(e);
+                        return;
+                    }
+                    result.complete(null);
+                }
+            }
+
+            @Override
+            public void failed(Throwable exc, Void attachment) {
+                try {
+                    channel.close();
+                } catch (IOException ignored) {
+                }
+                result.completeExceptionally(exc);
+            }
+        });
+    }
+
 }
diff --git a/subprojects/groovy-nio/src/test/groovy/org/apache/groovy/nio/extensions/NioExtensionsTest.groovy b/subprojects/groovy-nio/src/test/groovy/org/apache/groovy/nio/extensions/NioExtensionsTest.groovy

Original file line number	Diff line number	Diff line change
`@@ -109,6 +109,7 @@ dependencies {`
`109`	`109`	`}`
`110`	`110`
`111`	`111`	`testImplementation projects.groovyAnt`
	`112`	`+ testImplementation projects.groovyNio`
`112`	`113`	`testImplementation projects.groovyXml`
`113`	`114`	`testImplementation projects.groovyJson`
`114`	`115`	`testImplementation projects.groovyTest`