Интерфейс Путь

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

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

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

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

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

static Path of(URI uri)

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

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

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

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

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

, при условии, что исходный Path, URI и новый Path созданы в (возможно, различных вызовах) одной виртуальной машине Java. Гарантии других поставщиков зависят от конкретной реализации и поэтому не определены.

FileSystem getFileSystem()

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

boolean isAbsolute()

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

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

Path getRoot()

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

Path getFileName()

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

Path getParent()

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

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

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

 subpath(0, getNameCount()-1);
 

int getNameCount()

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

Path getName(int index)

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

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

Path subpath(int beginIndex, int endIndex)

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

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

boolean startsWith(Path other)

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

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

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

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

default boolean startsWith(String other)

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

boolean endsWith(Path other)

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

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

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

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

default boolean endsWith(String other)

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

Path normalize()

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

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

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

Path resolve(Path other)

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

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

default Path resolve(String other)

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

default Path resolveSibling(Path other)

Резолвирует заданный путь относительно родительского пути этого пути. Это полезно, когда имя файла нужно заменить другим именем файла. Например, предположим, что разделитель имён - "/" и путь представляет "dir1/dir2/foo", тогда вызов этого метода со строкой "bar" приведёт к результирующему пути "dir1/dir2/bar". Если у этого пути нет родительского пути, или other является absolute, то этот метод возвращает other. Если other является пустым путём, то этот метод возвращает родительский путь этого пути, или, если у этого пути нет родительского пути, пустой путь.

default Path resolveSibling(String other)

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

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".

URI toUri()

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

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

В случае стандартного поставщика, URI является иерархическим с path компонентой, которая абсолютна. Компоненты запроса и фрагмента не определены. Определённость компоненты авторизации зависит от реализации. Нет гарантии, что URI может быть использован для построения java.io.File. В частности, если этот путь представляет собой UNC-путь, то имя UNC-сервера может быть закодировано в компоненте авторизации результирующего URI. В случае стандартного поставщика и если файл существует и можно определить, что это каталог, то результирующий URI будет заканчиваться слешем.

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

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

пока оригинальный Path, URI и новый Path были созданы (возможно, в разных вызовах) в одной и той же виртуальной машине Java. Гарантии других поставщиков зависят от поставщика и поэтому не определены.

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

Path toAbsolutePath()

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

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

Path toRealPath(LinkOption... options) throws IOException

Возвращает фактический путь существующего файла.

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

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

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

default File toFile()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

default Iterator<Path> iterator()

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

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

int compareTo(Path other)

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

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

boolean equals(Object other)

Проверяет этот путь на равенство с данным объектом.

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

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

Этот метод удовлетворяет общему контракту метода Object.equals.

int hashCode()

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

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

String toString()

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

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

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