鸿蒙OS HttpURLConnection

HttpURLConnection

java.lang.Object

|---java.net.URLConnection

|---|---java.net.HttpURLConnection

public abstract class HttpURLConnection
extends URLConnection

支持 HTTP 特定功能的 URLConnection。 有关详细信息，请参阅规范。

每个 HttpURLConnection 实例用于发出单个请求，但到 HTTP 服务器的底层网络连接可能会被其他实例透明地共享。 在请求之后对 HttpURLConnection 的 InputStream 或 OutputStream 调用 close() 方法可能会释放与此实例关联的网络资源，但不会影响任何共享的持久连接。 如果持续连接当时处于空闲状态，则调用 disconnect() 方法可能会关闭底层套接字。

HTTP 协议处理程序有一些可以通过系统属性访问的设置。 这包括代理设置以及各种其他设置。

安全权限

如果安装了安全管理器，并且调用了导致尝试打开连接的方法，则调用者必须拥有：-

• 连接到目标 URL 的主机/端口组合的 SocketPermission 或
• 允许此请求的 URLPermission。

如果启用了自动重定向，并且此请求被重定向到另一个目的地，那么调用者还必须有权连接到重定向的主机/URL。

字段摘要

修饰符和类型	字段	描述
protected int	chunkLength	使用分块编码流模式进行输出时的块长度。
protected int	fixedContentLength	使用固定长度流模式时的固定内容长度。
protected long	fixedContentLengthLong	使用固定长度流模式时的固定内容长度。
static int	HTTP_ACCEPTED	HTTP 状态码 202：已接受。
static int	HTTP_BAD_GATEWAY	HTTP 状态码 502：网关错误。
static int	HTTP_BAD_METHOD	HTTP 状态码 405：不允许的方法。
static int	HTTP_BAD_REQUEST	HTTP 状态码 400：错误请求。
static int	HTTP_CLIENT_TIMEOUT	HTTP 状态码 408：请求超时。
static int	HTTP_CONFLICT	HTTP 状态码 409：冲突。
static int	HTTP_CREATED	HTTP 状态码 201：已创建。
static int	HTTP_ENTITY_TOO_LARGE	HTTP 状态码 413：请求实体太大。
static int	HTTP_FORBIDDEN	HTTP 状态码 403：禁止。
static int	HTTP_GATEWAY_TIMEOUT	HTTP 状态码 504：网关超时。
static int	HTTP_GONE	HTTP 状态码 410：已消失。
static int	HTTP_INTERNAL_ERROR	HTTP 状态码 500：内部服务器错误。
static int	HTTP_LENGTH_REQUIRED	HTTP 状态码 411：长度要求。
static int	HTTP_MOVED_PERM	HTTP 状态码 301：永久移动。
static int	HTTP_MOVED_TEMP	HTTP 状态码 302：临时重定向。
static int	HTTP_MULT_CHOICE	HTTP 状态码 300：多项选择。
static int	HTTP_NO_CONTENT	HTTP 状态码 204：无内容。
static int	HTTP_NOT_ACCEPTABLE	HTTP 状态码 406：不可接受。
static int	HTTP_NOT_AUTHORITATIVE	HTTP 状态码 203：非权威信息。
static int	HTTP_NOT_FOUND	HTTP 状态码 404：未找到。
static int	HTTP_NOT_IMPLEMENTED	HTTP 状态码 501：未实现。
static int	HTTP_NOT_MODIFIED	HTTP 状态码 304：未修改。
static int	HTTP_OK	HTTP 状态码 200：正常。
static int	HTTP_PARTIAL	HTTP 状态码 206：部分内容。
static int	HTTP_PAYMENT_REQUIRED	HTTP 状态码 402：需要付款。
static int	HTTP_PRECON_FAILED	HTTP 状态码 412：前提条件失败。
static int	HTTP_PROXY_AUTH	HTTP 状态码 407：需要代理身份验证。
static int	HTTP_REQ_TOO_LONG	HTTP 状态码 414：请求 URI 太大。
static int	HTTP_RESET	HTTP 状态码 205：重置内容。
static int	HTTP_SEE_OTHER	HTTP 状态码 303：请参阅其他。
static int	HTTP_SERVER_ERROR	已弃用。 它放错了地方，不应该存在。
static int	HTTP_UNAUTHORIZED	HTTP 状态码 401：未经授权。
static int	HTTP_UNAVAILABLE	HTTP 状态码 503：服务不可用。
static int	HTTP_UNSUPPORTED_TYPE	HTTP 状态码 415：不支持的媒体类型。
static int	HTTP_USE_PROXY	HTTP 状态码 305：使用代理。
static int	HTTP_VERSION	HTTP 状态码 505：不支持 HTTP 版本。
protected boolean	instanceFollowRedirects	如果为真，协议将自动遵循重定向。
protected String	method	HTTP 方法（GET、POST、PUT 等）。
protected int	responseCode	一个表示三位 HTTP 状态码的 int。
protected String	responseMessage	HTTP 响应消息。

