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