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.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  @Nullable
117  PackageContainerGroup getPackageContainerGroup(Location location);
118
119  /**
120   * Get a collection of all package container groups in this file manager.
121   *
122   * @return the package container groups.
123   */
124  Collection<PackageContainerGroup> getPackageContainerGroups();
125
126  /**
127   * Get the container group for the given module-oriented location.
128   *
129   * @param location the module oriented location.
130   * @return the container group, or null if one does not exist.
131   */
132  @Nullable
133  ModuleContainerGroup getModuleContainerGroup(Location location);
134
135  /**
136   * Get a collection of all module container groups in this file manager.
137   *
138   * @return the module container groups.
139   */
140  Collection<ModuleContainerGroup> getModuleContainerGroups();
141
142  /**
143   * Get the container group for the given output-oriented location.
144   *
145   * @param location the output oriented location.
146   * @return the container group, or null if one does not exist.
147   */
148  @Nullable
149  OutputContainerGroup getOutputContainerGroup(Location location);
150
151  /**
152   * Get a collection of all output container groups in this file manager.
153   *
154   * @return the output container groups.
155   */
156  Collection<OutputContainerGroup> getOutputContainerGroups();
157
158  /**
159   * List all file objects in the given location matching the given criteria.
160   *
161   * @param location    the location to search in.
162   * @param packageName the package name to search in, or {@code ""} to search in the root
163   *                    location.
164   * @param kinds       the kinds of file to return, or {@link Set#of} {@code (} {@link Kind#OTHER}
165   *                    {@code )} to find all files.
166   * @param recurse     {@code true} to recurse into subpackages, {@code false} to only check the
167   *                    current package.
168   * @return a collection of unique file objects that were found.
169   * @throws IOException if an IO error occurs reading the file system.
170   */
171  @Override
172  Set<JavaFileObject> list(
173      Location location,
174      String packageName,
175      Set<Kind> kinds,
176      boolean recurse
177  ) throws IOException;
178
179  ///
180  /// Default helper overrides
181  ///
182
183  /**
184   * Get the location holding the {@link StandardLocation#CLASS_OUTPUT class outputs}.
185   *
186   * @return the location, or {@code null} if the location is not present in the file manager.
187   * @since 0.1.0
188   */
189  @Nullable
190  default OutputContainerGroup getClassOutputGroup() {
191    return getOutputContainerGroup(StandardLocation.CLASS_OUTPUT);
192  }
193
194  /**
195   * Get the location holding the {@link StandardLocation#SOURCE_OUTPUT source outputs}.
196   *
197   * @return the location, or {@code null} if the location is not present in the file manager.
198   * @since 0.1.0
199   */
200  @Nullable
201  default OutputContainerGroup getSourceOutputGroup() {
202    return getOutputContainerGroup(StandardLocation.SOURCE_OUTPUT);
203  }
204
205  /**
206   * Get the location holding the {@link StandardLocation#CLASS_PATH class path}.
207   *
208   * @return the location, or {@code null} if the location is not present in the file manager.
209   * @since 0.1.0
210   */
211  @Nullable
212  default PackageContainerGroup getClassPathGroup() {
213    return getPackageContainerGroup(StandardLocation.CLASS_PATH);
214  }
215
216  /**
217   * Get the location holding the {@link StandardLocation#SOURCE_PATH source path}.
218   *
219   * @return the location, or {@code null} if the location is not present in the file manager.
220   * @since 0.1.0
221   */
222  @Nullable
223  default PackageContainerGroup getSourcePathGroup() {
224    return getPackageContainerGroup(StandardLocation.SOURCE_PATH);
225  }
226
227  /**
228   * Get the location holding the
229   * {@link StandardLocation#ANNOTATION_PROCESSOR_PATH annotation processor path}.
230   *
231   * @return the location, or {@code null} if the location is not present in the file manager.
232   * @since 0.1.0
233   */
234  @Nullable
235  default PackageContainerGroup getAnnotationProcessorPathGroup() {
236    return getPackageContainerGroup(StandardLocation.ANNOTATION_PROCESSOR_PATH);
237  }
238
239  /**
240   * Get the location holding the
241   * {@link StandardLocation#ANNOTATION_PROCESSOR_MODULE_PATH annotation processor module path}.
242   *
243   * @return the location, or {@code null} if the location is not present in the file manager.
244   * @since 0.1.0
245   */
246  @Nullable
247  default ModuleContainerGroup getAnnotationProcessorModulePathGroup() {
248    return getModuleContainerGroup(StandardLocation.ANNOTATION_PROCESSOR_MODULE_PATH);
249  }
250
251  /**
252   * Get the location holding the {@link StandardLocation#MODULE_SOURCE_PATH module source path}.
253   *
254   * @return the location, or {@code null} if the location is not present in the file manager.
255   * @since 0.1.0
256   */
257  @Nullable
258  default ModuleContainerGroup getModuleSourcePathGroup() {
259    return getModuleContainerGroup(StandardLocation.MODULE_SOURCE_PATH);
260  }
261
262  /**
263   * Get the location holding the {@link StandardLocation#MODULE_PATH module path}.
264   *
265   * @return the location, or {@code null} if the location is not present in the file manager.
266   * @since 0.1.0
267   */
268  @Nullable
269  default ModuleContainerGroup getModulePathGroup() {
270    return getModuleContainerGroup(StandardLocation.MODULE_PATH);
271  }
272}