Интерфейс Path

Все суперинтерфейсы:: Comparable<Path>, Iterable<Path>, Watchable

public interface Path extends Comparable<Path>, Iterable<Path>, Watchable

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

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

Помимо доступа к компонентам пути, Path также определяет методы resolve и resolveSibling для объединения путей. Метод relativize можно использовать для построения относительного пути между двумя путями. Пути можно compared, а также сравнивать друг с другом с помощью методов startsWith и endsWith.

Этот интерфейс расширяет интерфейс Watchable, чтобы каталог, найденный по пути, можно было registered в WatchService и отслеживать записи в каталоге.

ПРЕДУПРЕЖДЕНИЕ: Этот интерфейс предназначен только для реализации разработчиками пользовательских файловых систем. В будущих выпусках в этот интерфейс могут быть добавлены методы.

Доступ к файлам

Пути можно использовать с классом Files для работы с файлами, каталогами и другими типами файлов. Например, предположим, что нам нужен BufferedReader для чтения текста из файла «access.log». Файл находится в каталоге «logs» относительно текущего рабочего каталога и закодирован в UTF-8.

    Path path = FileSystems.getDefault().getPath("logs", "access.log");
    BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);

Взаимодействие

Пути, связанные с поставщиком файловой системы provider по умолчанию, обычно совместимы с классом java.io.File. Пути, созданные другими поставщиками, скорее всего, несовместимы с абстрактными именами путей, представленными java.io.File. Метод toPath можно использовать для получения Path из абстрактного имени пути, представленного объектом java.io.File. Полученный Path можно использовать для работы с тем же файлом, что и объект java.io.File. Кроме того, метод toFile полезен для создания File из представления String объекта Path.

Параллельное выполнение

Реализации этого интерфейса неизменяемы и безопасны для использования несколькими параллельно работающими потоками.

Начиная с версии:: 1.7

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

Модификатор и тип	Метод	Описание
`int`	`compareTo(Path other)`	Сравнивает два абстрактных пути в лексикографическом порядке.
`default boolean`	`endsWith(String other)`	Проверяет, заканчивается ли этот путь на `Path`, созданном преобразованием заданной строки пути точно так, как указано в методе `endsWith(Path)`.
`boolean`	`endsWith(Path other)`	Проверяет, заканчивается ли этот путь заданным путем.
`boolean`	`equals(Object other)`	Проверяет, равен ли этот путь заданному объекту.
`Path`	`getFileName()`	Возвращает имя файла или каталога, обозначенного этим путем, в виде объекта `Path`.
`FileSystem`	`getFileSystem()`	Возвращает файловую систему, создавшую этот объект.
`Path`	`getName(int index)`	Возвращает элемент имени этого пути в виде объекта `Path`.
`int`	`getNameCount()`	Возвращает количество элементов имен в пути.
`Path`	`getParent()`	Возвращает родительский путь или `null`, если у этого пути нет родительского пути.
`Path`	`getRoot()`	Возвращает корневой компонент этого пути в виде объекта `Path` или `null`, если у этого пути нет корневого компонента.
`int`	`hashCode()`	Вычисляет хеш-код этого пути.
`boolean`	`isAbsolute()`	Определяет, является ли этот путь абсолютным.
`default Iterator<Path>`	`iterator()`	Возвращает итератор по элементам имен этого пути.
`Path`	`normalize()`	Возвращает путь, совпадающий с этим путем, из которого удалены избыточные элементы имен.
`static Path`	`of(String first, String... more)`	Возвращает `Path`, преобразуя строку пути или последовательность строк, которые при объединении образуют строку пути.
`static Path`	`of(URI uri)`	Возвращает `Path`, преобразуя URI.
`default WatchKey`	`register(WatchService watcher, WatchEvent.Kind<?>... events)`	Регистрирует файл, найденный по этому пути, в службе наблюдения.
`WatchKey`	`register(WatchService watcher, WatchEvent.Kind<?>[] events, WatchEvent.Modifier... modifiers)`	Регистрирует файл, найденный по этому пути, в службе наблюдения.
`Path`	`relativize(Path other)`	Создает относительный путь между этим путем и заданным путем.
`default Path`	`resolve(String other)`	Преобразует заданную строку пути в `Path` и разрешает ее относительно этого `Path` точно так, как указано в методе `resolve`.
`default Path`	`resolve(String first, String... more)`	Преобразует строку пути в путь, разрешает этот путь относительно данного пути, а затем итеративно выполняет ту же процедуру для всех дополнительных строк путей.
`Path`	`resolve(Path other)`	Разрешает заданный путь относительно этого пути.
`default Path`	`resolve(Path first, Path... more)`	Разрешает путь относительно этого пути, а затем итеративно разрешает все дополнительные пути.
`default Path`	`resolveSibling(String other)`	Преобразует заданную строку пути в `Path` и разрешает ее относительно `parent` пути точно так, как указано в методе `resolveSibling`.
`default Path`	`resolveSibling(Path other)`	Разрешает заданный путь относительно `parent` этого пути.
`default boolean`	`startsWith(String other)`	Проверяет, начинается ли этот путь с `Path`, созданного преобразованием заданной строки пути точно так, как указано в методе `startsWith(Path)`.
`boolean`	`startsWith(Path other)`	Проверяет, начинается ли этот путь с заданного пути.
`Path`	`subpath(int beginIndex, int endIndex)`	Возвращает относительный `Path`, представляющий собой подпоследовательность элементов имен этого пути.
`Path`	`toAbsolutePath()`	Возвращает объект `Path`, представляющий абсолютный путь этого пути.
`default File`	`toFile()`	Возвращает объект `File`, представляющий этот путь.
`Path`	`toRealPath(LinkOption... options)`	Возвращает реальный путь к существующему файлу.
`String`	`toString()`	Возвращает строковое представление этого пути.
`URI`	`toUri()`	Возвращает URI, представляющий этот путь.

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

