Интерфейс JavaFileManager

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

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

Некоторые методы в этом интерфейсе используют имена классов. Такие имена классов должны быть предоставлены во внутренней форме виртуальной машины 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 аргумент.

Методы

getClassLoader

ClassLoader getClassLoader(JavaFileManager.Location location)

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

Параметры:

location - расположение

Возвращает:

загрузчик классов для данного расположения; или null если загрузка плагинов из данного расположения отключена или расположение неизвестно

Исключения:

SecurityException - если загрузчик классов не может быть создан в текущем контексте безопасности

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

list

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

Параметры:

location - расположение

packageName - имя пакета

kinds - возвращать объекты только этих типов

recurse - если true, включать «подпакеты»

Возвращает:

Iterable объектов файлов, соответствующих заданным критериям

Исключения:

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

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

inferBinaryName

String inferBinaryName(JavaFileManager.Location location,
                       JavaFileObject file)

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

Параметры:

location - расположение

file - объект файла

Возвращает:

двоичное имя или null если объект файла не найден в указанном расположении

Исключения:

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

Параметры:

location - расположение

className - имя класса

kind - тип файла, должен быть одним из SOURCE или CLASS

sibling - объект файла, используемый в качестве подсказки для размещения; может быть null

Возвращает:

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

Исключения:

IllegalArgumentException - если «сестра» неизвестна этому менеджеру файлов, или если расположение неизвестно этому менеджеру файлов и менеджер файлов не поддерживает неизвестные расположения, или если тип недействителен

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

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

getFileForInput

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

getFileForInput(SOURCE_PATH, "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

Параметры:

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()