001/*
002 * Copyright (C) 2022 - 2023, 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.io.InputStream;
020import java.net.URL;
021import java.nio.charset.Charset;
022import java.nio.file.Path;
023import org.apiguardian.api.API;
024import org.apiguardian.api.API.Status;
025
026/**
027 * Chainable builder for creating individual files.
028 *
029 * @author Ashley Scopes
030 * @since 0.0.1
031 */
032@API(since = "0.0.1", status = Status.STABLE)
033public interface FileBuilder {
034
035  /**
036   * Create the file with the given contents.
037   *
038   * @param lines the lines to write using the default charset.
039   * @return the root managed directory for further configuration.
040   */
041  ManagedDirectory withContents(String... lines);
042
043  /**
044   * Create the file with the given contents.
045   *
046   * @param charset the character encoding to use.
047   * @param lines   the lines to write.
048   * @return the root managed directory for further configuration.
049   */
050  ManagedDirectory withContents(Charset charset, String... lines);
051
052  /**
053   * Create the file with the given byte contents.
054   *
055   * @param contents the bytes to write.
056   * @return the root managed directory for further configuration.
057   */
058  ManagedDirectory withContents(byte[] contents);
059
060  /**
061   * Copy a resource from the class loader on the current thread into the file system.
062   *
063   * @param resource the resource to copy.
064   * @return the root managed directory for further configuration.
065   */
066  ManagedDirectory copiedFromClassPath(String resource);
067
068  /**
069   * Copy a resource from the given class loader into the file system.
070   *
071   * @param classLoader the class loader to use.
072   * @param resource    the resource to copy.
073   * @return the root managed directory for further configuration.
074   */
075  ManagedDirectory copiedFromClassPath(ClassLoader classLoader, String resource);
076
077  /**
078   * Copy the contents from the given file into the file system.
079   *
080   * @param file the file to read.
081   * @return the root managed directory for further configuration.
082   */
083  ManagedDirectory copiedFromFile(File file);
084
085  /**
086   * Copy the contents from the given path into the file system.
087   *
088   * @param file the file to read.
089   * @return the root managed directory for further configuration.
090   */
091  ManagedDirectory copiedFromFile(Path file);
092
093  /**
094   * Copy the contents from the given URL into the file system.
095   *
096   * @param url the URL to read.
097   * @return the root managed directory for further configuration.
098   */
099  ManagedDirectory copiedFromUrl(URL url);
100
101  /**
102   * Create an empty file with nothing in it.
103   *
104   * @return the root managed directory for further configuration.
105   */
106  ManagedDirectory thatIsEmpty();
107
108  /**
109   * Copy the contents from the given input stream into the file system.
110   *
111   * <p>The input stream will be closed when reading completes.
112   *
113   * @param inputStream the input stream to read.
114   * @return the root managed directory for further configuration.
115   */
116  ManagedDirectory fromInputStream(InputStream inputStream);
117}