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

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

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