Класс URLConnection

public abstract class URLConnection
extends Object

Абстрактный класс URLConnection является суперклассом всех классов, представляющих канал связи между приложением и URL. Экземпляры этого класса могут использоваться как для чтения, так и для записи в ресурс, на который ссылается URL. В общем случае создание соединения с URL — многоэтапный процесс:

openConnection()	connect()
Изменение параметров, влияющих на соединение с удалённым ресурсом.	Взаимодействие с ресурсом; запросы к полям заголовка и содержимому.

---------------------------->
время

1. Объект соединения создаётся путём вызова метода openConnection на объекте URL.
2. Настраиваются параметры и общие свойства запроса.
3. Производится фактическое соединение с удалённым объектом, используя метод connect.
4. Удалённый объект становится доступным. Можно получить доступ к полям заголовка и содержимому удалённого объекта.

Параметры настройки изменяются с помощью следующих методов:

• setAllowUserInteraction
• setDoInput
• setDoOutput
• setIfModifiedSince
• setUseCaches

а общие свойства запроса изменяются с помощью метода:

• setRequestProperty

Значения по умолчанию для параметров AllowUserInteraction и UseCaches могут быть установлены с помощью методов setDefaultAllowUserInteraction и setDefaultUseCaches.

Каждый из перечисленных set методов имеет соответствующий get метод для получения значения параметра или общего свойства запроса. Конкретные параметры и общие свойства запроса зависят от протокола.

После установления соединения с удалённым объектом для доступа к полям заголовка и содержимому используются следующие методы:

• getContent
• getHeaderField
• getInputStream
• getOutputStream

Некоторые поля заголовка используются часто. Методы:

• getContentEncoding
• getContentLength
• getContentType
• getDate
• getExpiration
• getLastModifed

обеспечивают удобный доступ к этим полям. Метод getContentType используется методом getContent для определения типа удалённого объекта; подклассы могут посчитать удобным переопределение метода getContentType.

В большинстве случаев можно проигнорировать все параметры до соединения и общие свойства запроса: значения по умолчанию для них разумны. Для большинства клиентов этого интерфейса интересны только два метода: getInputStream и getContent, которые дублируются в классе URL удобными методами.

Дополнительную информацию о свойствах запроса и полях заголовка подключения http можно найти по адресу:

http://www.ietf.org/rfc/rfc2616.txt

Вызов методов close() на объектах InputStream или OutputStream объекта URLConnection после запроса может освободить сетевые ресурсы, связанные с этим экземпляром, если протокол не предписывает иное поведение.

Поля

url

protected URL url

См. также:

getURL(), url

doInput

protected boolean doInput

См. также:

getDoInput(), setDoInput(boolean)

doOutput

protected boolean doOutput

См. также:

getDoOutput(), setDoOutput(boolean)

allowUserInteraction

protected boolean allowUserInteraction

См. также:

getAllowUserInteraction(), setAllowUserInteraction(boolean), setDefaultAllowUserInteraction(boolean)

useCaches

protected boolean useCaches

См. также:

setUseCaches(boolean), getUseCaches(), setDefaultUseCaches(boolean)

ifModifiedSince

protected long ifModifiedSince

См. также:

getIfModifiedSince(), setIfModifiedSince(long)

connected

protected boolean connected

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

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

URLConnection

protected URLConnection(URL url)

Создаёт соединение с указанным URL. Соединение с объектом, на который ссылается URL, не создаётся.

Параметры:

url — указанный URL.

Методы

getFileNameMap

public static FileNameMap getFileNameMap()

Загружает карту имён файлов (таблицу mime) из файла данных. Сначала будет попытка загрузить пользовательскую таблицу, определённую свойством "content.types.user.table". Если это не удастся, будет попытка загрузить встроенную таблицу по умолчанию.

Возвращает:

FileNameMap

Начиная с:

1.2

См. также:

setFileNameMap(java.net.FileNameMap)

setFileNameMap

public static void setFileNameMap(FileNameMap map)

Параметры:

map — FileNameMap для установки

Исключения:

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

Начиная с:

1.2

См. также:

SecurityManager.checkSetFactory(), getFileNameMap()

connect

public abstract void connect()
                      throws IOException

Исключения:

SocketTimeoutException — если таймаут истекает перед установлением соединения

IOException — если при открытии соединения произошла ошибка ввода-вывода.

См. также:

connected, getConnectTimeout(), setConnectTimeout(int)

setConnectTimeout

public void setConnectTimeout(int timeout)

Параметры:

timeout — значение таймаута подключения в миллисекундах

