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

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

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

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

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

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

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

API Note:: Для использования определённой кодировки для кодирования содержимого файла, можно создать OutputStreamWriter с выбранной кодировкой из объекта, возвращённого методом. Если объект, возвращённый методом, непосредственно используется для записи, его кодировка определяется реализацией. Инструмент обработки аннотаций может иметь флаг -encoding или аналогичный параметр для указания этого; в противном случае, обычно используется кодировка по умолчанию платформы.
Для предотвращения последующих ошибок содержимое исходного файла должно быть совместимо с используемой версией исходного кода для этой операции.
Implementation Note:: В эталонной реализации, если инструмент обработки аннотаций обрабатывает один модуль 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

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

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

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

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

API Note:: Для предотвращения последующих ошибок содержимое файла класса должно быть совместимо с используемой версией исходного кода для этой операции.
Implementation Note:: В эталонной реализации, если инструмент обработки аннотаций обрабатывает один модуль 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. Реализация может использовать информацию о конфигурации инструмента обработки аннотаций в процессе вывода.

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

Implementation Note:: В эталонной реализации, если инструмент обработки аннотаций обрабатывает один модуль 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, 2021, 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/17/docs/api/java.compiler/javax/annotation/processing/Filer.html