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.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   * <p>For example:
037   *
038   * <pre><code>
039   *   thisDirectory
040   *       .createFile("foo", "bar", "baz.txt").withContents(...)
041   *       .and().also()
042   *       .createFile("foo", "bar", "bork.txt").withContents(...);
043   * </code></pre>
044   *
045   * @return this object.
046   * @see #and
047   * @see #then
048   */
049  default ManagedDirectory also() {
050    return this;
051  }
052
053  /**
054   * Method that returns the object it is called upon to enable creating fluent-language builders.
055   *
056   * <p>For example:
057   *
058   * <pre><code>
059   *   thisDirectory
060   *       .createFile("foo", "bar", "baz.txt").withContents(...)
061   *       .and()
062   *       .createFile("foo", "bar", "bork.txt").withContents(...);
063   * </code></pre>
064   *
065   * @return this object.
066   * @see #also
067   * @see #then
068   */
069  default ManagedDirectory and() {
070    return this;
071  }
072
073  /**
074   * Close the resource.
075   *
076   * <p>This specifically is not provided by implementing {@link Closeable} as to prevent IDEs
077   * giving false linting errors about not closing resources.
078   *
079   * <p>Users should not need to call this directly if they are using instances produced from a
080   * {@link Workspace} implementation.
081   *
082   * @throws IOException if an IO exception occurs.
083   */
084  void close() throws IOException;
085
086  /**
087   * Create a directory builder for the given path in this RAM file system.
088   *
089   * <p>Examples:
090   *
091   * <pre><code>
092   *   // Using platform-specific separators.
093   *   dir.createDirectory("foo/bar/baz")...;
094   *
095   *   // Letting JCT infer the correct path separators to use (recommended).
096   *   dir.createDirectory("foo", "bar", "baz")...;
097   * </code></pre>
098   *
099   * @param first the first part of the path.
100   * @param rest  any additional parts of the path.
101   * @return the directory builder.
102   */
103  DirectoryBuilder createDirectory(String first, String... rest);
104
105  /**
106   * Create a file builder for the given path in this RAM file system.
107   *
108   * <pre><code>
109   *   // Using platform-specific separators.
110   *   dir.createFile("foo/bar/baz.txt")...;
111   *
112   *   // Letting JCT infer the correct path separators to use (recommended).
113   *   dir.createFile("foo", "bar", "baz.txt")...;
114   * </code></pre>
115   *
116   * @param fragment  the first part of the path.
117   * @param fragments any additional parts of the path.
118   * @return the file builder.
119   */
120  FileBuilder createFile(String fragment, String... fragments);
121
122  /**
123   * Get the identifying name of the temporary file system.
124   *
125   * @return the identifier string.
126   */
127  String getName();
128
129  /**
130   * Method that returns the object it is called upon to enable creating fluent-language builders.
131   *
132   * <p>For example:
133   *
134   * <pre><code>
135   *   thisDirectory
136   *       .createFile("foo", "bar", "baz.txt").withContents(...)
137   *       .and().then()
138   *       .createFile("foo", "bar", "bork.txt").withContents(...);
139   * </code></pre>
140   *
141   * @return this object.
142   * @see #and
143   * @see #also
144   */
145  default ManagedDirectory then() {
146    return this;
147  }
148
149}