Spec-Zone.ru › OpenJDK 8

Класс URI

  • java.lang.Object
    • java.net.URI
Все реализуемые интерфейсы:
Serializable, Comparable<URI>

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

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

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

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

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

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

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

mailto:java-net@java.sun.com
news:comp.lang.java
urn:isbn:096139210x

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

http://java.sun.com/j2se/1.3/ docs/guide/collections/designfaq.html#28 ../../../demo/jfc/SwingSet2/src/SwingSet2.java file:///~/calendar

Иерархический 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 разрешается относительно пути базового и затем нормализуется. Результатом, например, разрешения 

docs/guide/collections/designfaq.html#28 (1)
относительно базового URI http://java.sun.com/j2se/1.3/ является результирующий URI 
https://docs.oracle.com/javase/1.3/docs/guide/collections/designfaq.html#28
Разрешение относительного URI 
../../../demo/jfc/SwingSet2/src/SwingSet2.java (2)
относительно этого результата в свою очередь дает 
http://java.sun.com/j2se/1.3/demo/jfc/SwingSet2/src/SwingSet2.java
Поддерживается разрешение как абсолютных, так и относительных URI, а также абсолютных и относительных путей в случае иерархических URI. Разрешение URI file:///~calendar относительно любого другого URI просто возвращает исходный URI, так как он абсолютный. Разрешение относительного URI (2) выше относительно относительного базового URI (1) дает нормализованный, но по-прежнему относительный URI 
demo/jfc/SwingSet2/src/SwingSet2.java

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

u.relativize(u.resolve(v)).equals(v) and u.resolve(u.relativize(v)).equals(v) .
Эта операция часто полезна при построении документа, содержащего URI, которые должны быть сделаны относительными к базовому URI документа, где это возможно. Например, относительное преобразование URI 
https://docs.oracle.com/javase/1.3/docs/guide/index.html
относительно базового URI 
http://java.sun.com/j2se/1.3
дает относительный URI docs/guide/index.html.

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

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

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

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

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

  • Для кодирования символов, отличных от US-ASCII, когда URI должен строго соответствовать RFC 2396, не содержа ни каких other символов.

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

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

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

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

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

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

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

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

  • Методы 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://java.sun.com: ), и который не кодирует символы, кроме тех, которые должны быть заключены в кавычки, следующие тождества также справедливы: 
new URI(u.getScheme(),
             u.getSchemeSpecificPart(),
             u.getFragment())
     .equals(u)
во всех случаях, 
new URI(u.getScheme(),
             u.getUserInfo(), u.getAuthority(),
             u.getPath(), u.getQuery(),
             u.getFragment())
     .equals(u)
если u является иерархическим, и 
new URI(u.getScheme(),
             u.getUserInfo(), u.getHost(), u.getPort(),
             u.getPath(), u.getQuery(),
             u.getFragment())
     .equals(u)
если u является иерархическим и имеет либо нет авторизации, либо авторизацию на основе сервера.

URI, URL и URN

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

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

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

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

С момента:
1.4
См. также:
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()

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

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

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

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

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

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

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

Возвращает сырой компонент фрагмента этого URI.
String getRawPath()

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

Возвращает сырой компонент запроса этого URI.
String getRawSchemeSpecificPart()

Возвращает сырую схему-специфическую часть этого URI.
String getRawUserInfo()

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

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

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

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

Возвращает хэш-код для этого URI.
boolean isAbsolute()

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

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

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

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

Определяет относительность данного URI относительно этого URI.
URI resolve(String str)

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

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

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

Возвращает содержимое этого URI как строку.
URL toURL()

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

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

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

Конструкторы

URI

public URI(String str)
    throws URISyntaxException

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

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

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

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

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

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

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

  • Символы в категории other разрешены там, где RFC 2396 допускает escaped октеты, то есть в компонентах user-information, path, query и fragment, а также в компоненте authority, если authority базируется на реестре. Это позволяет 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 из заданных компонентов.

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

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

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

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

  3. Если заданы user information, host или port, то добавляется строка "//".

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

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

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

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

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

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

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

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

URI

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

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

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

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

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

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

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

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

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

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

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

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

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, используя заданные компоненты следующим образом:

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

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

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

  4. Наконец, если задан fragment, то добавляется символ # ('#') к строке, за которым следует fragment. Любой символ, не являющийся допустимым символом 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, объявленных в программе, и поэтому считается программистской ошибкой, если строка не анализируется как таковая. Конструкторы, напрямую выбрасывающие URISyntaxException, должны использоваться в ситуациях, когда URI строится из пользовательского ввода или из другого источника, который может быть подвержен ошибкам.

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

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

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

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

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 выше. В противном случае нормализованный путь не будет содержать "." или ".." сегментов.

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

resolve

public URI resolve(URI uri)

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

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

Если компонент фрагмента заданного URI определён, его компонент 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 абсолютный.

Параметры:
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 вычисляется следующим образом:

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

  2. В противном случае создаётся новый относительный иерархический URI с компонентами query и fragment, взятыми из заданного URI, и с компонентом path, вычисленным путём удаления пути этого 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()

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

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

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

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

isAbsolute

public boolean isAbsolute()

Определяет, является ли этот URI абсолютным.

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

Возвращает:
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, если определен, содержит только символ коммерческого ат (@) и символы из категорий unreserved, punct, escaped и other. Если власть основана на сервере, то она дополнительно ограничена наличием корректных компонентов пользовательских данных, хоста и порта.

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

getAuthority

public String getAuthority()

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

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

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

getRawUserInfo

public String getRawUserInfo()

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

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

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

getUserInfo

public String getUserInfo()

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

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

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

getHost

public String getHost()

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

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

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

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

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

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

getPort

public int getPort()

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

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

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

getRawPath

public String getRawPath()

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

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

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

Overrides:
equals в классе Object
Parameters:
ob - Объект, с которым должен быть сравнен этот объект
Returns:
true если и только если данный объект является URI, идентичным этому URI
See Also:
Object.hashCode(), HashMap

hashCode

public int hashCode()

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

Overrides:
hashCode в классе Object
Возвращает:
Значение хэш-кода для этого URI
See Also:
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 с идентичными схемами упорядочиваются в соответствии с порядком их компонентов авторитета:

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

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

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

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

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

toString

public String toString()

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

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

Overrides:
toString in class Object
Returns:
Строковая форма этого URI

toASCIIString

public String toASCIIString()

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

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

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

© 1993, 2020, 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.

Spec-Zone.ru

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