Класс 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 не подвергаются дальнейшему разбору. Примеры непрозрачных 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: схема, часть, специфичная для схемы, полномочия, информация о пользователе, хост, порт, путь, запрос, фрагмент
Компонент	Тип
scheme	`String`
scheme-specific-part	`String`
authority	`String`
user-info	`String`
host	`String`
port	`int`
path	`String`
query	`String`
fragment	`String`

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

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

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

Ключевые операции, поддерживаемые этим классом, — это нормализация, разрешение и преобразование в относительный URI.

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

Разрешение — это процесс разрешения одного URI относительно другого URI, называемого базовым. Результирующий URI формируется из компонентов обоих URI способом, указанным в RFC 2396, при этом компоненты, не заданные в исходном URI, берутся из базового URI. Для иерархических URI путь исходного 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 — любой нормализованный абсолютный 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 относительно базового 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. Например, символ валюты евро ('\u20AC') кодируется как "%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' — символ замены Unicode.

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

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

Тождества

Для любого 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), которые называют ресурсы, но не указывают способ их обнаружения. Примеры URN — показанные выше URI mailto, news и isbn.

Концептуальное различие между URI и URL отражено различиями между этим классом и классом URL.

Экземпляр этого класса представляет ссылку URI в синтаксическом смысле, определённом RFC 2396. URI может быть абсолютным или относительным. Строка 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, следует учитывать рекомендации из документа RFC 3986, раздел 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()`	Возвращает декодированный компонент полномочий этого 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.

Методы, объявленные в классе 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.
Имена хостов в компонентах хоста, состоящие только из одной метки домена, могут начинаться с символа буквенно-цифровой категории. По-видимому, это и подразумевалось в разделе 3.2.2 RFC 2396, хотя грамматика этого не допускает. Следствием этого отклонения является то, что компонент полномочий иерархического URI, например s://123, будет разобран как полномочия на основе сервера.
В компоненте хоста допускаются адреса IPv6. Адрес IPv6 должен быть заключен в квадратные скобки ('[' и ']'), как указано в RFC 2732. Сам адрес IPv6 должен соответствовать правилам разбора, заданным в RFC 2373. Кроме того, адрес IPv6 не должен содержать более шестнадцати байтов адресной информации; это ограничение подразумевается в RFC 2373, но не может быть выражено грамматикой.
Символы категории other допускаются везде, где RFC 2396 допускает экранированные октеты: в компонентах пользовательской информации, пути, запроса и фрагмента, а также в компоненте полномочий, если он основан на реестре. Это позволяет 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 из заданных компонентов согласно правилам, указанным в разделе 5.2, шаге 7 RFC 2396:

Изначально результирующая строка пуста.
Если указана схема, она добавляется к результату, после чего добавляется символ двоеточия (':').
Если указана пользовательская информация, хост или порт, добавляется строка "//".
Если указана пользовательская информация, она добавляется, после чего добавляется символ коммерческого «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; или если компонент полномочий присутствует в строке, но не может быть разобран как полномочия на основе сервера

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

URI

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

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

Изначально результирующая строка пуста.
Если указана схема, она добавляется к результату, после чего добавляется символ двоеточия (':').
Если указаны полномочия, добавляется строка "//", после которой указываются полномочия. Если полномочия содержат явный адрес IPv6, он должен быть заключен в квадратные скобки ('[' и ']'). Любой символ, не принадлежащий категориям unreserved, punct, escaped или other и не являющийся символом коммерческого «at» ('@'), экранируется.
Если указан путь, он добавляется. Любой символ, не принадлежащий категориям unreserved, punct, escaped или other и не являющийся символом косой черты ('/') или коммерческого «at» ('@'), экранируется.
Если указан запрос, добавляется символ вопросительного знака ('?'), после которого указывается запрос. Любой символ, не являющийся допустимым символом 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);

Параметры:: 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.

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

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

create

public static URI create(String str)

Создает URI, разбирая заданную строку.

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

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

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

parseServerAuthority

public URI parseServerAuthority() throws URISyntaxException

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

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

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

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

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

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

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

Возвращает:

URI, поле полномочий которого разобрано как полномочия на основе сервера

Исключения:

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

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

normalize

public URI normalize()

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

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

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

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

Возвращает:

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

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

resolve

public URI resolve(URI uri)

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

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

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

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

Создается новый URI со схемой этого URI и компонентами запроса и фрагмента заданного URI.
Если заданный URI содержит компонент полномочий, полномочия и путь нового URI берутся из заданного URI.
В противном случае компонент полномочий нового URI копируется из этого URI, а его путь вычисляется следующим образом:
1. Если путь заданного URI абсолютный, путь нового URI берется из заданного URI.
2. В противном случае путь заданного URI относительный, поэтому путь нового URI вычисляется путем разрешения пути заданного URI относительно пути этого URI. Для этого все сегменты пути этого URI, кроме последнего, если он есть, объединяются с путем заданного URI, а результат нормализуется так, как если бы был вызван метод normalize.

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

Параметры:

uri - URI, который необходимо разрешить относительно этого URI

Возвращает:

Результирующий URI

Исключения:

NullPointerException - Если uri равно null

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

resolve

public URI resolve(String str)

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

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

Параметры:: str - Строка, которую необходимо разобрать как URI
Возвращает:: Результирующий URI
Исключения:: 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.

Параметры:: uri - URI, который необходимо преобразовать в относительную форму относительно этого URI
Возвращает:: Результирующий URI
Исключения:: 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()

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

Компонент полномочий URI, если он определен, содержит только символ коммерческого «at» ('@') и символы категорий unreserved, punct, escaped и other. Если полномочия основаны на сервере, для них также должны быть заданы корректные компоненты пользовательской информации, хоста и порта.

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

getAuthority

public String getAuthority()

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

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

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

getRawUserInfo

public String getRawUserInfo()

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

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

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

getUserInfo

public String getUserInfo()

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

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

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

getHost

public String getHost()

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

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

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

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

Возвращает:

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

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

getPort

public int getPort()

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

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

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

getRawPath

public String getRawPath()

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

Компонент пути URI, если он определён, содержит только символ косой черты ('/'), символ коммерческого «at» ('@') и символы из категорий не зарезервированные, пунктуация, экранированные и прочие.

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

getPath

public String getPath()

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

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

Возвращает:: Декодированный компонент пути этого 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.

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

equals в классе Object

Параметры:

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

Возвращает:

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

См. также:

hashCode

public int hashCode()

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

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

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.

Определён в:: compareTo в интерфейсе Comparable<URI>
Параметры:: that — объект, с которым сравнивается этот URI
Возвращает:: Отрицательное целое число, ноль или положительное целое число, если этот URI соответственно меньше, равен или больше указанного URI
Выбрасывает:: ClassCastException — если указанный объект не является URI

toString

public String toString()

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

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

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

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://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/URI.html