Интерфейс Filer

public interface Filer

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

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

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

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

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

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

Если среда настроена на поддержку неявно объявленных классов, аргумент name используется для предоставления ведущей компоненты имени, используемого для выходного файла. Например, filer.createSourceFile("Foo") для создания неявно объявленного класса, размещённого в Foo.java. Все неявно объявленные классы должны находиться в безымянном пакете.

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

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:: Чтобы избежать последующих ошибок, содержимое файла класса должно быть совместимо с версией исходного кода, используемой для этого запуска.
Примечание реализации:: В эталонной реализации, если инструмент обработки аннотаций обрабатывает один модуль 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)) возвращает пакет, модуль, которому принадлежит возвращённый пакет, используется в качестве целевого модуля. Отдельная опция может быть использована для предоставления целевого модуля, если его невозможно определить с помощью вышеуказанных правил.
Parameters:: location - местоположение нового файла; moduleAndPkg - модуль и/или пакет, относительно которых файл должен быть назван, или пустая строка, если нет; relativeName - конечные компоненты имени файла; originatingElements - классы или интерфейсы или пакеты или модули, причинно связанные с созданием этого файла, могут быть пропущены или null
Returns:: объект FileObject для записи нового ресурса
Throws:: 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 не содержит символа "/", весь аргумент интерпретируется как имя пакета.

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

© 1993, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.compiler/javax/annotation/processing/Filer.html