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

Class Filter

java.lang.Object
com.sun.net.httpserver.Filter
public abstract class Filter extends Object
用于预处理和后处理传入请求的过滤器。预处理发生在应用程序的交换处理程序被调用之前，后处理发生在交换处理程序返回之后。过滤器以链的形式组织，并与 HttpContext 实例相关联。

链中的每个 Filter 在其自身的 doFilter(HttpExchange, Chain) 实现中调用下一个过滤器。链中的最后一个 Filter 调用应用程序的交换处理程序。

自版本:
1.6

  • Constructor Details

    • Filter

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

  • Method Details

    • doFilter

      public abstract void doFilter(HttpExchange exchange, Filter.Chain chain) throws IOException
      请求此过滤器对给定的交换进行预处理或后处理。该过滤器可以：
      • 检查或修改请求标头。
      • 通过创建适当的过滤器流并调用 HttpExchange.setStreams(InputStream, OutputStream) 来过滤请求主体或响应主体。
      • 在交换中设置属性对象，其他过滤器或交换处理程序可以访问。
      • 决定要么：
        1. 调用链中的下一个过滤器，通过调用 Filter.Chain.doFilter(HttpExchange)。
        2. 终止调用链，通过 不 调用 Filter.Chain.doFilter(HttpExchange)。
      • 如果选择了选项 1.，则当 doFilter() 返回时，链中的所有后续过滤器都已被调用，响应标头可以被检查或修改。
      • 如果选择了选项 2.，则此过滤器必须使用 HttpExchange 发送适当的响应。
      参数:
      exchange - 要过滤的 HttpExchange
      chain - 允许调用下一个过滤器的 Chain
      抛出:
      IOException - 可能由任何过滤器模块抛出，如果捕获到，必须重新抛出
      NullPointerException - 如果交换或链为 null

    • description

      public abstract String description()
      返回此 Filter 的简短描述。
      返回:
      描述该 Filter 的 String

    • beforeHandler

      public static Filter beforeHandler(String description, Consumer<HttpExchange> operation)
      返回一个带有给定描述和操作的预处理 Filter。

      operation 是过滤器的有效实现。在调用链中的每个 HttpExchange 之前执行该操作，以调用链中的下一个过滤器或交换处理程序（如果这是链中的最后一个过滤器）为目的。过滤器不处理由 operation 抛出的异常。

      API 注意:
      beforeHandler 过滤器通常用于在处理之前检查或修改交换状态。在调用 Filter.Chain.doFilter(HttpExchange) 之前执行过滤器 operation，因此在执行链中的任何后续过滤器和交换处理程序之前执行。过滤器 operation 不应该处理请求或 发送响应标头，因为这通常由交换处理程序完成。

      示例：向所有响应添加 "Foo" 响应标头：

      
     var filter = Filter.beforeHandler("添加响应标头 Foo",
                 e -> e.getResponseHeaders().set("Foo", "Bar"));
     httpContext.getFilters().add(filter);
      参数:
      description - 从 description() 返回的字符串
      operation - 返回的过滤器的操作
      返回:
      在处理交换之前调用其操作的过滤器
      抛出:
      NullPointerException - 如果任何参数为 null
      自版本:
      17

    • afterHandler

      public static Filter afterHandler(String description, Consumer<HttpExchange> operation)
      返回一个带有给定描述和操作的后处理 Filter。

      operation 是过滤器的有效实现。在调用链中的每个 HttpExchange 之后执行该操作，以调用链中的下一个过滤器或交换处理程序（如果此过滤器是链中的最后一个过滤器）为目的。过滤器不处理由 operation 抛出的异常。

      API 注意:
      afterHandler 过滤器通常用于检查交换状态而不是修改它。在调用 Filter.Chain.doFilter(HttpExchange) 之后执行过滤器 operation，这意味着已执行链中的任何后续过滤器和交换处理程序。过滤器 operation 不应该处理交换或 发送响应标头。这样做可能会失败，因为在调用 operation 之前，交换通常已被处理。更具体地说，响应可能在执行过滤器 operation之前发送。

      示例：添加一个过滤器，记录所有交换的响应代码：

      
     var filter = Filter.afterHandler("记录响应代码", e -> log(e.getResponseCode());
     httpContext.getFilters().add(filter);

      示例：向上下文添加一系列 afterHandler 过滤器：
      调用过滤器操作的顺序与将过滤器添加到上下文的过滤器列表的顺序相反。

      
     var a1Set = Filter.afterHandler("设置 a1", e -> e.setAttribute("a1", "some value"));
     var a1Get = Filter.afterHandler("获取 a1", e -> doSomething(e.getAttribute("a1")));
     httpContext.getFilters().addAll(List.of(a1Get, a1Set));

      a1Get 的操作将在 a1Set 的操作之后调用，因为 a1Get 在 a1Set 之前添加。

      参数:
      description - 从 description() 返回的字符串
      operation - 返回的过滤器的操作
      返回:
      在处理交换后调用其操作的过滤器
      抛出:
      NullPointerException - 如果任何参数为 null
      自版本:
      17

    • adaptRequest

      public static Filter adaptRequest(String description, UnaryOperator<Request> requestOperator)
      返回一个检查并可能调整请求状态的 预处理过滤器。由 requestOperator 返回的 Request 将是交换的有效请求状态。在调用链中的每个 HttpExchange 之前执行该操作，以调用链中的下一个过滤器或交换处理程序（如果这是链中的最后一个过滤器）为目的。过滤器不处理由 requestOperator 抛出的异常。
      API 注意:
      当调用返回的过滤器时，它首先使用给定的交换 ex 调用 requestOperator，以检索 适应的请求状态。然后调用链中的下一个过滤器或交换处理程序，传递一个等效于 ex 的交换，并将 适应的请求状态 设置为有效请求状态。

      示例：向所有请求添加 "Foo" 请求标头：

      
     var filter = Filter.adaptRequest("添加 Foo 标头", r -> r.with("Foo", List.of("Bar")));
     httpContext.getFilters().add(filter);
      参数:
      description - 从 description() 返回的字符串
      requestOperator - 请求操作符
      返回:
      在处理交换之前调整请求状态的过滤器
      抛出:
      NullPointerException - 如果任何参数为 null
      自版本:
      18