Интерфейс Filer

public interface Filer

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


 OutputStream

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

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

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

Например, если обработчик аннотаций пытается создать исходный файл, GeneratedFromUserSource, в ответ на обработку

  @Generate
  public class UserSource {}

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

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

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

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

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

Обработчики могут указывать, что исходный или классный файл сгенерирован, включив аннотацию 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. Реализация может использовать информацию о конфигурации инструмента обработки аннотаций в процессе определения.

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

Если среда настроена для поддержки безымянных классов^{ПРЕДПРОСМОТР}, аргумент `name` используется для предоставления начальной части имени, используемого для выходного файла. Например, filer.createSourceFile("Foo") для создания безымянного класса, размещенного в Foo.java. Все безымянные классы должны находиться в безымянном пакете.

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

createClassFile

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

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

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

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

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

Если среда настроена для поддержки безымянных классов^{ПРЕДПРОСМОТР}, аргумент `name` используется для предоставления начальной части имени, используемого для выходного файла. Например, filer.createClassFile("Foo") для создания безымянного класса, размещенного в Foo.class. Все безымянные классы должны находиться в безымянном пакете.

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

Создать ресурс

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

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

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

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

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

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

Получить ресурс

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

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

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

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

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

© 1993, 2023, 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/21/docs/api/java.compiler/javax/annotation/processing/Filer.html