Класс 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. Для иерархических 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

Наконец, преобразование в относительную форму можно рассматривать как обратную операцию разрешения. Пусть 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	Символы Юникода, не входящие в набор символов 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' — символ замены Юникода.

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

Конструктор с одним аргументом требует заключать в кавычки все недопустимые символы аргумента и сохраняет имеющиеся экранированные октеты и символы категории 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), которые именуют ресурсы, но не указывают, как их найти. Приведённые выше URI mailto, news и isbn являются примерами URN.

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

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

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

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

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

Некоторые компоненты URL или URI, например информация о пользователе, могут использоваться для создания вводящих в заблуждение 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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`protected void`	`finalize()`	Устарело, подлежит удалению: этот элемент API может быть удалён в будущей версии. Финализация устарела и может быть удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо истечения определённого промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо истечения определённого промежутка реального времени.

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

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, но не может быть выражено в грамматике.
Символы категории прочих допускаются везде, где 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» ('@'). Все символы, не относящиеся к категориям незарезервированных, знаков препинания, экранированных или прочих, экранируются.
Если задан узел, он добавляется. Если узел представляет собой буквальный адрес IPv6, но не заключен в квадратные скобки ('[' и ']'), квадратные скобки добавляются.
Если задан номер порта, добавляется символ двоеточия (':'), за которым следует номер порта в десятичной системе счисления.
Если задан путь, он добавляется. Все символы, не относящиеся к категориям незарезервированных, знаков препинания, экранированных или прочих и не являющиеся символом косой черты ('/') или символом коммерческого «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, этот адрес должен быть заключен в квадратные скобки ('[' и ']'). Все символы, не относящиеся к категориям незарезервированных, знаков препинания, экранированных или прочих и не являющиеся символом коммерческого «at» ('@'), экранируются.
Если задан путь, он добавляется. Все символы, не относящиеся к категориям незарезервированных, знаков препинания, экранированных или прочих и не являющиеся символом косой черты ('/') или символом коммерческого «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)
Удаляются все избыточные "/" (пустые сегменты). (Отклонение от RFC 2396)

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

Возвращает:

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

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

resolve

public URI resolve(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, если он определен, содержит только символы категории буквенно-цифровых и символы строки "-.+". Схема всегда начинается с символа категории буквенных.

Компонент схемы 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» ('@') и символы категорий незарезервированных, знаков препинания, экранированных и прочих. Если полномочие основано на сервере, оно дополнительно ограничено требованием наличия корректных компонентов пользовательской информации, узла и порта.

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

getAuthority

public String getAuthority()

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

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

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

getRawUserInfo

public String getRawUserInfo()

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

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

Возвращает:: Необработанный компонент пользовательской информации этого 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 согласно правилам, указанным в разделе 5.2, шаге 7 документа RFC 2396.

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

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.