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.Closeable;
019import java.io.IOException;
020import org.apiguardian.api.API;
021import org.apiguardian.api.API.Status;
022
023/**
024 * Base interface for a managed directory, including the interfaces for creating fluent-style
025 * builders.
026 *
027 * @author Ashley Scopes
028 * @since 0.0.1
029 */
030@API(since = "0.0.1", status = Status.STABLE)
031public interface ManagedDirectory extends DirectoryBuilder, PathRoot {
032
033  /**
034   * Method that returns the object it is called upon to enable creating fluent-language builders.
035   *
036   * @return this object.
037   * @see #and
038   * @see #then
039   */
040  default ManagedDirectory also() {
041    return this;
042  }
043
044  /**
045   * Method that returns the object it is called upon to enable creating fluent-language builders.
046   *
047   * @return this object.
048   * @see #also
049   * @see #then
050   */
051  default ManagedDirectory and() {
052    return this;
053  }
054
055  /**
056   * Close the resource.
057   *
058   * <p>This specifically is not provided by implementing {@link Closeable} as to prevent IDEs
059   * giving false linting errors about not closing resources.
060   *
061   * <p>Users should not need to call this directly if they are using instances produced from a
062   * {@link Workspace} implementation.
063   *
064   * @throws IOException if an IO exception occurs.
065   */
066  void close() throws IOException;
067
068  /**
069   * Create a directory builder for the given path in this RAM file system.
070   *
071   * <p>Examples:
072   *
073   * <pre><code>
074   *   // Using platform-specific separators.
075   *   dir.createDirectory("foo/bar/baz")...;
076   *
077   *   // Letting JCT infer the correct path separators to use (recommended).
078   *   dir.createDirectory("foo", "bar", "baz")...;
079   * </code></pre>
080   *
081   * @param first the first part of the path.
082   * @param rest  any additional parts of the path.
083   * @return the directory builder.
084   */
085  DirectoryBuilder createDirectory(String first, String... rest);
086
087  /**
088   * Create a file builder for the given path in this RAM file system.
089   *
090   * <pre><code>
091   *   // Using platform-specific separators.
092   *   dir.createFile("foo/bar/baz.txt")...;
093   *
094   *   // Letting JCT infer the correct path separators to use (recommended).
095   *   dir.createFile("foo", "bar", "baz.txt")...;
096   * </code></pre>
097   *
098   * @param fragment  the first part of the path.
099   * @param fragments any additional parts of the path.
100   * @return the file builder.
101   */
102  FileBuilder createFile(String fragment, String... fragments);
103
104  /**
105   * Get the identifying name of the temporary file system.
106   *
107   * @return the identifier string.
108   */
109  String getName();
110
111  /**
112   * Method that returns the object it is called upon to enable creating fluent-language builders.
113   *
114   * @return this object.
115   * @see #and
116   * @see #also
117   */
118  default ManagedDirectory then() {
119    return this;
120  }
121
122}