001/*
002 * Copyright (C) 2022 - 2024, the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *    http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package io.github.ascopes.jct.workspaces;
017
018import java.io.File;
019import java.nio.file.FileSystem;
020import java.nio.file.Path;
021import java.util.List;
022import org.apiguardian.api.API;
023import org.apiguardian.api.API.Status;
024
025/**
026 * Chainable builder for creating directories.
027 *
028 * @author Ashley Scopes
029 * @since 0.0.1
030 */
031@SuppressWarnings("unused")
032@API(since = "0.0.1", status = Status.STABLE)
033public interface DirectoryBuilder {
034
035  /**
036   * Copy the contents of the directory at the given path recursively into this directory.
037   *
038   * <p>Symbolic links will not be followed.
039   *
040   * <p>This uses the default file system. If you want to use a different {@link FileSystem}
041   * as your source, then use {@link #copyContentsFrom(Path)} instead.
042   *
043   * <p>Examples:
044   *
045   * <pre><code>
046   *   // Letting JCT infer the correct path separators to use (recommended).
047   *   directoryBuilder.copyContentsFrom(List.of("foo", "bar", "baz"));
048   *
049   *   // Using POSIX platform-specific separators (may cause issues if your tests run on Windows)
050   *   directoryBuilder.copyContentsFrom(List.of("foo/bar/baz"));
051   *
052   *   // Using Windows platform-specific separators (may cause issues if your tests run on POSIX)
053   *   directoryBuilder.copyContentsFrom(List.of("foo\\bar\\baz"));
054   * </code></pre>
055   *
056   * @param fragments parts of the path.
057   * @return the root managed directory for further configuration.
058   * @throws IllegalArgumentException if no path fragments are provided.
059   * @throws NullPointerException     if any null path fragments are provided.
060   * @see #copyContentsFrom(Path)
061   * @see #copyContentsFrom(String...)
062   * @since 4.0.0
063   */
064  @API(since = "4.0.0", status = Status.STABLE)
065  ManagedDirectory copyContentsFrom(List<String> fragments);
066
067  /**
068   * Copy the contents of the directory at the given path recursively into this directory.
069   *
070   * <p>Symbolic links will not be followed.
071   *
072   * <p>This uses the default file system. If you want to use a different {@link FileSystem}
073   * as your source, then use {@link #copyContentsFrom(Path)} instead.
074   *
075   * <p>Examples:
076   *
077   * <pre><code>
078   *   // Letting JCT infer the correct path separators to use (recommended).
079   *   directoryBuilder.copyContentsFrom("foo", "bar", "baz");
080   *
081   *   // Using POSIX platform-specific separators (may cause issues if your tests run on Windows)
082   *   directoryBuilder.copyContentsFrom("foo/bar/baz");
083   *
084   *   // Using Windows platform-specific separators (may cause issues if your tests run on POSIX)
085   *   directoryBuilder.copyContentsFrom("foo\\bar\\baz");
086   * </code></pre>
087   *
088   * @param fragments parts of the path.
089   * @return the root managed directory for further configuration.
090   * @throws IllegalArgumentException if no path fragments are provided.
091   * @throws NullPointerException     if any null path fragments are provided.
092   * @see #copyContentsFrom(Path)
093   * @see #copyContentsFrom(List)
094   */
095  default ManagedDirectory copyContentsFrom(String... fragments) {
096    return copyContentsFrom(List.of(fragments));
097  }
098
099  /**
100   * Copy the contents of the directory at the given path recursively into this directory.
101   *
102   * <p>Symbolic links will not be followed.
103   *
104   * <pre><code>
105   *  directory.copyContentsFrom(new File("code/examples"));
106   * </code></pre>
107   *
108   * @param dir the directory to copy the contents from.
109   * @return the root managed directory for further configuration.
110   */
111  ManagedDirectory copyContentsFrom(File dir);
112
113  /**
114   * Copy the contents of the directory at the given path recursively into this directory.
115   *
116   * <p>Symbolic links will not be followed.
117   *
118   * <pre><code>
119   *   directory.copyContentsFrom(Path.of("code", "examples"));
120   * </code></pre>
121   *
122   * @param rootDir the directory to copy the contents from.
123   * @return the root managed directory for further configuration.
124   */
125  ManagedDirectory copyContentsFrom(Path rootDir);
126
127  /**
128   * Create an empty directory.
129   *
130   * <pre><code>
131   *   directory.thatIsEmpty();
132   * </code></pre>
133   *
134   * @return the root managed directory for further configuration.
135   */
136  ManagedDirectory thatIsEmpty();
137}