Интерфейс JavaFileManager

Все суперинтерфейсы:: AutoCloseable, Closeable, Flushable, OptionChecker

Все известные подинтерфейсы:: StandardJavaFileManager

Все известные реализующие классы:: ForwardingJavaFileManager

public interface JavaFileManager extends Closeable, Flushable, OptionChecker

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

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

Некоторые методы в этом интерфейсе используют имена классов. Такие имена классов должны быть предоставлены в внутренней форме виртуальной машины Java с полными квалифицированными именами классов и интерфейсов. Для удобства '.' и '/' взаимозаменяемы. Внутренняя форма определена в главе четыре Спецификации виртуальной машины Java.

Обсуждение: это означает, что имена "java/lang.package-info", "java/lang/package-info", "java.lang.package-info" допустимы и эквивалентны. Сравни с бинарным именем, как определено в Спецификации языка Java, раздел 13.1 «Форма бинарного файла».

Регистр имен важен. Все имена должны рассматриваться как чувствительные к регистру. Например, некоторые файловые системы имеют нечувствительные к регистру, но чувствительные к регистру имена файлов. Объекты файлов, представляющие такие файлы, должны позаботиться о сохранении регистра, используя File.getCanonicalFile() или аналогичные средства. Если система нечувствительна к регистру, объекты файлов должны использовать другие средства для сохранения регистра.

Относительные имена: некоторые методы в этом интерфейсе используют относительные имена. Относительный имя — это непустая последовательность сегментов пути, разделенных '/'. '.' или '..' недопустимы в качестве сегментов пути. Допустимое относительное имя должно соответствовать правилу «без корня пути» из RFC 3986, раздел 3.3. Неформально, это должно быть так:

  URI.create(relativeName).normalize().getPath().equals(relativeName)

Все методы в этом интерфейсе могут выбрасывать исключение SecurityException.

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

Примечание для реализации: следствием этого требования является то, что тривиальная реализация вывода в JarOutputStream не является достаточной реализацией. То есть, вместо создания JavaFileObject, который возвращает JarOutputStream напрямую, содержимое должно кэшироваться до закрытия, а затем записываться в JarOutputStream.

Если явно не разрешено, все методы этого интерфейса могут вызвать исключение NullPointerException, если получат null аргумент.

С момента:

1.6

См. также:

Краткое описание вложенных классов

Модификатор и тип	Интерфейс	Описание
`static interface`	`JavaFileManager.Location`	Интерфейс для расположения объектов файлов.

Краткое описание методов