Исключения:

IllegalArgumentException — если параметр таймаута отрицательный

Начиная с:

1.5

См. также:

getConnectTimeout(), connect()

getConnectTimeout

public int getConnectTimeout()

Возвращает:

значение таймаута подключения в миллисекундах

Начиная с:

1.5

См. также:

setConnectTimeout(int), connect()

setReadTimeout

public void setReadTimeout(int timeout)

Параметры:

timeout — значение таймаута чтения в миллисекундах

Исключения:

IllegalArgumentException — если параметр таймаута отрицательный

Начиная с:

1.5

См. также:

getReadTimeout(), InputStream.read()

getReadTimeout

public int getReadTimeout()

Возвращает установленное значение таймаута чтения. Возвращаемое значение 0 означает, что параметр отключён (т.е., таймаут бесконечен).

Возвращает:

значение таймаута чтения в миллисекундах

Начиная с:

1.5

См. также:

setReadTimeout(int), InputStream.read()

getURL

public URL getURL()

Возвращает значение поля URLConnection этого URL.

Возвращает:

значение поля URLConnection этого URL.

См. также:

url

getContentLength

public int getContentLength()

Возвращает:

длину содержимого ресурса, на который ссылается URL этого соединения, -1 если длина содержимого неизвестна или превышает Integer.MAX_VALUE.

getContentLengthLong

public long getContentLengthLong()

Возвращает значение поля заголовка content-length как long.

Возвращает:

длина содержимого ресурса, на который ссылается URL этого соединения, или -1, если длина содержимого неизвестна.

С:

7.0

getContentType

public String getContentType()

Возвращает значение поля заголовка content-type.

Возвращает:

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

См. также:

getHeaderField(java.lang.String)

getContentEncoding

public String getContentEncoding()

Возвращает значение поля заголовка content-encoding.

Возвращает:

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

См. также:

getHeaderField(java.lang.String)

getExpiration

public long getExpiration()

Возвращает значение поля заголовка expires.

Возвращает:

дата истечения срока действия ресурса, на который ссылается этот URL, или 0, если неизвестна. Значение представляет собой количество миллисекунд, прошедших с 1 января 1970 года по Гринвичу.

См. также:

getHeaderField(java.lang.String)

getDate

public long getDate()

Возвращает значение поля заголовка date.

Возвращает:

дата отправки ресурса, на который ссылается URL, или 0, если неизвестна. Возвращаемое значение — количество миллисекунд, прошедших с 1 января 1970 года по Гринвичу.

См. также:

getHeaderField(java.lang.String)

getLastModified

public long getLastModified()

Возвращает значение поля заголовка last-modified. Результат — количество миллисекунд, прошедших с 1 января 1970 года по Гринвичу.

Возвращает:

дата последнего изменения ресурса, на который ссылается этот URLConnection, или 0, если неизвестна.

См. также:

getHeaderField(java.lang.String)

getHeaderField

public String getHeaderField(String name)

Параметры:

name - имя поля заголовка.

Возвращает:

значение поля заголовка с заданным именем, или null, если такого поля в заголовке нет.

getHeaderFields

public Map<String,List<String>> getHeaderFields()

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

Возвращает:

карта полей заголовка

С:

1.4

getHeaderFieldInt

public int getHeaderFieldInt(String name,
                             int Default)

Параметры:

name - имя поля заголовка.

Default - значение по умолчанию.

Возвращает:

значение указанного поля, проанализированное как целое число. Если поле отсутствует или имеет неправильный формат, возвращается значение Default.

getHeaderFieldLong

public long getHeaderFieldLong(String name,
                               long Default)

Параметры:

name - имя поля заголовка.

Default - значение по умолчанию.

Возвращает:

значение указанного поля, проанализированное как число типа long. Если поле отсутствует или имеет неправильный формат, возвращается значение Default.

С:

7.0

getHeaderFieldDate

public long getHeaderFieldDate(String name,
                               long Default)

Параметры:

name - имя поля заголовка.

Default - значение по умолчанию.

Возвращает:

значение поля, проанализированное как дата. Если поле отсутствует или имеет неправильный формат, возвращается значение аргумента Default.

getHeaderFieldKey

public String getHeaderFieldKey(int n)

Возвращает ключ для n-го поля заголовка. Возвращает null, если полей меньше n+1.

Параметры:

n - индекс, где n>=0

Возвращает:

ключ для n-го поля заголовка, или null, если полей меньше n+1.

getHeaderField

public String getHeaderField(int n)

Параметры:

