Module jdk.httpserver
Package com.sun.net.httpserver

Class HttpExchange

java.lang.Object
com.sun.net.httpserver.HttpExchange
所有已实现的接口:
Request, AutoCloseable
直接已知的子类:
HttpsExchange
public abstract class HttpExchange extends Object implements AutoCloseable, Request
这个类封装了一个接收到的HTTP请求和要生成的响应，提供了用于检查来自客户端的请求以及构建和发送响应的方法。

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

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

  • Constructor Details

    • HttpExchange

      protected HttpExchange()
      子类调用的构造函数。

  • Method Details

    • getRequestHeaders

      public abstract Headers getRequestHeaders()
      返回一个不可变的包含与此请求一起包含的HTTP头的Headers。

      此Headers中的键是头部名称，而值是包含请求中包含的每个值的List，按照它们被包含的顺序。多次出现的头字段表示为多个字符串值。

      Headers中的键不区分大小写。

      指定者:
      getRequestHeaders 在接口 Request中
      返回:
      一个只读的Headers，可用于访问请求头。

    • getResponseHeaders

      public abstract Headers getResponseHeaders()
      返回一个可变的Headers，其中可以存储HTTP响应头，并作为此响应的一部分传输。

      Headers中的键是头部名称，而值必须是包含应包含多次的每个值的List，按照应包含的顺序。

      Headers中的键不区分大小写。

      返回:
      一个可写的Headers，可用于设置响应头。

    • getRequestURI

      public abstract URI getRequestURI()
      返回请求的URI。
      指定者:
      getRequestURI 在接口 Request中
      返回:
      请求的URI

    • getRequestMethod

      public abstract String getRequestMethod()
      返回请求方法。
      指定者:
      getRequestMethod 在接口 Request中
      返回:
      请求方法字符串

    • getHttpContext

      public abstract HttpContext getHttpContext()
      返回此交换的HttpContext。
      返回:
      HttpContext

    • close

      public abstract void close()
      通过按顺序执行以下操作来结束此交换:
      1. 关闭请求InputStream（如果尚未关闭）。
      2. 关闭响应OutputStream（如果尚未关闭）。
      指定者:
      close 在接口 AutoCloseable中

    • getRequestBody

      public abstract InputStream getRequestBody()
      返回一个流，可以从中读取请求体。多次调用此方法将返回相同的流。建议应用程序在关闭之前应消耗（读取）此流中的所有数据。如果在读取所有数据之前关闭流，则InputStream.close()调用将读取并丢弃剩余数据（最多到特定数量的字节）。
      返回:
      可以读取请求体的流

    • getResponseBody

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

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

      如果调用sendResponseHeaders(int, long)指定了固定的响应主体长度，则必须向此流写入在该调用中指定的确切字节数。如果写入的字节数过多，则OutputStream的写入方法将抛出IOException。如果写入的字节数过少，则流OutputStream.close()将抛出IOException。在这两种情况下，交换将被中止，并且底层TCP连接将关闭。

      返回：
      写入响应主体的流

    • sendResponseHeaders

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

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

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

      实现注意：
      此实现允许调用者在调用sendResponseHeaders之前向响应头提供Connection: close头，以强制在交换终止后关闭连接。
      参数：
      rCode - 要发送的响应代码
      responseLength - 如果> 0，则指定固定的响应主体长度，并且必须向从getResponseCode()获取的流写入确切数量的字节。如果== 0，则使用分块编码，并且可以写入任意数量的字节。如果<= -1，则未指定响应主体长度，且不得写入响应主体。
      抛出：
      IOException - 如果响应头已发送或发生I/O错误
      参见：

    • 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)
      Filter模块可以使用HttpExchange实例作为一种端到端通信机制存储任意对象。其他过滤器或交换处理程序可以访问这些对象。

      每个Filter类将记录它们提供的属性。

      参数：
      name - 要检索的属性的名称
      返回：
      属性对象，如果不存在则为null
      抛出：
      NullPointerException - 如果名称为null

    • setAttribute

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

      每个Filter类将记录它们提供的属性。

      参数：
      name - 要与属性值关联的名称
      value - 要存储为属性值的对象。允许null值。
      抛出：
      NullPointerException - 如果名称为null

    • setStreams

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

    • getPrincipal

      public abstract HttpPrincipal getPrincipal()
      如果在拥有此交换的HttpContext上设置了验证器，则此方法将返回表示此HttpExchange的经过身份验证用户的HttpPrincipal。
      返回：
      HttpPrincipal，如果未设置验证器则为null