从类 java.net.URLConnection 继承的字段
allowUserInteraction, connected, doInput, doOutput, ifModifiedSince, url, useCaches

构造函数摘要

修饰符	构造函数	描述
protected	HttpURLConnection(URL u)	HttpURLConnection 的构造函数。

方法总结

修饰符和类型	方法	描述
abstract void	disconnect()	表示在不久的将来不太可能向服务器发出其他请求。
InputStream	getErrorStream()	如果连接失败但服务器仍然发送了有用的数据，则返回错误流。
static boolean	getFollowRedirects()	返回一个布尔值，指示是否应自动遵循 HTTP 重定向 (3xx)。
String	getHeaderField(int n)	返回第 n 个标头字段的值。
long	getHeaderFieldDate(String name, long Default)	返回解析为日期的命名字段的值。
String	getHeaderFieldKey(int n)	返回第 n 个标头字段的键。
boolean	getInstanceFollowRedirects()	返回此 HttpURLConnection 的 instanceFollowRedirects 字段的值。
Permission	getPermission()	返回一个 SocketPermission 对象，表示连接到目标主机和端口所需的权限。
String	getRequestMethod()	获取请求方法。
int	getResponseCode()	从 HTTP 响应消息中获取状态代码。
String	getResponseMessage()	获取与响应代码一起从服务器返回的 HTTP 响应消息（如果有）。
void	setChunkedStreamingMode(int chunklen)	当事先不知道内容长度时，此方法用于启用没有内部缓冲的 HTTP 请求正文的流式传输。
void	setFixedLengthStreamingMode(int contentLength)	当预先知道内容长度时，此方法用于启用没有内部缓冲的 HTTP 请求正文的流式传输。
void	setFixedLengthStreamingMode(long contentLength)	当预先知道内容长度时，此方法用于启用没有内部缓冲的 HTTP 请求正文的流式传输。
static void	setFollowRedirects(boolean set)	设置该类是否应自动跟随 HTTP 重定向（响应代码为 3xx 的请求）。
void	setInstanceFollowRedirects(boolean followRedirects)	设置此 HttpURLConnection 实例是否应自动跟随 HTTP 重定向（响应代码为 3xx 的请求）。
void	setRequestMethod(String method)	设置 URL 请求的方法，其中之一： GET POST HEAD OPTIONS PUT DELETE TRACE 是合法的，受协议限制。
abstract boolean	usingProxy()	指示连接是否通过代理。

从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

从类 java.net.URLConnection 继承的方法

addRequestProperty, connect, getAllowUserInteraction, getConnectTimeout, getContent, getContent, getContentEncoding, getContentLength, getContentLengthLong, getContentType, getDate, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderFieldInt, getHeaderFieldLong, getHeaderFields, getIfModifiedSince, getInputStream, getLastModified, getOutputStream, getReadTimeout, getRequestProperties, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setConnectTimeout, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setReadTimeout, setRequestProperty, setUseCaches, toString

