Класс URL

Все реализуемые интерфейсы:
Serializable
public final class URL
extends Object
implements Serializable

Класс URL представляет собой унифицированный указатель на ресурс (URL), указатель на «ресурс» в Всемирной паутине. Ресурсом может быть что угодно, от простого файла или каталога до ссылки на более сложный объект, такой как запрос к базе данных или поисковой системе. Более подробную информацию о типах URL-адресов и их форматах можно найти по адресу: Типы URL

В общем случае URL можно разбить на несколько частей. Рассмотрим следующий пример:

http://www.example.com/docs/resource1.html

Приведённый выше URL указывает на то, что протокол, который следует использовать, это http (протокол передачи гипертекста), и что информация находится на узле с именем www.example.com. Информация на этом узле называется /docs/resource1.html. Точное значение этого имени на хост-машине зависит как от протокола, так и от самого хоста. Информация обычно хранится в файле, но может быть сгенерирована динамически. Эта часть URL называется путь.

URL может необязательно содержать «порт», представляющий собой номер порта, к которому устанавливается TCP-соединение на удалённом узле. Если порт не указан, используется порт по умолчанию для данного протокола. Например, порт по умолчанию для http равен 80. Альтернативный порт можно указать следующим образом:

http://www.example.com:1080/docs/resource1.html

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

К URL может быть добавлен фрагмент, также известный как «ссылка» или «референс». Фрагмент обозначается знаком решётки «#» и последующими символами. Например,

http://java.sun.com/index.html#chapter1

Этот фрагмент не является технической частью URL. Скорее, он указывает, что после извлечения указанного ресурса приложение интересуется той частью документа, к которой прикреплена метка chapter1. Значение метки зависит от ресурса.

Приложение также может указать «относительный URL», который содержит только необходимую информацию для доступа к ресурсу относительно другого URL. Относительные URL часто используются в HTML-страницах. Например, если содержимое URL:

http://java.sun.com/index.html
содержало относительный URL:
FAQ.html
это было бы сокращённой записью для:
http://java.sun.com/FAQ.html

Относительный URL необязательно должен содержать все компоненты URL. Если протокол, имя хоста или номер порта отсутствуют, они наследуются из полностью указанного URL. Компонент файла должен быть указан. Необязательный фрагмент не наследуется.

Класс URL сам по себе не кодирует или декодирует компоненты URL в соответствии со способом экранирования, определённым в RFC2396. Ответственность за кодирование любых полей, которые необходимо экранировать перед вызовом URL, и декодирование любых экранированных полей, возвращаемых URL, лежит на вызывающей стороне. Кроме того, поскольку URL не знает об экранировании URL, он не распознаёт эквивалентность закодированной или декодированной формы одного и того же URL. Например, два URL:

http://foo.com/hello world/ and http://foo.com/hello%20world
считались бы неравными.

Обратите внимание, что класс URI выполняет экранирование своих компонент в определённых случаях. Рекомендуемый способ управления кодированием и декодированием URL — использование URI и преобразование между этими двумя классами с помощью toURI() и URI.toURL().

Классы URLEncoder и URLDecoder также могут быть использованы, но только для кодирования HTML-форм, что не то же самое, что схема кодирования, определённая в RFC2396.

С:
1.0
См. также:
Сериализованная форма

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

Конструктор Описание
URL​(String spec)

Создаёт объект URL из строки String.

URL​(String protocol, String host, int port, String file)

Создаёт объект URL из указанного protocol, host, целочисленного значения port и file.

URL​(String protocol, String host, int port, String file, URLStreamHandler handler)

Создаёт объект URL из указанного protocol, host, целочисленного значения port, file и handler.

URL​(String protocol, String host, String file)

Создаёт URL из указанного имени protocol, имени host и имени file.

URL​(URL context, String spec)

Создаёт URL путём разбора заданного спецификатора в заданном контексте.

URL​(URL context, String spec, URLStreamHandler handler)

Создаёт URL путём разбора заданного спецификатора с указанным обработчиком в заданном контексте.

Методы

Модификатор и тип Метод Описание
boolean equals​(Object obj)

Сравнивает этот URL с другим объектом на равенство.

String getAuthority()

Возвращает часть «власть» этого URL.

Object getContent()

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

Object getContent​(Class<?>[] classes)

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

int getDefaultPort()

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

String getFile()

Возвращает имя файла этого URL.

String getHost()

Возвращает имя хоста этого URL, если применимо.

String getPath()

Возвращает часть пути этого URL.

int getPort()

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

