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