forEach, spliterator

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

of

static Path of(String first, String... more)

Возвращает Path, преобразуя строку пути или последовательность строк, которые при объединении образуют строку пути. Если more не задаёт ни одного элемента, значением параметра first является строка пути для преобразования. Если more задаёт один или несколько элементов, каждая непустая строка, включая first, считается последовательностью элементов имени и объединяется в строку пути. Способ объединения строк зависит от поставщика, но обычно строки объединяются с использованием name-separator в качестве разделителя. Например, если разделителем имён является "/" и вызывается getPath("/foo","bar","gus"), строка пути "/foo/bar/gus" преобразуется в Path. Если first является пустой строкой, а more не содержит непустых строк, возвращается Path, представляющий пустой путь.

Path получается вызовом метода getPath у default FileSystem.

Обратите внимание: хотя этот метод очень удобен, его использование подразумевает ссылку на FileSystem по умолчанию и ограничивает возможности повторного использования вызывающего кода. Поэтому его не следует использовать в библиотечном коде, предназначенном для гибкого повторного использования. Более гибкая альтернатива — использовать существующий экземпляр Path в качестве опорного, например:

    Path dir = ...
    Path path = dir.resolve("file");

Параметры:

first - строка пути или начальная часть строки пути

more - дополнительные строки, объединяемые для формирования строки пути

Возвращает:

результирующий Path

Вызывает:

InvalidPathException - если строку пути невозможно преобразовать в Path

Начиная с версии:

См. также:

of

static Path of(URI uri)

Возвращает Path, преобразуя URI.

Этот метод перебирает поставщиков installed, чтобы найти поставщика, определяемого scheme заданного URI. Схемы URI сравниваются без учёта регистра. Если поставщик найден, вызывается его метод getPath для преобразования URI.

Для поставщика по умолчанию, определяемого схемой URI "file", заданный URI имеет непустой компонент пути и неопределённые компоненты запроса и фрагмента. Наличие компонента полномочий зависит от платформы. Возвращённый Path связан с файловой системой default.

Поставщик по умолчанию обеспечивает гарантию обратного преобразования, аналогичную гарантии класса File. Для заданного Path p гарантируется, что

Path.of(p.toUri()).equals( p.toAbsolutePath())

при условии, что исходные Path, URI и новые


Path

созданы в одной и той же виртуальной машине Java (возможно, при разных её запусках). Наличие каких-либо гарантий у других поставщиков зависит от конкретного поставщика и поэтому не определено.