String getProtocol()

Возвращает имя протокола этого URL.

String getQuery()

Возвращает часть запроса этого URL.

String getRef()

Возвращает якорь (также известный как «ссылка») этого URL.

String getUserInfo()

Возвращает часть userInfo этого URL.

int hashCode()

Создаёт целое число, подходящее для индексирования в хеш-таблице.

URLConnection openConnection()

Возвращает экземпляр URLConnection, который представляет подключение к удалённому объекту, на который указывает URL.

URLConnection openConnection​(Proxy proxy)

Аналогично openConnection(), за исключением того, что подключение будет установлено через указанный прокси; обработчики протоколов, которые не поддерживают проксирование, проигнорируют параметр прокси и установят обычное подключение.

InputStream openStream()

Устанавливает подключение к этому URL и возвращает InputStream для чтения из этого подключения.

boolean sameFile​(URL other)

Сравнивает два URL, исключая компонент фрагмента.

static void setURLStreamHandlerFactory​(URLStreamHandlerFactory fac)

Устанавливает URLStreamHandlerFactory приложения.

String toExternalForm()

Создаёт строковое представление этого URL.

String toString()

Создаёт строковое представление этого URL.

URI toURI()

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

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

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

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

URL

public URL(String protocol,
           String host,
           int port,
           String file)
    throws MalformedURLException

Создаёт объект URL из указанного protocol, host, port номера и file.

host может быть выражен как имя хоста или литеральное IP-адрес. Если используется литеральный IPv6-адрес, он должен быть заключён в квадратные скобки ('[' и ']'), как указано в RFC 2732; Однако, также принимается формат литерального IPv6-адреса, определённый в RFC 2373: Архитектура адресации IP версии 6.

Указание port номера -1 означает, что URL должен использовать стандартный порт для протокола.

Если это первый объект URL, созданный с указанным протоколом, для этого протокола создается объект обработчика потокового протокола, экземпляр класса URLStreamHandler.

  1. Если приложение ранее настроило экземпляр URLStreamHandlerFactory в качестве фабрики обработчиков потоковых протоколов, то вызывается метод createURLStreamHandler этого экземпляра со строкой протокола в качестве аргумента для создания обработчика потокового протокола.
  2. Если фабрика URLStreamHandlerFactory ещё не настроена, или метод createURLStreamHandler фабрики возвращает null, используется механизм ServiceLoader для поиска реализаций URLStreamHandlerProvider с помощью системного загрузчика классов. Порядок поиска поставщиков зависит от реализации, и реализация может кэшировать найденных поставщиков. Возникновение ServiceConfigurationError, Error или RuntimeException из createURLStreamHandler будет передано в поток вызова. Метод createURLStreamHandler каждого поставщика, если он был создан, вызывается со строкой протокола, пока поставщик не вернёт значение отличное от null, или пока не будут исчерпаны все поставщики.
  3. Если на предыдущем шаге обработчик протокола не найден, конструктор считывает значение системной переменной:
    java.protocol.handler.pkgs
    Если значение этой системной переменной не null, оно интерпретируется как список пакетов, разделённых вертикальной чертой '|'. Конструктор пытается загрузить класс с именем:
    <package>.<protocol>.Handler
    где <package> заменяется именем пакета и <protocol> заменяется именем протокола. Если этот класс не существует, или если класс существует, но не является подклассом URLStreamHandler, то пробуется следующий пакет в списке.
  4. Если на предыдущем шаге обработчик протокола не найден, конструктор пытается загрузить встроенный обработчик протокола. Если этот класс не существует, или если класс существует, но не является подклассом URLStreamHandler, выбрасывается MalformedURLException.

Обработчики протоколов для следующих протоколов гарантированно присутствуют на пути поиска :-

http, https, file, and jar
Обработчики протоколов для дополнительных протоколов также могут быть доступны. Некоторые обработчики протоколов, например, те, которые используются для загрузки платформных классов или классов на пути поиска классов, не могут быть переопределены. Подробности таких ограничений и когда эти ограничения применяются (например, во время инициализации среды выполнения), зависят от реализации и поэтому не специфицированы.

В этом конструкторе не выполняется валидация входных данных.

Параметры:
protocol - имя используемого протокола.
host - имя хоста.
port - номер порта на хосте.
file - файл на хосте
Исключения:
MalformedURLException - если неизвестен протокол или порт является отрицательным числом, отличным от -1
См. также:
System.getProperty(java.lang.String), setURLStreamHandlerFactory( java.net.URLStreamHandlerFactory), URLStreamHandler, URLStreamHandlerFactory.createURLStreamHandler( java.lang.String)

