Интерфейс Filer

public interface Filer

Этот интерфейс поддерживает создание новых файлов обработчиком аннотаций. Файлы, созданные таким образом, будут известны инструменту обработки аннотаций, реализующему этот интерфейс, что лучше позволит инструменту управлять ими. Сгенерированные файлы исходного кода и файлы классов будут рассмотрены для обработки инструментом в последующем раунде обработки после вызова метода close на объекте Writer или OutputStream, используемом для записи содержимого файла. Различаются три типа файлов: файлы исходного кода, файлы класса и вспомогательные файлы ресурсов.

Существует два поддерживаемых расположения (поддеревья в логической файловой системе), где размещаются вновь созданные файлы: одно для новых файлов исходного кода и одно для новых файлов класса. (Эти расположения могут быть заданы в командной строке инструмента, например, с помощью флагов, таких как -s и -d.) Фактические расположения для новых файлов исходного кода и новых файлов класса могут или не могут различаться при конкретном запуске инструмента. Файлы ресурсов могут быть созданы в любом из этих расположений. Методы чтения и записи ресурсов принимают аргумент относительного имени. Относительное имя — это непустая, непустая последовательность сегментов пути, разделенных '/'; '.' и '..' являются недопустимыми сегментами пути. Действительное относительное имя должно соответствовать правилу "path-rootless" RFC 3986, раздел 3.3.

Методы создания файлов принимают переменное количество аргументов, чтобы предоставить исходные элементы в качестве подсказок для инфраструктуры инструмента для лучшего управления зависимостями. Исходные элементы — это типы или пакеты (представляющие package-info файлы), которые заставили обработчик аннотаций попытаться создать новый файл. Например, если обработчик аннотаций пытается создать файл исходного кода, GeneratedFromUserSource, в ответ на обработку

@Generate
public class UserSource {}

элемента типа для UserSource должен быть передан в качестве части вызова метода создания, как в:

filer.createSourceFile("GeneratedFromUserSource",
                       eltUtils.getTypeElement("UserSource"));

Если нет исходных элементов, их передавать не нужно. Эта информация может использоваться в инкрементальной среде для определения необходимости повторного запуска обработчиков или удаления сгенерированных файлов. В неинкрементальных средах информация об исходных элементах может быть проигнорирована.

Во время каждого запуска инструмента обработки аннотаций файл с заданным именем пути может быть создан только один раз. Если этот файл уже существует до первой попытки его создания, старое содержимое будет удалено. Любая последующая попытка создать тот же файл во время запуска вызовет исключение FilerException, так же как и попытка создать одновременно файл класса и файл исходного кода для одного и того же имени типа или имени пакета. Первоначальные входные данные для инструмента считаются созданными в нулевом раунде; поэтому попытка создать файл исходного кода или файл класса, соответствующий одному из этих входных данных, приведет к исключению FilerException.

В общем случае, обработчики не должны преднамеренно пытаться перезаписывать существующие файлы, которые не были сгенерированы каким-либо обработчиком. Обработчик Filer может отклонить попытки открыть файл, соответствующий существующему типу, например, java.lang.Object. Аналогично, вызывающий инструмент обработки аннотаций не должен намеренно настраивать инструмент таким образом, чтобы обнаруженные обработчики пытались перезаписать существующие файлы, которые не были сгенерированы.

Обработчики могут указать, что файл исходного кода или файл класса сгенерирован, включив аннотацию @Generated.

Обратите внимание, что часть эффекта перезаписи файла можно достичь с помощью паттерна декоратора. Вместо непосредственного изменения класса, класс разрабатывается таким образом, что либо его суперкласс генерируется обработкой аннотаций, либо подклассы класса генерируются обработкой аннотаций. Если подклассы генерируются, родительский класс может быть разработан таким образом, чтобы использовать фабрики вместо публичных конструкторов, чтобы клиенты родительского класса получали только экземпляры подклассов.

Методы

createSourceFile

JavaFileObject createSourceFile(CharSequence name,
                                Element... originatingElements)
                         throws IOException

Параметры:

name - каноническое (полное квалифицированное) имя основного типа, объявленного в этом файле, или имя пакета, за которым следует ".package-info" для файла информации о пакете

originatingElements - элементы типа или пакета, причинно связанные с созданием этого файла, могут быть опущены или null

Возвращает:

объект JavaFileObject для записи нового файла исходного кода

Исключения:

FilerException - если имя пути уже было создано, тот же тип уже был создан или имя не является допустимым для типа

IOException - если файл не может быть создан

createClassFile

JavaFileObject createClassFile(CharSequence name,
                               Element... originatingElements)
                        throws IOException

Параметры:

name - бинарное имя записываемого типа или имя пакета, за которым следует ".package-info" для файла информации о пакете

originatingElements - элементы типа или пакета, причинно связанные с созданием этого файла, могут быть опущены или null

Возвращает:

объект JavaFileObject для записи нового файла класса

Исключения:

FilerException - если имя пути уже было создано, тот же тип уже был создан или имя не является допустимым для типа

IOException - если файл не может быть создан

createResource

FileObject createResource(JavaFileManager.Location location,
                          CharSequence pkg,
                          CharSequence relativeName,
                          Element... originatingElements)
                   throws IOException

Параметры:

location - расположение нового файла

pkg - пакет, относительно которого файл должен быть назван, или пустая строка, если нет

relativeName - конечные компоненты имени пути файла

originatingElements - элементы типа или пакета, причинно связанные с созданием этого файла, могут быть опущены или null

Возвращает:

объект FileObject для записи нового ресурса

Исключения:

IOException - если файл не может быть создан

FilerException - если имя пути уже было создано

IllegalArgumentException - для неподдерживаемого расположения

IllegalArgumentException - если relativeName не относительно

getResource

FileObject getResource(JavaFileManager.Location location,
                       CharSequence pkg,
                       CharSequence relativeName)
                throws IOException

Возвращает объект для чтения существующего ресурса. Расположения CLASS_OUTPUT и SOURCE_OUTPUT должны быть поддерживаемыми.

Параметры:

location - расположение файла

pkg - пакет, относительно которого файл должен быть найден, или пустая строка, если нет

relativeName - конечные компоненты имени пути файла

Возвращает:

объект для чтения файла

Исключения:

FilerException - если то же имя пути уже открыто для записи

IOException - если файл не может быть открыт

IllegalArgumentException - для неподдерживаемого расположения

IllegalArgumentException - если relativeName не относительно