Класс 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_ids. Синтаксис и использование scope_ids описаны здесь. Этот класс предоставляет конструкторы для создания экземпляров 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: схема, часть схемы, авторитет, информация о пользователе, хост, порт, путь, запрос, фрагмент
Компонент	Тип
схема	`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

Относительное преобразование, наконец, можно рассматривать как обратную операцию к разрешению. Пусть u — любой нормализованный абсолютный URI, заканчивающийся символом косой черты ('/'), а v — любой нормализованный относительный URI, не начинающийся с символа точки ('.') или символа косой черты ('/'). Тогда справедливо следующее утверждение:

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

Пусть u — любой нормализованный абсолютный URI, заканчивающийся символом косой черты ('/'), а v — любой нормализованный абсолютный URI. Тогда справедливо следующее утверждение:

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, не содержа то других символов.
Для кодирования символов, которые в противном случае являются недопустимыми в компоненте. Компоненты user-info, path, query и fragment немного различаются в отношении допустимых и недопустимых символов.

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

Символ кодируется, заменяя его последовательностью экранированных октетов, представляющих этот символ в наборе символов 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. Если при декодировании экранированных октетов происходит ошибка декодирования, то ошибочные октеты заменяются символом Unicode замены '\uFFFD'.

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

Конструктор с одним аргументом требует, чтобы все недопустимые символы в его аргументе были закодированы, и сохраняет любые экранированные октеты и другие символы, которые присутствуют.
Конструкторы с множеством аргументов кодируют недопустимые символы, как требуется компонентами, в которых они появляются. Символ процента ('%') всегда закодирован этими конструкторами. Все другие символы сохраняются.
Методы 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), которые называют ресурсы, но не указывают, как их найти. mailto, news и isbn URI, показанные выше, являются примерами 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, Рассмотрение вопросов безопасности.

Since:

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()`	Возвращает декодированный компонент авторизации этого URI.
`String`	`getFragment()`	Возвращает декодированный фрагмент компонента этого URI.
`String`	`getHost()`	Возвращает компонент хоста этого URI.
`String`	`getPath()`	Возвращает декодированный компонент пути этого URI.
`int`	`getPort()`	Возвращает номер порта этого URI.
`String`	`getQuery()`	Возвращает декодированный компонент запроса этого URI.
`String`	`getRawAuthority()`	Возвращает необработанный компонент авторизации этого URI.
`String`	`getRawFragment()`	Возвращает необработанный компонент фрагмента этого URI.
`String`	`getRawPath()`	Возвращает необработанный компонент пути этого URI.
`String`	`getRawQuery()`	Возвращает необработанный компонент запроса этого URI.
`String`	`getRawSchemeSpecificPart()`	Возвращает необработанную часть URI, специфичную для схемы.
`String`	`getRawUserInfo()`	Возвращает необработанный компонент информации об пользователе этого URI.
`String`	`getScheme()`	Возвращает компонент схемы этого URI.
`String`	`getSchemeSpecificPart()`	Возвращает декодированную часть URI, специфичную для схемы.
`String`	`getUserInfo()`	Возвращает декодированный компонент информации о пользователе этого URI.
`int`	`hashCode()`	Возвращает хэш-код для этого URI.
`boolean`	`isAbsolute()`	Определяет, является ли этот URI абсолютным.
`boolean`	`isOpaque()`	Определяет, является ли этот URI непрозрачным.
`URI`	`normalize()`	Нормализует путь этого URI.
`URI`	`parseServerAuthority()`	Попытка проанализировать компонент авторизации этого URI (если он определен) на компоненты информации о пользователе, хоста и порта.
`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, за исключением следующих отличий:

Разрешена пустая компонента авторизации, если за ней следует непустой путь, компонент запроса или компонент фрагмента. Это позволяет парсить URI, такие как "file:///foo/bar", что, по-видимому, является намерением RFC 2396, хотя грамматика этого не допускает. Если компонент авторизации пустой, то компоненты пользователя, хоста и порта не определены.
Разрешены пустые относительные пути; это, по-видимому, является намерением RFC 2396, хотя грамматика этого не допускает. Основным следствием этого отличия является то, что автономный фрагмент, такой как "#foo", парсится как относительный URI с пустым путём и заданным фрагментом, и может быть полезно разрешён относительно базового URI.
IPv4-адреса в компонентах хоста парсятся строго, как указано в RFC 2732: Каждый элемент адреса в формате «точка с запятой» должен содержать не более трёх десятичных цифр. Каждый элемент дополнительно ограничен значением не более 255.
Имена хостов в компонентах хоста, состоящие только из одного доменного метки, разрешается начинать с символа alphanum. По-видимому, это является намерением RFC 2396 в разделе 3.2.2, хотя грамматика этого не допускает. Следствием этого отличия является то, что компонент авторизации иерархического URI, такого как s://123, будет парситься как авторизация на основе сервера.
IPv6-адреса разрешены для компонента хоста. IPv6-адрес должен быть заключён в квадратные скобки ('[' и ']'), как указано в RFC 2732. Сам IPv6-адрес должен парситься в соответствии с RFC 2373. IPv6-адреса дополнительно ограничены описанием не более шестнадцати байтов адресной информации, ограничение, неявное в RFC 2373, но не выражаемое в грамматике.
Символы в категории other разрешены там, где RFC 2396 допускает escaped октеты, то есть в компонентах пользователя, пути, запроса и фрагмента, а также в компоненте авторизации, если авторизация основана на реестре. Это позволяет URI содержать символы Юникода, не входящие в набор символов 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:

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

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

Параметры:

scheme - Имя схемы

userInfo - Имя пользователя и информация об авторизации

host - Имя хоста

port - Номер порта

path - Путь

query - Запрос

fragment - Фрагмент

Исключения:

URISyntaxException - Если заданы как схема, так и путь, но путь является относительным, если строка URI, построенная из заданных компонентов, нарушает RFC 2396, или если компонент авторизации строки присутствует, но не может быть проанализирован как авторизация на основе сервера

Внешние спецификации

URI

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

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

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

Параметры:

scheme - Имя схемы

authority - Авторизация

path - Путь

query - Запрос

fragment - Фрагмент

Исключения:

Внешние спецификации

URI

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

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

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

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

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

Parameters:: scheme - Имя схемы; host - Имя хоста; path - Путь; fragment - Фрагмент
Throws:: 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

Попытка проанализировать компонент авторизации этого URI, если он определён, в компоненты пользовательских данных, хоста и порта.

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

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

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

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

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

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

Returns:

URI, чьё поле авторизации было обработано как авторизация на основе сервера

Throws:

URISyntaxException - Если компонент авторизации этого URI определён, но не может быть проанализирован как авторизация на основе сервера в соответствии с RFC 2396

Внешние спецификации

normalize

public URI normalize()

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

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

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

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

Returns:

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

Внешние спецификации

resolve

public URI resolve(URI uri)

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

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

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

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

Создаётся новый URI со схемой этого URI и компонентами запроса и фрагмента данного URI.
Если у данного URI есть компонент авторизации, то компонент авторизации и путь нового URI берутся из данного URI.
В противном случае компонент авторизации нового 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 являются непрозрачными, или если схемы и компоненты авторизации двух URI не идентичны, или если путь текущего URI не является префиксом пути заданного URI, то возвращается заданный URI.
В противном случае создаётся новый относительный иерархический URI с компонентами запроса и фрагмента, взятыми из заданного URI, и с компонентом пути, вычисленным путём удаления пути текущего 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 является абсолютным.

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

getScheme

public String getScheme()

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

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

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

Returns:: Компонент схемы этого URI или null, если схема не определена

isAbsolute

public boolean isAbsolute()

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

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

Returns:: true, если и только если этот URI является абсолютным

isOpaque

public boolean isOpaque()

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

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

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

getRawSchemeSpecificPart

public String getRawSchemeSpecificPart()

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

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

Returns:: Необработанная схема-специфическая часть этого URI (никогда null)

getSchemeSpecificPart

public String getSchemeSpecificPart()

Возвращает декодированную схему-специфическую часть этого URI.

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

Returns:: Декодированная схема-специфическая часть этого URI (никогда null)

getRawAuthority

public String getRawAuthority()

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

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

Returns:: Необработанный компонент авторизации этого URI или null, если авторизация не определена

getAuthority

public String getAuthority()

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

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

Returns:: Декодированный компонент авторизации этого URI или null, если авторизация не определена

getRawUserInfo

public String getRawUserInfo()

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

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

Returns:: Необработанный компонент user-information этого URI или null, если user-information не определён

getUserInfo

public String getUserInfo()

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

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

Returns:: Декодированный компонент 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 не может содержать закодированные октеты, поэтому этот метод не выполняет никакого декодирования.

Returns:

Компонент host этого URI или null, если host не определён

External Specifications

getPort

public int getPort()

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

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

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

getRawPath

public String getRawPath()

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

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

Returns:: Компонент пути этого URI или null, если путь не определён

getPath

public String getPath()

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

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

Returns:: Декодированный компонент пути этого URI или null, если путь не определён

getRawQuery

public String getRawQuery()

Возвращает компонент запроса URI в исходном виде.

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

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

getQuery

public String getQuery()

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

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

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

getRawFragment

public String getRawFragment()

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

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

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

getFragment

public String getFragment()

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

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

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

equals

public boolean equals(Object ob)

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

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

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

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

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

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

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

Overrides:

equals в классе Object

Параметры:

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

Возвращает:

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

См. также:

hashCode

public int hashCode()

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

Overrides:

hashCode в классе Object

Возвращает:

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

См. также:

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>
Параметры:: that - Объект, с которым должен быть сравнен этот URI
Возвращает:: Отрицательное целое число, ноль или положительное целое число, если этот URI меньше, равен или больше данного URI
Исключения:: ClassCastException - Если данный объект не является URI

toString

public String toString()

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

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

Overrides:

toString в классе Object

Возвращает:

Строковая форма этого URI

Внешние спецификации

toASCIIString

public String toASCIIString()

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

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

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

© 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/net/URI.html