URL

public URL(String protocol,
           String host,
           String file)
    throws MalformedURLException

Создаёт URL из указанного protocol имени, host имени и file имени. Используется стандартный порт для указанного протокола.

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

Параметры:
protocol - имя используемого протокола.
host - имя хоста.
file - файл на хосте.
Исключения:
MalformedURLException - если указан неизвестный протокол.
См. также:
URL(java.lang.String, java.lang.String, int, java.lang.String)

URL

public URL(String protocol,
           String host,
           int port,
           String file,
           URLStreamHandler handler)
    throws MalformedURLException

Создаёт объект URL из указанного protocol, host, port номера, file, и handler. Указание port номера -1 означает, что URL должен использовать стандартный порт для протокола. Указание handler null означает, что URL должен использовать стандартный обработчик потоков для протокола, как описано в: java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)

Если обработчик не равен null и существует менеджер безопасности, вызывается метод checkPermission менеджера безопасности с разрешением NetPermission("specifyStreamHandler"). Это может привести к SecurityException. В этом конструкторе не выполняется валидация входных данных.

Параметры:
protocol - имя используемого протокола.
host - имя хоста.
port - номер порта на хосте.
file - файл на хосте
handler - обработчик потоков для URL.
Исключения:
MalformedURLException - если неизвестен протокол или порт является отрицательным числом, отличным от -1
SecurityException - если менеджер безопасности существует и его метод checkPermission не разрешает явное указание обработчика потоков.
См. также:
System.getProperty(java.lang.String), setURLStreamHandlerFactory( java.net.URLStreamHandlerFactory), URLStreamHandler, URLStreamHandlerFactory.createURLStreamHandler( java.lang.String), SecurityManager.checkPermission(java.security.Permission), NetPermission

URL

public URL(String spec)
    throws MalformedURLException

Создаёт объект URL из String представления.

Этот конструктор эквивалентен вызову двухаргументного конструктора с null первым аргументом.

Параметры:
spec - String для парсинга как URL.
Исключения:
MalformedURLException - если не указан протокол, или найден неизвестный протокол, или spec является null, или распарсенный URL не соответствует синтаксису связанного протокола.
См. также:
URL(java.net.URL, java.lang.String)

URL

public URL(URL context,
           String spec)
    throws MalformedURLException

Создаёт URL, парся spec в заданном контексте. Новый URL создается из заданного контекстного URL и аргумента spec, как описано в RFC2396 "Uniform Resource Identifiers: Общий синтаксис":

<scheme>://<authority><path>?<query>#<fragment>
Ссылка разбирается на схему, авторитет, путь, запрос и фрагмент. Если компонент пути пустой, а компоненты схемы, авторитета и запроса не определены, то новый URL является ссылкой на текущий документ. В противном случае фрагмент и часть запроса, присутствующие в spec, используются в новом URL.

Если компонент схемы определен в заданном spec и не соответствует схеме контекста, то новый URL создается как абсолютный URL на основе только spec. В противном случае компонент схемы наследуется от контекстного URL.

Если компонент авторитета присутствует в spec, то spec обрабатывается как абсолютный, и авторитет и путь spec заменят авторитет и путь контекста. Если компонент авторитета отсутствует в spec, то авторитет нового URL будет унаследован от контекста.

Если компонент пути spec начинается с символа слеша "/", то путь рассматривается как абсолютный, и путь spec заменяет путь контекста.

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

Для более подробного описания парсинга URL см. RFC2396.

Параметры:
context - контекст, в котором необходимо разобрать спецификацию.
spec - String для парсинга как URL.
Исключения:
MalformedURLException - если не указан протокол, или найден неизвестный протокол, или spec является null, или распарсенный URL не соответствует синтаксису связанного протокола.
См. также:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandler, URLStreamHandler.parseURL(java.net.URL, java.lang.String, int, int)

URL

public URL(URL context,
           String spec,
           URLStreamHandler handler)
    throws MalformedURLException

Создает URL, парся заданный spec с указанным обработчиком в указанном контексте. Если обработчик равен null, парсинг происходит так же, как и в конструкторе с двумя аргументами.

Параметры:
context - контекст, в котором следует проанализировать спецификацию.
spec - String для анализа в качестве URL.
handler - обработчик потока для URL.
Исключения:
MalformedURLException - если не указан протокол, или обнаружен неизвестный протокол, или spec имеет null, или проанализированный URL не соответствует определённому синтаксису связанного протокола.
SecurityException - если существует менеджер безопасности и его метод checkPermission не допускает указания обработчика потока.
См. также:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandler, URLStreamHandler.parseURL(java.net.URL, java.lang.String, int, int)