Модификатор и тип	Метод	Описание
`void`	`close()`	Освобождает все ресурсы, открытые этим менеджером файлов напрямую или косвенно.
`default boolean`	`contains(JavaFileManager.Location location, FileObject fo)`	Определяет, содержится ли данный объект файла в указанном расположении.
`void`	`flush()`	Очищает все ресурсы, открытые для вывода этим менеджером файлов напрямую или косвенно.
`ClassLoader`	`getClassLoader(JavaFileManager.Location location)`	Возвращает загрузчик классов для загрузки плагинов из заданного расположения, ориентированного на пакет.
`FileObject`	`getFileForInput(JavaFileManager.Location location, String packageName, String relativeName)`	Возвращает объект файла для ввода, представляющий заданное относительное имя в указанном пакете в заданном расположении, ориентированном на пакет.
`FileObject`	`getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling)`	Возвращает объект файла для вывода, представляющий заданное относительное имя в указанном пакете в заданном расположении.
`JavaFileObject`	`getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind)`	Возвращает объект файла для ввода, представляющий указанный класс заданного типа в заданном расположении, ориентированном на пакет.
`JavaFileObject`	`getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling)`	Возвращает объект файла для вывода, представляющий указанный класс заданного типа в заданном расположении, ориентированном на пакет.
`default JavaFileManager.Location`	`getLocationForModule(JavaFileManager.Location location, String moduleName)`	Получает расположение для указанного модуля внутри расположения, которое может быть расположением, ориентированным на модуль, или расположением для вывода.
`default JavaFileManager.Location`	`getLocationForModule(JavaFileManager.Location location, JavaFileObject fo)`	Получает расположение для модуля, содержащего определенный файл, который должен быть найден внутри расположения, которое может быть расположением, ориентированным на модуль, или расположением для вывода.
`default <S> ServiceLoader<S>`	`getServiceLoader(JavaFileManager.Location location, Class<S> service)`	Получает загрузчик сервиса для определенного класса сервиса из заданного расположения.
`boolean`	`handleOption(String current, Iterator<String> remaining)`	Обрабатывает один параметр.
`boolean`	`hasLocation(JavaFileManager.Location location)`	Определяет, известно ли менеджеру файлов расположение.
`String`	`inferBinaryName(JavaFileManager.Location location, JavaFileObject file)`	Вычисляет бинарное имя объекта файла на основе расположения, ориентированного на пакет.
`default String`	`inferModuleName(JavaFileManager.Location location)`	Определяет имя модуля по его расположению, возвращаемому `getLocationForModule` или `listModuleLocations`.
`boolean`	`isSameFile(FileObject a, FileObject b)`	Сравнивает два объекта файла и возвращает true, если они представляют один и тот же базовый объект.
`Iterable<JavaFileObject>`	`list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse)`	Выводит все объекты файлов, соответствующие заданным критериям в заданном расположении, ориентированном на пакет.
`default Iterable<Set<JavaFileManager.Location>>`	`listLocationsForModules(JavaFileManager.Location location)`	Выводит расположения для всех модулей в расположении, ориентированном на модуль, или расположении для вывода.

Методы, объявленные в интерфейсе javax.tools.OptionChecker

isSupportedOption

Подробное описание методов

getClassLoader

ClassLoader getClassLoader(JavaFileManager.Location location)

Возвращает загрузчик классов для загрузки плагинов из заданного расположения, ориентированного на пакеты. Например, для загрузки процессоров аннотаций компилятор запросит загрузчик классов для расположения ANNOTATION_PROCESSOR_PATH.

Параметры:: location - расположение
Возвращает:: загрузчик классов для заданного расположения; или null если загрузка плагинов из заданного расположения отключена или расположение неизвестно
Исключения:: SecurityException - если загрузчик классов не может быть создан в текущем контексте безопасности; IllegalStateException - если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт; IllegalArgumentException - если расположение ориентировано на модули

list

Iterable<JavaFileObject> list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse) throws IOException

Перечисляет все объекты файлов, соответствующие заданным критериям, в заданном расположении, ориентированном на пакеты. Перечисляет объекты файлов в "подпакетах", если recurse имеет значение true.

Примечание: даже если заданное расположение неизвестно этому менеджеру файлов, он может не вернуть null. Кроме того, неизвестное расположение может не вызвать исключение.

Параметры:: location - расположение; packageName - имя пакета; kinds - возвращать объекты только этих типов; recurse - если true, включать "подпакеты"
Возвращает:: Iterable объектов файлов, соответствующих заданным критериям
Исключения:: IOException - если произошла ошибка ввода-вывода или если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт; IllegalArgumentException - если расположение ориентировано на модули; IllegalStateException - если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт

inferBinaryName

String inferBinaryName(JavaFileManager.Location location, JavaFileObject file)

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

Параметры:: location - расположение; file - объект файла
Возвращает:: двоичное имя или null объект файла не найден в заданном расположении
Исключения:: IllegalArgumentException - если расположение ориентировано на модули; IllegalStateException - если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт

isSameFile

boolean isSameFile(FileObject a, FileObject b)

Сравнивает два объекта файла и возвращает true, если они представляют один и тот же базовый объект.

Параметры:: a - объект файла; b - объект файла
Возвращает:: true, если заданные объекты файла представляют один и тот же базовый объект
Исключения:: IllegalArgumentException - если любой из аргументов был создан с другим менеджером файлов, и этот менеджер файлов не поддерживает внешние объекты файлов

handleOption

