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