Класс URI

Создаёт URI, разобрав заданную строку.

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

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

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

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

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

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

• Символы в категории other разрешены везде, где RFC 2396 разрешает escaped-октеты, то есть в компонентах user-information, path, query и fragment, а также в компоненте authority, если authority основана на реестре. Это позволяет URI содержать символы Unicode, выходящие за рамки набора символов US-ASCII.

Создаёт иерархический 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Создаёт URI, разобрав заданную строку.

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

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

Попытка разобрать компонент «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.

Если этот 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.

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

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

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

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

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

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

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

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

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

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

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

Относительно заданного URI относительно этого URI.

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

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

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

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

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

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

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

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

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

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

Определяет, является ли этот URI неиерархическим.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Иерархический URI считается меньше, чем непрозрачный URI с идентичной схемой.

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

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

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

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

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

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

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

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

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

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

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