2.12. RESTEasy フィルターおよびインターセプター

RESTEasy は JAX-RS 呼び出しをインターセプトし、インターセプターと呼ばれるリスナーのようなオブジェクトでそれらをルーティングできます。

フィルターはリクエストまたは応答ヘッダーを変更しますが、インターセプターはメッセージボディーを処理します。インターセプターは、対応するリーダーまたはライターと同じ呼び出しスタックで実行されます。ReaderInterceptors は MessageBodyReaders の実行をラップします。WriterInterceptors は MessageBodyWriters の実行をラップします。これは、特定のコンテンツエンコーディングを実装するために使用できます。これらは、デジタル署名の生成や、マーシャリング前後の Java オブジェクトモデルの投稿または事前処理に使用することができます。

ReaderInterceptors および WriterInterceptors は、サーバー側またはクライアント側のいずれかで使用することができます。これらは、@ServerInterceptor または @ClientInterceptor のいずれかや、@Provider でアノテーションが付けられたため、RESTEasy はそれらをインターセプター一覧に追加するかどうかを認識できます。

これらのインターセプターは、MessageBodyReader.readFrom() または MessageBodyWriter.writeTo() の呼び出しをラップします。これらは、Output や Input ストリームをラップするために使用できます。

@Provider
public class BookReaderInterceptor implements ReaderInterceptor {
    @Inject private Logger log;
    @Override
    @ReaderInterceptorBinding
    public Object aroundReadFrom(ReaderInterceptorContext context) throws IOException, WebApplicationException {
        log.info("*** Intercepting call in BookReaderInterceptor.aroundReadFrom()");
        VisitList.add(this);
        Object result = context.proceed();
        log.info("*** Back from intercepting call in BookReaderInterceptor.aroundReadFrom()"); return result;
    }
}

インターセプターと MessageBodyReader または Writer は、単一の大きな Java 呼び出しスタックで呼び出されます。ReaderInterceptorContext.proceed() または WriterInterceptorContext.proceed() は、次のインターセプターに移動するために呼び出されます。または、呼び出すインターセプターがない場合は、MessageBodyReader や MessageBodyWriter の readFrom() や writeTo() メソッドになります。このラッピングにより、オブジェクトは Reader や Writer に到達する前に変更でき、proceed() が返された後にクリーンアップされます。

以下の例は、ヘッダー値を応答に追加するサーバー側のインターセプターです。

@Provider
public class BookWriterInterceptor implements WriterInterceptor {
   @Inject private Logger log;

   @Override
   @WriterInterceptorBinding
   public void aroundWriteTo(WriterInterceptorContext context) throws IOException, WebApplicationException {
      log.info("*** Intercepting call in BookWriterInterceptor.aroundWriteTo()");
      VisitList.add(this);
      context.proceed();
      log.info("*** Back from intercepting call in BookWriterInterceptor.aroundWriteTo()");
   }
}

アプリケーションで RESTEasy JAX-RS インターセプターを登録するには、context-param 要素の resteasy.providers パラメーターの下で web.xml ファイルにリストするか、これをクラスまたは Application.getClasses() や Application.getSingletons() メソッドのオブジェクトとして返します。

<context-param>
    <param-name>resteasy.providers</param-name>
    <param-value>my.app.CustomInterceptor</paramvalue>
</context-param>

package org.jboss.resteasy.example;

import javax.ws.rs.core.Application;
import java.util.HashSet;
import java.util.Set;

public class MyApp extends Application {

  public java.util.Set<java.lang.Class<?>> getClasses() {
    Set<Class<?>> resources = new HashSet<Class<?>>();
    resources.add(MyResource.class);
    resources.add(MyProvider.class);
    return resources;
  }
}

package org.jboss.resteasy.example;

import javax.ws.rs.core.Application;
import java.util.HashSet;
import java.util.Set;

public class MyApp extends Application {

    protected Set<Object> singletons = new HashSet<Object>();

    public MyApp() {
        singletons.add(new MyResource());
        singletons.add(new MyProvider());
    }

    @Override
    public Set<Object> getSingletons() {
        return singletons;
    }
}

GZIP 圧縮と展開には、以下の 3 つのインターセプターが関係します。

GZIP デコンプレッシングを有効にすると、GZIPDecodingInterceptor が圧縮メッセージボディーから抽出できるバイト数の上限が設定されます。デフォルトの制限は 10,000,000 です。

インターセプターを有効にするには、クラスパスの javax.ws.rs.ext.Providers ファイルにクラス名を追加します。圧縮ファイルの上限は、web アプリケーションコンテキストパラメーター resteasy.gzip.max.input を使用して設定します。サーバー側でこの制限を超えると、GZIPDecodingInterceptor はステータス 413 - Request Entity Too Large の応答と、上限を指定するメッセージを返します。

Client client = new ResteasyClientBuilder() // Activate gzip compression on client:
    .register(AcceptEncodingGZIPFilter.class)
    .register(GZIPDecodingInterceptor.class)
    .register(GZIPEncodingInterceptor.class)
    .build();

Client client = new ResteasyClientBuilder() // Activate gzip compression on client:
    .register(AcceptEncodingGZIPFilter.class)
    .register(new GZIPDecodingInterceptor(256))
    .register(GZIPEncodingInterceptor.class)
    .build();