模块 java.base
包 java.net

类 HttpURLConnection

java.lang.Object
java.net.URLConnection
java.net.HttpURLConnection
已知子类：
HttpsURLConnection
public abstract class HttpURLConnection extends URLConnection
支持 HTTP 特定功能的 URLConnection。有关详细信息，请参阅 规范。

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

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

安全权限

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

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

自从：
1.1
参见：

  • 字段详细信息

    • method

      protected String  method
      HTTP 方法（GET、POST、PUT 等）。

    • chunkLength

      protected int chunkLength
      使用分块编码流模式输出时的分块长度。 -1 的值表示对输出禁用分块编码。
      自从：
      1.5

    • fixedContentLength

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

      NOTE:建议使用 fixedContentLengthLong 而不是此字段，因为它允许设置更大的内容长度。

      自从：
      1.5

    • fixedContentLengthLong

      protected long fixedContentLengthLong
      使用固定长度流模式时的固定内容长度。 -1 的值表示为输出禁用固定长度流模式。
      自从：
      1.7

    • responseCode

      protected int responseCode
      int 表示三位数的 HTTP 状态代码。
      • 1xx：信息性
      • 2xx：成功
      • 3xx：重定向
      • 4xx：客户端错误
      • 5xx：服务错误

    • responseMessage

      protected String  responseMessage
      HTTP 响应消息。

    • instanceFollowRedirects

      protected boolean instanceFollowRedirects
      如果 true ，协议将自动遵循重定向。如果是 false ，协议将不会自动遵循重定向。

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

      它的默认值基于 HttpURLConnection 构造时静态 followRedirects 的值。

      参见：

    • HTTP_OK

      public static final int HTTP_OK
      HTTP 状态代码 200：好的。
      参见：

    • HTTP_CREATED

      public static final int HTTP_CREATED
      HTTP 状态代码 201：已创建。
      参见：

    • HTTP_ACCEPTED

      public static final int HTTP_ACCEPTED
      HTTP 状态代码 202：已接受。
      参见：

    • HTTP_NOT_AUTHORITATIVE

      public static final int HTTP_NOT_AUTHORITATIVE
      HTTP 状态代码 203：非权威信息。
      参见：

    • HTTP_NO_CONTENT

      public static final int HTTP_NO_CONTENT
      HTTP 状态代码 204：无内容。
      参见：

    • HTTP_RESET

      public static final int HTTP_RESET
      HTTP 状态代码 205：重置内容。
      参见：

    • HTTP_PARTIAL

      public static final int HTTP_PARTIAL
      HTTP 状态代码 206：部分内容。
      参见：

    • HTTP_MULT_CHOICE

      public static final int HTTP_MULT_CHOICE
      HTTP 状态代码 300：多项选择。
      参见：

    • 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_SEE_OTHER

      public static final int HTTP_SEE_OTHER
      HTTP 状态代码 303：参见其他。
      参见：

    • HTTP_NOT_MODIFIED

      public static final int HTTP_NOT_MODIFIED
      HTTP 状态代码 304：未修改。
      参见：

    • HTTP_USE_PROXY

      public static final int HTTP_USE_PROXY
      HTTP 状态代码 305：使用代理。
      参见：

    • HTTP_BAD_REQUEST

      public static final int HTTP_BAD_REQUEST
      HTTP 状态代码 400：错误请求。
      参见：

    • HTTP_UNAUTHORIZED

      public static final int HTTP_UNAUTHORIZED
      HTTP 状态代码 401：未经授权。
      参见：

    • HTTP_PAYMENT_REQUIRED

      public static final int HTTP_PAYMENT_REQUIRED
      HTTP 状态代码 402：需要付款。
      参见：

    • HTTP_FORBIDDEN

      public static final int HTTP_FORBIDDEN
      HTTP 状态代码 403：禁止访问。
      参见：

    • HTTP_NOT_FOUND

      public static final int HTTP_NOT_FOUND
      HTTP 状态代码 404：未找到。
      参见：

    • HTTP_BAD_METHOD

      public static final int HTTP_BAD_METHOD
      HTTP 状态代码 405：方法不允许。
      参见：

    • HTTP_NOT_ACCEPTABLE

      public static final int HTTP_NOT_ACCEPTABLE
      HTTP 状态代码 406：不可接受。
      参见：

    • HTTP_PROXY_AUTH

      public static final int HTTP_PROXY_AUTH
      HTTP 状态代码 407：需要代理身份验证。
      参见：

    • HTTP_CLIENT_TIMEOUT

      public static final int HTTP_CLIENT_TIMEOUT
      HTTP 状态代码 408：请求超时。
      参见：

    • HTTP_CONFLICT

      public static final int HTTP_CONFLICT
      HTTP 状态代码 409：冲突。
      参见：

    • HTTP_GONE

      public static final int HTTP_GONE
      HTTP 状态代码 410：消失。
      参见：

    • HTTP_LENGTH_REQUIRED

      public static final int HTTP_LENGTH_REQUIRED
      HTTP 状态代码 411：需要长度。
      参见：

    • HTTP_PRECON_FAILED

      public static final int HTTP_PRECON_FAILED
      HTTP 状态代码 412：前提条件失败。
      参见：

    • HTTP_ENTITY_TOO_LARGE

      public static final int HTTP_ENTITY_TOO_LARGE
      HTTP 状态代码 413：请求实体太大。
      参见：

    • HTTP_REQ_TOO_LONG

      public static final int HTTP_REQ_TOO_LONG
      HTTP 状态代码 414：请求 URI 太大。
      参见：

    • HTTP_UNSUPPORTED_TYPE

      public static final int HTTP_UNSUPPORTED_TYPE
      HTTP 状态代码 415：不支持的媒体类型。
      参见：

    • HTTP_SERVER_ERROR

      @Deprecated public static final int HTTP_SERVER_ERROR
      已弃用。
      它放错了地方，不应该存在。
      HTTP 状态代码 500：内部服务错误。
      参见：

    • HTTP_INTERNAL_ERROR

      public static final int HTTP_INTERNAL_ERROR
      HTTP 状态代码 500：内部服务错误。
      参见：

    • HTTP_NOT_IMPLEMENTED

      public static final int HTTP_NOT_IMPLEMENTED
      HTTP 状态代码 501：未实现。
      参见：

    • HTTP_BAD_GATEWAY

      public static final int HTTP_BAD_GATEWAY
      HTTP 状态代码 502：错误的网关。
      参见：

    • HTTP_UNAVAILABLE

      public static final int HTTP_UNAVAILABLE
      HTTP 状态代码 503：服务不可用。
      参见：

    • HTTP_GATEWAY_TIMEOUT

      public static final int HTTP_GATEWAY_TIMEOUT
      HTTP 状态代码 504：网关超时。
      参见：

    • HTTP_VERSION

      public static final int HTTP_VERSION
      HTTP 状态代码 505：不支持的 HTTP 版本。
      参见：

  • 构造方法详细信息

    • HttpURLConnection

      protected HttpURLConnection(URL  u)
      HttpURLConnection 的构造方法。
      参数：
      u - 网址

  • 方法详情

    • setAuthenticator

      public void setAuthenticator(Authenticator  auth)
      提供一个 Authenticator 以在通过 HTTP 协议为此 HttpURLConnection 请求身份验证时使用。如果未提供身份验证器，将使用 默认验证器。
      实现要求：
      此方法的默认行为是无条件抛出 UnsupportedOperationException 。支持为特定 HttpURLConnection 实例提供 Authenticator 的 HttpURLConnection 的具体实现应该覆盖此方法以实现不同的行为。
      实现注意事项：
      根据身份验证方案，实现可能需要也可能不需要使用提供的身份验证器来获取密码。例如，如果这些库被配置为这样做，那么依赖第三方安全库的实现可能仍会调用默认身份验证器。同样，支持透明 NTLM 身份验证的实现可以让系统在调用提供的身份验证器之前首先尝试使用系统用户凭据进行连接。
      但是，如果专门提供了身份验证器，则基础连接可能仅可重用于共享相同 Authenticator 实例的 HttpURLConnection 实例，并且身份验证信息（如果已缓存）仅可重用于共享相同 Authenticator 的 HttpURLConnection 实例。
      参数：
      auth - 这个 HttpURLConnection 应该使用的 Authenticator。
      抛出：
      UnsupportedOperationException - 如果底层实现不支持设置 Authenticator。
      IllegalStateException - 如果 URLConnection 已经连接。
      NullPointerException - 如果提供的 auth 是 null。
      自从：
      9

    • getHeaderFieldKey

      public String  getHeaderFieldKey(int n)
      返回 n 的密钥日标题字段。一些实现可能会处理0日标头字段作为特殊的，即作为 HTTP 服务返回的状态行。在这种情况下，getHeaderField(0) 返回状态行，但 getHeaderFieldKey(0) 返回 null。
      重写：
      getHeaderFieldKey 在类 URLConnection 中
      参数：
      n - 一个索引，其中 n >=0 。
      返回：
      n 的关键日标头字段，或者 null 如果密钥不存在。

    • setFixedLengthStreamingMode

      public void setFixedLengthStreamingMode(int contentLength)
      当事先知道内容长度时，此方法用于在没有内部缓冲的情况下启用 HTTP 请求主体的流式传输。

      如果应用程序尝试写入比指示的内容长度更多的数据，或者如果应用程序在写入指示的数量之前关闭 OutputStream，将抛出异常。

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

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

      NOTE:建议使用 setFixedLengthStreamingMode(long) 而不是此方法，因为它允许设置更大的内容长度。

      参数：
      contentLength - 将写入 OutputStream 的字节数。
      抛出：
      IllegalStateException - 如果 URLConnection 已连接或已启用不同的流模式。
      IllegalArgumentException - 如果指定的内容长度小于零。
      自从：
      1.5
      参见：

    • setFixedLengthStreamingMode

      public void setFixedLengthStreamingMode(long contentLength)
      当事先知道内容长度时，此方法用于在没有内部缓冲的情况下启用 HTTP 请求主体的流式传输。

      如果应用程序尝试写入比指示的内容长度更多的数据，或者如果应用程序在写入指示的数量之前关闭 OutputStream，将抛出异常。

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

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

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

      参数：
      contentLength - 将写入 OutputStream 的字节数。
      抛出：
      IllegalStateException - 如果 URLConnection 已连接或已启用不同的流模式。
      IllegalArgumentException - 如果指定的内容长度小于零。
      自从：
      1.7

    • setChunkedStreamingMode

      public void setChunkedStreamingMode(int chunklen)
      当内容长度为not提前知道。在这种模式下，分块传输编码用于发送请求体。请注意，并非所有 HTTP 服务都支持此模式。

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

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

      参数：
      chunklen - 每个块中要写入的字节数。如果 chunklen 小于或等于零，将使用默认值。
      抛出：
      IllegalStateException - 如果 URLConnection 已连接或已启用不同的流模式。
      自从：
      1.5
      参见：

    • getHeaderField

      public String  getHeaderField(int n)
      返回 n 的值日标题字段。一些实现可能会处理0日标头字段作为特殊的，即作为 HTTP 服务返回的状态行。

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

      重写：
      getHeaderField 在类 URLConnection 中
      参数：
      n - 一个索引，其中 n>=0 。
      返回：
      n的值日标头字段，或者 null 如果该值不存在。
      参见：

    • setFollowRedirects

      public static void setFollowRedirects(boolean set)
      设置此类是否应自动遵循 HTTP 重定向（响应代码为 3xx 的请求）。默认情况下为真。小程序无法更改此变量。

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

      参数：
      set - 一个 boolean 指示是否遵循 HTTP 重定向。
      抛出：
      SecurityException - 如果安全管理器存在且其 checkSetFactory 方法不允许该操作。
      参见：

    • getFollowRedirects

      public static boolean getFollowRedirects()
      返回一个 boolean 指示是否应自动遵循 HTTP 重定向 (3xx)。
      返回：
      true 是否应自动遵循 HTTP 重定向，false 否则。
      参见：

    • setInstanceFollowRedirects

      public void setInstanceFollowRedirects(boolean followRedirects)
      设置此 HttpURLConnection 实例是否应自动遵循 HTTP 重定向（响应代码为 3xx 的请求）。

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

      参数：
      followRedirects - 一个 boolean 指示是否遵循 HTTP 重定向。
      自从：
      1.3
      参见：

    • getInstanceFollowRedirects

      public boolean getInstanceFollowRedirects()
      返回此 HttpURLConnection 的 instanceFollowRedirects 字段的值。
      返回：
      这个 HttpURLConnection 的 instanceFollowRedirects 字段的值。
      自从：
      1.3
      参见：

    • setRequestMethod

      public void setRequestMethod(String  method) throws ProtocolException
      设置 URL 请求的方法，可以是：
      • GET
      • POST
      • HEAD
      • OPTIONS
      • PUT
      • DELETE
      • TRACE
      是合法的，受协议限制。默认方法是 GET。
      参数：
      method - HTTP 方法
      抛出：
      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
      抛出：
      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
      抛出：
      IOException - 如果连接到服务时发生错误。

    • disconnect

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

    • usingProxy

      public abstract boolean usingProxy()
      指示连接是否通过代理。如果已知连接正在进行或已经通过代理，则此方法返回 true；如果连接永远不会通过代理或无法确定是否使用代理，则返回 false。
      返回：
      指示连接是否使用代理的boolean。

    • getPermission

      public Permission  getPermission() throws IOException
      返回一个 SocketPermission 对象，表示连接到目标主机和端口所需的权限。
      重写：
      getPermission 在类 URLConnection 中
      返回：
      一个 SocketPermission 对象，表示连接到目标主机和端口所需的权限。
      抛出：
      IOException - 如果在计算权限时发生错误。

    • getErrorStream

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

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

      返回：
      错误流（如果有），如果没有错误、连接未连接或服务未发送任何有用数据，则为 null。