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