Параметры:: uri - URI для преобразования
Возвращает:: результирующий Path
Вызывает:: IllegalArgumentException - если не выполнены предварительные условия для параметра uri. Формат URI зависит от поставщика.; FileSystemNotFoundException - файловая система, определяемая URI, не существует и не может быть создана автоматически, либо поставщик, определяемый компонентом схемы URI, не установлен
Начиная с версии:: 11

getFileSystem

FileSystem getFileSystem()

Возвращает файловую систему, создавшую этот объект.

Возвращает:: файловую систему, создавшую этот объект

isAbsolute

boolean isAbsolute()

Проверяет, является ли этот путь абсолютным.

Абсолютный путь является полным: для определения местоположения файла его не нужно объединять с другой информацией о пути.

Возвращает:: true тогда и только тогда, когда этот путь абсолютный

getRoot

Path getRoot()

Возвращает корневой компонент этого пути в виде объекта Path или null, если у этого пути нет корневого компонента.

Возвращает:: путь, представляющий корневой компонент этого пути, или null

getFileName

Path getFileName()

Возвращает имя файла или каталога, обозначенного этим путём, в виде объекта Path. Имя файла — это элемент, наиболее удалённый от корня в иерархии каталогов.

Возвращает:: путь, представляющий имя файла или каталога, или null, если этот путь не содержит элементов

getParent

Path getParent()

Возвращает родительский путь или null, если у этого пути нет родительского пути.

Родительский путь этого объекта состоит из корневого компонента этого пути, если он есть, и всех элементов пути, кроме элемента, наиболее удалённого от корня в иерархии каталогов. Этот метод не обращается к файловой системе; путь или его родительский путь могут не существовать. Кроме того, этот метод не удаляет специальные имена, такие как "." и "..", которые могут использоваться в некоторых реализациях. Например, в UNIX родительским путём для "/a/b/c" является "/a/b", а родительским путём для "x/y/." является "x/y". Этот метод можно использовать вместе с методом normalize, чтобы удалить избыточные имена в случаях, когда требуется навигация в стиле командной оболочки.

Если этот путь содержит более одного элемента и не имеет корневого компонента, то данный метод эквивалентен вычислению выражения:

    subpath(0, getNameCount()-1);

Возвращает:: путь, представляющий родительский путь данного пути

getNameCount

int getNameCount()

Возвращает количество элементов имени в пути.

Возвращает:: количество элементов в пути или 0, если этот путь представляет только корневой компонент

getName

Path getName(int index)

Возвращает элемент имени этого пути в виде объекта Path.

Параметр index задаёт индекс возвращаемого элемента имени. Элемент, расположенный ближе всего к корню в иерархии каталогов, имеет индекс 0. Элемент, расположенный дальше всего от корня, имеет индекс count-1.

Параметры:: index - индекс элемента
Возвращает:: элемент имени
Вызывает:: IllegalArgumentException - если index отрицательно, index больше или равно количеству элементов либо этот путь не содержит элементов имени

subpath

Path subpath(int beginIndex, int endIndex)

Возвращает относительный Path, являющийся подпоследовательностью элементов имени этого пути.

Параметры beginIndex и endIndex задают подпоследовательность элементов имени. Имя, расположенное ближе всего к корню в иерархии каталогов, имеет индекс 0. Имя, расположенное дальше всего от корня, имеет индекс count-1. Возвращаемый объект Path содержит элементы имени, начиная с beginIndex и заканчивая элементом с индексом endIndex-1.

Параметры:: beginIndex - индекс первого элемента включительно; endIndex - индекс последнего элемента исключительно
Возвращает:: новый объект Path, являющийся подпоследовательностью элементов имени этого Path
Вызывает:: IllegalArgumentException - если beginIndex отрицательно или больше либо равно количеству элементов. Если endIndex меньше либо равно beginIndex или больше количества элементов.

startsWith

boolean startsWith(Path other)

Проверяет, начинается ли этот путь с заданного пути.

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

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

Если заданный путь связан с FileSystem, отличной от той, с которой связан этот путь, возвращается false.

Параметры:: other - заданный путь
Возвращает:: true, если этот путь начинается с заданного пути; в противном случае false

startsWith

default boolean startsWith(String other)

Проверяет, начинается ли этот путь с Path, созданного преобразованием заданной строки пути точно так, как указано в методе startsWith(Path). Например, в UNIX путь "foo/bar" начинается с "foo" и "foo/bar". Он не начинается с "f" или "fo".

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

