Интерфейс Filer

public interface Filer

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

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

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

@Generate
public class UserSource {}

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

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

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

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

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

Процессоры могут указать, что исходный или классный файл сгенерирован, включив аннотацию javax.annotation.Generated, если среда настроена так, что этот тип доступен.

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

Методы

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

Методы

createSourceFile

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

Создаёт новый исходный файл и возвращает объект, позволяющий записывать в него. Можно создать исходный файл для типа или пакета. Имя и путь файла (относительно корневого расположения вывода исходных файлов) основаны на имени элемента, который должен быть объявлен в этом файле, а также на указанном модуле для этого элемента (если таковой имеется). Если в одном файле (то есть одном файле компиляции) объявляется более одного типа, имя файла должно соответствовать имени основного верхнего уровня типа (например, публичного).

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

Необязательное имя модуля добавляется в префикс к имени типа или имени пакета и отделяется символом "/". Например, чтобы создать исходный файл для типа a.B в модуле foo, используйте аргумент name "foo/a.B".

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

Создание исходного файла в безымянном пакете или для него в именованном модуле не поддерживается.

Примечание API:: Для использования определённой кодировки символов для кодирования содержимого файла, объект с выбранной кодировкой можно создать из объекта OutputStream возвращённого объекта. Если объект Writer возвращённого объекта используется напрямую для записи, его кодировка определяется реализацией. Инструмент обработки аннотаций может иметь флаг -encoding или аналогичный параметр для указания этого; в противном случае, как правило, будет использоваться кодировка по умолчанию платформы.
Чтобы избежать последующих ошибок, содержимое исходного файла должно быть совместимо с версией исходного кода, используемой для этого запуска.
Примечание реализации:: В эталонной реализации, если инструмент обработки аннотаций обрабатывает единственный модуль M, то M используется как модуль для файлов, созданных без явного префикса модуля. Если инструмент обрабатывает несколько модулей, и Elements.getPackageElement(package-of(name)) возвращает пакет, модуль, которому принадлежит возвращённый пакет, используется как целевой модуль. Для предоставления целевого модуля, если его нельзя определить по вышеуказанным правилам, может быть использован отдельный параметр.
Параметры:: name - каноническое (полное квалифицированное) имя основного типа, объявляемого в этом файле, или имя пакета, за которым следует ".package-info" для файла информации о пакете; originatingElements - элементы типа, пакета или модуля, причинно связанные с созданием этого файла, могут быть опушены или null
Возвращает:: объект JavaFileObject для записи нового исходного файла
Исключение:: FilerException - если тот же путь уже был создан, тот же тип уже был создан, имя не является допустимым для запрашиваемого элемента, если целевой модуль не может быть определён, если целевой модуль не доступен для записи, или модуль указан, когда среда не поддерживает модули.; IOException - если файл не может быть создан

createClassFile

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

Создаёт новый файл класса и возвращает объект, позволяющий записывать в него. Можно создать файл класса для типа или пакета. Имя и путь файла (относительно корневого расположения вывода файлов классов) основаны на имени объявляемого элемента и указанном модуле для него (если таковой имеется).

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

Необязательное имя модуля добавляется в префикс к имени типа или имени пакета и отделяется символом "/". Например, чтобы создать файл класса для типа a.B в модуле foo, используйте аргумент name "foo/a.B".

Создание файла класса в безымянном пакете или для него в именованном модуле не поддерживается.

Примечание API:: Чтобы избежать последующих ошибок, содержимое файла класса должно быть совместимо с версией исходного кода, используемой для этого запуска.
Примечание реализации:: В эталонной реализации, если инструмент обработки аннотаций обрабатывает единственный модуль M, то M используется как модуль для файлов, созданных без явного префикса модуля. Если инструмент обрабатывает несколько модулей, и Elements.getPackageElement(package-of(name)) возвращает пакет, модуль, которому принадлежит возвращённый пакет, используется как целевой модуль. Для предоставления целевого модуля, если его нельзя определить по вышеуказанным правилам, может быть использован отдельный параметр.
Параметры:: name - двоичное имя типа, который записывается, или имя пакета, за которым следует ".package-info" для файла информации о пакете; originatingElements - элементы типа, пакета или модуля, причинно связанные с созданием этого файла, могут быть опушены или null
Возвращает:: объект JavaFileObject для записи нового файла класса
Исключение:: FilerException - если тот же путь уже был создан, тот же тип уже был создан, имя не является допустимым для типа, если целевой модуль не может быть определён, если целевой модуль не доступен для записи, или модуль указан, когда среда не поддерживает модули.; IOException - если файл не может быть создан

createResource

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

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

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

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

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

Примечание реализации:: В эталонной реализации, если инструмент обработки аннотаций обрабатывает единственный модуль M, то M используется как модуль для файлов, созданных без явного префикса модуля. Если инструмент обрабатывает несколько модулей, и Elements.getPackageElement(package-of(name)) возвращает пакет, модуль, которому принадлежит возвращённый пакет, используется как целевой модуль. Для предоставления целевого модуля, если его нельзя определить по вышеуказанным правилам, может быть использован отдельный параметр.
Параметры:: location - расположение нового файла; moduleAndPkg - модуль и/или пакет, относительно которого должен быть назван файл, или пустая строка, если таковых нет; relativeName - конечные компоненты пути файла; originatingElements - элементы типа, пакета или модуля, причинно связанные с созданием этого файла, могут быть опушены или null
Возвращает:: объект FileObject для записи нового ресурса
Исключение:: IOException - если файл не может быть создан; FilerException - если тот же путь уже был создан, если целевой модуль не может быть определён, или если целевой модуль не доступен для записи, или если явный целевой модуль указан, а расположение его не поддерживает.; IllegalArgumentException - для неподдерживаемого расположения; IllegalArgumentException - если moduleAndPkg имеет неправильный формат; IllegalArgumentException - если relativeName не является относительным

getResource

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

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

Если moduleAndPkg содержит символ "/", префикс перед символом "/" — это имя модуля, а суффикс после символа "/" — имя пакета. Суффикс пакета может быть пустым; однако, если имя модуля присутствует, оно должно быть непустым. Если moduleAndPkg не содержит символа "/", весь аргумент интерпретируется как имя пакета.

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

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

Примечание реализации:: В эталонной реализации, если инструмент обработки аннотаций обрабатывает один модуль M, то M используется в качестве модуля для файлов, считываемых без явного префикса модуля. Если инструмент обрабатывает несколько модулей, и Elements.getPackageElement(package-of(name)) возвращает пакет, модуль, который владеет возвращённым пакетом, используется в качестве исходного модуля. Может быть использован отдельный параметр для указания целевого модуля, если его невозможно определить по вышеуказанным правилам.
Параметры:: location - расположение файла; moduleAndPkg - модуль и/или пакет относительно которого файл должен быть найден, или пустая строка, если ни один; relativeName - конечные компоненты пути к файлу
Возвращает:: объект для чтения файла
Выбрасывает:: FilerException - если один и тот же путь к файлу уже открыт для записи, если исходный модуль не может быть определен, или если целевой модуль недоступен для записи, или если задан явный целевой модуль, а расположение его не поддерживает.; IOException - если файл не может быть открыт; IllegalArgumentException - для недопустимого расположения; IllegalArgumentException - если moduleAndPkg имеет неправильный формат; IllegalArgumentException - если relativeName не является относительным

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.compiler/javax/annotation/processing/Filer.html