Класс URI

java.lang.Object

java.net.URI

Все реализованные интерфейсы:: Serializable, Comparable<URI>

public final class URI extends Object implements Comparable<URI>, Serializable

Представляет ссылку на универсальный идентификатор ресурса (URI).

Помимо некоторых незначительных отклонений, описанных ниже, экземпляр этого класса представляет ссылку URI, как определено в RFC 2396: Универсальные идентификаторы ресурсов (URI): Общий синтаксис, дополненный RFC 2732: Формат буквальных адресов IPv6 в URL. Формат буквального адреса IPv6 также поддерживает scope_id. Синтаксис и использование scope_id описано здесь. Этот класс предоставляет конструкторы для создания экземпляров URI из их компонентов или путем разбора их строковых форм, методы для доступа к различным компонентам экземпляра и методы для нормализации, разрешения и относительной ссылки на экземпляры URI. Экземпляры этого класса неизменяемы.

Синтаксис и компоненты URI

На высшем уровне ссылка URI (ниже просто "URI") в строковом виде имеет синтаксис

[схема:]часть-специфичная-для-схемы[#фрагмент]

где квадратные скобки [...] обозначают необязательные компоненты, а символы : и # обозначают сами себя.

Абсолютный URI указывает схему; URI, который не является абсолютным, называется относительным. URI также классифицируются в зависимости от того, являются ли они непрозрачными или иерархическими.

Непрозрачный URI — это абсолютный URI, у которого часть, специфичная для схемы, не начинается с символа косой черты ('/'). Непрозрачные URI не подлежат дальнейшему разбору. Некоторые примеры непрозрачных URI:

mailto:java-net@www.example.com

news:comp.lang.java

urn:isbn:096139210x

Иерархический URI — это либо абсолютный URI, у которого часть, специфичная для схемы, начинается с символа косой черты, либо относительный URI, то есть URI, который не указывает схему. Некоторые примеры иерархических URI:

http://example.com/languages/java/
sample/a/index.html#28
../../demo/b/index.html
file:///~/calendar

Иерархический URI подлежит дальнейшему разбору в соответствии с синтаксисом

[схема:][//авторитет][путь][?запрос][#фрагмент]

где символы :, /, ? и # обозначают сами себя. Часть URI, специфичная для схемы иерархического URI, состоит из символов между компонентами схемы и фрагмента.

Компонент авторитета иерархического URI, если он указан, является либо базированным на сервере, либо базированным на реестре. Серверный авторитет разбирается в соответствии с привычным синтаксисом

[информация-пользователя@]хост[:порт]

где символы @ и : обозначают сами себя. Почти все схемы URI, которые используются в настоящее время, основаны на сервере. Компонент авторитета, который не разбирается таким образом, считается базированным на реестре.

Компонент пути иерархического URI называется абсолютным, если он начинается с символа косой черты ('/'); в противном случае он относительный. Путь иерархического URI, который является либо абсолютным, либо указывает на авторитет, всегда является абсолютным.

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

Описание компонентов URI:схема,часть-специфичная-для-схемы,авторитет,информация-пользователя,хост,порт,путь,запрос,фрагмент
Компонент	Тип
схема	`String`
часть-специфичная-для-схемы	`String`
авторитет	`String`
информация-пользователя	`String`
хост	`String`
порт	`int`
путь	`String`
запрос	`String`
фрагмент	`String`

В данном экземпляре любой конкретный компонент либо неопределен, либо определен с конкретным значением. Неопределенные строковые компоненты представлены null, а неопределенные целочисленные компоненты — -1. Строковый компонент может быть определен со значением пустой строки; это не эквивалентно тому, что этот компонент не определен.

Определение того, определен ли конкретный компонент в экземпляре или нет, зависит от типа представляемого URI. Абсолютный URI имеет компонент схемы. Непрозрачный URI имеет схему, часть, специфичную для схемы, и, возможно, фрагмент, но не имеет других компонентов. Иерархический URI всегда имеет путь (хотя он может быть пустым) и часть, специфичную для схемы (которая, по крайней мере, содержит путь), и может иметь любые другие компоненты. Если компонент авторитета присутствует и основан на сервере, то компонент хоста будет определен, а компоненты информации пользователя и порта могут быть определены.

Операции с экземплярами URI

Основными операциями, поддерживаемыми этим классом, являются нормализация, разрешение и относительная ссылка.

Нормализация — это процесс удаления ненужных "." и ".." сегментов из компонента пути иерархического URI. Каждый "." сегмент просто удаляется. ".." сегмент удаляется только в том случае, если ему предшествует не-".." сегмент. Нормализация не оказывает влияния на непрозрачные URI.

Разрешение — это процесс разрешения одного URI по отношению к другому, базовому URI. Результирующий URI конструируется из компонентов обоих URI способом, указанным в RFC 2396, используя компоненты базового URI для тех, которые не указаны в оригинале. Для иерархических URI путь оригинала разрешается по отношению к пути базы и затем нормализуется. Результат, например, разрешения

sample/a/index.html#28 (1)

по отношению к базовому URI http://example.com/languages/java/ — это результирующий URI

http://example.com/languages/java/sample/a/index.html#28

Разрешение относительного URI

../../demo/b/index.html (2)

по отношению к этому результату, в свою очередь, дает

http://example.com/languages/java/demo/b/index.html

Поддерживается разрешение как абсолютных, так и относительных URI, а также абсолютных и относительных путей в случае иерархических URI. Разрешение URI file:///~calendar по отношению к любому другому URI просто возвращает исходный URI, так как он является абсолютным. Разрешение относительного URI (2) выше по отношению к относительному базовому URI (1) дает нормализованный, но все же относительный URI

demo/b/index.html

Относительная ссылка, наконец, — обратная операция разрешению: для любых двух нормализованных URI u и v,

u.relativize(u.resolve(v)).equals(v) и
u.resolve(u.relativize(v)).equals(v) .

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

http://example.com/languages/java/sample/a/index.html#28

по отношению к базовому URI

http://example.com/languages/java/

дает относительный URI sample/a/index.html#28.

Категории символов

RFC 2396 точно определяет, какие символы разрешены в различных компонентах ссылки URI. Ниже приведены следующие категории, большинство из которых взяты из этого спецификации, используемые для описания этих ограничений:

Описание категорий alpha,digit,alphanum,unreserved,punct,reserved,escaped,и other
Категория	Описание
alpha	Символы US-ASCII букв, `'A'` по `'Z'` и `'a'` по `'z'`
digit	Символы US-ASCII десятичных цифр, `'0'` по `'9'`
alphanum	Все символы alpha и digit
unreserved	Все символы alphanum вместе с символами в строке `"_-!.~'()*"`
punct	Символы в строке `",;:$&+="`
reserved	Все символы punct вместе с символами в строке `"?/[]@"`
escaped	Экранированные октеты, то есть тройки, состоящие из символа процента (`'%'`) и двух шестнадцатеричных цифр (`'0'`-`'9'`, `'A'`-`'F'`, и `'a'`-`'f'`).
other	Символы Unicode, которые не находятся в наборе символов US-ASCII, не являются управляющими символами (в соответствии с методом `Character.isISOControl`) и не являются пробельными символами (в соответствии с методом `Character.isSpaceChar`) (Отклонение от RFC 2396, который ограничен US-ASCII)

Набор всех допустимых символов URI состоит из unreserved, reserved, escaped и other символов.

Экранированные октеты, кавычки, кодирование и декодирование

RFC 2396 разрешает появление экранированных октетов в компонентах информация-пользователя, путь, запрос и фрагмент. Экранирование служит двум целям в URI:

Для кодирования символов, не являющихся US-ASCII, когда URI должен строго соответствовать RFC 2396, не содержать символов other.
Для цитирования символов, которые в противном случае являются недопустимыми в компоненте. Компоненты информация-пользователя, путь, запрос и фрагмент незначительно отличаются по тому, какие символы считаются допустимыми и недопустимыми.

Эти цели обслуживаются в этом классе тремя взаимосвязанными операциями:

Символ кодируется путем замены его на последовательность эскейп-октетов, которые представляют этот символ в наборе символов UTF-8. Например, символ евро (€) кодируется как "%E2%82%AC". (Отклонение от RFC 2396, который не определяет какой-либо конкретный набор символов.)
Недопустимый символ цитируется просто путем его кодирования. Например, пробел цитируется путем замены его на "%20". UTF-8 содержит US-ASCII, поэтому для символов US-ASCII это преобразование имеет точно такой же эффект, как и требуется RFC 2396.
Последовательность эскейп-октетов декодируется путем замены ее на последовательность символов, которую она представляет в наборе символов UTF-8. UTF-8 содержит US-ASCII, поэтому декодирование имеет эффект отмены цитирования любых цитируемых символов US-ASCII, а также декодирования любых символов, не являющихся US-ASCII. Если при декодировании эскейп-октетов возникает ошибка декодирования, то ошибочные октеты заменяются на '\uFFFD', символ замены Юникода.

Эти операции доступны в конструкторах и методах этого класса следующим образом:

Конструктор с одним аргументом (single-argument constructor) требует цитирования всех недопустимых символов в своем аргументе и сохраняет все эскейп-октеты и другие присутствующие символы.
Многоаргументные конструкторы (multi-argument constructors) цитируют недопустимые символы в соответствии с требованиями компонентов, в которых они появляются. Символ процента ('%') всегда цитируется этими конструкторами. Любые другие символы сохраняются.
Методы getRawUserInfo, getRawPath, getRawQuery, getRawFragment, getRawAuthority и getRawSchemeSpecificPart возвращают значения соответствующих компонентов в сыром виде, не интерпретируя эскейп-октеты. Возвращаемые этими методами строки могут содержать как эскейп-октеты, так и другие символы, и не будут содержать недопустимых символов.
Методы getUserInfo, getPath, getQuery, getFragment, getAuthority и getSchemeSpecificPart декодируют все эскейп-октеты в соответствующих компонентах. Возвращаемые этими методами строки могут содержать как другие символы, так и недопустимые, но не будут содержать эскейп-октетов.
Метод toString возвращает строку URI со всеми необходимыми цитированиями, которая может содержать другие символы.
Метод toASCIIString возвращает полностью цитированную и закодированную строку URI, которая не содержит других символов.

Тождества

Для любого URI u всегда справедливо, что

new URI(u.toString()).equals(u) .

Для любого URI u, который не содержит избыточного синтаксиса, такого как два слеша перед пустым авторитетом (как в file:///tmp/ ) или двоеточие после имени хоста, но без порта (как в http://www.example.com: ), и который не кодирует символы, кроме тех, которые необходимо цитировать, также выполняются следующие тождества:

     new URI(u.getScheme(),
             u.getSchemeSpecificPart(),
             u.getFragment())
     .equals(u)

во всех случаях,

     new URI(u.getScheme(),
             u.getAuthority(),
             u.getPath(), u.getQuery(),
             u.getFragment())
     .equals(u)

если u иерархический, и

     new URI(u.getScheme(),
             u.getUserInfo(), u.getHost(), u.getPort(),
             u.getPath(), u.getQuery(),
             u.getFragment())
     .equals(u)

если u иерархический и имеет либо нет авторитета, либо авторитет на основе сервера.

URI, URL и URN

URI — это универсальный идентификатор ресурса, а URL — универсальный локатор ресурса. Поэтому, абстрактно говоря, каждый URL является URI, но не каждый URI является URL. Это связано с тем, что существует ещё одна подкатегория URI — универсальные имена ресурсов (URN), которые называют ресурсы, но не указывают, как их найти. URI mailto, news, и isbn — примеры URN.

Понятийное различие между URI и URL отражается в различиях между этим классом и классом URL.

Экземпляр этого класса представляет URI-ссылку в синтаксическом смысле, определенном RFC 2396. URI может быть абсолютным или относительным. Строка URI анализируется в соответствии с общим синтаксисом без учета схемы, если таковая имеется. Никакой поиск хоста, если таковой имеется, не выполняется, и никакой обработчик потока, зависящий от схемы, не создается. Равенство, хэширование и сравнение определяются строго в терминах символьного содержимого экземпляра. Другими словами, экземпляр URI — это не более чем структурированная строка, которая поддерживает синтаксические, независимые от схемы операции сравнения, нормализации, разрешения и относительного выражения.

Экземпляр класса URL, напротив, представляет синтаксические компоненты URL вместе с некоторыми данными, необходимыми для доступа к ресурсу, который он описывает. URL должен быть абсолютным, то есть он всегда должен указывать схему. Строка URL анализируется в соответствии со своей схемой. Обработчик потока всегда устанавливается для URL, и, фактически, создать экземпляр URL для схемы, для которой нет обработчика, невозможно. Равенство и хэширование зависят как от схемы, так и от интернет-адреса хоста, если таковой имеется; сравнение не определено. Другими словами, URL — это структурированная строка, которая поддерживает синтаксическую операцию разрешения, а также сетевые операции ввода-вывода для поиска хоста и открытия соединения с указанным ресурсом.

Примечание API:

Приложения, работающие с путями к файлам и URI файлов, должны быть очень внимательны при использовании соответствующих методов для преобразования между ними. Метод-фабрика Path.of(URI) и конструктор File(URI) могут использоваться для создания объектов Path или File из URI файла. Path.toUri() и File.toURI() могут использоваться для создания URI из пути к файлу. Приложения никогда не должны пытаться создавать, парсить или разрешать URI из непосредственного строкового представления экземпляра File или Path.

Некоторые компоненты URL или URI, такие как userinfo, могут быть использованы для создания вводящих в заблуждение URL или URI. Приложения, которые работают с URL или URI, должны учитывать рекомендации, указанные в RFC3986, Раздел 7, Рассмотрение вопросов безопасности.

С:

1.4

См. также:

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

Конструктор	Описание
`URI(String str)`	Создаёт URI путём разбора заданной строки.
`URI(String scheme, String ssp, String fragment)`	Создаёт URI из заданных компонентов.
`URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment)`	Создаёт иерархический URI из заданных компонентов.
`URI(String scheme, String host, String path, String fragment)`	Создаёт иерархический URI из заданных компонентов.
`URI(String scheme, String authority, String path, String query, String fragment)`	Создаёт иерархический URI из заданных компонентов.

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

Модификатор и тип	Метод	Описание
`int`	`compareTo(URI that)`	Сравнивает этот URI с другим объектом, который должен быть URI.
`static URI`	`create(String str)`	Создаёт URI путём разбора заданной строки.
`boolean`	`equals(Object ob)`	Проверяет равенство этого URI с другим объектом.
`String`	`getAuthority()`	Возвращает декодированный компонент authority этого URI.
`String`	`getFragment()`	Возвращает декодированный компонент fragment этого URI.
`String`	`getHost()`	Возвращает компонент host этого URI.
`String`	`getPath()`	Возвращает декодированный компонент path этого URI.
`int`	`getPort()`	Возвращает номер порта этого URI.
`String`	`getQuery()`	Возвращает декодированный компонент query этого URI.
`String`	`getRawAuthority()`	Возвращает необработанный компонент authority этого URI.
`String`	`getRawFragment()`	Возвращает необработанный компонент fragment этого URI.
`String`	`getRawPath()`	Возвращает необработанный компонент path этого URI.
`String`	`getRawQuery()`	Возвращает необработанный компонент query этого URI.
`String`	`getRawSchemeSpecificPart()`	Возвращает необработанную часть URI, специфичную для схемы.
`String`	`getRawUserInfo()`	Возвращает необработанный компонент user-information этого URI.
`String`	`getScheme()`	Возвращает компонент scheme этого URI.
`String`	`getSchemeSpecificPart()`	Возвращает декодированную часть URI, специфичную для схемы.
`String`	`getUserInfo()`	Возвращает декодированный компонент user-information этого URI.
`int`	`hashCode()`	Возвращает хеш-код для этого URI.
`boolean`	`isAbsolute()`	Указывает, является ли этот URI абсолютным.
`boolean`	`isOpaque()`	Указывает, является ли этот URI непрозрачным.
`URI`	`normalize()`	Нормализует путь этого URI.
`URI`	`parseServerAuthority()`	Пытается разобрать компонент authority этого URI (если он определён) на компоненты user-information, host и port.
`URI`	`relativize(URI uri)`	Относительно заданного URI к этому URI.
`URI`	`resolve(String str)`	Создаёт новый URI путём разбора заданной строки и последующего разрешения по отношению к этому URI.
`URI`	`resolve(URI uri)`	Разрешает заданный URI по отношению к этому URI.
`String`	`toASCIIString()`	Возвращает содержимое этого URI как строку US-ASCII.
`String`	`toString()`	Возвращает содержимое этого URI как строку.
`URL`	`toURL()`	Создаёт URL из этого URI.

Методы, объявленные в классе java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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

URI

public URI(String str) throws URISyntaxException

Создаёт URI путём разбора заданной строки.

Этот конструктор анализирует заданную строку точно так, как указано в грамматике в RFC 2396, Приложение A, за исключением следующих отличий:

Разрешена пустая компонента authority, при условии, что за ней следует непустой путь, компонент запроса или фрагмент. Это позволяет парсить URI, такие как "file:///foo/bar", что, похоже, и предполагалось в RFC 2396, хотя грамматика этого не допускает. Если компонент authority пустой, то компоненты user-information, host и port не определены.
Разрешены пустые относительные пути; это, похоже, и предполагалось в RFC 2396, хотя грамматика этого не допускает. Основным следствием этого отличия является то, что автономный фрагмент, такой как "#foo", анализируется как относительный URI с пустым путём и указанным фрагментом, и может быть полезно разрешён относительно базового URI.
IPv4-адреса в компонентах host парсятся строго, как указано в RFC 2732: каждый элемент адреса с точками должен содержать не более трёх десятичных цифр. Каждый элемент дополнительно ограничен значением, не превышающим 255.
Имена хостов в компонентах host, состоящие только из одного доменного метки, разрешается начинать с символа alphanum. Это, похоже, предполагалось в RFC 2396 разделе 3.2.2, хотя грамматика этого не допускает. Последствием этого отличия является то, что компонент authority иерархического URI, такого как s://123, будет анализироваться как серверная authority.
IPv6-адреса разрешены для компонента host. IPv6-адрес должен быть заключён в квадратные скобки ('[' и ']') как указано в RFC 2732. Сам IPv6-адрес должен анализироваться в соответствии с RFC 2373. IPv6-адреса дополнительно ограничены описанием не более шестнадцати байтов адресной информации, ограничение, подразумеваемое в RFC 2373, но не выражаемое в грамматике.
Символы из категории other разрешены там, где RFC 2396 разрешает escaped октеты, то есть в компонентах user-information, path, query и fragment, а также в компоненте authority, если authority регистровая. Это позволяет URI содержать символы Unicode, выходящие за рамки набора символов US-ASCII.

Параметры:: str - Строка, подлежащая разбору в URI
Исключения:: NullPointerException - Если str является null; URISyntaxException - Если заданная строка нарушает RFC 2396, как дополнено вышеуказанными отличиями

URI

public URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment) throws URISyntaxException

Создаёт иерархический URI из заданных компонентов.

Если задан схему, то путь, если он также задан, должен быть пустым или начинаться с символа косой черты ('/'). В противном случае компонент нового URI может быть оставлен неопределённым, передав null для соответствующего параметра или, в случае параметра port, передав -1.

Этот конструктор сначала строит строку URI из заданных компонентов в соответствии с правилами, указанными в RFC 2396, раздел 5.2, шаг 7:

Изначально строка результата пуста.
Если задана схема, то она добавляется к результату, за которой следует двоеточие (':').
Если заданы user information, хост или порт, то добавляется строка "//".
Если задана user information, то она добавляется, за которой следует символ коммерческого-at ('@'). Любой символ, не входящий в категории unreserved, punct, escaped или other, подлежит цитированию.
Если задан хост, то он добавляется. Если хост является литеральным IPv6-адресом, но не заключён в квадратные скобки ('[' и ']'), то добавляются квадратные скобки.
Если задан номер порта, то добавляется двоеточие (':'), за которым следует номер порта в десятичном формате.
Если задан путь, то он добавляется. Любой символ, не входящий в категории unreserved, punct, escaped или other, и не равный символу косой черты ('/') или символу коммерческого-at ('@'), подлежит цитированию.
Если задан запрос, то добавляется вопросительный знак ('?'), за которым следует запрос. Любой символ, не являющийся законным символом URI, подлежит цитированию.
Наконец, если задан фрагмент, то добавляется символ решётки ('#'), за которым следует фрагмент. Любой символ, не являющийся законным символом URI, подлежит цитированию.

Полученная строка URI затем анализируется так, как будто вызывается конструктор URI(String), а затем вызывается метод parseServerAuthority() для результата; это может вызвать исключение URISyntaxException.

Параметры:: scheme - Имя схемы; userInfo - Имя пользователя и информация об авторизации; host - Имя хоста; port - Номер порта; path - Путь; query - Запрос; fragment - Фрагмент
Исключения:: URISyntaxException - Если и схема, и путь заданы, но путь относительный, если строка URI, построенная из заданных компонентов, нарушает RFC 2396, или если компонент authority строки присутствует, но не может быть проанализирован как серверная authority

URI

public URI(String scheme, String authority, String path, String query, String fragment) throws URISyntaxException

Создаёт иерархический URI из заданных компонентов.

Компонент может быть оставлен неопределённым, передав null.

Этот конструктор работает так, как будто вызывается конструктор с семью аргументами следующим образом:

new URI(scheme, null, host, -1, path, null, fragment);

Параметры:: scheme - Имя схемы; authority - Authority; path - Путь; query - Запрос; fragment - Фрагмент
Исключения:: URISyntaxException - Если строка URI, построенная из заданных компонентов, нарушает RFC 2396

URI

public URI(String scheme, String host, String path, String fragment) throws URISyntaxException

Создаёт иерархический URI из заданных компонентов.

Компонент может быть оставлен неопределённым, передав null.

Этот удобный конструктор работает так, как будто вызывается конструктор с семью аргументами следующим образом:

new URI(scheme, null, host, -1, path, null, fragment);

Параметры:: scheme - Имя схемы; host - Имя хоста; path - Путь; fragment - Фрагмент
Исключения:: URISyntaxException - Если строка URI, построенная из заданных компонентов, нарушает RFC 2396

URI

public URI(String scheme, String ssp, String fragment) throws URISyntaxException

Создаёт URI из заданных компонентов.

Компонент может быть опущен, передав null.

Этот конструктор сначала строит URI в строковом формате, используя заданные компоненты следующим образом:

Изначально, строка результата пуста.
Если схема задана, то она добавляется к результату, за которой следует символ двоеточия (':').
Если задана схема-специфическая часть, то она добавляется. Любой символ, который не является допустимым символом URI, квотируется.
Наконец, если задан фрагмент, то к строке добавляется символ решётки ('#'), за которым следует фрагмент. Любой символ, который не является допустимым символом URI, квотируется.

Результирующая строка URI затем анализируется для создания нового экземпляра URI так, как если бы был вызван конструктор URI(String); это может вызвать исключение URISyntaxException.

Parameters:: scheme - Имя схемы; ssp - Часть, специфичная для схемы; fragment - Фрагмент
Throws:: URISyntaxException - Если строка URI, построенная из заданных компонентов, нарушает RFC 2396

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

create

public static URI create(String str)

Создаёт URI, проанализировав заданную строку.

Этот удобный фабричный метод работает так, как если бы был вызван конструктор URI(String); любое исключение URISyntaxException, сгенерированное конструктором, перехватывается и оборачивается в новый объект IllegalArgumentException, который затем выбрасывается.

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

Parameters:: str - Строка, подлежащая анализу в URI
Returns:: Новый URI
Throws:: NullPointerException - Если str является null; IllegalArgumentException - Если заданная строка нарушает RFC 2396

parseServerAuthority

public URI parseServerAuthority() throws URISyntaxException

Пытается разобрать компонент authority этого URI, если он определён, на компоненты user-information, host и port.

Если компонент authority этого URI уже распознан как серверный, то он уже будет разобран на компоненты user-information, host и port. В этом случае, или если у этого URI нет компонента authority, этот метод просто возвращает этот URI.

В противном случае этот метод ещё раз пытается разобрать компонент authority на компоненты user-information, host и port и выбрасывает исключение, описывающее причину, по которой компонент authority не может быть проанализирован таким образом.

Этот метод предоставляется потому, что общий синтаксис URI, указанный в RFC 2396, не всегда может отличить неправильно сформированный серверный authority от законного registry-based authority. Поэтому он должен рассматривать некоторые случаи первого как случаи второго. Компонент authority в строке URI "//foo:bar", например, не является законным серверным authority, но является законным как registry-based authority.

Во многих распространённых ситуациях, например, при работе с URI, которые известны как URN или URL, иерархические URI, используемые, всегда будут server-based. Поэтому они должны быть проанализированы как таковые или обработаны как ошибка. В этих случаях утверждение, такое как

URI u = new URI(str).parseServerAuthority();

может использоваться для обеспечения того, что u всегда относится к URI, который, если у него есть компонент authority, имеет серверный authority с правильными компонентами user-information, host и port. Вызов этого метода также гарантирует, что если authority не может быть проанализирован таким образом, то соответствующее диагностическое сообщение может быть выведено на основе исключения, которое будет выброшено.

Returns:: URI, чьё поле authority было проанализировано как серверный authority
Throws:: URISyntaxException - Если компонент authority этого URI определён, но не может быть проанализирован как серверный authority в соответствии с RFC 2396

normalize

public URI normalize()

Нормализует путь этого URI.

Если этот URI является opaque или если его путь уже находится в нормальной форме, то возвращается этот URI. В противном случае создаётся новый URI, идентичный этому URI, за исключением того, что его путь вычисляется путём нормализации пути этого URI способом, согласованным с RFC 2396, раздел 5.2, шаг 6, подшаги с c по f; то есть:

Все "." сегменты удаляются.
Если ".." сегмент предшествует не-".." сегменту, то оба этих сегмента удаляются. Этот шаг повторяется до тех пор, пока он больше не применим.
Если путь является относительным и если его первый сегмент содержит символ двоеточия (':'), то впереди добавляется "." сегмент. Это предотвращает относительный URI с путём, таким как "a:b/c/d", от дальнейшего переразбора как opaque URI со схемой "a" и схемо-специфической частью "b/c/d". (Отклонение от RFC 2396)

Нормализованный путь будет начинаться с одного или нескольких ".." сегментов, если было недостаточно не-".." сегментов, предшествующих им, чтобы позволить их удаление. Нормализованный путь будет начинаться с "." сегмента, если он был вставлен на шаге 3 выше. В противном случае нормализованный путь не будет содержать "." или ".." сегменты.

Returns:: URI, эквивалентный этому URI, но чья путь находится в нормальной форме

resolve

public URI resolve(URI uri)

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

Если заданный URI уже абсолютный или этот URI opaque, то возвращается заданный URI.

Если компонент fragment заданного URI определён, его компонент path пуст, и компоненты scheme, authority и query не определены, то возвращается URI с заданным fragment, но со всеми другими компонентами равными компонентам этого URI. Это позволяет URI, представляющему автономную ссылку на фрагмент, например, "#foo", быть полезно разрешённым относительно базового URI.

В противном случае этот метод строит новый иерархический URI, согласованный с RFC 2396, раздел 5.2; то есть:

Создаётся новый URI со схемой этого URI и компонентами query и fragment заданного URI.
Если у заданного URI есть компонент authority, то authority и path нового URI берутся из заданного URI.
В противном случае компонент authority нового URI копируется из этого URI, а его путь вычисляется следующим образом:
1. Если у заданного URI путь абсолютный, то путь нового URI берётся из заданного URI.
2. В противном случае путь заданного URI относительный, и поэтому путь нового URI вычисляется путём разрешения пути заданного URI относительно пути этого URI. Это делается путём конкатенации всех сегментов пути этого URI, за исключением последнего, если таковые имеются, с путём заданного URI, а затем нормализации результата, как если бы был вызван метод normalize.

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

Parameters:: uri - URI, подлежащий разрешению относительно этого URI
Returns:: Результат URI
Throws:: NullPointerException - Если uri является null

resolve

public URI resolve(String str)

Строит новый URI, проанализировав заданную строку, а затем разрешив её относительно этого URI.

Этот удобный метод работает так, как если бы вызов был эквивалентен вычислению выражения resolve(URI.create(str)).

Parameters:: str - Строка, подлежащая анализу в URI
Returns:: Результат URI
Throws:: NullPointerException - Если str является null; IllegalArgumentException - Если заданная строка нарушает RFC 2396

relativize

public URI relativize(URI uri)

Относительзирует заданный URI относительно этого URI.

Относительзирование заданного URI относительно этого URI вычисляется следующим образом:

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

Parameters:: uri - URI, подлежащий относительзированию относительно этого URI
Returns:: Результат URI
Throws:: NullPointerException - Если uri является null

toURL

public URL toURL() throws MalformedURLException

Создаёт URL из этого URI.

Этот метод-удобство работает так, как если бы вызов был эквивалентен вычислению выражения new URL(this.toString()) после предварительной проверки, является ли этот URI абсолютным.

Возвращает:: URL, созданный из этого URI
Выбрасывает:: IllegalArgumentException - если этот URL не абсолютный; MalformedURLException - если обработчик протокола для URL не был найден или произошла какая-либо другая ошибка при построении URL

getScheme

public String getScheme()

Возвращает компонент схемы этого URI.

Компонент схемы URI, если определён, содержит только символы в категории alphanum и в строке "-.+". Схема всегда начинается с символа alpha.

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

Возвращает:: Компонент схемы этого URI или null если схема не определена

isAbsolute

public boolean isAbsolute()

Указывает, является ли этот URI абсолютным.

URI является абсолютным тогда и только тогда, когда он имеет компонент схемы.

Возвращает:: true если и только если этот URI является абсолютным

isOpaque

public boolean isOpaque()

Указывает, является ли этот URI непрозрачным.

URI является непрозрачным, если и только если он является абсолютным, а его часть, специфичная для схемы, не начинается с символа косой черты ('/'). Непрозрачный URI имеет схему, часть, специфичную для схемы, и, возможно, фрагмент; все остальные компоненты не определены.

Возвращает:: true если и только если этот URI является непрозрачным

getRawSchemeSpecificPart

public String getRawSchemeSpecificPart()

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

Часть URI, специфичная для схемы, содержит только допустимые символы URI.

Возвращает:: Исходная часть URI, специфичная для схемы (никогда null)

getSchemeSpecificPart

public String getSchemeSpecificPart()

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

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

Возвращает:: Декодированная часть URI, специфичная для схемы (никогда null)

getRawAuthority

public String getRawAuthority()

Возвращает исходный компонент authority этого URI.

Компонент authority URI, если определён, содержит только символ коммерческого а ('@') и символы в категориях unreserved, punct, escaped и other. Если authority основан на сервере, то он дополнительно ограничен наличием валидных компонентов user-information, host и port.

Возвращает:: Исходный компонент authority этого URI, или null если authority не определён

getAuthority

public String getAuthority()

Возвращает декодированный компонент authority этого URI.

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

Возвращает:: Декодированный компонент authority этого URI, или null если authority не определён

getRawUserInfo

public String getRawUserInfo()

Возвращает исходный компонент user-information этого URI.

Компонент user-information URI, если определён, содержит только символы в категориях unreserved, punct, escaped и other.

Возвращает:: Исходный компонент user-information этого URI, или null если user information не определён

getUserInfo

public String getUserInfo()

Возвращает декодированный компонент user-information этого URI.

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

Возвращает:: Декодированный компонент user-information этого URI, или null если user information не определён

getHost

public String getHost()

Возвращает компонент host этого URI.

Компонент host URI, если определён, будет иметь один из следующих форматов:

Имя домена, состоящее из одного или нескольких меток, разделённых точками ('.'), необязательно заканчивающихся точкой. Каждая метка состоит из символов alphanum и дефисов ('-'), хотя дефисы никогда не встречаются в качестве первого или последнего символа метки. Правая метка домена, состоящего из двух или более меток, начинается с символа alpha.
Четырёхточечный IPv4-адрес в формате цифра+.цифра+.цифра+.цифра+, где ни одна последовательность цифр не длиннее трёх символов и ни одна последовательность не имеет значения больше 255.
IPv6-адрес в квадратных скобках ('[' и ']') и состоящий из шестнадцатеричных цифр, двоеточий (':') и, возможно, вложенного IPv4-адреса. Полный синтаксис IPv6-адресов указан в RFC 2373: IPv6 Addressing Architecture.

Компонент host URI не может содержать закодированных октетов, поэтому этот метод не выполняет никаких декодирований.

Возвращает:: Компонент host этого URI, или null если host не определён

getPort

public int getPort()

Возвращает номер порта этого URI.

Компонент порта URI, если определён, представляет собой целое неотрицательное число.

Возвращает:: Компонент порта этого URI, или -1 если порт не определён

getRawPath

public String getRawPath()

Возвращает исходный компонент path этого URI.

Компонент path URI, если определён, содержит только символ косой черты ('/'), символ коммерческого а ('@') и символы в категориях unreserved, punct, escaped и other.

Возвращает:: Компонент path этого URI, или null если path не определён

getPath

public String getPath()

Возвращает декодированный компонент path этого URI.

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

Возвращает:: Декодированный компонент path этого URI, или null если path не определён

getRawQuery

public String getRawQuery()

Возвращает исходный компонент query этого URI.

Компонент query URI, если определён, содержит только допустимые символы URI.

Возвращает:: Исходный компонент query этого URI, или null если query не определён

getQuery

public String getQuery()

Возвращает декодированный компонент query этого URI.

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

Возвращает:: Декодированный компонент query этого URI, или null если query не определён

getRawFragment

public String getRawFragment()

Возвращает исходный компонент fragment этого URI.

Компонент fragment URI, если определён, содержит только допустимые символы URI.

Возвращает:: Исходный компонент fragment этого URI, или null если fragment не определён

getFragment

public String getFragment()

Возвращает декодированный компонент fragment этого URI.

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

Возвращает:: Декодированный компонент fragment этого URI, или null если fragment не определён

equals

public boolean equals(Object ob)

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

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

Для того, чтобы два URI считались равными, требуется, чтобы оба были либо неявными, либо иерархическими. Их схемы должны быть либо обе не определены, либо равны без учета регистра. Их фрагменты должны быть либо обе не определены, либо равны.

Для того, чтобы два неявных URI считались равными, их специфические для схемы части должны быть равны.

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

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

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

Overrides:

equals в классе Object

Parameters:

ob - Объект, с которым должен быть сравнен этот объект

Returns:

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

See Also:

hashCode

public int hashCode()

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

Overrides:

hashCode в классе Object

Returns:

Значение хэш-кода для этого URI

See Also:

compareTo

public int compareTo(URI that)

Сравнивает этот URI с другим объектом, который должен быть URI.

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

Порядок URI определяется следующим образом:

Два URI с различными схемами упорядочиваются в соответствии с порядком их схем, без учета регистра.
Иерархический URI считается меньше неявного URI с идентичной схемой.
Два неявных URI с идентичными схемами упорядочиваются в соответствии с порядком их частей, специфичных для схемы.
Два неявных URI с идентичными схемами и частями, специфичными для схемы, упорядочиваются в соответствии с порядком их фрагментов.
Два иерархических URI с идентичными схемами упорядочиваются в соответствии с порядком их компонентов авторитета:
- Если оба компонента авторитета основаны на сервере, то URI упорядочиваются в соответствии с их компонентами информации о пользователе; если эти компоненты идентичны, то URI упорядочиваются в соответствии с порядком их хостов, без учета регистра; если хосты идентичны, то URI упорядочиваются в соответствии с порядком их портов.
- Если один или оба компонента авторитета основаны на реестре, то URI упорядочиваются в соответствии с порядком их компонентов авторитета.
В конечном счете, два иерархических URI с идентичными схемами и компонентами авторитета упорядочиваются в соответствии с порядком их путей; если их пути идентичны, то они упорядочиваются в соответствии с порядком их запросов; если запросы идентичны, то они упорядочиваются в соответствии с порядком их фрагментов.

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

Specified by:: compareTo в интерфейсе Comparable<URI>
Parameters:: that - Объект, с которым должен быть сравнен этот URI
Returns:: Отрицательное целое число, ноль или положительное целое число, если этот URI меньше, равен или больше заданного URI
Throws:: ClassCastException - Если заданный объект не является URI

toString

public String toString()

Возвращает содержимое этого URI в виде строки.

Если этот URI был создан вызовом одного из конструкторов в этом классе, то возвращается строка, эквивалентная исходной строке ввода, или строка, вычисленная из исходных компонентов, в зависимости от ситуации. В противном случае этот URI был создан путем нормализации, разрешения или релятивизации, поэтому строка строится из компонентов этого URI в соответствии с правилами, указанными в RFC 2396, раздел 5.2, шаг 7.

Overrides:: toString в классе Object
Returns:: Строковая форма этого URI

toASCIIString

public String toASCIIString()

Возвращает содержимое этого URI в виде строки US-ASCII.

Если этот URI не содержит символов в категории other, то вызов этого метода вернет то же значение, что и вызов метода toString. В противном случае этот метод работает так, как если бы он вызывал этот метод, а затем выполнял кодирование результата.

Returns:: Строковая форма этого URI, закодированная в соответствии с потребностями, чтобы она содержала только символы набора символов US-ASCII

© 1993, 2021, 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/17/docs/api/java.base/java/net/URI.html