模块  java.base
软件包  java.net

Class HttpURLConnection

  • 已知直接子类:
    HttpsURLConnection

    public abstract class HttpURLConnection
    extends URLConnection
    URLConnection,支持HTTP特定功能。 有关详细信息,请参见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构造时的静态followRedirects的值。

        另请参见:
        setInstanceFollowRedirects(boolean)getInstanceFollowRedirects()setFollowRedirects(boolean)
      • 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版本。
        另请参见:
        常数字段值
    • 构造方法详细信息

      • HttpURLConnection

        protected HttpURLConnection​(URL u)
        HttpURLConnection的构造函数。
        参数
        u - URL
    • 方法详细信息

      • setAuthenticator

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

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

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

        public static boolean getFollowRedirects()
        返回 boolean指示是否应自动遵循HTTP重定向(3xx)。
        结果
        true如果应自动遵循HTTP重定向,如果不是, false
        另请参见:
        setFollowRedirects(boolean)
      • setInstanceFollowRedirects

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

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

        参数
        followRedirects - boolean指示是否遵循HTTP重定向。
        从以下版本开始:
        1.3
        另请参见:
        instanceFollowRedirectsgetInstanceFollowRedirects()
      • getInstanceFollowRedirects

        public boolean getInstanceFollowRedirects()
        返回此 HttpURLConnectioninstanceFollowRedirects字段的值。
        结果
        HttpURLConnectioninstanceFollowRedirects字段的值。
        从以下版本开始:
        1.3
        另请参见:
        instanceFollowRedirectssetInstanceFollowRedirects(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)。
        结果
        HTTP状态代码,或-1
        异常
        IOException - 如果连接到服务器时发生错误。
      • getResponseMessage

        public String getResponseMessage()
                                  throws IOException
        获取与服务器的响应代码一起返回的HTTP响应消息(如果有)。 从响应中:
          HTTP/1.0 200 OK
         HTTP/1.0 404 Not Found 
        分别提取字符串“OK”和“Not Found”。 如果无法从响应中识别出任何内容,则返回null(结果不是有效的HTTP)。
        结果
        HTTP响应消息,或 null
        异常
        IOException - 如果连接到服务器时发生错误。
      • disconnect

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

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

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

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

        结果
        错误流(如果有),如果没有错误,则为null,连接未连接或服务器未发送任何有用数据。