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