Класс 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-адреса также поддерживает scope_ids. Синтаксис и использование scope_ids описаны здесь.

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

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

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

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

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

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.

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

URL

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

http, https, file, and jar

Параметры:

protocol - имя используемого протокола.

host - имя хоста.

port - номер порта на хосте.

file - файл на хосте

Исключения:

MalformedURLException - если указан неизвестный протокол.

См. также:

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

Параметры:

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

Параметры:

protocol - имя используемого протокола.

host - имя хоста.

port - номер порта на хосте.

file - файл на хосте

handler - обработчик потоков для URL.

Исключения:

MalformedURLException - если указан неизвестный протокол.

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

Параметры:

spec - строка для разбора в качестве URL.

Исключения:

MalformedURLException - если не указан протокол, или найден неизвестный протокол, или spec имеет null значение.

См. также:

URL(java.net.URL, java.lang.String)

URL

public URL(URL context,
           String spec)
    throws MalformedURLException

<scheme>://<authority><path>?<query>#<fragment>

Параметры:

context - контекст для разбора спецификации.

spec - спецификация для разбора в качестве URL.

Исключения:

MalformedURLException - если не указан протокол, или найден неизвестный протокол, или spec имеет null значение.

См. также:

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

Параметры:

context - контекст для разбора спецификации.

spec - спецификация для разбора в качестве URL.

handler - обработчик потоков для URL.

Исключения:

MalformedURLException - если не указан протокол, или найден неизвестный протокол, или spec имеет null значение.

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)

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

equals в классе Object

Параметры:

obj - URL для сравнения.

Возвращает:

false если объекты идентичны; false в противном случае.

См. также:

Object.hashCode(), HashMap

hashCode

public int hashCode()

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

hashCode в классе Object

Возвращает:

хеш-код для этого URL.

См. также:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

sameFile

public boolean sameFile(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.

Бросает:

URISyntaxException - если этот URL не отформатирован строго в соответствии с RFC2396 и не может быть преобразован в URI.

С:

1.5

openConnection

public URLConnection openConnection()
                             throws IOException

Возвращает:

a 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.

Возвращает:

a 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(Class[])

Параметры:

classes - массив типов Java

Возвращает:

объект содержимого этого URL, который является первым соответствием указанным типам в массиве классов. null, если ни один из запрошенных типов не поддерживается.

Бросает:

IOException - если происходит ошибка ввода-вывода.

С:

1.3

См. также:

URLConnection.getContent(Class[])

setURLStreamHandlerFactory

public static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)

Параметры:

fac - желаемый фабричный объект.

Исключения:

Error - если приложение уже установило фабричный объект.

SecurityException - если менеджер безопасности существует и его метод checkSetFactory не разрешает операцию.

См. также:

URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandlerFactory, SecurityManager.checkSetFactory()