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}