Module java.base
Package java.net

Class 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
另请参阅:

  • Field Details

    • method

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

    • chunkLength

      protected int chunkLength
      在使用分块编码流模式进行输出时的块长度。值为-1表示已禁用输出的分块编码。
      自版本:
      1.5

    • fixedContentLength

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

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

      自版本:
      1.5

    • fixedContentLengthLong

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

    • responseCode

      protected int responseCode
      代表三位数HTTP状态码的int。
      • 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
      Deprecated.
      it is misplaced and shouldn't have existed.
      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版本。
      参见：

  • Constructor Details

    • HttpURLConnection

      protected HttpURLConnection(URL u)
      HttpURLConnection的构造函数。
      参数：
      u - URL

  • Method Details

    • setAuthenticator

      public void setAuthenticator(Authenticator auth)
      为此HttpURLConnection请求HTTP协议时使用的Authenticator提供支持。如果未提供认证器，则将使用默认认证器。
      实现要求：
      此方法的默认行为是无条件地抛出UnsupportedOperationException。支持为特定HttpURLConnection实例提供Authenticator的具体实现应覆盖此方法以实现不同的行为。
      实现说明：
      根据认证方案，实现可能需要或不需要使用提供的认证器来获取密码。例如，依赖第三方安全库的实现仍可能调用默认认证器，如果这些库配置为这样做。同样，支持透明NTLM认证的实现可能会让系统首先尝试使用系统用户凭据进行连接，然后再调用提供的认证器。
      但是，如果专门提供了认证器，则底层连接可能仅用于共享相同Authenticator实例的HttpURLConnection实例，并且如果已缓存认证信息，则仅可用于共享该相同Authenticator的HttpURLConnection。
      参数：
      auth - 应该由此HttpURLConnection使用的Authenticator。
      抛出：
      UnsupportedOperationException - 如果底层实现不支持设置认证器。
      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。
      返回：
      第 nth 头字段的键，如果键不存在则返回 null。

    • setFixedLengthStreamingMode

      public void setFixedLengthStreamingMode(int contentLength)
      此方法用于在内容长度事先已知的情况下启用 HTTP 请求体的流式传输，而无需内部缓冲。

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

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

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

      注意：建议使用 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)
      此方法用于在内容长度事先未知的情况下启用 HTTP 请求体的流式传输。在此模式下，使用分块传输编码来发送请求体。请注意，并非所有 HTTP 服务器都支持此模式。

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

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

      参数：
      chunklen - 每个块中要写入的字节数，包括一个十六进制字符串作为块大小标头（至少 1 字节）、两个 CRLF（4 字节）和最小有效载荷长度为 1 字节。如果 chunklen 小于或等于 5，则将使用更高的默认值。
      抛出：
      IllegalStateException - 如果 URLConnection 已连接或已启用不同的流模式。
      自：
      1.5
      参见：

    • getHeaderField

      public String getHeaderField(int n)
      返回第 nth 头字段的值。某些实现可能将第 0th 头字段视为特殊字段，即作为 HTTP 服务器返回的状态行。

      此方法可与 getHeaderFieldKey 方法一起使用，以遍历消息中的所有头字段。

      覆盖：
      getHeaderField 在类 URLConnection
      参数：
      n - 一个索引，其中 n>=0。
      返回：
      第 nth 头字段的值，如果值不存在则返回 null。
      参见：

    • setFollowRedirects

      public static void setFollowRedirects(boolean set)
      设置此类是否应自动跟随 HTTP 重定向（响应代码为 3xx）。 默认为 true。小程序无法更改此变量。

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

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

    • getFollowRedirects

      public static boolean getFollowRedirects()
      返回一个指示是否应自动跟随 HTTP 重定向（3xx）的 boolean。
      返回：
      如果应自动跟随 HTTP 重定向，则返回 true，否则返回 false。
      参见：

    • setInstanceFollowRedirects

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

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

      参数：
      followRedirects - 一个指示是否自动跟随 HTTP 重定向的 boolean。
      自：
      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 响应消息（如果有）。从类似以下响应的响应中： 
       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。
      返回：
      一个布尔值，指示连接是否使用代理。

    • getPermission

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

    • getErrorStream

      public InputStream getErrorStream()
      如果连接失败但服务器仍然发送了有用的数据，则返回错误流。典型的例子是当HTTP服务器响应404时，在connect中将引发FileNotFoundException，但服务器发送了一个包含建议的HTML帮助页面。

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

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