Реализация по умолчанию для этого пути эквивалентна следующему выражению:

    startsWith(getFileSystem().getPath(other));

Параметры:

other - заданная строка пути

Возвращает:

true, если этот путь начинается с заданного пути; в противном случае false

Вызывает:

InvalidPathException - если строку пути невозможно преобразовать в Path.

endsWith

boolean endsWith(Path other)

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

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

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

Если заданный путь связан с FileSystem, отличной от той, с которой связан этот путь, возвращается false.

Параметры:: other - заданный путь
Возвращает:: true, если этот путь заканчивается заданным путём; в противном случае false

endsWith

default boolean endsWith(String other)

Проверяет, заканчивается ли этот путь на Path, созданном преобразованием заданной строки пути точно так, как указано в методе endsWith(Path). Например, в UNIX путь "foo/bar" заканчивается на "foo/bar" и "bar". Он не заканчивается на "r" или "/bar". Обратите внимание, что конечные разделители не учитываются, поэтому вызов этого метода для


Path

"foo/bar" с String "bar/" возвращает true.

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

Реализация по умолчанию для этого пути эквивалентна следующему выражению:

    endsWith(getFileSystem().getPath(other));

Параметры:

other - заданная строка пути

Возвращает:

true, если этот путь заканчивается заданным путём; в противном случае false

Вызывает:

InvalidPathException - если строку пути невозможно преобразовать в Path.

normalize

Path normalize()

Возвращает этот путь без избыточных элементов имени.

Точное определение этого метода зависит от реализации, но в общем случае он формирует на основе этого пути путь, не содержащий избыточных элементов имени. Во многих файловых системах "." и ".." — специальные имена, обозначающие текущий каталог и родительский каталог. В таких файловых системах все вхождения "." считаются избыточными. Если перед ".." стоит имя, не являющееся "..", оба имени считаются избыточными (поиск таких имён повторяется, пока это правило применимо).

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

Возвращает:

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

См. также:

resolve

Path resolve(Path other)

Разрешает заданный путь относительно этого пути.

Если параметр other задаёт absolute путь, этот метод просто возвращает other. Если other — пустой путь, этот метод просто возвращает данный путь. В противном случае метод рассматривает этот путь как каталог и разрешает заданный путь относительно него. В простейшем случае заданный путь не имеет компонента root; тогда этот метод присоединяет заданный путь к этому пути и возвращает результирующий путь, который ends заданным путём. Если заданный путь имеет корневой компонент, способ разрешения в значительной степени зависит от реализации и поэтому не определён.

Параметры:

other - путь, разрешаемый относительно этого пути

Возвращает:

результирующий путь

См. также:

resolve

default Path resolve(String other)

Преобразует заданную строку пути в Path и разрешает его относительно этого Path точно так, как указано в методе resolve. Например, если разделителем имён является "/", а путь обозначает "foo/bar", вызов этого метода со строкой пути "gus" приведёт к получению Path "foo/bar/gus".

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

Реализация по умолчанию для этого пути эквивалентна следующему выражению:

    resolve(getFileSystem().getPath(other));

Параметры:

other - строка пути, разрешаемая относительно этого пути

Возвращает:

результирующий путь

Вызывает:

InvalidPathException - если строку пути невозможно преобразовать в Path.

См. также:

resolve

default Path resolve(Path first, Path... more)

Разрешает путь относительно этого пути, а затем последовательно разрешает дополнительные пути.

Этот метод разрешает first относительно этого Path, как если бы был вызван метод resolve(Path). Если more содержит один или несколько элементов, первый элемент разрешается относительно полученного результата, после чего последовательно разрешаются все остальные элементы. Метод возвращает результат последнего разрешения.

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

Реализация по умолчанию эквивалентна результату, полученному с помощью:

    Path result = resolve(first);
    for (Path p : more) {
        result = result.resolve(p);
    }

Параметры:

first - первый путь, разрешаемый относительно этого пути

more - дополнительные пути для последовательного разрешения

Возвращает:

результирующий путь

Начиная с версии:

См. также:

resolve

default Path resolve(String first, String... more)

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

