ICompiler.java
/*
* Janino - An embedded Java[TM] compiler
*
* Copyright (c) 2019 Arno Unkrig. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
* following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the
* following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
* following disclaimer in the documentation and/or other materials provided with the distribution.
* 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
* products derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
* INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package org.codehaus.commons.compiler;
import java.io.File;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.charset.Charset;
import java.util.Collections;
import org.codehaus.commons.compiler.util.resource.ListableResourceFinder;
import org.codehaus.commons.compiler.util.resource.Resource;
import org.codehaus.commons.compiler.util.resource.ResourceCreator;
import org.codehaus.commons.compiler.util.resource.ResourceFinder;
import org.codehaus.commons.nullanalysis.Nullable;
/**
* A simplified substitute for the <tt>javac</tt> tool.
*/
public
interface ICompiler {
/**
* Special value for {@link #setDestinationDirectory(File, boolean)}'s first parameter: Indicates that .class files
* are to be created in the directory of the .java file from which they are generated.
*/
@Nullable File NO_DESTINATION_DIRECTORY = null;
/**
* Special value for {@link #setClassFileFinder(ResourceFinder)}.
*
* @see #setClassFileFinder(ResourceFinder)
*/
ResourceFinder FIND_NEXT_TO_SOURCE_FILE = new ListableResourceFinder() {
@Override @Nullable public Resource findResource(String resourceName) { throw new UnsupportedOperationException("FIND_NEXT_TO_SOUJRCE_FILE"); }
@Override @Nullable public Iterable<Resource> list(String resourceNamePrefix, boolean recurse) { return Collections.emptyList(); }
@Override public String toString() { return "FIND_NEXT_TO_SOUJRCE_FILE"; }
};
/**
* Special value for {@link #setClassFileCreator(ResourceCreator)}: Indicates that .class resources are to be
* created in the directory of the .java resource from which they are generated.
*/
ResourceCreator CREATE_NEXT_TO_SOURCE_FILE = new ResourceCreator() {
@Override public boolean deleteResource(String resourceName) { throw new UnsupportedOperationException("CREATE_NEXT_TO_SOURCE_FILE"); }
@Override public OutputStream createResource(String resourceName) { throw new UnsupportedOperationException("CREATE_NEXT_TO_SOURCE_FILE"); }
@Override public String toString() { return "CREATE_NEXT_TO_SOURCE_FILE"; }
};
/**
* The equivalent of JAVA's "{@code -encoding}" command line option.
*
* @see #setSourceCharset(Charset)
*/
void setEncoding(Charset encoding);
/**
* Same as {@link #setEncoding(Charset)}, but with a more precise name.
*/
void setSourceCharset(Charset charset);
/**
* @deprecated Use {@link #setSourceCharset(Charset)} instead
*/
@Deprecated void setCharacterEncoding(@Nullable String characterEncoding);
/**
* Equivalent of {@code -g:lines}.
*/
void setDebugLines(boolean value);
/**
* Equivalent of {@code -g:vars}.
*/
void setDebugVars(boolean value);
/**
* Equivalent of {@code -g:source}.
*/
void setDebugSource(boolean value);
/**
* Specifies the version of source code accepted, in analogy with JAVAC's {@code -source} command line option.
* May be ignored by an implementation (e.g. the {@code janino} implementation always accepts the language features
* as described on the home page).
* Allowed values, and the default value, depend on the implementation.
* {@code -1} means to use a default version.
*/
void setSourceVersion(int version);
/**
* Generates class files that target a specified release of the virtual machine, in analogy with JAVAC's {@code
* -target} command line option.
* Allowed values depend on the implementation.
* The default value also depends on the implementation.
* The only invariant is that the generated class files are suitable for the currently executing JVM.
* {@code -1} means to use a default version.
*/
void setTargetVersion(int version);
/**
* Finds more {@code .java} resources that need to be compiled, i.e. implements JAVAC's {@code -sourcepath} option.
*/
void setSourceFinder(ResourceFinder sourceFinder);
/**
* Equivalent of {@code --source-path}.
* <p>
* Equivalent with {@code setSourceFinder(new PathResourceFinder(directoriesAndArchives))}.
* </p>
*/
void setSourcePath(File[] directoriesAndArchives);
/**
* Equivalent of <a href="https://docs.oracle.com/en/java/javase/11/tools/javac.html#
*GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-38BC1737-2F22-4288-8DC9-933C37D471AB">
*{@code --boot-class-path}</a>.
*/
void setBootClassPath(File[] directoriesAndArchives);
/**
* Equivalent of {@code -extdirs}.
*/
void setExtensionDirectories(File[] directories);
/**
* Equivalent of <a href="https://docs.oracle.com/en/java/javase/11/tools/javac.html#
*GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-45DC2932-19BD-435B-B14C-A230D0A4EC87">
*--class-path</a>.
*/
void setClassPath(File[] directoriesAndArchives);
/**
* Equivalent of <a href="https://docs.oracle.com/en/java/javase/11/tools/javac.html#
*GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-45DC2932-19BD-435B-B14C-A230D0A4EC87">
*-d</a> and {@code -rebuild}.
* <p>
* Overrides any previously configured {@link #setClassFileFinder(ResourceFinder) class file finder} and {@link
* #setClassFileCreator(ResourceCreator) class file creator}.
* </p>
*
* @param destinationDirectory {@link #NO_DESTINATION_DIRECTORY} means "create .class resources in
* the directory of the .java resource from which they are generated"
* @see #NO_DESTINATION_DIRECTORY
* @see #setClassFileFinder(ResourceFinder)
* @see #setClassFileCreator(ResourceCreator)
*/
void setDestinationDirectory(@Nullable File destinationDirectory, boolean rebuild);
/**
* Equivalent with {@code setClassFileFinder(rebuild ? ResourceFinder.EMPTY_RESOURCE_FINDER : classFileFinder)}.
*/
void setClassFileFinder(ResourceFinder classFileFinder, boolean rebuild);
/**
* This {@link ResourceFinder} is used to check whether a {@code .class} resource already exists and is younger
* than the {@code .java} resource from which it was generated.
* <p>
* If it is impossible to check whether an already-compiled class file exists, or if you want to enforce
* recompilation, pass {@link ResourceFinder#EMPTY_RESOURCE_FINDER} as the <var>classFileFinder</var>.
* </p>
* <p>
* The default is, as for JAVAC, {@link #FIND_NEXT_TO_SOURCE_FILE}.
* </p>
*
* @param classFileFinder Special value {@link #FIND_NEXT_TO_SOURCE_FILE} means ".class file is next to
* its source file, <em>not</em> in the destination directory"
* @see #FIND_NEXT_TO_SOURCE_FILE
*/
void setClassFileFinder(ResourceFinder classFileFinder);
/**
* This {@link ResourceCreator} is used to store generated {@code .class} files.
* <p>
* The default is, as for JAVAC, {@link #CREATE_NEXT_TO_SOURCE_FILE}.
* </p>
*
* @param classFileCreator Special value {@link #CREATE_NEXT_TO_SOURCE_FILE} means "create .class file
* next to its source file, <em>not</em> in the destination directory"
* @see #CREATE_NEXT_TO_SOURCE_FILE
*/
void setClassFileCreator(ResourceCreator classFileCreator);
/**
* Equivalent of {@code -verbose}.
*/
void setVerbose(boolean verbose);
/**
* Reads a set of Java compilation units (a.k.a. "source files") from the file system, compiles them into a set of
* "class files" and stores these in the file system. Additional source files are parsed and compiled on demand
* through the "source path" set of directories.
* <p>
* For example, if the source path comprises the directories "A/B" and "../C", then the source file for class
* "com.acme.Main" is searched in
* </p>
* <dl>
* <dd>A/B/com/acme/Main.java
* <dd>../C/com/acme/Main.java
* </dl>
* <p>
* Notice that it does make a difference whether you pass multiple source files to {@link #compile(File[])} or if
* you invoke {@link #compile(File[])} multiply: In the former case, the source files may contain arbitrary
* references among each other (even circular ones). In the latter case, only the source files on the source path
* may contain circular references, not the <var>sourceFiles</var>.
* </p>
* <p>
* This method must be called exactly once after object construction.
* </p>
* <p>
* Compile errors are reported as described at {@link #setCompileErrorHandler(ErrorHandler)}.
* </p>
*
* @param sourceFiles Contain the compilation units to compile
* @return {@code true} for backwards compatibility (return value can safely be ignored)
* @throws CompileException Fatal compilation error, or the {@link CompileException} thrown be the installed
* compile error handler
* @throws IOException Occurred when reading from the <var>sourceFiles</var>
*/
boolean compile(File[] sourceFiles) throws CompileException, IOException;
/**
* See {@link #compile(File[])}.
*
* @param sourceResources Contain the compilation units to compile
*/
void compile(Resource[] sourceResources) throws CompileException, IOException;
/**
* Installs an {@link ErrorHandler} which is invoked during compilation on each error. (By default, the compilation
* throws a {@link CompileException} on the first error and terminates.)
* <p>
* If the given {@link ErrorHandler} throws a {@link CompileException}, then the compilation terminates and
* the exception is propagated.
* </p>
* <p>
* If the given {@link ErrorHandler} does not throw a {@link CompileException} but completes normally, then the
* compilation may or may not continue, depending on the error. Iff the compilation of a compilation unit
* completes normally but errors were reported, then it will throw a {@link CompileException} indicating the
* number of errors.
* </p>
* <p>
* In other words: The {@link ErrorHandler} may throw a {@link CompileException} or not, but the compilation will
* definitely throw a {@link CompileException} if one or more compile errors have occurred.
* </p>
*
* @param errorHandler {@code null} to restore the default behavior (throwing a {@link CompileException})
*/
void setCompileErrorHandler(@Nullable ErrorHandler errorHandler);
/**
* By default, warnings are discarded, but an application my install a custom {@link WarningHandler}.
*
* @param warningHandler {@code null} to indicate that no warnings be issued
*/
void setWarningHandler(WarningHandler warningHandler);
}