The compiler might generate diagnostics during compilation (for duke@1: * example, error messages). If a diagnostic listener is provided, duke@1: * the diagnostics will be supplied to the listener. If no listener duke@1: * is provided, the diagnostics will be formatted in an unspecified duke@1: * format and written to the default output, which is {@code duke@1: * System.err} unless otherwise specified. Even if a diagnostic duke@1: * listener is supplied, some diagnostics might not fit in a {@code duke@1: * Diagnostic} and will be written to the default output. duke@1: * duke@1: *
A compiler tool has an associated standard file manager, which duke@1: * is the file manager that is native to the tool (or built-in). The duke@1: * standard file manager can be obtained by calling {@linkplain duke@1: * #getStandardFileManager getStandardFileManager}. duke@1: * duke@1: *
A compiler tool must function with any file manager as long as duke@1: * any additional requirements as detailed in the methods below are duke@1: * met. If no file manager is provided, the compiler tool will use a duke@1: * standard file manager such as the one returned by {@linkplain duke@1: * #getStandardFileManager getStandardFileManager}. duke@1: * jjh@972: *
An instance implementing this interface must conform to jjh@972: * The Java™ Language Specification jjh@972: * and generate class files conforming to jjh@972: * The Java™ Virtual Machine Specification. jjh@972: * The versions of these duke@1: * specifications are defined in the {@linkplain Tool} interface. duke@1: * duke@1: * Additionally, an instance of this interface supporting {@link duke@1: * javax.lang.model.SourceVersion#RELEASE_6 SourceVersion.RELEASE_6} duke@1: * or higher must also support {@linkplain javax.annotation.processing duke@1: * annotation processing}. duke@1: * duke@1: *
The compiler relies on two services: {@linkplain duke@1: * DiagnosticListener diagnostic listener} and {@linkplain duke@1: * JavaFileManager file manager}. Although most classes and duke@1: * interfaces in this package defines an API for compilers (and duke@1: * tools in general) the interfaces {@linkplain DiagnosticListener}, duke@1: * {@linkplain JavaFileManager}, {@linkplain FileObject}, and duke@1: * {@linkplain JavaFileObject} are not intended to be used in duke@1: * applications. Instead these interfaces are intended to be duke@1: * implemented and used to provide customized services for a duke@1: * compiler and thus defines an SPI for compilers. duke@1: * duke@1: *
There are a number of classes and interfaces in this package duke@1: * which are designed to ease the implementation of the SPI to duke@1: * customize the behavior of a compiler: duke@1: * duke@1: *
The standard file manager serves two purposes: duke@1: * duke@1: *
Reusing a file manager can potentially reduce overhead of duke@1: * scanning the file system and reading jar files. Although there duke@1: * might be no reduction in overhead, a standard file manager must duke@1: * work with multiple sequential compilations making the following duke@1: * example a recommended coding pattern: duke@1: * duke@1: *
vromero@1429: * File[] files1 = ... ; // input for first compilation task
vromero@1429: * File[] files2 = ... ; // input for second compilation task
duke@1: *
duke@1: * JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
duke@1: * StandardJavaFileManager fileManager = compiler.getStandardFileManager(null, null, null);
duke@1: *
duke@1: * {@code Iterable} compilationUnits1 =
duke@1: * fileManager.getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files1));
duke@1: * compiler.getTask(null, fileManager, null, null, null, compilationUnits1).call();
duke@1: *
duke@1: * {@code Iterable} compilationUnits2 =
duke@1: * fileManager.getJavaFileObjects(files2); // use alternative method
duke@1: * // reuse the same file manager to allow caching of jar files
duke@1: * compiler.getTask(null, fileManager, null, null, null, compilationUnits2).call();
duke@1: *
duke@1: * fileManager.close();
duke@1: *
duke@1: *
duke@1: * {@code Iterable} compilationUnits = ...;
duke@1: * JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
duke@1: * {@code DiagnosticCollector diagnostics = new DiagnosticCollector();}
duke@1: * StandardJavaFileManager fileManager = compiler.getStandardFileManager(diagnostics, null, null);
duke@1: * compiler.getTask(null, fileManager, diagnostics, null, null, compilationUnits).call();
duke@1: *
jjg@1326: * for ({@code Diagnostic} diagnostic : diagnostics.getDiagnostics())
jjg@824: * System.out.format("Error on line %d in %s%n",
jjg@824: * diagnostic.getLineNumber(),
duke@1: * diagnostic.getSource().toUri());
duke@1: *
duke@1: * fileManager.close();
duke@1: *
duke@1: * final {@linkplain java.util.logging.Logger Logger} logger = ...;
duke@1: * {@code Iterable} compilationUnits = ...;
duke@1: * JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
duke@1: * StandardJavaFileManager stdFileManager = compiler.getStandardFileManager(null, null, null);
duke@1: * JavaFileManager fileManager = new ForwardingJavaFileManager(stdFileManager) {
vromero@1429: * public void flush() throws IOException {
duke@1: * logger.entering(StandardJavaFileManager.class.getName(), "flush");
duke@1: * super.flush();
duke@1: * logger.exiting(StandardJavaFileManager.class.getName(), "flush");
duke@1: * }
duke@1: * };
duke@1: * compiler.getTask(null, fileManager, null, null, null, compilationUnits).call();
duke@1: *
duke@1: * /**
duke@1: * * A file object used to represent source coming from a string.
duke@1: * {@code *}/
duke@1: * public class JavaSourceFromString extends SimpleJavaFileObject {
duke@1: * /**
duke@1: * * The source code of this "file".
duke@1: * {@code *}/
duke@1: * final String code;
duke@1: *
duke@1: * /**
duke@1: * * Constructs a new JavaSourceFromString.
duke@1: * * {@code @}param name the name of the compilation unit represented by this file object
duke@1: * * {@code @}param code the source code for the compilation unit represented by this file object
duke@1: * {@code *}/
duke@1: * JavaSourceFromString(String name, String code) {
duke@1: * super({@linkplain java.net.URI#create URI.create}("string:///" + name.replace('.','/') + Kind.SOURCE.extension),
duke@1: * Kind.SOURCE);
duke@1: * this.code = code;
duke@1: * }
duke@1: *
duke@1: * {@code @}Override
duke@1: * public CharSequence getCharContent(boolean ignoreEncodingErrors) {
duke@1: * return code;
duke@1: * }
duke@1: * }
duke@1: * If a file manager is provided, it must be able to handle all duke@1: * locations defined in {@link StandardLocation}. duke@1: * darcy@375: *
Note that annotation processing can process both the
darcy@375: * compilation units of source code to be compiled, passed with
darcy@375: * the {@code compilationUnits} parameter, as well as class
darcy@375: * files, whose names are passed with the {@code classes}
darcy@375: * parameter.
darcy@375: *
duke@1: * @param out a Writer for additional output from the compiler;
duke@1: * use {@code System.err} if {@code null}
duke@1: * @param fileManager a file manager; if {@code null} use the
duke@1: * compiler's standard filemanager
duke@1: * @param diagnosticListener a diagnostic listener; if {@code
duke@1: * null} use the compiler's default method for reporting
duke@1: * diagnostics
duke@1: * @param options compiler options, {@code null} means no options
darcy@375: * @param classes names of classes to be processed by annotation
darcy@375: * processing, {@code null} means no class names
duke@1: * @param compilationUnits the compilation units to compile, {@code
duke@1: * null} means no compilation units
duke@1: * @return an object representing the compilation
duke@1: * @throws RuntimeException if an unrecoverable error
duke@1: * occurred in a user supplied component. The
duke@1: * {@linkplain Throwable#getCause() cause} will be the error in
duke@1: * user code.
duke@1: * @throws IllegalArgumentException if any of the given
duke@1: * compilation units are of other kind than
duke@1: * {@linkplain JavaFileObject.Kind#SOURCE source}
duke@1: */
duke@1: CompilationTask getTask(Writer out,
duke@1: JavaFileManager fileManager,
duke@1: DiagnosticListener diagnosticListener,
duke@1: Iterable The standard file manager will be automatically reopened if
duke@1: * it is accessed after calls to {@code flush} or {@code close}.
duke@1: * The standard file manager must be usable with other tools.
duke@1: *
duke@1: * @param diagnosticListener a diagnostic listener for non-fatal
duke@1: * diagnostics; if {@code null} use the compiler's default method
duke@1: * for reporting diagnostics
duke@1: * @param locale the locale to apply when formatting diagnostics;
duke@1: * {@code null} means the {@linkplain Locale#getDefault() default locale}.
duke@1: * @param charset the character set used for decoding bytes; if
duke@1: * {@code null} use the platform default
duke@1: * @return the standard file manager
duke@1: */
duke@1: StandardJavaFileManager getStandardFileManager(
duke@1: DiagnosticListener diagnosticListener,
duke@1: Locale locale,
duke@1: Charset charset);
duke@1:
duke@1: /**
duke@1: * Interface representing a future for a compilation task. The
duke@1: * compilation task has not yet started. To start the task, call
duke@1: * the {@linkplain #call call} method.
duke@1: *
duke@1: * Before calling the call method, additional aspects of the
duke@1: * task can be configured, for example, by calling the
duke@1: * {@linkplain #setProcessors setProcessors} method.
duke@1: */
duke@1: interface CompilationTask extends Callable