javax.annotation.processing

Интерфейсная Программа для работы с файлами

public interface Filer

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

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

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

  @Generate
  public class UserSource {}
 

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

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

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

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

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

Процессоры могут указать на источник, или файл класса сгенерирован включением @Generated аннотация.

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

С тех пор:

1.6

Сводка метода

Методы

Модификатор и Тип	Метод и Описание
JavaFileObject	createClassFile(CharSequence name, Element... originatingElements) Создает новый файл класса, и возвращает объект позволить писать в это.
FileObject	createResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName, Element... originatingElements) Создает новый вспомогательный файл ресурсов для записи и возвращает объект файла для этого.
JavaFileObject	createSourceFile(CharSequence name, Element... originatingElements) Создает новый исходный файл и возвращает объект позволить писать в это.
FileObject	getResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName) Возвращает объект для того, чтобы считать существующий ресурс.

Деталь метода

createSourceFile

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

Создает новый исходный файл и возвращает объект позволить писать в это. Имя файла и путь (относительно корневого выходного расположения для исходных файлов) основаны на типе, который будет объявлен в том файле. Если больше чем один тип объявляется, имя основного высокоуровневого типа (общедоступный, например) должно использоваться. Исходный файл может также быть создан, чтобы содержать информацию о пакете, включая аннотации пакета. Чтобы создать исходный файл для именованного пакета, иметь name будьте именем пакета, сопровождаемым ".package-info"; чтобы создать исходный файл для неназванного пакета, использовать "package-info".

Отметьте что использовать определенный набор символов, чтобы закодировать содержание файла, OutputStreamWriter с выбранным набором символов может быть создан из OutputStream от возвращенного объекта. Если Writer от возвращенного объекта непосредственно используется для того, чтобы записать, его набор символов определяется реализацией. Инструмент обработки аннотации может иметь -encoding флаг или аналогичная опция для того, чтобы определить это; иначе, это обычно будет кодировка по умолчанию платформы.

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

Параметры:

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

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

Возвраты:

a JavaFileObject записать новый исходный файл

Броски:

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

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

createClassFile

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

Создает новый файл класса, и возвращает объект позволить писать в это. Имя файла и путь (относительно корневого выходного расположения для файлов класса) основаны на имени записанного типа. Файл класса может также быть создан, чтобы содержать информацию о пакете, включая аннотации пакета. Чтобы создать файл класса для именованного пакета, иметь name будьте именем пакета, сопровождаемым ".package-info"; создание файла класса для неназванного пакета не поддерживается.

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

Параметры:

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

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

Возвраты:

a JavaFileObject записать новый файл класса

Броски:

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

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

createResource

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

Создает новый вспомогательный файл ресурсов для записи и возвращает объект файла для этого. Файл может быть расположен наряду с недавно создаваемыми исходными файлами, недавно создаваемыми двоичными файлами, или другим поддерживаемым расположением. Расположения CLASS_OUTPUT и SOURCE_OUTPUT должен поддерживаться. Ресурс можно назвать относительно некоторого пакета (как источник и файлы класса), и оттуда относительным путем. В свободном смысле полный путь нового файла будет связью location, pkg, и relativeName.

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

Параметры:

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

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

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

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

Возвраты:

a 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 не относительно