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.compilers;
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.diagnostics.TraceDiagnostic;
022import io.github.ascopes.jct.filemanagers.JctFileManager;
023import java.util.List;
024import java.util.Set;
025import javax.tools.JavaFileObject;
026import javax.tools.StandardLocation;
027import org.apiguardian.api.API;
028import org.apiguardian.api.API.Status;
029
030/**
031 * Interface representing the result of a compilation.
032 *
033 * @author Ashley Scopes
034 * @since 0.0.1
035 */
036@API(since = "0.0.1", status = Status.STABLE)
037public interface JctCompilation {
038
039  /**
040   * Get the command line arguments that were passed to the compiler.
041   *
042   * <p>Note that this throws an unsupported operation exception by default
043   * to prevent breaking existing functionality. In v1.0.0, this will become
044   * required behaviour.
045   *
046   * @return the command line arguments.
047   * @since 0.5.0
048   */
049  @API(since = "0.5.0", status = Status.STABLE)
050  default List<String> getArguments() {
051    throw new UnsupportedOperationException(
052        "This operation is not implemented, but will be mandatory in v1.0.0"
053    );
054  }
055
056  /**
057   * Determine if warnings were treated as errors.
058   *
059   * @return {@code true} if warnings were treated as errors, or {@code false} otherwise.
060   */
061  boolean isFailOnWarnings();
062
063  /**
064   * Determine if the compilation was successful or not.
065   *
066   * @return {@code true} if successful, or {@code false} if not successful.
067   */
068  boolean isSuccessful();
069
070  /**
071   * Determine if the compilation was a failure or not.
072   *
073   * @return {@code true} if not successful, or {@code false} if successful.
074   */
075  default boolean isFailure() {
076    return !isSuccessful();
077  }
078
079  /**
080   * Get the lines of output produced by the compiler, if any were captured.
081   *
082   * <p>This is separate to diagnostics.
083   *
084   * @return the lines of output.
085   */
086  List<String> getOutputLines();
087
088  /**
089   * Get the compilation units used in the compilation.
090   *
091   * @return the compilation units.
092   */
093  Set<JavaFileObject> getCompilationUnits();
094
095  /**
096   * Get the diagnostics that were reported by the compilation.
097   *
098   * @return the diagnostics
099   */
100  List<TraceDiagnostic<JavaFileObject>> getDiagnostics();
101
102  /**
103   * Get the file manager that was used to store and manage files.
104   *
105   * @return the file manager.
106   */
107  JctFileManager getFileManager();
108
109  /**
110   * Get the output container group for class outputs.
111   *
112   * @return the output container group, or {@code null} if it does not exist.
113   */
114  default OutputContainerGroup getClassOutputs() {
115    return getFileManager().getOutputContainerGroup(StandardLocation.CLASS_OUTPUT);
116  }
117
118  /**
119   * Get the output container group for source outputs.
120   *
121   * @return the output container group, or {@code null} if it does not exist.
122   */
123  default OutputContainerGroup getSourceOutputs() {
124    return getFileManager().getOutputContainerGroup(StandardLocation.SOURCE_OUTPUT);
125  }
126
127  /**
128   * Get the package container group for the class path.
129   *
130   * @return the package container group, or {@code null} if it does not exist.
131   */
132  default PackageContainerGroup getClassPath() {
133    return getFileManager().getPackageContainerGroup(StandardLocation.CLASS_PATH);
134  }
135
136  /**
137   * Get the package container group for the source path.
138   *
139   * @return the package container group, or {@code null} if it does not exist.
140   */
141  default PackageContainerGroup getSourcePath() {
142    return getFileManager().getPackageContainerGroup(StandardLocation.SOURCE_PATH);
143  }
144
145  /**
146   * Get the package container group for the annotation processor path.
147   *
148   * @return the package container group, or {@code null} if it does not exist.
149   */
150  default PackageContainerGroup getAnnotationProcessorPath() {
151    return getFileManager().getPackageContainerGroup(StandardLocation.ANNOTATION_PROCESSOR_PATH);
152  }
153
154  /**
155   * Get the module container group for the annotation processor module path.
156   *
157   * @return the module container group, or {@code null} if it does not exist.
158   */
159  default ModuleContainerGroup getAnnotationProcessorModulePath() {
160    return getFileManager()
161        .getModuleContainerGroup(StandardLocation.ANNOTATION_PROCESSOR_MODULE_PATH);
162  }
163
164  /**
165   * Get the package container group for the platform class path (a.k.a. the bootstrap class path).
166   *
167   * @return the package container group, or {@code null} if it does not exist.
168   */
169  default PackageContainerGroup getPlatformClassPath() {
170    return getFileManager().getPackageContainerGroup(StandardLocation.PLATFORM_CLASS_PATH);
171  }
172
173  /**
174   * Get the output container group for the native header file outputs.
175   *
176   * @return the output container group, or {@code null} if it does not exist.
177   */
178  default OutputContainerGroup getNativeHeaderOutputs() {
179    return getFileManager().getOutputContainerGroup(StandardLocation.NATIVE_HEADER_OUTPUT);
180  }
181
182  /**
183   * Get the module container group for the module source path.
184   *
185   * @return the module container group, or {@code null} if it does not exist.
186   */
187  default ModuleContainerGroup getModuleSourcePath() {
188    return getFileManager().getModuleContainerGroup(StandardLocation.MODULE_SOURCE_PATH);
189  }
190
191  /**
192   * Get the module container group for the upgrade module path.
193   *
194   * @return the module container group, or {@code null} if it does not exist.
195   */
196  default ModuleContainerGroup getUpgradeModulePath() {
197    return getFileManager().getModuleContainerGroup(StandardLocation.UPGRADE_MODULE_PATH);
198  }
199
200  /**
201   * Get the module container group for all system modules that are part of the JDK distribution.
202   *
203   * @return the module container group, or {@code null} if it does not exist.
204   */
205  default ModuleContainerGroup getSystemModules() {
206    return getFileManager().getModuleContainerGroup(StandardLocation.SYSTEM_MODULES);
207  }
208
209  /**
210   * Get the module container group for the module path.
211   *
212   * @return the module container group, or {@code null} if it does not exist.
213   */
214  default ModuleContainerGroup getModulePath() {
215    return getFileManager().getModuleContainerGroup(StandardLocation.MODULE_PATH);
216  }
217
218  /**
219   * Get the module container group for the patch module path.
220   *
221   * @return the module container group, or {@code null} if it does not exist.
222   */
223  default ModuleContainerGroup getPatchModulePath() {
224    return getFileManager().getModuleContainerGroup(StandardLocation.PATCH_MODULE_PATH);
225  }
226}