Module  java.base
软件包  java.net

Class HttpURLConnection

  • 已知直接子类：
    HttpsURLConnection 

    public abstract class HttpURLConnection
extends URLConnection
    支持HTTP特定功能的URLConnection。 详见the spec 。

    每个HttpURLConnection实例用于单个请求，但是到HTTP服务器的底层网络连接可能被其他实例透明地共享。 在请求之后，在HttpURLConnection的InputStream或OutputStream上调用close（）方法可以释放与该实例关联的网络资源，但对任何共享持久连接没有影响。 调用disconnect（）方法可能会关闭底层套接字，如果持久连接当时是空闲的。

    HTTP协议处理程序有一些可以通过系统属性访问的设置。 这包括Proxy settings以及various other settings 。

    安全权限

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

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

    从以下版本开始：
    1.1
    另请参见：
    disconnect()

    • 字段详细信息

      • 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
        一个int代表三位数的HTTP状态码。
        • 1xx：信息
        • 2xx：成功
        • 3xx：重定向
        • 4xx：客户端错误
        • 5xx：服务器错误

      • responseMessage

        protected String responseMessage
        HTTP响应消息。

      • instanceFollowRedirects

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

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

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

        另请参见：
        setInstanceFollowRedirects(boolean) ， getInstanceFollowRedirects() ， setFollowRedirects(boolean)

      • HTTP_OK

        public static final int HTTP_OK
        HTTP状态码200：确定。
        另请参见：
        Constant Field Values

      • HTTP_CREATED

        public static final int HTTP_CREATED
        HTTP状态代码201：创建。
        另请参见：
        Constant Field Values

      • HTTP_ACCEPTED

        public static final int HTTP_ACCEPTED
        HTTP状态码202：接受。
        另请参见：
        Constant Field Values

      • HTTP_NOT_AUTHORITATIVE

        public static final int HTTP_NOT_AUTHORITATIVE
        HTTP状态码203：非授权信息。
        另请参见：
        Constant Field Values

      • HTTP_NO_CONTENT

        public static final int HTTP_NO_CONTENT
        HTTP状态代码204：无内容。
        另请参见：
        Constant Field Values

      • HTTP_RESET

        public static final int HTTP_RESET
        HTTP状态码205：重置内容。
        另请参见：
        Constant Field Values

      • HTTP_PARTIAL

        public static final int HTTP_PARTIAL
        HTTP状态码206：部分内容。
        另请参见：
        Constant Field Values

      • HTTP_MULT_CHOICE

        public static final int HTTP_MULT_CHOICE
        HTTP状态代码300：多个选择。
        另请参见：
        Constant Field Values

      • HTTP_MOVED_PERM

        public static final int HTTP_MOVED_PERM
        HTTP状态代码301：永久移动。
        另请参见：
        Constant Field Values

      • HTTP_MOVED_TEMP

        public static final int HTTP_MOVED_TEMP
        HTTP状态码302：临时重定向。
        另请参见：
        Constant Field Values

      • HTTP_SEE_OTHER

        public static final int HTTP_SEE_OTHER
        HTTP状态码303：查看其他。
        另请参见：
        Constant Field Values

      • HTTP_NOT_MODIFIED

        public static final int HTTP_NOT_MODIFIED
        HTTP状态码304：未修改。
        另请参见：
        Constant Field Values

      • HTTP_USE_PROXY

        public static final int HTTP_USE_PROXY
        HTTP状态码305：使用代理。
        另请参见：
        Constant Field Values

      • HTTP_BAD_REQUEST

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

      • HTTP_UNAUTHORIZED

        public static final int HTTP_UNAUTHORIZED
        HTTP状态码401：未经授权
        另请参见：
        Constant Field Values

      • HTTP_PAYMENT_REQUIRED

        public static final int HTTP_PAYMENT_REQUIRED
        HTTP状态码402：需要支付。
        另请参见：
        Constant Field Values

      • HTTP_FORBIDDEN

        public static final int HTTP_FORBIDDEN
        HTTP状态码403：禁止。
        另请参见：
        Constant Field Values

      • HTTP_NOT_FOUND

        public static final int HTTP_NOT_FOUND
        HTTP状态码404：未找到。
        另请参见：
        Constant Field Values

      • HTTP_BAD_METHOD

        public static final int HTTP_BAD_METHOD
        HTTP状态代码405：不允许的方法。
        另请参见：
        Constant Field Values

      • HTTP_NOT_ACCEPTABLE

        public static final int HTTP_NOT_ACCEPTABLE
        HTTP状态码406：不可接受
        另请参见：
        Constant Field Values

      • HTTP_PROXY_AUTH

        public static final int HTTP_PROXY_AUTH
        HTTP状态码407：需要代理验证。
        另请参见：
        Constant Field Values

      • HTTP_CLIENT_TIMEOUT

        public static final int HTTP_CLIENT_TIMEOUT
        HTTP状态码408：请求超时。
        另请参见：
        Constant Field Values

      • HTTP_CONFLICT

        public static final int HTTP_CONFLICT
        HTTP状态代码409：冲突。
        另请参见：
        Constant Field Values

      • HTTP_GONE

        public static final int HTTP_GONE
        HTTP状态代码410：没有。
        另请参见：
        Constant Field Values

      • HTTP_LENGTH_REQUIRED

        public static final int HTTP_LENGTH_REQUIRED
        HTTP状态码411：需要长度。
        另请参见：
        Constant Field Values

      • HTTP_PRECON_FAILED

        public static final int HTTP_PRECON_FAILED
        HTTP状态码412：前提条件失败。
        另请参见：
        Constant Field Values

      • HTTP_ENTITY_TOO_LARGE

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

      • HTTP_REQ_TOO_LONG

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

      • HTTP_UNSUPPORTED_TYPE

        public static final int HTTP_UNSUPPORTED_TYPE
        HTTP状态码415：不支持的媒体类型。
        另请参见：
        Constant Field Values

      • HTTP_SERVER_ERROR

        @Deprecated