n - индекс, где n>=0

Возвращает:

значение n-го поля заголовка или null, если полей меньше n+1.

См. также:

getHeaderFieldKey(int)

getContent

public Object getContent()
                  throws IOException

Возвращает:

извлеченный объект. Оператор instanceof должен использоваться для определения конкретного типа возвращаемого объекта.

Исключения:

IOException - если при получении содержимого произошла ошибка ввода-вывода.

UnknownServiceException - если протокол не поддерживает тип содержимого.

См. также:

ContentHandlerFactory.createContentHandler(java.lang.String), getContentType(), setContentHandlerFactory(java.net.ContentHandlerFactory)

getContent

public Object getContent(Class[] classes)
                  throws IOException

Извлекает содержимое этого URL-соединения.

Параметры:

classes - массив Class указывающий на запрашиваемые типы

Возвращает:

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

Исключения:

IOException - если при получении содержимого произошла ошибка ввода-вывода.

UnknownServiceException - если протокол не поддерживает тип содержимого.

С:

1.3

См. также:

getContent(), ContentHandlerFactory.createContentHandler(java.lang.String), getContent(java.lang.Class[]), setContentHandlerFactory(java.net.ContentHandlerFactory)

getPermission

public Permission getPermission()
                         throws IOException

Возвращает:

объект разрешения, представляющий разрешение, необходимое для создания подключения, представленного этим URLConnection.

Имеет:

IOException - если вычисление разрешения требует сетевого или файлового ввода-вывода, и при его вычислении произошла ошибка.

getInputStream

public InputStream getInputStream()
                           throws IOException

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

Возвращает:

поток ввода, который считывает данные из этого открытого подключения.

Имеет:

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

UnknownServiceException - если протокол не поддерживает ввод.

См. также:

setReadTimeout(int), getReadTimeout()

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Возвращает поток вывода, который записывает данные в это подключение.

Возвращает:

поток вывода, который записывает данные в это подключение.

Имеет:

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

UnknownServiceException - если протокол не поддерживает вывод.

toString

public String toString()

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

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

toString в классе Object

Возвращает:

строковое представление этого URLConnection.

setDoInput

public void setDoInput(boolean doinput)

Параметры:

doinput - новое значение.

Имеет:

IllegalStateException - если уже подключено

См. также:

doInput, getDoInput()

getDoInput

public boolean getDoInput()

Возвращает значение флага URLConnection этого doInput.

Возвращает:

значение флага URLConnection этого doInput.

См. также:

setDoInput(boolean)

setDoOutput

public void setDoOutput(boolean dooutput)

Параметры:

dooutput - новое значение.

Имеет:

IllegalStateException - если уже подключено

См. также:

getDoOutput()

getDoOutput

public boolean getDoOutput()

Возвращает значение флага URLConnection этого doOutput.

Возвращает:

значение флага URLConnection этого doOutput.

См. также:

setDoOutput(boolean)

setAllowUserInteraction

public void setAllowUserInteraction(boolean allowuserinteraction)

Устанавливает значение поля allowUserInteraction этого URLConnection.

Параметры:

allowuserinteraction - новое значение.

Имеет:

IllegalStateException - если уже подключено

См. также:

getAllowUserInteraction()

getAllowUserInteraction

public boolean getAllowUserInteraction()

Возвращает значение поля allowUserInteraction для этого объекта.

Возвращает:

значение поля allowUserInteraction для этого объекта.

См. также:

setAllowUserInteraction(boolean)

setDefaultAllowUserInteraction

public static void setDefaultAllowUserInteraction(boolean defaultallowuserinteraction)

Устанавливает значение поля allowUserInteraction по умолчанию для всех будущих объектов URLConnection на указанное значение.

Параметры:

defaultallowuserinteraction - новое значение.

См. также:

getDefaultAllowUserInteraction()

getDefaultAllowUserInteraction

public static boolean getDefaultAllowUserInteraction()

Возвращает:

значение поля allowUserInteraction по умолчанию.

См. также:

setDefaultAllowUserInteraction(boolean)

setUseCaches

public void setUseCaches(boolean usecaches)

Параметры:

usecaches - значение, указывающее, разрешено ли кэширование

Имеет:

IllegalStateException - если уже подключено

См. также:

getUseCaches()

getUseCaches

public boolean getUseCaches()

Возвращает значение поля URLConnection этого useCaches.

Возвращает:

значение поля URLConnection этого useCaches.

См. также:

setUseCaches(boolean)

setIfModifiedSince

public void setIfModifiedSince(long ifmodifiedsince)