字段详细信息

HTTP_ACCEPTED

public static final int HTTP_ACCEPTED

HTTP 状态码 202：已接受。

HTTP_BAD_GATEWAY

public static final int HTTP_BAD_GATEWAY

HTTP 状态码 502：网关错误。

HTTP_BAD_METHOD

public static final int HTTP_BAD_METHOD

HTTP 状态码 405：不允许的方法。

HTTP_BAD_REQUEST

public static final int HTTP_BAD_REQUEST

HTTP 状态码 400：错误请求。

HTTP_CLIENT_TIMEOUT

public static final int HTTP_CLIENT_TIMEOUT

HTTP 状态码 408：请求超时。

HTTP_CONFLICT

public static final int HTTP_CONFLICT

HTTP 状态码 409：冲突。

HTTP_CREATED

public static final int HTTP_CREATED

HTTP 状态码 201：已创建。

HTTP_ENTITY_TOO_LARGE

public static final int HTTP_ENTITY_TOO_LARGE

HTTP 状态码 413：请求实体太大。

HTTP_FORBIDDEN

public static final int HTTP_FORBIDDEN

HTTP 状态码 403：禁止。

HTTP_GATEWAY_TIMEOUT

public static final int HTTP_GATEWAY_TIMEOUT

HTTP 状态码 504：网关超时。

HTTP_GONE

public static final int HTTP_GONE

HTTP 状态码 410：已消失。

HTTP_INTERNAL_ERROR

public static final int HTTP_INTERNAL_ERROR

HTTP 状态码 500：内部服务器错误。

HTTP_LENGTH_REQUIRED

public static final int HTTP_LENGTH_REQUIRED

HTTP 状态码 411：长度要求。

HTTP_MOVED_PERM

public static final int HTTP_MOVED_PERM

HTTP 状态码 301：永久移动。

HTTP_MOVED_TEMP

public static final int HTTP_MOVED_TEMP

HTTP 状态码 302：临时重定向。

HTTP_MULT_CHOICE

public static final int HTTP_MULT_CHOICE

HTTP 状态码 300：多项选择。

HTTP_NOT_ACCEPTABLE

public static final int HTTP_NOT_ACCEPTABLE

HTTP 状态码 406：不可接受。

HTTP_NOT_AUTHORITATIVE

public static final int HTTP_NOT_AUTHORITATIVE

HTTP 状态码 203：非权威信息。

HTTP_NOT_FOUND

public static final int HTTP_NOT_FOUND

HTTP 状态码 404：未找到。

HTTP_NOT_IMPLEMENTED

public static final int HTTP_NOT_IMPLEMENTED

HTTP 状态码 501：未实现。

HTTP_NOT_MODIFIED

public static final int HTTP_NOT_MODIFIED

HTTP 状态码 304：未修改。

HTTP_NO_CONTENT

public static final int HTTP_NO_CONTENT

HTTP 状态码 204：无内容。

HTTP_OK

public static final int HTTP_OK

HTTP 状态码 200：正常。

HTTP_PARTIAL

public static final int HTTP_PARTIAL

HTTP 状态码 206：部分内容。

HTTP_PAYMENT_REQUIRED

public static final int HTTP_PAYMENT_REQUIRED

HTTP 状态码 402：需要付款。

HTTP_PRECON_FAILED

public static final int HTTP_PRECON_FAILED

HTTP 状态码 412：前提条件失败。

HTTP_PROXY_AUTH

public static final int HTTP_PROXY_AUTH

HTTP 状态码 407：需要代理身份验证。

HTTP_REQ_TOO_LONG

public static final int HTTP_REQ_TOO_LONG

