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.filemanagers;
017
018import io.github.ascopes.jct.containers.ModuleContainerGroup;
019import io.github.ascopes.jct.containers.OutputContainerGroup;
020import io.github.ascopes.jct.containers.PackageContainerGroup;
021import io.github.ascopes.jct.workspaces.PathRoot;
022import io.github.ascopes.jct.workspaces.Workspace;
023import java.io.IOException;
024import java.util.Collection;
025import java.util.Set;
026import javax.tools.JavaFileManager;
027import javax.tools.JavaFileObject;
028import javax.tools.JavaFileObject.Kind;
029import javax.tools.StandardLocation;
030import org.apiguardian.api.API;
031import org.apiguardian.api.API.Status;
032import org.jspecify.annotations.Nullable;
033
034/**
035 * Extension around a {@link JavaFileManager} that allows adding of {@link PathRoot} objects to the
036 * manager.
037 *
038 * <p>This component is responsible for bridging the gap between a {@link Workspace} and
039 * a {@link javax.tools.JavaCompiler} when performing a compilation, and thus includes a number of
040 * required operations that the compiler will query the file system with. In addition, this
041 * interface also defines a number of additional functionalities that are useful for querying and
042 * verifying the outcome of compilations within tests.
043 *
044 * @author Ashley Scopes
045 * @since 0.0.1
046 */
047@API(since = "0.0.1", status = Status.STABLE)
048public interface JctFileManager extends JavaFileManager {
049
050  /**
051   * Add a package-oriented path to a given location.
052   *
053   * <p>To add a module, first obtain the module location using
054   * {@link #getLocationForModule(Location, String)}, and pass that result to this call.
055   *
056   * @param location the location to use.
057   * @param path     the path to add.
058   * @see #getLocationForModule(Location, String)
059   */
060  void addPath(Location location, PathRoot path);
061
062  /**
063   * Add a collection of package-oriented paths to a given location.
064   *
065   * <p>To add a module, first obtain the module location using
066   * {@link #getLocationForModule(Location, String)}, and pass that result to this call.
067   *
068   * @param location the location to use.
069   * @param paths    the paths to add.
070   * @see #getLocationForModule(Location, String)
071   */
072  void addPaths(Location location, Collection<? extends PathRoot> paths);
073
074  /**
075   * Copy all containers from the first location to the second location.
076   *
077   * @param from the first location.
078   * @param to   the second location.
079   */
080  void copyContainers(Location from, Location to);
081
082  /**
083   * Register an empty container for the given location to indicate to the compiler that the feature
084   * exists, but has no configured paths.
085   *
086   * <p>This is needed to coerce the behaviour for annotation processing in some cases.
087   *
088   * <p>If the location already exists, then do not do anything.
089   *
090   * <p>If the location is an output location, then this operation does not make any sense, since
091   * an empty location cannot have files output to it. In this case, you will likely get an
092   * exception.
093   *
094   * <p>Likewise, this operation does not make sense for module locations within a module-oriented
095   * location group, so this operation will fail with an error for those inputs as well.
096   *
097   * @param location the location to apply an empty container for.
098   * @throws IllegalArgumentException if the location is an output location or a module location.
099   */
100  void createEmptyLocation(Location location);
101
102  /**
103   * Get the associated effective release.
104   *
105   * @return the effective release.
106   * @since 0.0.1
107   */
108  String getEffectiveRelease();
109
110  /**
111   * Get the container group for the given package-oriented location.
112   *
113   * @param location the package oriented location.
114   * @return the container group, or null if one does not exist.
115   */
116  PackageContainerGroup getPackageContainerGroup(Location location);
117
118  /**
119   * Get a collection of all package container impl in this file manager.
120   *
121   * @return the package container impl.
122   */
123  Collection<PackageContainerGroup> getPackageContainerGroups();
124
125  /**
126   * Get the container group for the given module-oriented location.
127   *
128   * @param location the module oriented location.
129   * @return the container group, or null if one does not exist.
130   */
131  ModuleContainerGroup getModuleContainerGroup(Location location);
132
133  /**
134   * Get a collection of all module container impl in this file manager.
135   *
136   * @return the module container impl.
137   */
138  Collection<ModuleContainerGroup> getModuleContainerGroups();
139
140  /**
141   * Get the container group for the given output-oriented location.
142   *
143   * @param location the output oriented location.
144   * @return the container group, or null if one does not exist.
145   */
146  OutputContainerGroup getOutputContainerGroup(Location location);
147
148  /**
149   * Get a collection of all output container impl in this file manager.
150   *
151   * @return the output container impl.
152   */
153  Collection<OutputContainerGroup> getOutputContainerGroups();
154
155  /**
156   * List all file objects in the given location matching the given criteria.
157   *
158   * @param location    the location to search in.
159   * @param packageName the package name to search in, or {@code ""} to search in the root
160   *                    location.
161   * @param kinds       the kinds of file to return, or {@link Set#of} {@code (} {@link Kind#OTHER}
162   *                    {@code )} to find all files.
163   * @param recurse     {@code true} to recurse into subpackages, {@code false} to only check the
164   *                    current package.
165   * @return a collection of unique file objects that were found.
166   * @throws IOException if an IO error occurs reading the file system.
167   */
168  @Override
169  Set<JavaFileObject> list(
170      Location location,
171      String packageName,
172      Set<Kind> kinds,
173      boolean recurse
174  ) throws IOException;
175
176  ///
177  /// Default helper overrides
178  ///
179
180  /**
181   * Get the location holding the {@link StandardLocation#CLASS_OUTPUT class outputs}.
182   *
183   * @return the location, or {@code null} if the location is not present in the file manager.
184   * @since 0.1.0
185   */
186  @Nullable
187  default OutputContainerGroup getClassOutputGroup() {
188    return getOutputContainerGroup(StandardLocation.CLASS_OUTPUT);
189  }
190
191  /**
192   * Get the location holding the {@link StandardLocation#SOURCE_OUTPUT source outputs}.
193   *
194   * @return the location, or {@code null} if the location is not present in the file manager.
195   * @since 0.1.0
196   */
197  @Nullable
198  default OutputContainerGroup getSourceOutputGroup() {
199    return getOutputContainerGroup(StandardLocation.SOURCE_OUTPUT);
200  }
201
202  /**
203   * Get the location holding the {@link StandardLocation#CLASS_PATH class path}.
204   *
205   * @return the location, or {@code null} if the location is not present in the file manager.
206   * @since 0.1.0
207   */
208  @Nullable
209  default PackageContainerGroup getClassPathGroup() {
210    return getPackageContainerGroup(StandardLocation.CLASS_PATH);
211  }
212
213  /**
214   * Get the location holding the {@link StandardLocation#SOURCE_PATH source path}.
215   *
216   * @return the location, or {@code null} if the location is not present in the file manager.
217   * @since 0.1.0
218   */
219  @Nullable
220  default PackageContainerGroup getSourcePathGroup() {
221    return getPackageContainerGroup(StandardLocation.SOURCE_PATH);
222  }
223
224  /**
225   * Get the location holding the
226   * {@link StandardLocation#ANNOTATION_PROCESSOR_PATH annotation processor path}.
227   *
228   * @return the location, or {@code null} if the location is not present in the file manager.
229   * @since 0.1.0
230   */
231  @Nullable
232  default PackageContainerGroup getAnnotationProcessorPathGroup() {
233    return getPackageContainerGroup(StandardLocation.ANNOTATION_PROCESSOR_PATH);
234  }
235
236  /**
237   * Get the location holding the
238   * {@link StandardLocation#ANNOTATION_PROCESSOR_MODULE_PATH annotation processor module path}.
239   *
240   * @return the location, or {@code null} if the location is not present in the file manager.
241   * @since 0.1.0
242   */
243  @Nullable
244  default ModuleContainerGroup getAnnotationProcessorModulePathGroup() {
245    return getModuleContainerGroup(StandardLocation.ANNOTATION_PROCESSOR_MODULE_PATH);
246  }
247
248  /**
249   * Get the location holding the {@link StandardLocation#MODULE_SOURCE_PATH module source path}.
250   *
251   * @return the location, or {@code null} if the location is not present in the file manager.
252   * @since 0.1.0
253   */
254  @Nullable
255  default ModuleContainerGroup getModuleSourcePathGroup() {
256    return getModuleContainerGroup(StandardLocation.MODULE_SOURCE_PATH);
257  }
258
259  /**
260   * Get the location holding the {@link StandardLocation#MODULE_PATH module path}.
261   *
262   * @return the location, or {@code null} if the location is not present in the file manager.
263   * @since 0.1.0
264   */
265  @Nullable
266  default ModuleContainerGroup getModulePathGroup() {
267    return getModuleContainerGroup(StandardLocation.MODULE_PATH);
268  }
269}