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

サーバー側では、ContainerRequestFilters および ContainerResponseFilters という 2 種類のフィルターを利用できます。ContainerRequestFilters は、Jakarta RESTful Web Services リソースメソッドが呼び出される前に実行されます。ContainerResponseFilters は、Jakarta RESTful Web Services リソースメソッドが呼び出された後に実行されます。

さらに、ContainerRequestFilters には pre-matching および post-matching のタイプがあります。事前一致する ContainerRequestFilters が @PreMatching アノテーションで指定され、Jakarta RESTful Web Services リソースメソッドが受信 HTTP 要求に一致する前に実行されます。事後一致する ContainerRequestFilters は、@PostMatching アノテーションで指定され、Jakarta RESTful Web Services リソースメソッドが受信 HTTP 要求と照合された後に実行されます。

事前一致フィルターは多くの場合、要求属性を変更して、.xml をストリップし、Accept ヘッダーを追加するなど、特定のリソースメソッドへの一致方法を変更するために使用されます。ContainerRequestFilters は ContainerRequestContext.abortWith (Response) を呼び出して要求を中止できます。たとえば、フィルターはカスタム認証プロトコルを実装している場合に中止する必要があるかもしれません。

リソースクラスメソッド実行後、Jakarta RESTful Web Services はすべての ContainerResponseFilters を実行します。これらのフィルターにより、発信応答がマーシャリングされ、クライアントに送信される前に送信応答を変更できます。

public class RoleBasedSecurityFilter implements ContainerRequestFilter {
  protected String[] rolesAllowed;
  protected boolean denyAll;
  protected boolean permitAll;

  public RoleBasedSecurityFilter(String[] rolesAllowed, boolean denyAll, boolean permitAll) {
    this.rolesAllowed = rolesAllowed;
    this.denyAll = denyAll;
    this.permitAll = permitAll;
  }

  @Override
  public void filter(ContainerRequestContext requestContext) throws IOException  {
    if (denyAll) {
       requestContext.abortWith(Response.status(403).entity("Access forbidden: role not allowed").build());
       return;
    }
    if (permitAll) return;
    if (rolesAllowed != null) {
       SecurityContext context = ResteasyProviderFactory.getContextData(SecurityContext.class);
       if (context != null) {
          for (String role : rolesAllowed) {
             if (context.isUserInRole(role)) return;
          }
          requestContext.abortWith(Response.status(403).entity("Access forbidden: role not allowed").build());
          return;
       }
    }
    return;
  }
}

public class CacheControlFilter implements ContainerResponseFilter {
   private int maxAge;

   public CacheControlFilter(int maxAge) {
      this.maxAge = maxAge;
   }

   public void filter(ContainerRequestContext req, ContainerResponseContext res)
           throws IOException {
      if (req.getMethod().equals("GET")) {
         CacheControl cc = new CacheControl();
         cc.setMaxAge(this.maxAge);
         res.getHeaders().add("Cache-Control", cc);
      }
   }
}

クライアント側のフィルターの詳細は、本書の Jakarta RESTful Web Services Client API のセクションを参照してください。

RESTEasy は GZIP 圧縮および展開に対応しています。GZIP の展開をサポートするため、クライアントフレームワークまたは Jakarta RESTful Web Services サービスはメッセージボディーを gzip の Content-Encoding で自動的に展開し、Accept-Encoding ヘッダーを gzip, deflate に自動的に設定できるため、ヘッダーの手動設定は必要ありません。GZIP 圧縮をサポートするため、クライアントフレームワークがリクエストを送信している場合や、サーバーが gzip に設定された Content-Encoding ヘッダーを使用して応答を送信している場合に、RESTEasy は出力メッセージを圧縮します。@org.jboss.resteasy.annotation.GZIP アノテーションを使用して Content-Encoding ヘッダーを設定できます。

以下の例は、gzip 圧縮する、出力メッセージボディーの order をタグ付けします。

@Path("/")
public interface MyProxy {

   @Consumes("application/xml")
   @PUT
   public void put(@GZIP Order order);
}

@Path("/")
public class MyService {

   @GET
   @Produces("application/xml")
   @GZIP
   public String getData() {...}
}

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();

フィルターまたはインターセプターを特定のリソースメソッドに対してのみ実行したい場合があります。これは、以下の 2 つのの方法で実行できます。

DynamicFeature インターフェイスの実装

DynamicFeature インターフェイスには、コールバックメソッド configure(ResourceInfo resourceInfo, FeatureContext context) が含まれます。これは、デプロイされた各 Jakarta RESTful Web Services メソッドおよびデプロイされた各 Jakarta RESTful Web Services メソッドに対して呼び出されます。ResourceInfo パラメーターには、デプロイされている現在の Jakarta RESTful Web Services メソッドに関する情報が含まれています。FeatureContext は、Configurable インターフェイスの拡張機能です。このパラメーターの register() メソッドを使用して、このメソッドに割り当てるフィルターとインターセプターをバインドできます。

@Provider
public class AnimalTypeFeature implements DynamicFeature {
    @Override
    public void configure(ResourceInfo info, FeatureContext context) {
        if (info.getResourceMethod().getAnnotation(GET.class) != null)
            AnimalFilter filter = new AnimalFilter();
            context.register(filter);
        }
    }
}

上記の例では、AnimalTypeFeature を使用して登録するプロバイダーは、インターフェイスのいずれかを実装する必要があります。この例では、以下のインターフェイスのいずれかを実装する必要があるプロバイダー AnimalFilter を登録します。これは、ContainerRequestFilter、ContainerResponseFilter、ReaderInterceptor、WriterInterceptor、または Feature のいずれかを実装する必要があります。この場合、AnimalFilter は GET アノテーションが付けられたすべてのリソースメソッドに適用されます。詳細は DynamicFeature Documentation を参照してください。

@NameBinding アノテーションを使用します。

@NameBinding の動作は、Jakarta Contexts and Dependency Injection インターセプターと似ています。@NameBinding でカスタムアノテーションにアノテーションを付け、そのカスタムアノテーションをフィルターおよびリソースメソッドに適用します。

@NameBinding
public @interface DoIt {}

@DoIt
public class MyFilter implements ContainerRequestFilter {...}

@Path("/root")
public class MyResource {

   @GET
   @DoIt
   public String get() {...}
}

詳細は NameBinding Documentation のドキュメントを参照してください。

順序付けは、フィルターまたはインターセプタークラスの @Priority アノテーションを使用して実行されます。

フィルターまたはインターセプターに関連する例外は、クライアント側またはサーバー側で発生する可能性があります。クライアント側では、javax.ws.rs.client.ProcessingException および javax.ws.rs.client.ResponseProcessingException という例外を処理する必要があります。javax.ws.rs.client.ProcessingException は、リクエストがサーバーに送信される前にエラーが発生していた場合、クライアント側で出力されます。サーバーからクライアントが受信した応答の処理にエラーが発生すると、javax.ws.rs.client.ResponseProcessingException がクライアント側で出力されます。

サーバー側で、フィルターまたはインターセプターによって出力される例外は、Jakarta RESTful Web Services メソッドから出力された他の例外と同じ方法で処理されます。これは、出力される例外の ExceptionMapper を見つけようとします。Jakarta RESTful Web Services メソッドでの例外の処理方法は Exception Handling を参照してください。