Spec-Zone.ru › OpenJDK 21

Класс URI

java.lang.Object
java.net.URI
Все реализованные интерфейсы:
Serializable, Comparable<URI> 
public final class URI extends Object implements Comparable<URI>, Serializable
Представляет ссылку на универсальный идентификатор ресурса (URI).

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

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

На высшем уровне ссылка URI (в дальнейшем просто "URI") в строковой форме имеет синтаксис
[схема:]часть схемы[#фрагмент]
где квадратные скобки [...] обозначают необязательные компоненты, а символы : и # обозначают сами себя.

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

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

  • mailto:java-net@www.example.com
  • news:comp.lang.java
  • urn:isbn:096139210x

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

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

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

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

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

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

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

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

Описывает компоненты URI: схема, часть схемы, авторитет, информация о пользователе, хост, порт, путь, запрос, фрагмент
Компонент Тип
схема String
часть схемы String
авторитет String
информация о пользователе String
хост String
порт int
путь String
запрос String
фрагмент String
В данном экземпляре любой конкретный компонент либо неопределён, либо определён с определённым значением. Неопределённые строковые компоненты представлены null, а неопределённые целочисленные компоненты — -1. Строковый компонент может быть определён таким образом, чтобы иметь пустую строку в качестве значения; это не эквивалентно тому, что этот компонент является неопределённым.

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

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

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

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

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

sample/a/index.html#28 (1)
по отношению к базовому URI http://example.com/languages/java/ — это результирующий URI
http://example.com/languages/java/sample/a/index.html#28
Разрешение относительного URI
../../demo/b/index.html (2)
по отношению к этому результату, в свою очередь, даёт
http://example.com/languages/java/demo/b/index.html
Поддерживается разрешение как абсолютных, так и относительных URI, а также абсолютных и относительных путей в случае иерархических URI. Разрешение URI file:///~calendar по отношению к любому другому URI просто даёт исходный URI, так как он абсолютный. Разрешение относительного URI (2) выше по отношению к относительному базовому URI (1) даёт нормализованный, но всё ещё относительный URI
demo/b/index.html

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

u.relativize(u.resolve(v)).equals(v)
Пусть u — любой нормализованный абсолютный URI, заканчивающийся символом косой черты ('/') и v — любой нормализованный абсолютный URI. Тогда следующее утверждение верно:
u.resolve(u.relativize(v)).equals(v)
Эта операция часто полезна при создании документа, содержащего URI, которые должны быть сделаны относительными к базовому URI документа, где это возможно. Например, относительное представление URI
http://example.com/languages/java/sample/a/index.html#28
относительно базового URI
http://example.com/languages/java/
даёт относительный URI sample/a/index.html#28.

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

RFC 2396 точно определяет, какие символы разрешены в различных компонентах ссылки URI. Ниже используются следующие категории, большинство из которых взяты из этого спецификации, для описания этих ограничений:
Описывает категории alpha,digit,alphanum,unreserved,punct,reserved,escaped и другие
Категория Описание
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, не содержа в себе другие символы.

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

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

  • Символ кодируется заменой его на последовательность экранированных октетов, представляющих этот символ в наборе символов UTF-8. Например, символ евро (€) кодируется как "%E2%82%AC". (Отклонение от RFC 2396, который не определяет конкретный набор символов.)

  • Недопустимый символ котируется, просто кодируясь. Например, символ пробела котируется заменой его на "%20". UTF-8 содержит US-ASCII, поэтому для US-ASCII символов это преобразование имеет ровно тот же эффект, что и требуется RFC 2396.

  • Последовательность экранированных октетов декодируется заменой её на последовательность символов, которую она представляет в наборе символов UTF-8. UTF-8 содержит US-ASCII, поэтому декодирование имеет эффект отмены котирования любых закотированных US-ASCII символов, а также декодирования любых закодированных символов, не являющихся US-ASCII. Если при декодировании экранированных октетов возникает ошибка декодирования, то ошибочные октеты заменяются на '\uFFFD', универсальный символ замены Юникода.

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

  • Конструктор с одним аргументом требует котирования любых недопустимых символов в своём аргументе и сохраняет любые экранированные октеты и другие символы, которые присутствуют.

  • Конструкторы с множеством аргументов котируют недопустимые символы, как требуется компонентами, в которых они появляются. Символ процента ('%') всегда котируется этими конструкторами. Любые другие символы сохраняются.

  • Методы getRawUserInfo, getRawPath, getRawQuery, getRawFragment, getRawAuthority и getRawSchemeSpecificPart возвращают значения соответствующих компонентов в исходном виде, не интерпретируя экранированные октеты. Строки, возвращаемые этими методами, могут содержать как экранированные октеты, так и другие символы, и не будут содержать недопустимых символов.

  • Методы getUserInfo, getPath, getQuery, getFragment, getAuthority и getSchemeSpecificPart декодируют любые экранированные октеты в соответствующих компонентах. Строки, возвращаемые этими методами, могут содержать как другие символы, так и недопустимые символы, и не будут содержать экранированных октетов.

  • Метод toString возвращает строку URI со всеми необходимыми котированиями, но которая может содержать другие символы.

  • Метод toASCIIString возвращает полностью закотированную и закодированную строку URI, которая не содержит никаких других символов.

Тождества

Для любого URI u всегда выполняется следующее:
new URI(u.toString()).equals(u) .
Для любого URI u, который не содержит избыточного синтаксиса, например, двух слешей перед пустым авторитетом (как в file:///tmp/ ) или двоеточия после имени хоста, но без порта (как в http://www.example.com: ), и который не кодирует символы, кроме тех, которые должны быть закотированы, следующие тождества также выполняются: 
     new URI(u.getScheme(),
             u.getSchemeSpecificPart(),
             u.getFragment())
     .equals(u)
во всех случаях, 
     new URI(u.getScheme(),
             u.getAuthority(),
             u.getPath(), u.getQuery(),
             u.getFragment())
     .equals(u)
если u иерархический, и 
     new URI(u.getScheme(),
             u.getUserInfo(), u.getHost(), u.getPort(),
             u.getPath(), u.getQuery(),
             u.getFragment())
     .equals(u)
если u иерархический и не имеет авторитета или авторитета, основанного на сервере.

URI, URL и URN

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

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

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

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

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

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

С:
1.4
Внешние спецификации
  • RFC 2279: UTF-8, формат преобразования ISO 10646
  • RFC 2373: Архитектура адресации IPv6
  • RFC 2396: Унифицированные идентификаторы ресурсов (URI): Общий синтаксис
  • RFC 2732: Формат литеральных адресов IPv6 в URL
  • RFC 3986: Унифицированный идентификатор ресурса (URI): Общий синтаксис
См. также:
  • RFC 2279: UTF-8, формат преобразования ISO 10646
  • RFC 2373: Архитектура адресации IPv6
  • RFC 2396: Унифицированные идентификаторы ресурсов (URI): Общий синтаксис
  • RFC 2732: Формат литеральных адресов IPv6 в URL
  • URISyntaxException
  • Сериализованная форма

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

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

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

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

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

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

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

URI

public URI(String str) throws URISyntaxException
Создаёт URI путём разбора заданной строки.

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

  • Разрешено пустое поле авторитета, если за ним следует непустой путь, компонент запроса или компонент фрагмента. Это позволяет парсить URI, такие как "file:///foo/bar", что, похоже, является целью RFC 2396, хотя грамматика этого не допускает. Если компонент авторитета пуст, то компоненты имя пользователя, хост и порт не определены.

  • Разрешены пустые относительные пути; похоже, это соответствует намерениям RFC 2396, хотя грамматика этого не допускает. Основным следствием этого отклонения является то, что автономный фрагмент, такой как "#foo", анализируется как относительный URI с пустым путём и заданным фрагментом и может быть полезно разрешён относительно базового URI.

  • IPv4-адреса в компонентах хоста анализируются строго, как указано в RFC 2732: каждый элемент адреса в формате точка-тире должен содержать не более трёх десятичных цифр. Каждый элемент также ограничен значением, не превышающим 255.

  • Имена хостов в компонентах хоста, состоящих только из одной метки домена, разрешается начинать с символа alphanum. Это, похоже, соответствует намерениям раздела 3.2.2 RFC 2396, хотя грамматика этого не допускает. Следствием этого отклонения является то, что компонент авторитета иерархического URI, такого как s://123, будет анализироваться как авторитет на основе сервера.

  • IPv6-адреса разрешены для компонента хоста. IPv6-адрес должен быть заключён в квадратные скобки ('[' и ']') как указано в RFC 2732. Сам IPv6-адрес должен анализироваться в соответствии с RFC 2373. IPv6-адреса дополнительно ограничены описанием не более шестнадцати байтов информации об адресе, ограничение, подразумеваемое в RFC 2373, но не выражаемое в грамматике.

  • Символы в категории other разрешены там, где RFC 2396 допускает escaped октеты, то есть в компонентах имени пользователя, пути, запроса и фрагмента, а также в компоненте авторитета, если авторитет основан на реестре. Это позволяет URI содержать символы Юникода, выходящие за рамки набора символов US-ASCII.

Параметры:
str - Строка, подлежащая разбору в URI
Исключения:
NullPointerException - Если str является null
URISyntaxException - Если заданная строка нарушает RFC 2396, как дополнено вышеуказанными отклонениями
Внешние спецификации
  • RFC 2373: Архитектура адресации IP версии 6
  • RFC 2396: Универсальные идентификаторы ресурсов (URI): Общая синтаксис
  • RFC 2732: Формат литеральных IPv6-адресов в URL

URI

public URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment) throws URISyntaxException
Создаёт иерархический URI из заданных компонентов.

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

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

  1. Изначально строка результата пустая.

  2. Если задана схема, то она добавляется к результату, за которой следует двоеточие (':').

  3. Если заданы имя пользователя, хост или порт, то добавляется строка "//".

  4. Если задано имя пользователя, то оно добавляется, за которым следует коммерческое «@» ('@'). Любой символ, не входящий в категории unreserved, punct, escaped или other, записывается в кавычки.

  5. Если задан хост, то он добавляется. Если хост является литеральным IPv6-адресом, но не заключён в квадратные скобки ('[' и ']'), то добавляются квадратные скобки.

  6. Если задан номер порта, то добавляется двоеточие (':'), за которым следует номер порта в десятичной форме.

  7. Если задан путь, то он добавляется. Любой символ, не входящий в категории unreserved, punct, escaped или other, и не равный символу косой черты ('/') или символу коммерческого «@» ('@'), записывается в кавычки.

  8. Если задан запрос, то добавляется знак вопроса ('?'), за которым следует запрос. Любой символ, не являющийся законным символом URI, записывается в кавычки.

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

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

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

URI

public URI(String scheme, String authority, String path, String query, String fragment) throws URISyntaxException
Создаёт иерархический URI из заданных компонентов.

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

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

  1. Изначально строка результата пустая.

  2. Если задана схема, то она добавляется к результату, за которой следует двоеточие (':').

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

  4. Если задан путь, то он добавляется. Любой символ, не входящий в категории unreserved, punct, escaped или other, и не равный символу косой черты ('/') или символу коммерческого «@» ('@'), записывается в кавычки.

  5. Если задан запрос, то добавляется знак вопроса ('?'), за которым следует запрос. Любой символ, не являющийся законным символом URI, записывается в кавычки.

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

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

Параметры:
scheme - Имя схемы
authority - Авторитет
path - Путь
query - Запрос
fragment - Фрагмент
Исключения:
URISyntaxException - Если заданы схема и путь, но путь является относительным, если строка URI, созданная из заданных компонентов, нарушает RFC 2396 или если компонент авторитета строки присутствует, но не может быть проанализирован как авторитет на основе сервера
Внешние спецификации
  • RFC 2396: Универсальные идентификаторы ресурсов (URI): Общая синтаксис

URI

public URI(String scheme, String host, String path, String fragment) throws URISyntaxException
Создаёт иерархический URI из заданных компонентов.

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

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

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

URI

public URI(String scheme, String ssp, String fragment) throws URISyntaxException
Создаёт URI из заданных компонентов.

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

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

  1. Изначально, строка результата пустая.

  3. Если задана схема, то она добавляется к результату, за которой следует двоеточие (':').

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

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

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

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

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

create

public static URI create(String str)
Создаёт URI, парся заданную строку.

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

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

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

parseServerAuthority

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

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

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

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

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

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

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

Returns:
URI, у которого поле authority обработано как серверный authority
Throws:
URISyntaxException - Если компонент authority этого URI определён, но не может быть обработан как серверный authority в соответствии с RFC 2396
External Specifications
  • RFC 2396: Uniform Resource Identifiers (URI): Общий синтаксис

normalize

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

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

  1. Все "." сегменты удаляются.

  2. Если ".." сегмент предшествует не-".." сегменту, то оба этих сегмента удаляются. Этот шаг повторяется до тех пор, пока он больше не применим.

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

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

Returns:
URI, эквивалентный этому URI, но с путём в нормальной форме
External Specifications
  • RFC 2396: Uniform Resource Identifiers (URI): Общий синтаксис

resolve

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

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

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

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

  1. Создаётся новый URI со схемой этого URI и компонентами query и fragment заданного URI.

  2. Если у заданного URI есть компонент authority, то компонент authority и path нового URI берутся от заданного URI.

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

    1. Если путь заданного URI абсолютный, то путь нового URI берётся от заданного URI.

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

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

Parameters:
uri - URI, который разрешается относительно этого URI
Returns:
Результат URI
Throws:
NullPointerException - Если uri равен null
External Specifications
  • RFC 2396: Uniform Resource Identifiers (URI): Общий синтаксис

resolve

public URI resolve(String str)
Создаёт новый URI, анализируя заданную строку и затем разрешая её относительно данного URI.

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

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

relativize

public URI relativize(URI uri)
Относительствует данный URI к этому URI.

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

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

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

Parameters:
uri - URI, который будет относительзован к этому URI
Returns:
Результат URI
Throws:
NullPointerException - Если uri является null

toURL

public URL toURL() throws MalformedURLException
Строит URL из данного URI.

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

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

getScheme

public String getScheme()
Возвращает компонент схемы данного URI.

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

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

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

isAbsolute

public boolean isAbsolute()
Определяет, является ли данный URI абсолютным.

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

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

isOpaque

public boolean isOpaque()
Определяет, является ли данный URI непрозрачным.

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

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

getRawSchemeSpecificPart

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

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

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

getSchemeSpecificPart

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

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

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

getRawAuthority

public String getRawAuthority()
Возвращает исходный компонент авторизации данного URI.

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

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

getAuthority

public String getAuthority()
Возвращает декодированный компонент авторизации данного URI.

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

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

getRawUserInfo

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

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

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

getUserInfo

public String getUserInfo()
Возвращает декодированный компонент информации о пользователе данного URI.

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

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

getHost

public String getHost()
Возвращает компонент хоста данного URI.

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

  • Имя домена, состоящее из одного или нескольких метки, разделённых точками ('.'), необязательно за которым следует точка. Каждая метка состоит из символов alphanum, а также символов тире ('-'), хотя тире никогда не встречаются в качестве первого или последнего символа метки. Правая метка доменного имени, состоящего из двух или более меток, начинается с символа alpha.

  • Четырехточечный IPv4-адрес в формате цифра+.цифра+.цифра+.цифра+, где ни одна последовательность цифр не длиннее трёх символов и ни одна последовательность не имеет значения больше 255.

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

Компонент хоста URI не может содержать закодированных октетов, поэтому этот метод не выполняет никакого декодирования.
Returns:
Компонент хоста данного URI или null, если хост не определён
Внешние спецификации
  • RFC 2373: Архитектура адресации IPv6

getPort

public int getPort()
Возвращает номер порта данного URI.

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

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

getRawPath

public String getRawPath()
Возвращает исходный компонент пути данного URI.

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

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

getPath

public String getPath()
Возвращает декодированный компонент пути данного URI.

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

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

getRawQuery

public String getRawQuery()
Возвращает исходный компонент запроса данного URI.

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

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

getQuery

public String getQuery()
Возвращает декодированный компонент запроса данного URI.

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

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

getRawFragment

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

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

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

getFragment

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

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

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

equals

public boolean equals(Object ob)
Проверяет равенство этого URI с другим объектом.

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

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

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

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

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

Этот метод удовлетворяет общему соглашению метода Object.equals.

Overrides:
equals в классе Object
Параметры:
ob - Объект, с которым сравнивается этот объект
Возвращает:
true тогда и только тогда, когда данный объект является URI, идентичным этому URI
См. также:
  • Object.hashCode()
  • HashMap

hashCode

public int hashCode()
Возвращает значение хэш-кода для этого URI. Хэш-код основан на всех компонентах URI и удовлетворяет общему соглашению метода Object.hashCode.
Overrides:
hashCode в классе Object
Возвращает:
Значение хэш-кода для этого URI
См. также:
  • Object.equals(java.lang.Object)
  • System.identityHashCode(java.lang.Object)

compareTo

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

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

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

  • Два URI с разными схемами упорядочиваются по порядку их схем без учёта регистра.

  • Иерархический URI считается меньше неявного URI с идентичной схемой.

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

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

  • Два иерархических URI с идентичными схемами упорядочиваются по порядку их компонентов авторитета:

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

    • Если один или оба компонента авторитета основаны на реестре, то URIs упорядочиваются по порядку их компонентов авторитета.

  • Наконец, два иерархических 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.

Overrides:
toString в классе Object
Возвращает:
Строковая форма этого URI
Внешние спецификации
  • RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax

toASCIIString

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

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

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

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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API