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;
022
023/**
024 * Chainable builder for creating directories.
025 *
026 * @author Ashley Scopes
027 * @since 0.0.1
028 */
029@SuppressWarnings("unused")
030public interface DirectoryBuilder {
031
032  /**
033   * Copy the contents of the directory at the given path recursively into this directory.
034   *
035   * <p>Symbolic links will not be followed.
036   *
037   * <p>This uses the default file system. If you want to use a different {@link FileSystem}
038   * as your source, then use {@link #copyContentsFrom(Path)} instead.
039   *
040   * <p>Examples:
041   *
042   * <pre><code>
043   *   // Letting JCT infer the correct path separators to use (recommended).
044   *   directoryBuilder.copyContentsFrom(List.of("foo", "bar", "baz"));
045   *
046   *   // Using POSIX platform-specific separators (may cause issues if your tests run on Windows)
047   *   directoryBuilder.copyContentsFrom(List.of("foo/bar/baz"));
048   *
049   *   // Using Windows platform-specific separators (may cause issues if your tests run on POSIX)
050   *   directoryBuilder.copyContentsFrom(List.of("foo\\bar\\baz"));
051   * </code></pre>
052   *
053   * @param fragments parts of the path.
054   * @return the root managed directory for further configuration.
055   * @throws IllegalArgumentException if no path fragments are provided.
056   * @throws NullPointerException     if any null path fragments are provided.
057   * @see #copyContentsFrom(Path)
058   * @see #copyContentsFrom(String...)
059   * @since 4.0.0
060   */
061  ManagedDirectory copyContentsFrom(List<String> fragments);
062
063  /**
064   * Copy the contents of the directory at the given path recursively into this directory.
065   *
066   * <p>Symbolic links will not be followed.
067   *
068   * <p>This uses the default file system. If you want to use a different {@link FileSystem}
069   * as your source, then use {@link #copyContentsFrom(Path)} instead.
070   *
071   * <p>Examples:
072   *
073   * <pre><code>
074   *   // Letting JCT infer the correct path separators to use (recommended).
075   *   directoryBuilder.copyContentsFrom("foo", "bar", "baz");
076   *
077   *   // Using POSIX platform-specific separators (may cause issues if your tests run on Windows)
078   *   directoryBuilder.copyContentsFrom("foo/bar/baz");
079   *
080   *   // Using Windows platform-specific separators (may cause issues if your tests run on POSIX)
081   *   directoryBuilder.copyContentsFrom("foo\\bar\\baz");
082   * </code></pre>
083   *
084   * @param fragments parts of the path.
085   * @return the root managed directory for further configuration.
086   * @throws IllegalArgumentException if no path fragments are provided.
087   * @throws NullPointerException     if any null path fragments are provided.
088   * @see #copyContentsFrom(Path)
089   * @see #copyContentsFrom(List)
090   */
091  default ManagedDirectory copyContentsFrom(String... fragments) {
092    return copyContentsFrom(List.of(fragments));
093  }
094
095  /**
096   * Copy the contents of the directory at the given path recursively into this directory.
097   *
098   * <p>Symbolic links will not be followed.
099   *
100   * <pre><code>
101   *  directory.copyContentsFrom(new File("code/examples"));
102   * </code></pre>
103   *
104   * @param dir the directory to copy the contents from.
105   * @return the root managed directory for further configuration.
106   */
107  ManagedDirectory copyContentsFrom(File dir);
108
109  /**
110   * Copy the contents of the directory at the given path recursively into this directory.
111   *
112   * <p>Symbolic links will not be followed.
113   *
114   * <pre><code>
115   *   directory.copyContentsFrom(Path.of("code", "examples"));
116   * </code></pre>
117   *
118   * @param rootDir the directory to copy the contents from.
119   * @return the root managed directory for further configuration.
120   */
121  ManagedDirectory copyContentsFrom(Path rootDir);
122
123  /**
124   * Create an empty directory.
125   *
126   * <pre><code>
127   *   directory.thatIsEmpty();
128   * </code></pre>
129   *
130   * @return the root managed directory for further configuration.
131   */
132  ManagedDirectory thatIsEmpty();
133}