Класс URL
- java.lang.Object
-
- java.net.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 protocol,
String host,
int port,
String file) | Создаёт объект |
URL(String protocol,
String host,
int port,
String file,
URLStreamHandler handler) | Создаёт объект |
URL(String protocol,
String host,
String file) | Создаёт URL из указанного имени |
URL(URL context,
String spec) | Создаёт URL путём разбора заданного спецификатора в заданном контексте. |
URL(URL context,
String spec,
URLStreamHandler handler) | Создаёт URL путём разбора заданного спецификатора с указанным обработчиком в заданном контексте. |
Методы
| Модификатор и тип | Метод | Описание |
|---|---|---|
boolean | equals(Object obj) | Сравнивает этот URL с другим объектом на равенство. |
String | getAuthority() | Возвращает часть «власть» этого |
Object | getContent() | Возвращает содержимое этого URL. |
Object | getContent(Class<?>[] classes) | Возвращает содержимое этого URL. |
int | getDefaultPort() | Возвращает номер порта по умолчанию для протокола, связанного с этим |
String | getFile() | Возвращает имя файла этого |
String | getHost() | Возвращает имя хоста этого |
String | getPath() | Возвращает часть пути этого |
int | getPort() | Возвращает номер порта этого |
String | getProtocol() | Возвращает имя протокола этого |
String | getQuery() | Возвращает часть запроса этого |
String | getRef() | Возвращает якорь (также известный как «ссылка») этого |
String | getUserInfo() | Возвращает часть userInfo этого |
int | hashCode() | Создаёт целое число, подходящее для индексирования в хеш-таблице. |
URLConnection | openConnection() | Возвращает экземпляр |
URLConnection | openConnection(Proxy proxy) | Аналогично |
InputStream | openStream() | Устанавливает подключение к этому |
boolean | sameFile(URL other) | Сравнивает два URL, исключая компонент фрагмента. |
static void | setURLStreamHandlerFactory(URLStreamHandlerFactory fac) | Устанавливает |
String | toExternalForm() | Создаёт строковое представление этого |
String | toString() | Создаёт строковое представление этого |
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.
- Если приложение ранее настроило экземпляр
URLStreamHandlerFactoryв качестве фабрики обработчиков потоковых протоколов, то вызывается методcreateURLStreamHandlerэтого экземпляра со строкой протокола в качестве аргумента для создания обработчика потокового протокола. - Если фабрика
URLStreamHandlerFactoryещё не настроена, или методcreateURLStreamHandlerфабрики возвращаетnull, используется механизм ServiceLoader для поиска реализаций URLStreamHandlerProvider с помощью системного загрузчика классов. Порядок поиска поставщиков зависит от реализации, и реализация может кэшировать найденных поставщиков. Возникновение ServiceConfigurationError,ErrorилиRuntimeExceptionизcreateURLStreamHandlerбудет передано в поток вызова. МетодcreateURLStreamHandlerкаждого поставщика, если он был создан, вызывается со строкой протокола, пока поставщик не вернёт значение отличное от null, или пока не будут исчерпаны все поставщики. - Если на предыдущем шаге обработчик протокола не найден, конструктор считывает значение системной переменной:
java.protocol.handler.pkgs
Если значение этой системной переменной неnull, оно интерпретируется как список пакетов, разделённых вертикальной чертой '|'. Конструктор пытается загрузить класс с именем:<package>.<protocol>.Handler
где<package>заменяется именем пакета и<protocol>заменяется именем протокола. Если этот класс не существует, или если класс существует, но не является подклассомURLStreamHandler, то пробуется следующий пакет в списке. - Если на предыдущем шаге обработчик протокола не найден, конструктор пытается загрузить встроенный обработчик протокола. Если этот класс не существует, или если класс существует, но не является подклассом
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