Интерфейс JavaFileManager

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

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

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

public interface JavaFileManager
extends Closeable, Flushable, OptionChecker

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

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

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

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

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

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

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

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

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

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

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

С тех пор:: 1.6
См. также:: JavaFileObject, FileObject

Вложенные классы

Модификатор и тип	Интерфейс	Описание
`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 в те же каталоги, что и исходные файлы .java, если не указан каталог для файлов .class. Для обеспечения такого поведения javac может передать исходный файл .java в качестве «сестры» при вызове этого метода.

Параметры:: 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

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

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

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

flush

void flush()
    throws IOException

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

Определено в:: flush в интерфейсе Flushable
Выбрасывает:: IOException - если произошла ошибка ввода-вывода
См. также:: close()

close

void close()
    throws IOException

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

Определено в:: close в интерфейсе AutoCloseable
Определено в:: close в интерфейсе Closeable
Выбрасывает:: IOException - если произошла ошибка ввода-вывода
См. также:: flush()

getLocationForModule

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

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

Требования к реализации:: Эта реализация выбрасывает UnsupportedOperationException.
Параметры:: location - местоположение для модулей; moduleName - имя модуля, который нужно найти
Возвращает:: местоположение для модуля с именем
Выбрасывает:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов; IllegalArgumentException - если местоположение не является местом вывода и не местоположением для модулей
С:: 9

getLocationForModule

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

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

Требования к реализации:: Эта реализация выбрасывает UnsupportedOperationException.
Параметры:: location - местоположение для модулей; fo - файл
Возвращает:: модуль, содержащий файл
Выбрасывает:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов; IllegalArgumentException - если местоположение не является местом вывода и не местоположением для модулей
С:: 9

getServiceLoader

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

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

Требования к реализации:: Эта реализация выбрасывает UnsupportedOperationException.
Параметры типа:: S - класс сервиса
Параметры:: location - местоположение для модулей; service - объект Class класса сервиса
Возвращает:: загрузчик сервисов для заданного класса сервиса
Выбрасывает:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов
С:: 9

inferModuleName

default String inferModuleName(JavaFileManager.Location location)
                        throws IOException

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

Требования к реализации:: Эта реализация выбрасывает UnsupportedOperationException.
Параметры:: location - местоположение пакета, представляющее модуль
Возвращает:: имя модуля
Выбрасывает:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов; IllegalArgumentException - если местоположение не известно этому менеджеру файлов
С:: 9

listLocationsForModules

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

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

Требования к реализации:: Эта реализация выбрасывает UnsupportedOperationException.
Параметры:: location - местоположение для модулей, для которого необходимо вывести список модулей
Возвращает:: ряд наборов местоположений, содержащих модули
Выбрасывает:: IOException - если произошла ошибка ввода-вывода; UnsupportedOperationException - если эта операция не поддерживается этим менеджером файлов; IllegalArgumentException - если местоположение не является местоположением для модулей
С:: 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)

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

Требования к реализации:: Эта реализация выбрасывает UnsupportedOperationException.
Параметры:: location - местоположение; fo - объект файла
Возвращает:: содержит ли файл местоположение
Выбрасывает:: IOException - если есть проблема с определением результата; UnsupportedOperationException - если метод не поддерживается
С:: 9

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