Методы

getQuery

public String getQuery()

Возвращает часть запроса этого URL.

Возвращает:
часть запроса этого URL, или null если таковой не существует
С версии:
1.3

getPath

public String getPath()

Возвращает часть пути этого URL.

Возвращает:
часть пути этого URL, или пустую строку, если таковой не существует
С версии:
1.3

getUserInfo

public String getUserInfo()

Возвращает часть userInfo этого URL.

Возвращает:
часть userInfo этого URL, или null если таковой не существует
С версии:
1.3

getAuthority

public String getAuthority()

Возвращает часть authority этого URL.

Возвращает:
часть authority этого URL
С версии:
1.3

getPort

public int getPort()

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

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

getDefaultPort

public int getDefaultPort()

Возвращает номер порта по умолчанию протокола, связанного с этим URL. Если схема URL или URLStreamHandler для URL не определяют номер порта по умолчанию, возвращается -1.

Возвращает:
номер порта
С версии:
1.4

getProtocol

public String getProtocol()

Возвращает имя протокола этого URL.

Возвращает:
протокол этого URL.

getHost

public String getHost()

Возвращает имя хоста этого URL, если применимо. Формат хоста соответствует RFC 2732, т.е. для литерального IPv6-адреса этот метод вернет IPv6-адрес, заключенный в квадратные скобки ('[' и ']').

Возвращает:
имя хоста этого URL.

getFile

public String getFile()

Возвращает имя файла этого URL. Возвращаемая часть файла будет такой же, как getPath(), плюс конкатенация значения getQuery(), если таковое имеется. Если части запроса нет, этот метод и getPath() вернут идентичные результаты.

Возвращает:
имя файла этого URL, или пустую строку, если таковой не существует

getRef

public String getRef()

Возвращает якорь (также известный как "ссылка") этого URL.

Возвращает:
якорь (также известный как "ссылка") этого URL, или null если таковой не существует

equals

public boolean equals(Object obj)

Сравнивает этот URL на равенство с другим объектом.

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

Два объекта URL равны, если они имеют один и тот же протокол, эквивалентные хосты, один и тот же номер порта на хосте и один и тот же файл и фрагмент файла.

Два хоста считаются эквивалентными, если оба имени хоста могут быть разрешены в одни и те же IP-адреса; иначе, если ни одно из имен хостов не может быть разрешено, имена хостов должны быть равны без учета регистра; или оба имени хоста равны null.

Поскольку сравнение хостов требует разрешения имен, эта операция является блокирующей.

Примечание: Известно, что определенное поведение для equals несовместимо с виртуальным хостингом в HTTP.

Переопределяет:
equals в классе Object
Параметры:
obj - URL для сравнения.
Возвращает:
true если объекты одинаковы; false в противном случае.
См. также:
Object.hashCode(), HashMap

hashCode

public int hashCode()

Создает целое число, подходящее для индексации хеш-таблицы.

Хеш-код основан на всех компонентах URL, важных для сравнения URL. Таким образом, эта операция является блокирующей.

Переопределяет:
hashCode в классе Object
Возвращает:
хеш-код для этого URL.
См. также:
Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

sameFile

public boolean sameFile(URL other)

Сравнивает два URL, исключая компонент фрагмента.

Возвращает true, если этот URL и other аргумент равны без учета компонента фрагмента.

Параметры:
other - URL для сравнения.
Возвращает:
true если они ссылаются на один и тот же удаленный объект; false в противном случае.

toString

public String toString()

Конструирует строковое представление этого URL. Строка создается путем вызова метода toExternalForm обработчика протокола потока для этого объекта.

Переопределяет:
toString в классе Object
Возвращает:
строковое представление этого объекта.
См. также:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandler.toExternalForm(java.net.URL)

toExternalForm

public String toExternalForm()

Конструирует строковое представление этого URL. Строка создается путем вызова метода toExternalForm обработчика протокола потока для этого объекта.

Возвращает:
строковое представление этого объекта.
См. также:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandler.toExternalForm(java.net.URL)

toURI

public URI toURI()
          throws URISyntaxException

Возвращает эквивалент URI этого URL. Этот метод работает так же, как new URI (this.toString()).

Примечание: любой экземпляр URL, соответствующий RFC 2396, может быть преобразован в URI. Однако некоторые URL-адреса, которые не строго соответствуют спецификации, не могут быть преобразованы в URI.