Этот метод преобразует first в Path и разрешает этот Path относительно данного Path, как если бы был вызван метод resolve(String). Если more содержит один или несколько элементов, первый элемент преобразуется в путь и разрешается относительно полученного результата, после чего остальные элементы последовательно преобразуются и разрешаются. Метод возвращает результат последнего разрешения.

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

Реализация по умолчанию эквивалентна результату, полученному с помощью:

Path result = resolve(first);
for (String s : more) {
    result = result.resolve(s);
}

Параметры:

first - первая строка пути для преобразования в путь и разрешения относительно этого пути

more - дополнительные строки пути для последовательного преобразования в пути и разрешения

Возвращает:

результирующий путь

Вызывает:

InvalidPathException - если строку пути невозможно преобразовать в Path.

Начиная с версии:

См. также:

resolveSibling

default Path resolveSibling(Path other)

Разрешает заданный путь относительно parent этого пути. Это полезно, когда требуется заменить имя файла другим именем файла. Например, если разделителем имён является "/", а путь обозначает "dir1/dir2/foo", вызов этого метода с Path "bar" приведёт к получению


Path

"dir1/dir2/bar". Если у этого пути нет родительского пути или other является absolute, метод возвращает other. Если other — пустой путь, этот метод возвращает родительский путь данного пути или пустой путь, если у этого пути нет родительского пути.

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

Реализация по умолчанию для этого пути эквивалентна следующему выражению:

    (getParent() == null) ? other : getParent().resolve(other);

за исключением случая other == null, когда выбрасывается NullPointerException.

Параметры:

other - путь, разрешаемый относительно родительского пути этого пути

Возвращает:

результирующий путь

См. также:

resolveSibling

default Path resolveSibling(String other)

Преобразует заданную строку пути в Path и разрешает его относительно parent этого пути точно так, как указано в методе resolveSibling.

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

Реализация по умолчанию для этого пути эквивалентна следующему выражению:

    resolveSibling(getFileSystem().getPath(other));

Параметры:

other - строка пути, разрешаемая относительно родительского пути этого пути

Возвращает:

результирующий путь

Вызывает:

InvalidPathException - если строку пути невозможно преобразовать в Path.

См. также:

relativize

Path relativize(Path other)

Создаёт относительный путь между этим путём и заданным путём.

Преобразование в относительный путь является обратной операцией для resolution. Этот метод пытается создать relative путь, который при resolved относительно этого пути даст путь, указывающий на тот же файл, что и заданный путь. Например, в UNIX, если этот путь — "/a/b", а заданный путь — "/a/b/c/d", результирующим относительным путём будет "c/d". Если у этого и заданного путей нет компонента root, можно создать относительный путь. Относительный путь невозможно создать, если корневой компонент есть только у одного из путей. Если корневые компоненты есть у обоих путей, возможность создания относительного пути зависит от реализации. Если этот путь и заданный путь equal, возвращается пустой путь.

Для любых двух normalized путей p и q, где у q нет корневого компонента, выполняется следующее:

p.relativize(p .resolve(q)).equals(q)

Если поддерживаются символические ссылки, то зависит от реализации, будет ли результирующий путь после разрешения относительно этого пути указывать на путь, который можно использовать для поиска same файла, что и other. Например, если этот путь — "/a/b", а заданный путь — "/a/x", результирующим относительным путём может быть "../x". Если "b" является символической ссылкой, то зависит от реализации, будет ли "a/b/../x" указывать на тот же файл, что и "/a/x".

Параметры:: other - путь, относительно которого вычисляется относительный путь от этого пути
Возвращает:: результирующий относительный путь или пустой путь, если оба пути равны
Вызывает:: IllegalArgumentException - если other не является Path, относительно которого можно вычислить путь от этого пути

toUri

URI toUri()

Возвращает URI, представляющий этот путь.

Этот метод создаёт абсолютный URI с scheme, равной схеме URI, определяющей поставщика. Точная форма специфичной для схемы части в значительной степени зависит от поставщика.

Для поставщика по умолчанию URI является иерархическим и имеет абсолютный компонент path. Компоненты запроса и фрагмента не определены. Наличие компонента полномочий зависит от реализации. Нет гарантии, что URI можно использовать для создания java.io.File. В частности, если этот путь представляет собой путь Universal Naming Convention (UNC), имя сервера UNC может быть закодировано в компоненте полномочий результирующего URI. Если используется поставщик по умолчанию, файл существует и можно определить, что файл является каталогом, результирующий URI будет заканчиваться косой чертой.

