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 org.apiguardian.api.API;
022import org.apiguardian.api.API.Status;
023
024/**
025 * Chainable builder for creating directories.
026 *
027 * @author Ashley Scopes
028 * @since 0.0.1
029 */
030@API(since = "0.0.1", status = Status.STABLE)
031public interface DirectoryBuilder {
032
033  /**
034   * Copy the contents of the directory at the given path recursively into this directory.
035   *
036   * <p>Symbolic links will not be followed.
037   *
038   * <p>This uses the default file system. If you want to use a different {@link FileSystem}
039   * as your source, then use {@link #copyContentsFrom(Path)} instead.
040   *
041   * <p>Examples:
042   *
043   * <pre><code>
044   *   // Letting JCT infer the correct path separators to use (recommended).
045   *   directoryBuilder.copyContentsFrom("foo", "bar", "baz");
046   *
047   *   // Using POSIX platform-specific separators (may cause issues if your tests run on Windows)
048   *   directoryBuilder.copyContentsFrom("foo/bar/baz");
049   *
050   *   // Using Windows platform-specific separators (may cause issues if your tests run on POSIX)
051   *   directoryBuilder.copyContentsFrom("foo\\bar\\baz");
052   * </code></pre>
053   *
054   * @param first the first part of the path to the directory to copy from.
055   * @param rest  any additional parts of the path.
056   * @return the root managed directory for further configuration.
057   * @see #copyContentsFrom(Path)
058   */
059  ManagedDirectory copyContentsFrom(String first, String... rest);
060
061  /**
062   * Copy the contents of the directory at the given path recursively into this directory.
063   *
064   * <p>Symbolic links will not be followed.
065   *
066   * <pre><code>
067   *  directory.copyContentsFrom(new File("code/examples"));
068   * </code></pre>
069   *
070   * @param dir the directory to copy the contents from.
071   * @return the root managed directory for further configuration.
072   */
073  ManagedDirectory copyContentsFrom(File dir);
074
075  /**
076   * Copy the contents of the directory at the given path recursively into this directory.
077   *
078   * <p>Symbolic links will not be followed.
079   *
080   * <pre><code>
081   *   directory.copyContentsFrom(Path.of("code", "examples"));
082   * </code></pre>
083   *
084   * @param rootDir the directory to copy the contents from.
085   * @return the root managed directory for further configuration.
086   */
087  ManagedDirectory copyContentsFrom(Path rootDir);
088
089  /**
090   * Create an empty directory.
091   *
092   * <pre><code>
093   *   directory.thatIsEmpty();
094   * </code></pre>
095   *
096   * @return the root managed directory for further configuration.
097   */
098  ManagedDirectory thatIsEmpty();
099}