Интерфейс 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;
    }
}