Path.of(p.toUri()).equals(p .toAbsolutePath())

при условии, что исходные Path, URI и новые


Path

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

Возвращает:: URI, представляющий этот путь
Вызывает:: IOError - если при получении абсолютного пути возникает ошибка ввода-вывода либо если файловая система создаётся для доступа к содержимому файла как к файловой системе и невозможно получить URI содержащей файловой системы

toAbsolutePath

Path toAbsolutePath()

Возвращает объект Path, представляющий абсолютный путь этого пути. Если этот Path связан с поставщиком по умолчанию, возвращаемый абсолютный путь будет иметь корневой компонент root component, не являющийся null.

Если этот путь уже absolute, метод просто возвращает этот путь. В противном случае метод разрешает путь способом, зависящим от реализации, обычно разрешая путь относительно каталога файловой системы по умолчанию. В зависимости от реализации этот метод может выдать ошибку ввода-вывода, если файловая система недоступна.

Возвращает:: объект Path, представляющий абсолютный путь
Выбрасывает:: IOError - если происходит ошибка ввода-вывода

toRealPath

Path toRealPath(LinkOption... options) throws IOException

Возвращает реальный путь существующего файла.

Точное определение этого метода зависит от реализации, но, как правило, он строит на основе этого пути absolute путь, указывающий на same файл, что и этот путь, но с элементами имени, соответствующими фактическим именам каталогов и файла. Например, если сравнение имён файлов в файловой системе не учитывает регистр, элементы имени соответствуют именам в их фактическом регистре. Кроме того, в результирующем пути удаляются избыточные элементы имени.

Если этот путь относительный, сначала получается его абсолютный путь, как если бы был вызван метод toAbsolutePath.

Массив options можно использовать, чтобы указать способ обработки символических ссылок. По умолчанию символические ссылки разрешаются до конечного целевого объекта. Если указан параметр NOFOLLOW_LINKS, этот метод не разрешает символические ссылки. Некоторые реализации допускают специальные имена, например "..", для обозначения родительского каталога. При построении реального пути, если перед именем ".." (или его эквивалентом) находится имя, не являющееся "..", реализация обычно удаляет оба имени. Если символические ссылки не разрешаются и предыдущее имя является символической ссылкой, имена удаляются только в том случае, если гарантируется, что результирующий путь будет указывать на тот же файл, что и этот путь.

Параметры:: options - параметры, указывающие способ обработки символических ссылок
Возвращает:: абсолютный путь, представляющий реальный путь к файлу, на который указывает этот объект
Выбрасывает:: IOException - если файл не существует или происходит ошибка ввода-вывода

toFile

default File toFile()

Возвращает объект File, представляющий этот путь. Если этот


Path

связан с поставщиком по умолчанию, этот метод эквивалентен возврату объекта File, созданного с использованием представления String этого пути.

Если этот путь был создан вызовом метода File toPath, нет гарантии, что объект File, возвращённый этим методом, будет equal исходному File.

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

Реализация по умолчанию эквивалентна для этого пути следующему:

    new File(toString());

если FileSystem, создавшая этот Path, является файловой системой по умолчанию; в противном случае выбрасывается UnsupportedOperationException.

Возвращает:

объект File, представляющий этот путь

Выбрасывает:

UnsupportedOperationException - если этот Path не связан с поставщиком по умолчанию

register

WatchKey register(WatchService watcher, WatchEvent.Kind<?>[] events, WatchEvent.Modifier... modifiers) throws IOException

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

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

ENTRY_CREATE - запись создана или перемещена в каталог
ENTRY_DELETE - запись удалена или перемещена из каталога
ENTRY_MODIFY - запись в каталоге изменена

context для этих событий — относительный путь между каталогом, на который указывает этот путь, и путём, указывающим на созданную, удалённую или изменённую запись каталога.

Набор событий может включать дополнительные события, зависящие от реализации и не определённые перечислением StandardWatchEventKinds.

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

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

