7.4. Jakarta RESTful Web サービスと RESTEasy アプリケーションの変更

インターセプターおよび MessageBody クラス

JSR 311: JAX-RS: The Java™ API for RESTful Web Services にはインターセプターフレームワークが含まれなかったため、RESTEasy 2 によって提供されました。JSR 339: JAX-RS 2.0: The Java API for RESTful Web Services は、公式のインターセプターおよびフィルターフレームワークを導入したため、RESTEasy 2 に含まれるインターセプターフレームワークは現在非推奨となり、RESTEasy 3.x の Jakarta REST 準拠インターセプター機能に置き換えられました。関連するインターフェイスは、jakarta.ws.rs.api モジュールの jakarta.ws.rs.ext パッケージで定義されています。

以下のプロバイダーは JBoss EAP 8.0 で削除されました。

以下は Jakarta RESTful Web Services に置き換えられたため、JBoss EAP 8.0 では削除されました。

クライアント API

resteasy-jaxrs の RESTEasy クライアントフレームワークは、JBoss EAP 7.0 で JAX-RS 2.0 準拠の resteasy-client モジュールに置き換えられました。そのため、RESTEasy クライアント API クラスおよびメソッドの中には非推奨となっているものもあります。

StringConverter

org.jboss.resteasy.spi.StringConverter クラスは、RESTEasy 3.x および JBoss EAP 8.0 で非推奨になりました。この機能は、Jakarta REST jakarta.ws.rs.ext.ParamConverterProvider クラスを使用して置き換えることができます。

ResteasyProviderFactory Add メソッド

RESTEasy 3.0 では、org.jboss.resteasy.spi.ResteasyProviderFactory add() メソッドのほとんどが削除または保護されています。たとえば、addBuiltInMessageBodyReader() および addBuiltInMessageBodyWriter() メソッドは削除され addMessageBodyReader() および addMessageBodyWriter() メソッドは保護されました。

現時点では、registerProvider() と registerProviderInstance() のメソッドを使用してください。

RESTEasy 3 から削除された他のクラス

Jakarta REST メソッドへの応答をサーバー上にキャッシュする必要があることを指定した @org.jboss.resteasy.annotations.cache.ServerCached アノテーションは RESTEasy 3 から削除されたため、アプリケーションコードから削除する必要があります。

このセクションでは、JBoss EAP の RESTEasy への追加的な変更点を説明します。

SignedInput および SignedOuput

セキュリティーフィルター

@RolesAllowed、@PermitAll、および @DenyAll のセキュリティーフィルターは、"401 Unauthorized" ではなく "403 Forbidden" を返すようになりました。

クライアント側のフィルター

RESTEasy 3.0 より前のリリースから RESTEasy クライアント API を使用している場合は、JAX-RS 2.0 で導入されたクライアント側のフィルターはバインドされず、実行されません。

非同期 HTTP サポート

JAX-RS 2.0 仕様は、@Suspended アノテーションと AsynResponse インターフェイスを使用した非同期 HTTP サポートを追加したため、非同期 HTTP の RESTEasy プロプライエタリー API は非推奨となりました。非同期 Tomcat モジュールと非同期 JBoss Web モジュールもサーバーインストールから削除されました。非同期 Tomcat と非同期 JBoss Web モジュールもサーバーインストールから削除されています。Servlet 3.0 コンテナーまたはそれ以降を使用していない場合、非同期 HTTP サーバー側の処理がシミュレートされ、同一リクエストスレッドで同期的に実行されます。

サーバー側のキャッシュ

サーバー側のキャッシュ設定が変更されました。詳細は、RESTEasy のドキュメント を参照してください。

YAML プロバイダーの設定変更

以前のリリースの JBoss EAP では、RESTEasy YAML プロバイダー設定はデフォルトで有効になっていました。これは JBoss EAP 7 で変更になりました。YAML プロバイダーがデフォルトで無効化されるようになりました。アンマーシャリングで RESTEasy によって使用される SnakeYAML ライブラリーにセキュリティー上の問題があるため、YAML プロバイダーの使用はサポートされず、アプリケーションで明示的に有効にする必要があります。アプリケーションで YAML プロバイダーを有効にし、Maven 依存関係を追加する方法は、JBoss EAP 7.4 Web サービスアプリケーションの開発 の YAML プロバイダー を参照してください。

Content-Type ヘッダーのデフォルトの文字セット UTF-8