boolean handleOption(String current, Iterator<String> remaining)

Обрабатывает один параметр. Если current является параметром для этого менеджера файлов, он потребляет все аргументы к этому параметру из remaining и возвращает true, в противном случае возвращает false.

Параметры:: current - текущий параметр; remaining - оставшиеся параметры
Возвращает:: true, если этот параметр был обработан этим менеджером файлов, false в противном случае
Исключения:: IllegalArgumentException - если этот параметр для этого менеджера файлов используется неправильно; IllegalStateException - если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт

hasLocation

boolean hasLocation(JavaFileManager.Location location)

Определяет, известно ли расположение этому менеджеру файлов.

Параметры:: location - расположение
Возвращает:: true, если расположение известно

getJavaFileForInput

JavaFileObject getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind) throws IOException

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

Параметры:: location - расположение; className - имя класса; kind - тип файла, должен быть одним из SOURCE или CLASS
Возвращает:: объект файла, может вернуть null если файл не существует
Исключения:: IllegalArgumentException - если расположение не известно этому менеджеру файлов и менеджер файлов не поддерживает неизвестные расположения, или если тип не является допустимым, или если расположение ориентировано на модули; IOException - если произошла ошибка ввода-вывода или если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт; IllegalStateException - если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт

getJavaFileForOutput

JavaFileObject getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling) throws IOException

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

По желанию, этот менеджер файлов может учитывать брата как подсказку для размещения вывода. Точные семантика этой подсказки не определена. Например, компилятор JDK, javac, поместит файлы .class в те же каталоги, что и исходные файлы, если не указана каталога вывода файлов .class. Для упрощения этого поведения javac может предоставить исходный файл как брата при вызове этого метода.

Параметры:: location - расположение, ориентированное на пакеты; className - имя класса; kind - тип файла, должен быть одним из SOURCE или CLASS; sibling - объект файла, используемый в качестве подсказки для размещения; может быть null
Возвращает:: объект файла для вывода
Исключения:: IllegalArgumentException - если брат не известен этому менеджеру файлов, или если расположение не известно этому менеджеру файлов и менеджер файлов не поддерживает неизвестные расположения, или если тип не является допустимым, или если расположение не является расположением вывода; IOException - если произошла ошибка ввода-вывода или если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт; IllegalStateException - метод close() был вызван, и этот менеджер файлов не может быть повторно открыт

getFileForInput

FileObject getFileForInput(JavaFileManager.Location location, String packageName, String relativeName) throws IOException

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

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

Неформально, объект файла, возвращаемый этим методом, находится в конкатенации расположения, имени пакета и относительного имени. Например, чтобы найти файл свойств "resources/compiler.properties" в пакете "com.sun.tools.javac" в расположении SOURCE_PATH, этот метод может быть вызван следующим образом:

getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");

Если вызов был выполнен в Windows, с SOURCE_PATH, заданным на "C:\Documents and Settings\UncleBob\src\share\classes", допустимым результатом был бы объект файла, представляющий файл "C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties".

Параметры:: location - расположение, ориентированное на пакеты; packageName - имя пакета; relativeName - относительное имя
Возвращает:: объект файла, может вернуть null если файл не существует
Исключения:: IllegalArgumentException - если расположение не известно этому менеджеру файлов и менеджер файлов не поддерживает неизвестные расположения, или если relativeName не является допустимым, или если расположение ориентировано на модули; IOException - если произошла ошибка ввода-вывода или если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт; IllegalStateException - если метод close() был вызван, и этот менеджер файлов не может быть повторно открыт

getFileForOutput

FileObject getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling) throws IOException

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

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

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

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

Parameters:: location - расположение вывода; packageName - имя пакета; relativeName - относительное имя; sibling - объект файла, используемый в качестве подсказки для размещения; может быть null
Returns:: объект файла
Throws:: IllegalArgumentException - если брат по папке неизвестен этому менеджеру файлов, или если расположение неизвестно этому менеджеру файлов и менеджер файлов не поддерживает неизвестные расположения, или если relativeName недействительно, или если расположение не является расположением вывода; IOException - если произошла ошибка ввода-вывода, или если close() был вызван и этот менеджер файлов не может быть повторно открыт; IllegalStateException - если close() был вызван и этот менеджер файлов не может быть повторно открыт