Определено в:: register в интерфейсе Watchable
Параметры:: watcher - служба наблюдения, в которой регистрируется этот объект; events - события, для которых следует зарегистрировать этот объект; modifiers - модификаторы, если они есть, изменяющие способ регистрации объекта
Возвращает:: ключ, представляющий регистрацию этого объекта в указанной службе наблюдения
Выбрасывает:: UnsupportedOperationException - если указаны неподдерживаемые события или модификаторы; IllegalArgumentException - если указано недопустимое сочетание событий или модификаторов; ClosedWatchServiceException - если служба наблюдения закрыта; NotDirectoryException - если файл регистрируется для наблюдения за записями каталога, но сам файл не является каталогом (необязательное специализированное исключение); IOException - если происходит ошибка ввода-вывода

register

default WatchKey register(WatchService watcher, WatchEvent.Kind<?>... events) throws IOException

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

Вызов этого метода ведёт себя точно так же, как вызов

    register(watcher, events, new WatchEvent.Modifier[0]);

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

    Path dir = ...
    WatchService watcher = ...

    WatchKey key = dir.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY);

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

register в интерфейсе Watchable

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

Реализация по умолчанию эквивалентна для этого пути следующему:

    register(watcher, events, new WatchEvent.Modifier[0]);

Параметры:

watcher - служба наблюдения, в которой регистрируется этот объект

events - события, для которых следует зарегистрировать этот объект

Возвращает:

ключ, представляющий регистрацию этого объекта в указанной службе наблюдения

Выбрасывает:

UnsupportedOperationException - если указаны неподдерживаемые события

IllegalArgumentException - если указано недопустимое сочетание событий

ClosedWatchServiceException - если служба наблюдения закрыта

NotDirectoryException - если файл регистрируется для наблюдения за записями каталога, но сам файл не является каталогом (необязательное специализированное исключение)

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

iterator

default Iterator<Path> iterator()

Возвращает итератор по элементам имени этого пути.

Первый элемент, возвращаемый итератором, представляет элемент имени, ближайший к корню в иерархии каталогов; второй элемент — следующий по близости и так далее. Последний возвращаемый элемент — имя файла или каталога, обозначенного этим путём. Компонент root, если он присутствует, итератором не возвращается.

Определено в:: iterator в интерфейсе Iterable<Path>
Требования к реализации:: Реализация по умолчанию возвращает Iterator<Path>, который для этого пути проходит по Pathам, возвращаемым методом getName(index), где index изменяется от нуля до getNameCount() - 1 включительно.
Возвращает:: итератор по элементам имени этого пути

compareTo

int compareTo(Path other)

Лексикографически сравнивает два абстрактных пути. Порядок, определяемый этим методом, зависит от поставщика, а для поставщика по умолчанию — от платформы. Этот метод не обращается к файловой системе, и существование обоих файлов не требуется.

Этот метод нельзя использовать для сравнения путей, связанных с разными поставщиками файловых систем.

Определено в:: compareTo в интерфейсе Comparable<Path>
Параметры:: other - путь, сравниваемый с этим путём.
Возвращает:: ноль, если аргумент equal этому пути; значение меньше нуля, если этот путь лексикографически меньше аргумента; или значение больше нуля, если этот путь лексикографически больше аргумента
Выбрасывает:: ClassCastException - если пути связаны с разными поставщиками

equals

boolean equals(Object other)

Проверяет равенство этого пути указанному объекту.

Если указанный объект не является Path или является Path, связанным с другим FileSystem, метод возвращает false.

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

Этот метод соблюдает общий контракт метода Object.equals.

Переопределяет:

equals в классе Object

Параметры:

other - объект, с которым сравнивается этот объект

Возвращает:

true тогда и только тогда, когда указанный объект является Path, идентичным этому Path

См. также:

hashCode

int hashCode()

Вычисляет хэш-код этого пути.

Хэш-код основан на компонентах пути и соблюдает общий контракт метода Object.hashCode.

Переопределяет:

hashCode в классе Object

Возвращает:

значение хэш-кода этого пути

См. также:

toString

String toString()

Возвращает строковое представление этого пути.

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

В возвращаемой строке пути для разделения имён используется разделитель имён по умолчанию separator.

Переопределяет:: toString в классе Object
Возвращает:: строковое представление этого пути

© 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.base/java/nio/file/Path.html