Интерфейс JavaCompiler

Компилятор может генерировать диагностические сообщения во время компиляции (например, сообщения об ошибках). Если указан слушатель диагностических сообщений, эти сообщения будут переданы слушателю. Если слушатель не указан, диагностические сообщения будут отформатированы в неопределенном формате и выведены в стандартный вывод, который является System.err, если не указано иное. Даже если указан слушатель диагностических сообщений, некоторые сообщения могут не поместиться в Diagnostic и будут выведены в стандартный вывод.

Компилятор имеет связанный стандартный менеджер файлов, который является менеджером файлов, встроенным в инструмент (или встроенным). Стандартный менеджер файлов можно получить, вызвав getStandardFileManager.

Инструмент компиляции должен работать с любым менеджером файлов, при соблюдении дополнительных требований, указанных в методах ниже. Если менеджер файлов не указан, инструмент компиляции будет использовать стандартный менеджер файлов, такой как тот, что возвращается getStandardFileManager.

Экземпляр, реализующий этот интерфейс, должен соответствовать Спецификации языка Java и генерировать файлы классов, соответствующие Спецификации виртуальной машины Java. Версии этих спецификаций определены в интерфейсе Tool. Кроме того, экземпляр этого интерфейса, поддерживающий SourceVersion.RELEASE_6 или более позднюю версию, также должен поддерживать обработку аннотаций.

Компилятор использует два сервиса: слушатель диагностических сообщений и менеджер файлов. Хотя большинство классов и интерфейсов в этом пакете определяют API для компиляторов (и инструментов в целом), интерфейсы DiagnosticListener, JavaFileManager, FileObject и JavaFileObject не предназначены для использования в приложениях. Вместо этого эти интерфейсы предназначены для реализации и использования для предоставления настраиваемых сервисов для компилятора, и, таким образом, определяют SPI для компиляторов.

В этом пакете есть ряд классов и интерфейсов, которые предназначены для упрощения реализации SPI, чтобы настроить поведение компилятора:

StandardJavaFileManager

Каждый компилятор, который реализует этот интерфейс, предоставляет стандартный менеджер файлов для работы с обычными файлами. Интерфейс StandardJavaFileManager определяет дополнительные методы для создания объектов файлов из обычных файлов.

Стандартный менеджер файлов выполняет две функции:

• основной строительный блок для настройки того, как компилятор читает и записывает файлы
• обмен между несколькими задачами компиляции

Использование менеджера файлов может потенциально уменьшить накладные расходы на сканирование файловой системы и чтение файлов JAR. Хотя уменьшение накладных расходов может отсутствовать, стандартный менеджер файлов должен работать с несколькими последовательными компиляциями, делая следующий пример рекомендуемым шаблоном программирования:

File[] files1 = ... ; // input for first compilation task
File[] files2 = ... ; // input for second compilation task

JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
StandardJavaFileManager fileManager = compiler.getStandardFileManager(null, null, null);

Iterable<? extends JavaFileObject> compilationUnits1 =
    fileManager.getJavaFileObjectsFromFiles(Arrays.asList(files1));
compiler.getTask(null, fileManager, null, null, null, compilationUnits1).call();

Iterable<? extends JavaFileObject> compilationUnits2 =
    fileManager.getJavaFileObjects(files2); // use alternative method
// reuse the same file manager to allow caching of jar files
compiler.getTask(null, fileManager, null, null, null, compilationUnits2).call();

fileManager.close();

DiagnosticCollector

Используется для сбора диагностических сообщений в списке, например:

Iterable<? extends JavaFileObject> compilationUnits = ...;
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<JavaFileObject>();
StandardJavaFileManager fileManager = compiler.getStandardFileManager(diagnostics, null, null);
compiler.getTask(null, fileManager, diagnostics, null, null, compilationUnits).call();

for (Diagnostic<? extends JavaFileObject> diagnostic : diagnostics.getDiagnostics()) {
    System.out.format("Error on line %d in %s%n",
                      diagnostic.getLineNumber(),
                      diagnostic.getSource().toUri());
}

fileManager.close();

ForwardingJavaFileManager, ForwardingFileObject и ForwardingJavaFileObject

Наследование не доступно для переопределения поведения стандартного менеджера файлов, так как он создаётся вызовом метода компилятора, а не вызовом конструктора. Вместо этого следует использовать делегирование. Эти классы упрощают делегирование большинства вызовов заданному менеджеру файлов или объекту файла, позволяя настроить поведение. Например, рассмотрим, как зарегистрировать все вызовы JavaFileManager.flush():

final  Logger logger = ...;
Iterable<? extends JavaFileObject> compilationUnits = ...;
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
StandardJavaFileManager stdFileManager = compiler.getStandardFileManager(null, null, null);
JavaFileManager fileManager = new ForwardingJavaFileManager(stdFileManager) {
    @Override
    public void flush() throws IOException {
        logger.entering(StandardJavaFileManager.class.getName(), "flush");
        super.flush();
        logger.exiting(StandardJavaFileManager.class.getName(), "flush");
    }
};
compiler.getTask(null, fileManager, null, null, null, compilationUnits).call();

SimpleJavaFileObject

Этот класс предоставляет базовую реализацию объекта файла, которая может использоваться как строительный блок для создания объектов файлов. Например, вот как определить объект файла, представляющий исходный код, хранящийся в строке:

/**
 * A file object used to represent source coming from a string.
 */
public class JavaSourceFromString extends SimpleJavaFileObject {
    /**
     * The source code of this "file".
     */
    final String code;

    /**
     * Constructs a new JavaSourceFromString.
     * @param name the name of the compilation unit represented by this file object
     * @param code the source code for the compilation unit represented by this file object
     */
    JavaSourceFromString(String name, String code) {
        super(URI.create("string:///" + name.replace('.','/') + Kind.SOURCE.extension),
              Kind.SOURCE);
        this.code = code;
    }

    @Override
    public CharSequence getCharContent(boolean ignoreEncodingErrors) {
        return code;
    }
}