HTTP 状态码 414：请求 URI 太大。

HTTP_RESET

public static final int HTTP_RESET

HTTP 状态码 205：重置内容。

HTTP_SEE_OTHER

public static final int HTTP_SEE_OTHER

HTTP 状态码 303：请参阅其他。

HTTP_SERVER_ERROR

@Deprecated public static final int HTTP_SERVER_ERROR

已弃用。 它放错了地方，不应该存在。

HTTP 状态码 500：内部服务器错误。

HTTP_UNAUTHORIZED

public static final int HTTP_UNAUTHORIZED

HTTP 状态码 401：未经授权。

HTTP_UNAVAILABLE

public static final int HTTP_UNAVAILABLE

HTTP 状态码 503：服务不可用。

HTTP_UNSUPPORTED_TYPE

public static final int HTTP_UNSUPPORTED_TYPE

HTTP 状态码 415：不支持的媒体类型。

HTTP_USE_PROXY

public static final int HTTP_USE_PROXY

HTTP 状态码 305：使用代理。

HTTP_VERSION

public static final int HTTP_VERSION

HTTP 状态码 505：不支持 HTTP 版本。

chunkLength

protected int chunkLength

使用分块编码流模式进行输出时的块长度。 值 -1 表示对输出禁用分块编码。

fixedContentLength

protected int fixedContentLength

使用固定长度流模式时的固定内容长度。 值 -1 表示对输出禁用固定长度流模式。

注意：建议使用 fixedContentLengthLong 代替此字段，因为它允许设置更大的内容长度。

fixedContentLengthLong

protected long fixedContentLengthLong

使用固定长度流模式时的固定内容长度。 值 -1 表示对输出禁用固定长度流模式。

instanceFollowRedirects

protected boolean instanceFollowRedirects

如果为true，协议将自动遵循重定向。 如果为 false，协议将不会自动遵循重定向。

该字段由 setInstanceFollowRedirects 方法设置。 它的值由 getInstanceFollowRedirects 方法返回。

其默认值基于 HttpURLConnection 构建时静态 followRedirects 的值。

method

protected String method

HTTP 方法（GET、POST、PUT 等）。

responseCode

protected int responseCode

一个表示三位 HTTP 状态码的 int。

• 1xx：信息
• 2xx：成功
• 3xx：重定向
• 4xx：客户端错误
• 5xx：服务器错误

responseMessage

protected String responseMessage

HTTP 响应消息。

构造函数详细信息

HttpURLConnection

protected HttpURLConnection(URL u)

HttpURLConnection 的构造函数。

参数：

参数名称	参数描述
u	网址

方法详情

getHeaderFieldKey

public String getHeaderFieldKey(int n)

返回第 n 个标头字段的键。 某些实现可能会将第 0 个标头字段视为特殊字段，即作为 HTTP 服务器返回的状态行。 在这种情况下，getHeaderField(0) 返回状态行，但 getHeaderFieldKey(0) 返回 null。

覆盖：

类 URLConnection 中的 getHeaderFieldKey

参数：

参数名称	参数描述
n	一个索引，其中 n >=0。

返回:

第 n 个标头字段的键，如果键不存在，则返回 null。

setFixedLengthStreamingMode

public void setFixedLengthStreamingMode(int contentLength)

当预先知道内容长度时，此方法用于启用没有内部缓冲的 HTTP 请求正文的流式传输。

如果应用程序尝试写入超过指定内容长度的数据，或者应用程序在写入指定数量之前关闭了 OutputStream，则会引发异常。

启用输出流时，无法自动处理身份验证和重定向。 如果需要身份验证或重定向，则在读取响应时将抛出 HttpRetryException。 可以查询此异常以获取错误的详细信息。

此方法必须在 URLConnection 连接之前调用。

注意：建议使用 setFixedLengthStreamingMode(long) 代替此方法，因为它允许设置更大的内容长度。

参数：