JBoss EAP 7.1 より、デフォルトで resteasy.add.charset パラメーターが true に設定されています。リソースメソッドが明示的な文字セットなしで text/* または application/xml* メディアタイプを返すときに、返された content-type ヘッダーに charset=UTF-8 を追加したくない場合は、resteasy.add.charset パラメーターを false に設定できます。

テキストメディアタイプと文字セットの詳細は、JBoss EAP 7.4 Web サービスアプリケーションの開発 の テキストメディアタイプおよび文字セット を参照してください。

SerializableProvider

信用できないソースから Java オブジェクトをデシリアライズすることは危険です。そのため、JBoss EAP 7 以降では org.jboss.resteasy.plugins.providers.SerializableProvider クラスがデフォルトで無効となり、このプロバイダーの使用は推奨されません。

リソースメソッドへのリクエストの一致

RESTEasy 3 では、JAX-RS 仕様の定義どおりに、一致ルールの実装に改善および修正が加えられました。特に、サブリソースメソッドおよびサブリソースロケーターのあいまいな URI の処理方法が変更されました。

RESTEasy 2 では、同じ URI を持つ別のサブリソースが存在していても、サブリソースロケーターが正常に実行される可能性がありました。仕様上ではこの挙動は適切ではありません。

RESTEasy 3 では、サブリソースおよびサブリソースロケーターのあいまいな URI が存在する場合、サブリソースの呼び出しには成功しますが、サブリソースロケーターの呼び出しは HTTP ステータス 405 Method Not Allowed のエラーによって失敗します。

以下の例には、サブリソースメソッドおよびサブリソースロケーターのあいまいな @Path アノテーションが含まれています。エンドポイント anotherResource および anotherResourceLocator 両方の URI は同じであることに注目してください。この 2 つのエンドポイントの違いは、anotherResource メソッドは REST 動詞である POST に関連付けられていることです。anotherResourceLocator メソッドに関連付けられている REST 動詞はありません。仕様上では、REST 動詞を持つエンドポイント (この場合は anotherResource メソッド) が常に選択されます。

@Path("myResource")
public class ExampleSubResources {
    @POST
    @Path("items")
    @Produces("text/plain")
    public Response anotherResource(String text) {
        return Response.ok("ok").build();
    }

    @Path("items")
    @Produces("text/plain")
    public SubResource anotherResourceLocator() {
        return new SubResource();
    }
}

@Path("myResource")
public class ExampleSubResources {
    @POST
    @Path("items")
    @Produces("text/plain")
    public Response anotherResource(String text) {
        return Response.ok("ok").build();
    }

    @Path("items")
    @Produces("text/plain")
    public SubResource anotherResourceLocator() {
        return new SubResource();
    }
}

RESTEasy SPI プロバイダーは JBoss EAP 8 で削除されました。

SPI 例外

すべての SPI 失敗例外は非推奨となり、内部的には使用されません。これらは、対応する Jakarta REST 例外に置き換えられました。

InjectorFactory および Registry

InjectorFactory および Registry SPI が変更されました。ドキュメントに従ってサポートされるように RESTEasy を使用する場合は、問題はありません。

JBoss EAP 6.4 に含まれる Jackson のバージョンが変更されました。JBoss EAP 7 以降、Jackson プロバイダーは resteasy-jackson-provider から resteasy-jackson2-provider に変更されました。

resteasy-jackson2-provider へのアップグレードにはいくつかのパッケージ変更が必要になります。たとえば、Jackson アノテーションパッケージは org.codehaus.jackson.annotate から com.fasterxml.jackson.annotation に変更されました。

JBoss EAP 8.0 は RESTEasy 6.2 のサポートを提供します。JBoss EAP 8.0 で Spring 6.0 フレームワークを使用する予定の場合は、Java 17 を使用する必要があります。

Spring 4.0 フレームワークには、Java 8 のサポートが導入されました。Spring と RESTEasy 3.x 統合を使用する場合は、使用するデプロイメントで最小 Spring バージョンに 4.2.x を指定してください。これは JBoss EAP 7 がサポートする安定性のある最も早期のバージョンです。

RESTEasy Jettison JSON プロバイダーは JBoss EAP 7 以降非推奨となり、デフォルトでデプロイメントに追加されなくなりました。推奨される RESTEasy Jackson プロバイダーに切り替えるようにしてください。Jettison プロバイダーの使用継続を希望する場合は、以下の例で示すように jboss-deployment-descriptor.xml ファイルでその明示的な依存関係を定義する必要があります。

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
      <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
    </exclusions>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jettison-provider" services="import"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
      <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
    </exclusions>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jettison-provider" services="import"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

明示的な依存関係を定義する方法の詳細は、JBoss EAP 7.4 開発ガイド の デプロイメントへの明示的なモジュール依存関係の追加 を参照してください。

MicroProfile は、開発者がアプリケーションを変更したり再パッケージ化したりすることなく、複数の環境で実行できるようにアプリケーションやマイクロサービスを設定するために使用できる仕様の名前です。以前は、MicroProfile はテクノロジープレビューとして JBoss EAP 7.3 で利用可能でしたが、その後削除されました。MicroProfile は現在、JBoss EAP XP でのみ使用可能です。