Возвращает:
экземпляр URI, эквивалентный этому URL.
Вызывает исключение:
URISyntaxException - если этот URL не отформатирован строго в соответствии с RFC2396 и не может быть преобразован в URI.
С версии:
1.5

openConnection

public URLConnection openConnection()
                             throws IOException

Возвращает экземпляр URLConnection, представляющий собой соединение с удаленным объектом, на который ссылается URL.

Новый экземпляр URLConnection создается каждый раз при вызове метода URLStreamHandler.openConnection(URL) обработчика протокола для этого URL.

Следует отметить, что экземпляр URLConnection не устанавливает фактическое сетевое соединение при создании. Это произойдет только при вызове URLConnection.connect().

Если для протокола URL (например, HTTP или JAR) существует общедоступный специализированный подкласс URLConnection, принадлежащий одному из следующих пакетов или одному из их подпакетов: java.lang, java.io, java.util, java.net, возвращаемое соединение будет этого подкласса. Например, для HTTP будет возвращен HttpURLConnection, а для JAR — JarURLConnection.

Возвращает:
URLConnection, связанный с URL.
Вызывает исключение:
IOException - если возникает исключение ввода-вывода.
См. также:
URL(java.lang.String, java.lang.String, int, java.lang.String)

openConnection

public URLConnection openConnection(Proxy proxy)
                             throws IOException

То же, что и openConnection(), за исключением того, что соединение будет установлено через указанный прокси; Обработчики протоколов, которые не поддерживают проксирование, будут игнорировать параметр прокси и устанавливать обычное соединение. Вызов этого метода отменяет настройки селектора прокси по умолчанию системы ProxySelector.

Параметры:
proxy - прокси, через который будет установлено это соединение. Если требуется прямое соединение, следует указать Proxy.NO_PROXY.
Возвращает:
URLConnection к URL.
Вызывает исключение:
IOException - если возникает исключение ввода-вывода.
SecurityException - если присутствует диспетчер безопасности и вызывающий абонент не имеет разрешения на подключение к прокси-серверу.
IllegalArgumentException - будет выброшено, если прокси-сервер равен null или имеет неправильный тип
UnsupportedOperationException - если подкласс, реализующий обработчик протокола, не поддерживает этот метод.
С версии:
1.5
См. также:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLConnection, URLStreamHandler.openConnection(java.net.URL, java.net.Proxy)

openStream

public final InputStream openStream()
                             throws IOException

Открывает соединение с этим URL и возвращает InputStream для чтения из этого соединения. Этот метод является сокращением для:

openConnection().getInputStream()

Возвращает:
входной поток для чтения из соединения URL.
Вызывает исключение:
IOException - если возникает исключение ввода-вывода.
См. также:
openConnection(), URLConnection.getInputStream()

getContent

public final Object getContent()
                        throws IOException

Получает содержимое этого URL. Этот метод является сокращением для:

openConnection().getContent()

Возвращает:
содержимое этого URL.
Вызывает исключение:
IOException - если возникает исключение ввода-вывода.
См. также:
URLConnection.getContent()

getContent

public final Object getContent(Class<?>[] classes)
                        throws IOException

Получает содержимое этого URL. Этот метод является сокращением для:

openConnection().getContent(classes)

Параметры:
classes - массив Java типов
Возвращает:
объект содержимого этого URL, который является первым совпадением типов, указанных в массиве классов. null, если ни один из запрошенных типов не поддерживается.
Выбрасывает:
IOException - если произошла ошибка ввода-вывода.
С:
1.3
См. также:
URLConnection.getContent(Class[])

setURLStreamHandlerFactory

public static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)

Устанавливает URLStreamHandlerFactory приложения. Этот метод может быть вызван не более одного раза в данной виртуальной машине Java.

Экземпляр URLStreamHandlerFactory используется для построения обработчика протокола потока по имени протокола.

Если существует менеджер безопасности, этот метод сначала вызывает метод checkSetFactory менеджера безопасности, чтобы убедиться, что операция разрешена. Это может привести к SecurityException.

Параметры:
fac - желаемый фабричный объект.
Выбрасывает:
Error - если приложение уже установило фабрику.
SecurityException - если менеджер безопасности существует, и его метод checkSetFactory не позволяет выполнить операцию.
См. также:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandlerFactory, SecurityManager.checkSetFactory()

© 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.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/URL.html

Spec-Zone .ru
спецификации, руководства, описания, API