参数名称	参数描述
contentLength	将写入 OutputStream 的字节数。

Throws:

Throw名称	Throw描述
IllegalStateException	如果 URLConnection 已经连接或者已经启用了不同的流模式。
IllegalArgumentException	如果指定的内容长度小于零。

setFixedLengthStreamingMode

public void setFixedLengthStreamingMode(long contentLength)

当预先知道内容长度时，此方法用于启用没有内部缓冲的 HTTP 请求正文的流式传输。

如果应用程序尝试写入超过指定内容长度的数据，或者应用程序在写入指定数量之前关闭了 OutputStream，则会引发异常。

启用输出流时，无法自动处理身份验证和重定向。 如果需要身份验证或重定向，则在读取响应时将抛出 HttpRetryException。 可以查询此异常以获取错误的详细信息。

此方法必须在 URLConnection 连接之前调用。

通过调用此方法设置的内容长度优先于由 setFixedLengthStreamingMode(int) 设置的任何值。

参数：

参数名称	参数描述
contentLength	将写入 OutputStream 的字节数。

Throws:

Throw名称	Throw描述
IllegalStateException	如果 URLConnection 已经连接或者已经启用了不同的流模式。
IllegalArgumentException	如果指定的内容长度小于零。

setChunkedStreamingMode

public void setChunkedStreamingMode(int chunklen)

当事先不知道内容长度时，此方法用于启用没有内部缓冲的 HTTP 请求正文的流式传输。 在这种模式下，分块传输编码用于发送请求正文。 注意，并不是所有的 HTTP 服务器都支持这种模式。

启用输出流时，无法自动处理身份验证和重定向。 如果需要身份验证或重定向，则在读取响应时将抛出 HttpRetryException。 可以查询此异常以获取错误的详细信息。

此方法必须在 URLConnection 连接之前调用。

参数：

参数名称	参数描述
chunklen	每个块中要写入的字节数。 如果 chunklen 小于或等于零，将使用默认值。

Throws:

Throw名称	Throw描述
IllegalStateException	如果 URLConnection 已经连接或者已经启用了不同的流模式。

getHeaderField

public String getHeaderField(int n)

返回第 n 个标头字段的值。 某些实现可能会将第 0 个标头字段视为特殊字段，即作为 HTTP 服务器返回的状态行。

此方法可以与 getHeaderFieldKey 方法结合使用，以遍历消息中的所有标头。

覆盖：

类 URLConnection 中的 getHeaderField

参数：

参数名称	参数描述
n	一个索引，其中 n>=0。

返回:

第 n 个标头字段的值，如果该值不存在，则为 null。

setFollowRedirects

public static void setFollowRedirects(boolean set)

设置该类是否应自动跟随 HTTP 重定向（响应代码为 3xx 的请求）。 默认为真。 小程序无法更改此变量。

如果有安全管理器，该方法首先调用安全管理器的 checkSetFactory 方法，确保操作被允许。 这可能会导致 SecurityException。

参数：

参数名称	参数描述
set	一个布尔值，指示是否遵循 HTTP 重定向。

Throws:

Throw名称	Throw描述
SecurityException	如果存在安全管理器并且其 checkSetFactory 方法不允许该操作。

getFollowRedirects

public static boolean getFollowRedirects()

返回一个布尔值，指示是否应自动遵循 HTTP 重定向 (3xx)。

返回:

如果应该自动遵循 HTTP 重定向，则为 true，否则为 false。

setInstanceFollowRedirects

public void setInstanceFollowRedirects(boolean followRedirects)

设置此 HttpURLConnection 实例是否应自动跟随 HTTP 重定向（响应代码为 3xx 的请求）。

默认值来自followRedirects，默认为true。

参数：

参数名称	参数描述
followRedirects	一个布尔值，指示是否遵循 HTTP 重定向。

getInstanceFollowRedirects

public boolean getInstanceFollowRedirects()