public static final int HTTP_SERVER_ERROR
        已过时。 它是错误的，不应该存在。
        HTTP状态码500：内部服务器错误。
        另请参见：
        Constant Field Values

      • HTTP_INTERNAL_ERROR

        public static final int HTTP_INTERNAL_ERROR
        HTTP状态码500：内部服务器错误。
        另请参见：
        Constant Field Values

      • HTTP_NOT_IMPLEMENTED

        public static final int HTTP_NOT_IMPLEMENTED
        HTTP状态码501：未实现。
        另请参见：
        Constant Field Values

      • HTTP_BAD_GATEWAY

        public static final int HTTP_BAD_GATEWAY
        HTTP状态码502：坏网关。
        另请参见：
        Constant Field Values

      • HTTP_UNAVAILABLE

        public static final int HTTP_UNAVAILABLE
        HTTP状态码503：服务不可用。
        另请参见：
        Constant Field Values

      • HTTP_GATEWAY_TIMEOUT

        public static final int HTTP_GATEWAY_TIMEOUT
        HTTP状态代码504：网关超时。
        另请参见：
        Constant Field Values

      • HTTP_VERSION

        public static final int HTTP_VERSION
        HTTP状态码505：不支持HTTP版本。
        另请参见：
        Constant Field Values

    • 构造方法详细信息

      • HttpURLConnection

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

    • 方法详细信息

      • setAuthenticator

        public void setAuthenticator​(Authenticator auth)
        提供一个Authenticator ，通过HTTP协议为此HttpURLConnection请求认证时使用。 如果没有提供验证码，将使用default authenticator 。
        实现要求：
        该方法的默认行为是无条件抛出UnsupportedOperationException 。 的具体实现HttpURLConnection支持供给Authenticator特定HttpURLConnection实例应该重写此方法来实现不同的行为。
        Implementation Note:
        根据认证方案，实现可能需要使用提供的认证器来获取密码。 例如，如果这些库被配置为这样做，依赖于第三方安全库的实现可能仍然会调用默认验证器。 同样，支持透明NTLM身份验证的实现可能会在调用提供的身份验证者之前先尝试使用系统用户凭据进行连接。
        然而，如果具体提供的认证，则底层的连接可以仅针对重用HttpURLConnection实例共享同一Authenticator实例，认证信息，如果高速缓存，可以仅重新使用用于HttpURLConnection共享同一Authenticator 。
        参数
        auth - Authenticator应该由这个 HttpURLConnection 。
        异常
        UnsupportedOperationException - 如果底层实现不支持设置Authenticator。
        IllegalStateException - 如果URLConnection已连接。
        NullPointerException - 如果提供的 auth是 null 。
        从以下版本开始：
        9

      • getHeaderFieldKey

        public String getHeaderFieldKey​(int n)
        返回的关键n th头字段。 一些实现可以治疗0 th头字段作为特殊的，即由HTTP服务器返回的状态行。 在这种情况下， getHeaderField(0)返回状态行，但是getHeaderFieldKey(0)返回null。
        重写：
        getHeaderFieldKey在 URLConnection
        参数
        n - 一个索引，其中 n >=0 。
        结果
        的键控 n th头字段，或者 null如果键不存在。

      • setFixedLengthStreamingMode

        public void setFixedLengthStreamingMode​(int contentLength)
        当预先知道内容长度时，此方法用于启用HTTP请求体的流式传输，而无需内部缓冲。

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

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

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

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

        参数
        contentLength - 将要写入OutputStream的字节数。
        异常
        IllegalStateException - 如果URLConnection已连接，或者是否已启用不同的流式传输模式。
        IllegalArgumentException - 如果指定内容长度小于零。
        从以下版本开始：
        1.5
        另请参见：
        setChunkedStreamingMode(int)

      • 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 - 要在每个块中写入的字节数。 如果chunklen小于或等于零，将使用默认值。
        异常
        IllegalStateException - 如果URLConnection已连接或者已启用不同的流式传输模式。
        从以下版本开始：
        1.5
        另请参见：
        setFixedLengthStreamingMode(int)

      • getHeaderField

        public String getHeaderField​(int n)
        返回的值n th头字段。 一些实现可以治疗0 th头字段作为特殊的，即由HTTP服务器返回的状态行。

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

        重写：
        getHeaderField在 URLConnection
        参数
        n - 一个索引，其中 n>=0 。
        结果
        所述的值 n th头字段，或者 null如果该值不存在。
        另请参见：
        getHeaderFieldKey(int)

      • setFollowRedirects

        public static void setFollowRedirects​(boolean set)
        设置HTTP重定向（具有响应代码3xx的请求）是否应该在该类之后自动跟随。 默认为true。 Applet无法更改此变量。

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

        参数
        set - 表示是否遵循HTTP重定向的 boolean 。
        异常
        SecurityException - 如果存在安全管理员，并且其 checkSetFactory方法不允许该操作。
        另请参见：
        SecurityManager.checkSetFactory() ， getFollowRedirects()

      • getFollowRedirects

        public static boolean getFollowRedirects​()
        返回一个 boolean指示是否应自动跟踪HTTP重定向（3xx）。
        结果
        true如果HTTP重定向应该自动跟随， false如果没有。
        另请参见：
        setFollowRedirects(boolean)

      • setInstanceFollowRedirects

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

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

        参数
        followRedirects - 一个表示是否遵循HTTP重定向的 boolean 。
        从以下版本开始：
        1.3
        另请参见：
        instanceFollowRedirects ， getInstanceFollowRedirects()

      • getInstanceFollowRedirects

        public boolean getInstanceFollowRedirects​()
        返回此 HttpURLConnection的 instanceFollowRedirects字段的值。
        结果
        该值为 HttpURLConnection的 instanceFollowRedirects字段。
        从以下版本开始：
        1.3
        另请参见：
        instanceFollowRedirects ， setInstanceFollowRedirects(boolean)

      • setRequestMethod

        public void setRequestMethod​(String method)
                      throws ProtocolException
        设置URL请求的方法，其中之一：
        • 得到
        • POST
        • 头
        • OPTIONS
        • 放
        • 删除
        • 跟踪
        符合协议限制。 默认方法是GET。
        参数
        method - HTTP方法
        异常
        ProtocolException - 如果方法无法重置或请求的方法对HTTP无效。
        SecurityException - 如果设置了安全管理器，并且方法为“TRACE”，但未授予“allowHttpTrace”NetPermission。
        另请参见：
        getRequestMethod()

      • getResponseCode

        public int getResponseCode​()
                    throws IOException
        从HTTP响应消息获取状态代码。 例如，在以下状态行的情况下： 
          HTTP/1.0 200 OK
 HTTP/1.0 401 Unauthorized
        它将分别返回200和401。 如果不能从响应中识别出代码（即响应无效），则返回-1。
        结果
        HTTP状态代码或-1
        异常
        IOException - 如果连接到服务器发生错误。

      • getResponseMessage

        public String getResponseMessage​()
                          throws IOException
        获取与服务器的响应代码一起返回的HTTP响应消息（如果有）。 从响应如： 
          HTTP/1.0 200 OK
 HTTP/1.0 404 Not Found
        分别提取字符串“确定”和“未找到”。 如果无法从响应中识别出结果（结果无效HTTP），则返回null。
        结果
        HTTP响应消息，或 null
        异常
        IOException - 如果连接到服务器发生错误。

      • getHeaderFieldDate

        public long getHeaderFieldDate​(String name,
                               long Default)
        说明从类别复制URLConnection
        返回以日期解析的命名字段的值。 结果是自1970年1月1日GMT以指定字段表示的毫秒数。

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

        重写：
        getHeaderFieldDate在 URLConnection
        参数
        name - 标题字段的名称。
        Default - 默认值。
        结果
        该字段的值被解析为日期。 如果字段丢失或格式错误，则返回Default参数的值。

      • disconnect

        public abstract void disconnect​()
        表示在不久的将来不太可能对服务器的其他请求。 调用disconnect（）不应该意味着这个HttpURLConnection实例可以重用于其他请求。

      • usingProxy

        public abstract boolean usingProxy​()
        指示连接正在通过代理。
        结果
        一个布尔值，指示连接是否正在使用代理。

      • getErrorStream

        public InputStream getErrorStream​()
        如果连接失败但服务器发送有用的数据，则返回错误流。 典型的例子是当一个HTTP服务器响应一个404，这将导致FileNotFoundException在连接中抛出，但是服务器发送了一个HTML帮助页面，并提供了关于该做什么的建议。

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

        结果
        错误流（如果有），如果没有出现错误，则为null，连接未连接或服务器没有发送有用数据。