Устанавливает значение поля ifModifiedSince этого URLConnection на указанное значение.

Параметры:

ifmodifiedsince - новое значение.

Имеет:

IllegalStateException - если уже подключено

См. также:

getIfModifiedSince()

getIfModifiedSince

public long getIfModifiedSince()

Возвращает значение поля ifModifiedSince этого объекта.

Возвращает:

значение поля ifModifiedSince этого объекта.

См. также:

setIfModifiedSince(long)

getDefaultUseCaches

public boolean getDefaultUseCaches()

Возвращает:

значение флага URLConnection по умолчанию для useCaches.

См. также:

setDefaultUseCaches(boolean)

setDefaultUseCaches

public void setDefaultUseCaches(boolean defaultusecaches)

Устанавливает значение поля useCaches по умолчанию на указанное значение.

Параметры:

defaultusecaches - новое значение.

См. также:

getDefaultUseCaches()

setRequestProperty

public void setRequestProperty(String key,
                               String value)

Параметры:

key - ключевое слово, по которому известен запрос (например, "Accept").

value - ассоциированное с ним значение.

Имеет:

IllegalStateException - если уже подключено

NullPointerException - если ключ null

См. также:

getRequestProperty(java.lang.String)

addRequestProperty

public void addRequestProperty(String key,
                               String value)

Добавляет общее свойство запроса, заданное парой ключ-значение. Этот метод не будет перезаписывать существующие значения, связанные с тем же ключом.

Параметры:

key - ключевое слово, по которому известен запрос (например, "Accept").

value - значение, связанное с ним.

Исключения:

IllegalStateException - если уже подключено

NullPointerException - если ключ равен null

С:

1.4

См. также:

getRequestProperties()

getRequestProperty

public String getRequestProperty(String key)

Возвращает значение запрошенного свойства для этого подключения.

Параметры:

key - ключевое слово, по которому известен запрос (например, "Accept").

Возвращает:

значение указанного свойства запроса для этого соединения. Если ключ равен null, возвращается null.

Исключения:

IllegalStateException - если уже подключено

См. также:

setRequestProperty(java.lang.String, java.lang.String)

getRequestProperties

public Map<String,List<String>> getRequestProperties()

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

Возвращает:

карта общих свойств запроса для этого подключения.

Исключения:

IllegalStateException - если уже подключено

С:

1.4

setDefaultRequestProperty

@Deprecated
public static void setDefaultRequestProperty(String key,
                                                         String value)

Устарело. Следует использовать метод setRequestProperty для конкретного экземпляра URLConnection после получения соответствующего экземпляра URLConnection. Вызов этого метода не окажет никакого влияния.

Устанавливает значение по умолчанию для общего свойства запроса. Когда создается URLConnection, он инициализируется этими свойствами.

Параметры:

key - ключевое слово, по которому известен запрос (например, "Accept").

value - значение, связанное с ключом.

См. также:

setRequestProperty(java.lang.String,java.lang.String), getDefaultRequestProperty(java.lang.String)

getDefaultRequestProperty

@Deprecated
public static String getDefaultRequestProperty(String key)

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

Возвращает значение свойства запроса по умолчанию. Свойства запроса по умолчанию устанавливаются для каждого подключения.

Параметры:

key - ключевое слово, по которому известен запрос (например, "Accept").

Возвращает:

значение свойства запроса по умолчанию для указанного ключа.

См. также:

getRequestProperty(java.lang.String), setDefaultRequestProperty(java.lang.String, java.lang.String)

setContentHandlerFactory

public static void setContentHandlerFactory(ContentHandlerFactory fac)

Параметры:

fac - требуемый фабрика.

Исключения:

Error - если фабрика уже определена.

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

См. также:

ContentHandlerFactory, getContent(), SecurityManager.checkSetFactory()

guessContentTypeFromName

public static String guessContentTypeFromName(String fname)

Попытка определить тип содержимого объекта на основе указанной части "файл" URL-адреса. Это удобный метод, который могут использовать подклассы, переопределяющие метод getContentType.

Параметры:

fname - имя файла.

Возвращает:

предположение о типе содержимого объекта на основе его имени файла.

См. также:

getContentType()

guessContentTypeFromStream

public static String guessContentTypeFromStream(InputStream is)
                                         throws IOException

Параметры:

is - входной поток, поддерживающий метки.

Возвращает:

предположение о типе содержимого или null, если тип определить невозможно.

Исключения:

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

См. также:

InputStream.mark(int), InputStream.markSupported(), getContentType()