モジュール jdk.httpserver
パッケージ com.sun.net.httpserver

クラスFilter

java.lang.Object
com.sun.net.httpserver.Filter
public abstract class Filter extends Object
着信要求の事前処理および事後処理に使用されるフィルタです。 事前処理はアプリケーションの交換ハンドラが呼び出される前に行われ、事後処理は交換ハンドラが返されたあとに行われます。 フィルタはチェーンで編成され、HttpContextインスタンスに関連付けられます。

チェーン内の各Filterは、独自のdoFilter(HttpExchange, Chain)実装内で次のフィルタを呼び出します。 チェーン内の最後のFilterがアプリケーション交換ハンドラを呼び出します。

導入されたバージョン:
1.6

  • コンストラクタの詳細

    • Filter

      protected Filter()
      サブクラスが呼び出すためのコンストラクタ。

  • メソッドの詳細

    • 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フィルタは通常、交換状態が処理される前に調査または変更するために使用されます。 フィルタoperationは、Filter.Chain.doFilter(HttpExchange)が起動される前に実行されるため、チェーン内の後続のフィルタと交換ハンドラが実行されます。 フィルタoperationは、通常、これは交換ハンドラによって行われるため、リクエストまたは「レスポンス・ヘッダーの送信」を処理する必要はありません。

      すべてのレスポンスに"Foo"レスポンス・ヘッダーを追加する例: 

      
     var filter = Filter.beforeHandler("Add response header 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フィルタは、通常、交換状態を変更するのではなく調査するために使用されます。 フィルタoperationは、Filter.Chain.doFilter(HttpExchange)の起動後に実行されます。つまり、チェーン内の後続のフィルタおよび交換ハンドラが実行されたことを意味します。 フィルタoperationは、交換または「レスポンス・ヘッダーの送信」を処理するものではありません。 これを行うと、operationが起動される前に交換が通常処理されるため、失敗する可能性があります。 具体的には、フィルタoperationを実行する前にレスポンスを送信できます。

      すべての交換のレスポンス・コードを記録するフィルタの追加例: 

      
     var filter = Filter.afterHandler("Log response code", e -> log(e.getResponseCode());
     httpContext.getFilters().add(filter);

      コンテキストに一連のafterHandlerフィルタを追加する例:
      フィルタ操作が呼び出される順序は、フィルタがコンテキスト・フィルタ・リストに追加される順序と逆です。       

      
     var a1Set = Filter.afterHandler("Set a1", e -> e.setAttribute("a1", "some value"));
     var a1Get = Filter.afterHandler("Get 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("Add Foo header", r -> r.with("Foo", List.of("Bar")));
     httpContext.getFilters().add(filter);

      パラメータ:
      description - description()から返される文字列
      requestOperator - リクエスト・オペレータ
      戻り値:
      交換が処理される前にリクエスト状態に適応するフィルタ
      例外:
      NullPointerException - いずれかの引数がnullの場合
      導入されたバージョン:
      18