[18.0.0.1 and later]

MicroProfile Rest Client の構成

mpRestClient-1.0 フィーチャーを使用して MicroProfile Rest Client を起動します。

始める前に

MicroProfile Rest Client 1.0 には Java SDK 8 が必要です。

このタスクについて

MicroProfile Rest Client は JAX-RS 2.0 Client API にビルドされ、HTTP を介して RESTful サービスを呼び出すためのタイプ・セーフなアプローチを 提供します。よりモデル中心のコードを使用して クライアント・アプリケーションを作成することができます。 以下のステップを実行して、独自の REST クライアントを作成します。

手順

  1. リモート・サービスを示すインターフェースを作成します。インターフェースのメソッドを エン ドポイントの RESTful API に一致させます。 以下の例は、オンライン・ミュージックのサービスにアクセスする 、サンプルのインターフェースを示しています。
    @Path("/playlist")
    @Consumes("application/json")
    public interface MusicPlaylistService {
    
        @GET
        List<String> getPlaylistNames();
    
        @GET
        @Path("/{playlistName}")
        List<Song> getPlaylist(@PathParam("playlistName") name)
            throws UnknownPlaylistException;
    
        @POST
        @Path("/{playlistName}")
        long newPlayList(@PathParam("playlistName") name, List<Song> playlist)
            throws PlaylistAlreadyExistsException;
    
        @PUT
        @Path("/{playlistName}")
        long updatePlayList(@PathParam("playlistName") name, List<Song> playlist)
            throws UnknownPlaylistException;
    }

    サーバー・サイドの JAX-RS のように、サンプルのインターフェースは、 @Path@Consumes@GET、および @PathParam のようなアノテーションを使用します。

  2. インターフェースで定義されるメソッドを呼び出します。
    サンプル・インターフェースは呼び出し可能なメソッドを定義します。
    • getPlaylistNames メソッドを呼び出し、プレイ・リストの使用可能な名前を取得します。 REST クライアントの実装環境は、<baseUrl>/playlist ロケーションのエンドポイントに GET 要求を送信します。このロケーションは、プレイ・リストの使用 可能な名前を示すストリングのリストの application/json メディア・タイプを受け入れます。
    • プレイ・リストに含まれる歌を表示するには、getPlaylist メソッドを呼び出します。 このメソッドは UnknownPlaylistException エラーをスローします。 これは、リモート・サービスでも示される場合があり、HTTP 404 の応答 を返す場合があります。
  3. ResponseExceptionMapper コマンドを使用して、例外を処理します。 以下の例では、HTTP 404 応答を特定の例外に変換しています。
    @Provider
    public class PlaylistResponseExceptionMapper implements
        ResponseExceptionMapper<BasePlaylistException> {
    
        @Override
        public boolean handles(int statusCode, MultivaluedMap<String, Object> headers) {
            return statusCode == 404  // Not Found
                || statusCode == 409; // Conflict
        }
    
        @Override
        public BasePlaylistException toThrowable(Response response) {
            switch(response.getStatus()) {
            case 404: return new UnknownPlaylistException();
            case 409: return new PlaylistAlreadyExistsException();
            }
            return null;
        }
    
    }
    この例では、UnknownPlaylistException ケースと PlaylistAlreadyExistsException ケースの両方が、 BasePlaylistException ケースのサブクラスです。 toThrowable 応答は、例外のインスタンスをスローせずに返します。
  4. インターフェースと応答の例外マッパーを書き込み後、実装をビルドして 開始します。RestClientBuilder API または Contexts and Dependency Injection (CDI) および MP Config のいずれかを 使用して実装をビルドすることができます。
  5. オプション: RestClientBuilder API を使用します。これはより詳細ですが、テスト中など CDI が使用不可 の環境で便利です。
    1. RestClientBuilder API のインスタンスを作成します。
    2. リモート・エンドポイントの baseURL URL を指定し ます。これは、クライアントをビルドする前に必要です。
    3. 応答例外マッパーを登録します。MessageBodyReadersMessageBodyWritersfiltersinterceptors など、他のプロバイダー・クラスを登録す る必要がある場合は、register メソッドを使用して登録します。
    4. クライアントとパスをインターフェース・クラスでビルドします。
    5. 別の Java™ オブジェクトを 使用する場合と同様に、クライアントでメソッドを呼び出します。
    以下の例は、RestClientBuilder API を使用して実装をビルドして呼び 出すサンプル・コードを示しています。
    ...
    URL apiUrl = new URL("http://localhost:9080/onlineMusicService");
    MusicPlaylistService playlistSvc =
        RestClientBuilder.newBuilder()
                         .baseUrl(apiUrl)
                         .register(PlaylistResponseExceptionMapper.class)
                         .build(MusicPlaylistService.class);
    
    List<String> playlistNames = playlistSvc.getPlaylistNames();
    for (String name : playlistNames) {
        List<Song> songs = playlistSvc.getPlaylist(name);
        if (hasSongBy(songs, "band name")) {
            coolPlaylists.add(name);
        }
    }
    ...
  6. オプション: CDI および MP Config を使用して、クライアントをインスタン ス化します。
    1. Liberty server.xml ファイルで mpRestClient-1.0 フィーチャーをインストールします。
    2. cdi-1.2 フィーチャーまたは cdi-2.0 フィーチャーを追加します。
    3. mpConfig-1.1 フィーチャーまたは mpConfig-1.2 フィーチャーを追加します。
    4. MusicPlaylistService インターフェースを以下のア ノテーションで更新します。
      @Path("/playlist")
      @Consumes("application/json")
      @Dependent
      @RegisterRestClient
      @RegisterProvider(PlaylistResponseExceptionMapper.class)
      public interface MusicPlaylistService {
          ...
      @Dependent アノテーション、または @ApplicationScoped@RequestScoped など別のスコープ・アノテーションは、 CDI が Rest Client インターフェースを検出して管理するために必要です。 @RegisterRestClient アノテーションは、インターフェー スを動的に実装するように、MicroProfile Rest Client 実装環境に指示します。 @RegisterProvider アノテーションは、指定されたプ ロバイダー・クラスを登録するように、MicroProfile Rest Client 実装コード に指示します。同じインターフェースで必要なプロバイダーの数だけ @RegisterProvider アノテーションを繰り返すことができます。
    5. クライアントを別の管理対象オブジェクトに注入します。@Inject アノテーションと @RestClient デコレーターを結合して、 MusicPlaylistService インターフェースのインスタ ンスを注入するように CDI に指示します。
       @WebServlet(urlPatterns = "/PlaylistServlet")
      public class PlaylistServlet extends HttpServlet {
      
          @Inject
          @RestClient
          private MusicPlaylistService playlistService;
      
          @Override
          public void doGet(HttpServletRequest request, HttpServletResponse response) 
              throws ServletException, IOException {
      
              List<String> names = playlistService.getPlaylistNames();
              ...
    6. MP Config を使用して、MP Rest Client 実装のリモート・エン ドポイントの baseUrl URL を示します。MicroProfile Config で <fullyQualifiedInterfaceName>/mp-rest/url 構成 プロパティーを指定します。jvm.options ファイルでシステム・プ ロパティーを設定するオプションがあります。
      -Dcom.mypkg.MusicPlaylistService/mp-rest/url=http://localhost:9080/onlineMusicService

      CDI 注入は、クライアントをブートストラップする場合はよりシンプル です。MP Config を使用すると、環境ごとに異なる URL を使用することがで きます。例えば、コードを変更する必要なく、1 つの URL をテストに使用して 別の URL を実動に使用することができます。


トピックのタイプを示すアイコン タスク・トピック

ファイル名: twlp_mp_restclient.html