Интерфейс JavaCompiler

public interface JavaCompiler
extends Tool, OptionChecker

Интерфейс для вызова компиляторов языка программирования Java™ из программ.

Компилятор может генерировать диагностические сообщения во время компиляции (например, сообщения об ошибках). Если предоставлен слушатель диагностики, диагностические сообщения будут переданы слушателю. Если слушатель не предоставлен, диагностические сообщения будут отформатированы в неопределённом формате и выведены в стандартный вывод, который является 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) {
           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;
           }
       }

Методы

getTask

JavaCompiler.CompilationTask getTask(Writer out,
                                     JavaFileManager fileManager,
                                     DiagnosticListener<? super JavaFileObject> diagnosticListener,
                                     Iterable<String> options,
                                     Iterable<String> classes,
                                     Iterable<? extends JavaFileObject> compilationUnits)

Параметры:

out - объект Writer для дополнительного вывода компилятора; используйте System.err, если null

fileManager - менеджер файлов; если null используйте стандартный менеджер файлов компилятора

diagnosticListener - слушатель диагностики; если null используйте стандартный метод компилятора для отчётности о диагностике

options - параметры компилятора, null означает отсутствие параметров

classes - имена классов, подлежащих обработке обработкой аннотаций, null означает отсутствие имён классов

compilationUnits - единицы компиляции для компиляции, null означает отсутствие единиц компиляции

Возвращает:

объект, представляющий компиляцию

ИСКЛЮЧЕНИЯ:

RuntimeException - если произошла невосстановимая ошибка в предоставленном пользователем компоненте. Причина будет ошибкой в пользовательском коде.

IllegalArgumentException - если какие-либо из параметров неверны, или если любая из предоставленных единиц компиляции не относится к типу источник

getStandardFileManager

StandardJavaFileManager getStandardFileManager(DiagnosticListener<? super JavaFileObject> diagnosticListener,
                                               Locale locale,
                                               Charset charset)

Параметры:

diagnosticListener - слушатель диагностики для некритических диагностических сообщений; если null используйте стандартный метод компилятора для отчётности о диагностике

locale - область для применения при форматировании диагностических сообщений; null означает стандартную область.

charset - кодовая страница, используемая для декодирования байтов; если null используйте платформенную кодовую страницу по умолчанию

Возвращает:

стандартный менеджер файлов