Merge pull request #725 from ascopes/task/GH-721-add-new-overloads

GH-721: Add overloads for workspaces APIs to support list types.

Author: ascopes

java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/impl/OutputContainerGroupImpl.java

@@ -28,6 +28,7 @@
 import io.github.ascopes.jct.workspaces.impl.WrappingDirectoryImpl;
 import java.nio.file.Files;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import javax.tools.JavaFileManager.Location;
@@ -186,7 +187,7 @@ private PackageContainerGroup newPackageGroup(ModuleLocation moduleLocation) {
     var group = new AbstractPackageContainerGroup(moduleLocation, release) {};
     var pathWrapper = new WrappingDirectoryImpl(
         getPackages().iterator().next().getPathRoot(),
-        moduleLocation.getModuleName()
+        List.of(moduleLocation.getModuleName())
     );
     uncheckedIo(() -> Files.createDirectories(pathWrapper.getPath()));
     group.addPackage(pathWrapper);

java-compiler-testing/src/main/java/io/github/ascopes/jct/utils/FileUtils.java

@@ -95,7 +95,7 @@ public static URL retrieveRequiredUrl(Path path) {
    * @param parts the parts to resolve.
    * @return the resolved path.
    */
-  public static Path resolvePathRecursively(Path root, String... parts) {
+  public static Path resolvePathRecursively(Path root, List<String> parts) {
     return resolve(root, parts);
   }
 

java-compiler-testing/src/main/java/io/github/ascopes/jct/workspaces/DirectoryBuilder.java

@@ -18,6 +18,7 @@
 import java.io.File;
 import java.nio.file.FileSystem;
 import java.nio.file.Path;
+import java.util.List;
 import org.apiguardian.api.API;
 import org.apiguardian.api.API.Status;
 
@@ -31,6 +32,38 @@
 @API(since = "0.0.1", status = Status.STABLE)
 public interface DirectoryBuilder {
 
+  /**
+   * Copy the contents of the directory at the given path recursively into this directory.
+   *
+   * <p>Symbolic links will not be followed.
+   *
+   * <p>This uses the default file system. If you want to use a different {@link FileSystem}
+   * as your source, then use {@link #copyContentsFrom(Path)} instead.
+   *
+   * <p>Examples:
+   *
+   * <pre><code>
+   *   // Letting JCT infer the correct path separators to use (recommended).
+   *   directoryBuilder.copyContentsFrom(List.of("foo", "bar", "baz"));
+   *
+   *   // Using POSIX platform-specific separators (may cause issues if your tests run on Windows)
+   *   directoryBuilder.copyContentsFrom(List.of("foo/bar/baz"));
+   *
+   *   // Using Windows platform-specific separators (may cause issues if your tests run on POSIX)
+   *   directoryBuilder.copyContentsFrom(List.of("foo\\bar\\baz"));
+   * </code></pre>
+   *
+   * @param fragments parts of the path.
+   * @return the root managed directory for further configuration.
+   * @throws IllegalArgumentException if no path fragments are provided.
+   * @throws NullPointerException     if any null path fragments are provided.
+   * @see #copyContentsFrom(Path)
+   * @see #copyContentsFrom(String...)
+   * @since 4.0.0
+   */
+  @API(since = "4.0.0", status = Status.STABLE)
+  ManagedDirectory copyContentsFrom(List<String> fragments);
+
   /**
    * Copy the contents of the directory at the given path recursively into this directory.
    *
@@ -57,8 +90,11 @@ public interface DirectoryBuilder {
    * @throws IllegalArgumentException if no path fragments are provided.
    * @throws NullPointerException     if any null path fragments are provided.
    * @see #copyContentsFrom(Path)
+   * @see #copyContentsFrom(List)
    */
-  ManagedDirectory copyContentsFrom(String... fragments);
+  default ManagedDirectory copyContentsFrom(String... fragments) {
+    return copyContentsFrom(List.of(fragments));
+  }
 
   /**
    * Copy the contents of the directory at the given path recursively into this directory.

java-compiler-testing/src/main/java/io/github/ascopes/jct/workspaces/FileBuilder.java

@@ -18,8 +18,10 @@
 import java.io.File;
 import java.io.InputStream;
 import java.net.URL;
+import java.nio.ByteBuffer;
 import java.nio.charset.Charset;
 import java.nio.file.Path;
+import java.util.List;
 import org.apiguardian.api.API;
 import org.apiguardian.api.API.Status;
 
@@ -176,7 +178,6 @@ public interface FileBuilder {
    */
   ManagedDirectory thatIsEmpty();
 
-
   /**
    * Create the file with the given byte contents.
    *
@@ -211,9 +212,53 @@ public interface FileBuilder {
    *
    * @param contents the bytes to write.
    * @return the root managed directory for further configuration.
+   * @see #withContents(ByteBuffer)
    */
   ManagedDirectory withContents(byte[] contents);
 
+  /**
+   * An overload of {@link #withContents(byte[])} that consumes a NIO byte buffer.
+   *
+   * @param buffer the byte buffer to consume.
+   * @return the managed directory.
+   * @since 4.0.0
+   */
+  @API(since = "4.0.0", status = Status.STABLE)
+  default ManagedDirectory withContents(ByteBuffer buffer) {
+    var array = new byte[buffer.remaining()];
+    buffer.get(array);
+    return withContents(array);
+  }
+
+  /**
+   * Create the file with the given contents.
+   *
+   * <pre><code>
+   *   directory
+   *      .createFile("org", "example", "HelloWorld.java")
+   *      .withContents(StandardCharsets.US_ASCII, List.of(
+   *        "package org.example;",
+   *        "",
+   *        "public class HelloWorld {",
+   *        "  public static void main(String[] args) {",
+   *        "    System.out.println(\"Hello, World!\");",
+   *        "  }",
+   *        "}"
+   *      ));
+   * </code></pre>
+   *
+   * @param charset the character encoding to use.
+   * @param lines   the lines to write.
+   * @return the root managed directory for further configuration.
+   * @see #withContents(Charset, String...)
+   * @see #withContents(String...)
+   * @see #withContents(List)
+   * @see #withContents(byte[])
+   * @since 4.0.0
+   */
+  @API(since = "4.0.0", status = Status.STABLE)
+  ManagedDirectory withContents(Charset charset, List<String> lines);
+
   /**
    * Create the file with the given contents.
    *
@@ -253,10 +298,44 @@ public interface FileBuilder {
    * @param charset the character encoding to use.
    * @param lines   the lines to write.
    * @return the root managed directory for further configuration.
+   * @see #withContents(List)
+   * @see #withContents(Charset, List)
+   * @see #withContents(String...)
+   * @see #withContents(byte[])
+   */
+  default ManagedDirectory withContents(Charset charset, String... lines) {
+    return withContents(charset, List.of(lines));
+  }
+
+  /**
+   * Create the file with the given contents as UTF-8.
+   *
+   * <p>If you are using multi-line strings, an example of usage would be:
+   *
+   * <pre><code>
+   *   directory
+   *      .createFile("org", "example", "HelloWorld.java")
+   *      .withContents(List.of(
+   *        "package org.example;",
+   *        "",
+   *        "public class HelloWorld {",
+   *        "  public static void main(String[] args) {",
+   *        "    System.out.println(\"Hello, World!\");",
+   *        "  }",
+   *        "}"
+   *      ));
+   * </code></pre>
+   *
+   * @param lines the lines to write using the default charset.
+   * @return the root managed directory for further configuration.
+   * @see #withContents(Charset, String...)
    * @see #withContents(String...)
+   * @see #withContents(Charset, List)
    * @see #withContents(byte[])
+   * @since 4.0.0
    */
-  ManagedDirectory withContents(Charset charset, String... lines);
+  @API(since = "4.0.0", status = Status.STABLE)
+  ManagedDirectory withContents(List<String> lines);
 
   /**
    * Create the file with the given contents as UTF-8.
@@ -298,7 +377,11 @@ public interface FileBuilder {
    * @param lines the lines to write using the default charset.
    * @return the root managed directory for further configuration.
    * @see #withContents(Charset, String...)
+   * @see #withContents(List)
+   * @see #withContents(Charset, List)
    * @see #withContents(byte[])
    */
-  ManagedDirectory withContents(String... lines);
+  default ManagedDirectory withContents(String... lines) {
+    return withContents(List.of(lines));
+  }
 }

java-compiler-testing/src/main/java/io/github/ascopes/jct/workspaces/ManagedDirectory.java

@@ -17,6 +17,7 @@
 
 import java.io.Closeable;
 import java.io.IOException;
+import java.util.List;
 import org.apiguardian.api.API;
 import org.apiguardian.api.API.Status;
 
@@ -101,7 +102,31 @@ default ManagedDirectory and() {
    * @throws IllegalArgumentException if no path fragments are provided.
    * @throws NullPointerException     if any of the path fragments are {@code null}.
    */
-  DirectoryBuilder createDirectory(String... fragments);
+  default DirectoryBuilder createDirectory(String... fragments) {
+    return createDirectory(List.of(fragments));
+  }
+
+  /**
+   * Create a directory builder for the given path in this RAM file system.
+   *
+   * <p>Examples:
+   *
+   * <pre><code>
+   *   // Using platform-specific separators.
+   *   dir.createDirectory(List.of("foo/bar/baz"))...;
+   *
+   *   // Letting JCT infer the correct path separators to use (recommended).
+   *   dir.createDirectory(List.of("foo", "bar", "baz"))...;
+   * </code></pre>
+   *
+   * @param fragments the parts of the path.
+   * @return the directory builder.
+   * @throws IllegalArgumentException if no path fragments are provided.
+   * @throws NullPointerException     if any of the path fragments are {@code null}.
+   * @since 4.0.0
+   */
+  @API(since = "4.0.0", status = Status.STABLE)
+  DirectoryBuilder createDirectory(List<String> fragments);
 
   /**
    * Create a file builder for the given path in this RAM file system.
@@ -119,7 +144,29 @@ default ManagedDirectory and() {
    * @throws IllegalArgumentException if no path fragments are provided.
    * @throws NullPointerException     if any of the path fragments are {@code null}.
    */
-  FileBuilder createFile(String... fragments);
+  default FileBuilder createFile(String... fragments) {
+    return createFile(List.of(fragments));
+  }
+
+  /**
+   * Create a file builder for the given path in this RAM file system.
+   *
+   * <pre><code>
+   *   // Using platform-specific separators.
+   *   dir.createFile(List.of("foo/bar/baz.txt"))...;
+   *
+   *   // Letting JCT infer the correct path separators to use (recommended).
+   *   dir.createFile(List.of("foo", "bar", "baz.txt"))...;
+   * </code></pre>
+   *
+   * @param fragments the parts of the path.
+   * @return the file builder.
+   * @throws IllegalArgumentException if no path fragments are provided.
+   * @throws NullPointerException     if any of the path fragments are {@code null}.
+   * @since 4.0.0
+   */
+  @API(since = "4.0.0", status = Status.STABLE)
+  FileBuilder createFile(List<String> fragments);
 
   /**
    * Get the identifying name of the temporary file system.

java-compiler-testing/src/main/java/io/github/ascopes/jct/workspaces/Workspace.java

@@ -880,7 +880,7 @@ default <T extends Throwable> void use(ThrowingWorkspaceConsumer<T> consumer) th
    * @since 3.2.0
    */
   @API(since = "3.2.0", status = Status.STABLE)
-  public interface ThrowingWorkspaceConsumer<T extends Throwable> {
+  interface ThrowingWorkspaceConsumer<T extends Throwable> {
 
     /**
      * Consume a workspace.

java-compiler-testing/src/main/java/io/github/ascopes/jct/workspaces/impl/AbstractManagedDirectory.java

@@ -31,6 +31,7 @@
 import java.net.URI;
 import java.net.URL;
 import java.nio.file.Path;
+import java.util.List;
 import org.apiguardian.api.API;
 import org.apiguardian.api.API.Status;
 import org.jspecify.annotations.Nullable;
@@ -112,21 +113,21 @@ public String getName() {
   }
 
   @Override
-  public FileBuilder createFile(String... fragments) {
+  public FileBuilder createFile(List<String> fragments) {
     requireNonNullValues(fragments, "fragments");
     requireAtLeastOne(fragments, "fragments");
     return new FileBuilderImpl(this, fragments);
   }
 
   @Override
-  public DirectoryBuilder createDirectory(String... fragments) {
+  public DirectoryBuilder createDirectory(List<String> fragments) {
     requireNonNullValues(fragments, "fragments");
     requireAtLeastOne(fragments, "fragments");
     return new DirectoryBuilderImpl(this, fragments);
   }
 
   @Override
-  public ManagedDirectory copyContentsFrom(String... fragments) {
+  public ManagedDirectory copyContentsFrom(List<String> fragments) {
     requireNonNullValues(fragments, "fragments");
     requireAtLeastOne(fragments, "fragments");
     return rootDirectory().copyContentsFrom(fragments);
@@ -167,6 +168,6 @@ public String toString() {
   }
 
   private DirectoryBuilder rootDirectory() {
-    return new DirectoryBuilderImpl(this, "");
+    return new DirectoryBuilderImpl(this, List.of(""));
   }
 }

java-compiler-testing/src/main/java/io/github/ascopes/jct/workspaces/impl/DirectoryBuilderImpl.java

@@ -29,6 +29,7 @@
 import java.nio.file.Path;
 import java.nio.file.SimpleFileVisitor;
 import java.nio.file.attribute.BasicFileAttributes;
+import java.util.List;
 import java.util.StringJoiner;
 import org.apiguardian.api.API;
 import org.apiguardian.api.API.Status;
@@ -55,7 +56,7 @@ public final class DirectoryBuilderImpl implements DirectoryBuilder {
    * @param parent    the parent managed directory to chain calls back onto.
    * @param fragments parts of the directory path.
    */
-  public DirectoryBuilderImpl(ManagedDirectory parent, String... fragments) {
+  public DirectoryBuilderImpl(ManagedDirectory parent, List<String> fragments) {
     requireNonNullValues(fragments, "fragments");
     requireAtLeastOne(fragments, "fragments");
 
@@ -64,14 +65,15 @@ public DirectoryBuilderImpl(ManagedDirectory parent, String... fragments) {
   }
 
   @Override
-  public ManagedDirectory copyContentsFrom(String... fragments) {
+  public ManagedDirectory copyContentsFrom(List<String> fragments) {
     requireNonNullValues(fragments, "fragments");
     requireAtLeastOne(fragments, "fragments");
 
     // Path.of is fine here as it is for the default file system.
-    var path = Path.of(fragments[0]);
-    for (var i = 1; i < fragments.length; ++i) {
-      path = path.resolve(fragments[i]);
+    var iter = fragments.iterator();
+    var path = Path.of(iter.next());
+    while (iter.hasNext()) {
+      path = path.resolve(iter.next());
     }
 
     return copyContentsFrom(path);