模块  jdk.httpserver
软件包  com.sun.net.httpserver

Class HttpExchange

  • 已知直接子类：
    HttpsExchange 
    public abstract class HttpExchange
extends Object
    此类封装接收的HTTP请求和在一个交换中生成的响应。 它提供了检查来自客户端的请求以及构建和发送响应的方法。

    HttpExchange的典型生命周期如下所示。

    1. getRequestMethod()确定命令
    2. getRequestHeaders()检查请求标头（如果需要）
    3. getRequestBody()返回InputStream以读取请求正文。 读取请求主体后，流已关闭。
    4. getResponseHeaders()设置除content-length之外的任何响应头
    5. sendResponseHeaders(int,long)发送响应头。 必须在下一步之前调用。
    6. getResponseBody()获取OutputStream发送响应正文。 写入响应主体后，必须关闭流以终止交换。
    终止交流
    当请求InputStream和响应OutputStream都关闭时，交换将终止。 关闭OutputStream，隐式关闭InputStream（如果它尚未关闭）。 但是，建议在关闭之前使用InputStream中的所有数据。 便利方法close()完成所有这些任务。 在不消耗所有请求主体的情况下关闭交换不是错误，但可能使底层TCP连接无法用于后续交换。 未能终止交换的效果未定义，但通常会导致资源无法释放/重用。
    从以下版本开始：
    1.6

    • 构造方法详细信息

      • HttpExchange

        protected HttpExchange()

    • 方法详细信息

      • getRequestHeaders

        public abstract Headers getRequestHeaders()
        返回包含此请求中包含的HTTP标头的不可变Map。 此Map中的键将是标题名称，而值将是包含所包含的每个值的字符串列表（对于多次列出的标题，或者在a上接受以逗号分隔的值列表的标题）单线）。 在任何一种情况下，标题名称的值将按它们包含在请求中的顺序显示。

        Map中的键不区分大小写。

        结果
        只读地图，可用于访问请求标头

      • getResponseHeaders

        public abstract Headers getResponseHeaders()
        返回一个可变的Map，HTTP响应头可以存储在该Map中，并将作为此响应的一部分进行传输。 Map中的键将是标题名称，而值必须是一个字符串列表，其中包含应多次包含的每个值（按照它们应包括的顺序）。

        Map中的键不区分大小写。

        结果
        可写的Map，可用于设置响应头。

      • getRequestURI

        public abstract URI getRequestURI()
        获取请求URI
        结果
        请求URI

      • getRequestMethod

        public abstract String getRequestMethod()
        获取请求方法
        结果
        请求方法

      • getHttpContext

        public abstract HttpContext getHttpContext()
        获取此交换的HttpContext
        结果
        HttpContext

      • close

        public abstract void close()
        通过按顺序执行以下操作结束此交换：
        1. 关闭请求InputStream，如果尚未关闭;
        2. 关闭响应OutputStream，如果尚未关闭。

      • getRequestBody

        public abstract InputStream getRequestBody()
        返回可以从中读取请求正文的流。 多次调用此方法将返回相同的流。 建议应用程序在关闭之前使用（读取）此流中的所有数据。 如果在读取所有数据之前关闭流，则close（）调用将读取并丢弃剩余数据（最多为实现特定的字节数）。
        结果
        可以从中读取请求正文的流。

      • getResponseBody

        public abstract OutputStream getResponseBody()
        返回必须写入响应主体的流。 sendResponseHeaders(int,long) ）必须在调用此方法之前调用。 对此方法的多次调用（对于相同的交换）将返回相同的流。 为了正确终止每个交换，即使没有发送响应主体，也必须关闭输出流。

        关闭此流会隐式关闭从getRequestBody()返回的InputStream（如果它尚未关闭）。

        如果对sendResponseHeaders（）的调用指定了固定的响应主体长度，则必须将该调用中指定的确切字节数写入此流。 如果写入太多字节，则write（）将抛出IOException。 如果写入的字节太少，那么流close（）将抛出IOException。 在这两种情况下，中止交换并关闭底层TCP连接。

        结果
        写入响应正文的流

      • sendResponseHeaders

        public abstract void sendResponseHeaders​(int rCode,
                                         long responseLength)
                                  throws IOException
        使用当前响应标头集和此方法中指定的数字响应代码开始将响应发送回客户端。 响应体长度也如下指定。 如果响应长度参数大于零，则指定要发送的确切字节数，并且应用程序必须发送该确切数量的数据。 如果响应长度参数是zero ，则使用分块传输编码并且可以发送任意数量的数据。 应用程序通过关闭OutputStream来终止响应主体。 如果响应长度的值为-1则不会发送任何响应正文。

        如果尚未设置内容长度响应头，则根据响应长度参数将其设置为适当的值。

        必须在调用getResponseBody()之前调用此方法。

        参数
        rCode - 要发送的响应代码
        responseLength - 如果> 0，指定固定的响应主体长度，并且必须将精确的字节数写入从getResponseBody（）获取的流，否则如果等于0，则使用分块编码，并且可以使用任意数量的字节写的。 如果<= -1，则不指定响应主体长度，也不能写入响应主体。
        异常
        IOException
        另请参见：
        getResponseBody()

      • getRemoteAddress

        public abstract InetSocketAddress getRemoteAddress()
        返回调用此请求的远程实体的地址
        结果
        调用者的InetSocketAddress

      • getResponseCode

        public abstract int getResponseCode()
        返回响应代码（如果已设置）
        结果
        响应代码（如果有）。 -1若尚未提供。

      • getLocalAddress

        public abstract InetSocketAddress getLocalAddress()
        返回收到请求的本地地址
        结果
        本地接口的InetSocketAddress

      • getProtocol

        public abstract String getProtocol()
        以protocol / majorVersion.minorVersion形式从请求中返回协议字符串。 例如，“HTTP / 1.1”
        结果
        来自请求的协议字符串

      • getAttribute

        public abstract Object getAttribute​(String name)
        过滤器模块可以使用HttpExchange实例存储任意对象作为带外通信机制。 然后，其他过滤器或交换处理程序可以访问这些对象。

        每个Filter类都将记录它们可用的属性。

        参数
        name - 要检索的属性的名称
        结果
        属性对象，如果不存在则为null
        异常
        NullPointerException - 如果名称是 null

      • setAttribute

        public abstract void setAttribute​(String name,
                                  Object value)
        过滤器模块可以使用HttpExchange实例存储任意对象作为带外通信机制。 然后，其他过滤器或交换处理程序可以访问这些对象。

        每个Filter类都将记录它们可用的属性。

        参数
        name - 与属性值关联的名称
        value - 要存储为对象属性的对象。 null值为null 。
        异常
        NullPointerException - 如果名称是 null

      • setStreams

        public abstract void setStreams​(InputStream i,
                                OutputStream o)
        由Filters用于包装此交换的InputStream和OutputStream中的任何一个（或两者），使用给定的过滤流，以便后续调用getRequestBody()将返回给定的InputStream ，并且对getResponseBody()的调用将返回给定的OutputStream 。 提供给该调用的流必须包装原始流，并且可以是（但不是必须的） FilterInputStream和FilterOutputStream的子类。
        参数
        i - 要设置为此对象的输入流的已过滤输入流，如果没有更改， null 。
        o - 要设置为此对象的输出流的已过滤输出流，如果未更改则设置为 null 。

      • getPrincipal

        public abstract HttpPrincipal getPrincipal()
        如果认证被设置在拥有这种交换的HttpContext，则此方法将返回HttpPrincipal ，它表示此HttpExchange身份验证的用户。
        结果
        the HttpPrincipal, or null if no authenticator is set.