返回此 HttpURLConnection 的 instanceFollowRedirects 字段的值。

返回:

此 HttpURLConnection 的 instanceFollowRedirects 字段的值。

setRequestMethod

public void setRequestMethod(String method) throws ProtocolException

设置 URL 请求的方法，其中之一：

• GET
• POST
• HEAD
• OPTIONS
• PUT
• DELETE
• TRACE

是合法的，受协议限制。 默认方法是 GET。

参数：

参数名称	参数描述
method	HTTP方法

Throws:

Throw名称	Throw描述
ProtocolException	如果方法无法重置或者请求的方法对 HTTP 无效。
SecurityException	如果设置了安全管理器且方法为“TRACE”，但未授予“allowHttpTrace”NetPermission。

getRequestMethod

public String getRequestMethod()

获取请求方法。

返回:

HTTP 请求方法

getResponseCode

public int getResponseCode() throws IOException

从 HTTP 响应消息中获取状态代码。 例如，在以下状态行的情况下：

 HTTP/1.0 200 OK HTTP/1.0 401 Unauthorized 

它将分别返回 200 和 401。 如果无法从响应中识别出任何代码（即响应不是有效的 HTTP），则返回 -1。

返回:

HTTP 状态码，或 -1

Throws:

Throw名称	Throw描述
IOException	如果连接到服务器时发生错误。

getResponseMessage

public String getResponseMessage() throws IOException

获取与响应代码一起从服务器返回的 HTTP 响应消息（如果有）。 来自以下回复：

 HTTP/1.0 200 OK HTTP/1.0 404 Not Found 

分别提取字符串“OK”和“Not Found”。 如果无法从响应中辨别出任何内容（结果不是有效的 HTTP），则返回 null。

返回:

HTTP 响应消息，或 null

Throws:

Throw名称	Throw描述
IOException	如果连接到服务器时发生错误。

getHeaderFieldDate

public long getHeaderFieldDate(String name, long Default)

从类中复制的描述：URLConnection

返回解析为日期的命名字段的值。 结果是命名字段表示的自 1970 年 1 月 1 日 GMT 以来的毫秒数。

存在这种形式的 getHeaderField 是因为某些连接类型（例如 http-ng）具有预解析的标头。 该连接类型的类可以覆盖此方法并使解析短路。

覆盖：

类 URLConnection 中的 getHeaderFieldDate

参数：

参数名称	参数描述
name	标题字段的名称。
Default	默认值。

返回:

字段的值，解析为日期。 如果字段丢失或格式错误，则返回 Default 参数的值。

disconnect

public abstract void disconnect()

表示在不久的将来不太可能向服务器发出其他请求。 调用 disconnect() 不应暗示此 HttpURLConnection 实例可用于其他请求。

usingProxy

public abstract boolean usingProxy()

指示连接是否通过代理。

返回:

一个布尔值，指示连接是否使用代理。

getPermission

public Permission getPermission() throws IOException

返回一个 SocketPermission 对象，表示连接到目标主机和端口所需的权限。

覆盖：

类 URLConnection 中的 getPermission

返回:

一个 SocketPermission 对象，表示连接到目标主机和端口所需的权限。

Throws:

Throw名称	Throw描述
IOException	如果在计算权限时发生错误。

getErrorStream

public InputStream getErrorStream()

如果连接失败但服务器仍然发送了有用的数据，则返回错误流。 典型的例子是当 HTTP 服务器响应 404 时，这将导致在连接中抛出 FileNotFoundException，但服务器发送了一个 HTML 帮助页面，其中包含有关如何操作的建议。

此方法不会导致启动连接。 如果连接未连接，或者服务器在连接时没有错误，或者服务器有错误但没有发送错误数据，则此方法将返回 null。 这是默认设置。

返回:

如果有错误流，如果没有错误，则返回 null，连接未连接或服务器未发送有用数据。