flush

void flush() throws IOException

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

Specified by:

flush в интерфейсе Flushable

Throws:

IOException - если произошла ошибка ввода-вывода

See Also:

close()

close

void close() throws IOException

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

Specified by:

close в интерфейсе AutoCloseable

Specified by:

close в интерфейсе Closeable

Throws:

IOException - если произошла ошибка ввода-вывода

See Also:

flush()

getLocationForModule

default JavaFileManager.Location getLocationForModule(JavaFileManager.Location location, String moduleName) throws IOException

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

Implementation Requirements:: Эта реализация выбрасывает UnsupportedOperationException.
Parameters:: location - модульное расположение; moduleName - имя модуля для поиска
Returns:: расположение для указанного модуля
Throws:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов; IllegalArgumentException - если расположение не является расположением вывода и не модульным расположением
Since:: 9

getLocationForModule

default JavaFileManager.Location getLocationForModule(JavaFileManager.Location location, JavaFileObject fo) throws IOException

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

Implementation Requirements:: Эта реализация выбрасывает UnsupportedOperationException.
Parameters:: location - модульное расположение; fo - файл
Returns:: модуль, содержащий файл
Throws:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов; IllegalArgumentException - если расположение не является расположением вывода и не модульным расположением
Since:: 9

getServiceLoader

default <S> ServiceLoader<S> getServiceLoader(JavaFileManager.Location location, Class<S> service) throws IOException

Получает загрузчик сервисов для определённого класса сервиса из заданного расположения. Если расположение является модульным расположением, загрузчик сервисов будет использовать декларации сервиса в модулях, найденных в этом расположении. В противном случае, загрузчик сервисов создаётся с использованием расположения пакета, в котором случае сервисы определяются с использованием файлов конфигурации поставщика в META-INF/services.

Implementation Requirements:: Эта реализация выбрасывает UnsupportedOperationException.
Type Parameters:: S - класс сервиса
Parameters:: location - модульное расположение; service - Class объект класса сервиса
Returns:: загрузчик сервисов для данного класса сервиса
Throws:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов
Since:: 9

inferModuleName

default String inferModuleName(JavaFileManager.Location location) throws IOException

Определяет имя модуля по его расположению, как возвращаемому getLocationForModule или listModuleLocations.

Implementation Requirements:: Эта реализация выбрасывает UnsupportedOperationException.
Parameters:: location - расположение пакета, представляющее модуль
Returns:: имя модуля
Throws:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов; IllegalArgumentException - если расположение неизвестно этому менеджеру файлов
Since:: 9

listLocationsForModules

default Iterable<Set<JavaFileManager.Location>> listLocationsForModules(JavaFileManager.Location location) throws IOException

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

Implementation Requirements:: Эта реализация выбрасывает UnsupportedOperationException.
Parameters:: location - модульное расположение, для которого требуется список модулей
Returns:: последовательность наборов расположений, содержащих модули
Throws:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов; IllegalArgumentException - если расположение не является модульным расположением
Since:: 9

contains

default boolean contains(JavaFileManager.Location location, FileObject fo) throws IOException

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

Для расположения пакета объект файла содержится в расположении, если существуют значения для packageName и relativeName, такие что любой из следующих вызовов вернёт объект файла same:

     getFileForInput(location, packageName, relativeName)
     getFileForOutput(location, packageName, relativeName, null)

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

     getLocationForModule(location, moduleName)

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

Implementation Requirements:: Эта реализация выбрасывает UnsupportedOperationException.
Parameters:: location - расположение; fo - объект файла
Returns:: содержится ли файл в расположении
Throws:: IOException - если возникла проблема при определении результата; UnsupportedOperationException - если метод не поддерживается
Since:: 9

© 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/tools/JavaFileManager.html