Интерфейс JavaFileManager

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

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

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

public interface JavaFileManager extends Closeable, Flushable, OptionChecker

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

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

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

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

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

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

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

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

Примечание по реализации: следствием этого требования является то, что простая реализация вывода в 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)`	Возвращает объект файла для вывода, представляющий указанное относительное имя в указанном пакете в заданном расположении.
`default FileObject`	`getFileForOutputForOriginatingFiles(JavaFileManager.Location location, String packageName, String relativeName, FileObject... originatingFiles)`	Возвращает объект файла для вывода, представляющий указанное относительное имя в указанном пакете в заданном расположении.
`JavaFileObject`	`getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind)`	Возвращает объект файла для ввода, представляющий указанный класс заданного вида в указанном расположении, ориентированном на пакеты.
`JavaFileObject`	`getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling)`	Возвращает объект файла для вывода, представляющий указанный класс заданного вида в указанном расположении, ориентированном на пакеты.
`default JavaFileObject`	`getJavaFileForOutputForOriginatingFiles(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject... originatingFiles)`	Возвращает объект файла для вывода, представляющий указанный класс заданного вида в указанном расположении, ориентированном на пакеты.
`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)`	Перечисляет расположения всех модулей в расположении, ориентированном на модули, или в выходном расположении.

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

isSupportedOption

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

getClassLoader

ClassLoader getClassLoader(JavaFileManager.Location location)

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

Параметры:: location — расположение
Возвращает:: загрузчик классов для указанного расположения; или null, если загрузка подключаемых модулей из указанного расположения отключена или расположение неизвестно
Исключения:: 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 помещает файлы классов в те же каталоги, что и исходные файлы, если не задан каталог для выходных файлов классов. Чтобы обеспечить такое поведение, javac может передать исходный файл в качестве соседнего при вызове этого метода.

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

getJavaFileForOutputForOriginatingFiles

default JavaFileObject getJavaFileForOutputForOriginatingFiles(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject... originatingFiles) throws IOException

Переданные originatingFiles представляют файлы, которые тем или иным, не определённым образом использовались для создания содержимого файла, создаваемого этим методом. См. originatingElements в Filer.createSourceFile(CharSequence, Element...). Метод Elements.getFileObjectOf(Element) можно использовать для преобразования Element в FileObject.

Требования к реализации:

Реализация по умолчанию вызывает

getJavaFileForOutput(javax.tools.JavaFileManager.Location, java.lang.String, javax.tools.JavaFileObject.Kind, javax.tools.FileObject)

, передавая первый элемент originatingFiles, если он есть, в качестве sibling.

Параметры:

location — расположение, ориентированное на пакеты

className — имя класса

kind — вид файла; должен быть одним из SOURCE или CLASS

originatingFiles — файлы, участвующие в создании этого нового файла; null эквивалентен пустому originatingFiles, то есть отсутствию известных исходных файлов

Возвращает:

файловый объект для записи

Исключения:

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

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

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

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

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

getFileForOutputForOriginatingFiles

default FileObject getFileForOutputForOriginatingFiles(JavaFileManager.Location location, String packageName, String relativeName, FileObject... originatingFiles) throws IOException

Переданные originatingFiles представляют файлы, которые тем или иным, не определённым образом использовались для создания содержимого файла, создаваемого этим методом. См. originatingElements в Filer.createResource(JavaFileManager.Location, CharSequence, CharSequence, Element...). Метод Elements.getFileObjectOf(Element) можно использовать для преобразования Element в FileObject.

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

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

Требования к реализации:

Реализация по умолчанию вызывает getFileForOutput(javax.tools.JavaFileManager.Location, java.lang.String, java.lang.String, javax.tools.FileObject), передавая первый элемент originatingFiles, если он есть, в качестве sibling.

Параметры:

location — расположение для вывода

packageName — имя пакета

relativeName — относительное имя

Возвращает:

файловый объект

Исключения:

IllegalArgumentException — если соседний файл неизвестен этому файловому менеджеру, если расположение неизвестно этому файловому менеджеру и он не поддерживает неизвестные расположения, если relativeName недопустимо или если расположение не предназначено для вывода

IllegalStateException — если был вызван close() и этот файловый менеджер нельзя открыть повторно

Начиная с:

См. также:

flush

void flush() throws IOException

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

Определено в:

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

Исключения:

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

См. также:

close

void close() throws IOException

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

Определено в:

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

Определено в:

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

Исключения:

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

См. также:

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, 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://docs.oracle.com/en/java/javase/25/docs/api/java.compiler/javax/tools/JavaFileManager.html