検索

2.19. MicroProfile REST クライアント

download PDF
重要

MicroProfile REST クライアントはテクノロジープレビューとしてのみ提供されます。テクノロジープレビューの機能は、Red Hat の本番環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat は本番環境での使用は推奨しません。テクノロジープレビューの機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。

テクノロジープレビュー機能のサポート範囲については、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

JBoss EAP 7.3 は、HTTP 上で RESTful サービスを呼び出すために型安全なアプローチを利用するため、JAX-RS 2.1 クライアント上に構築される MicroProfile REST クライアント 1.4.x をサポートするようになりました。MicroProfile Type Safe REST クライアントは Java インターフェイスとして定義されます。MicroProfile REST クライアントでは、実行可能コードでクライアントアプリケーションの書き込みを行うことができます。

MicroProfile REST クライアントは以下を有効にします。

  • 直感的構文
  • プロバイダーのプログラムによる登録
  • プロバイダーの宣言的登録
  • ヘッダーの宣言的仕様
  • サーバー上のヘッダーの伝搬
  • ResponseExceptionMapper
  • CDI 統合

2.19.1. 直感的構文

MicroProfile REST クライアントは、CORBA、Java Remote Method Invocation (RMI)、JBoss Remoting Project、および RESTEasy にも実装されている分散オブジェクト通信のバージョンを有効にします。たとえば、以下のリソースについて見てみましょう。

@Path("resource")
public class TestResource {
   @Path("test")
   @GET
   String test() {
      return "test";
   }
 }

TestResource クラスにアクセスする JAX-RS のネイティブな方法は次のとおりです。

Client client = ClientBuilder.newClient();
String response = client.target("http://localhost:8081/test").request().get(String.class);

ただし、Microprofile REST クライアントは test() メソッドを直接呼び出すことで、より直感的な構文をサポートします。

@Path("resource")
public interface TestResourceIntf {
    @Path("test")
    @GET
    public String test();
}

TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl(http://localhost:8081/))
                              .build(TestResourceIntf.class);
String s = service.test();

上記の例では、TestResource クラスへの呼び出しは、呼び出し service.test() が示すように TestResourceIntf クラスにより大幅に容易になります。

以下の例は、TestResourceIntf クラスのより詳細なバージョンです。

@Path("resource")
public interface TestResourceIntf2 {
   @Path("test/{path}")mes("text/plain")
   @Produces("text/html")
   @POST
   public String test(@PathParam("path") String path, @QueryParam("query") String query, String entity);
}

service.test("p", "q", "e") メソッドを呼び出すと、以下のような HTTP メッセージが生成されます。

POST /resource/test/p/?query=q HTTP/1.1
Accept: text/html
Content-Type: text/plain
Content-Length: 1

e

2.19.2. プロバイダーのプログラムによる登録

MicroProfile REST クライアントでは、プロバイダーを登録してクライアント環境を設定することもできます。例を以下に示します。

TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl(http://localhost:8081/))
                              .register(MyClientResponseFilter.class)
                              .register(MyMessageBodyReader.class)
                              .build(TestResourceIntf.class);

2.19.3. プロバイダーの宣言型登録

以下のように org.eclipse.microprofile.rest.client.annotation.RegisterProvider アノテーションをターゲットインターフェイスに追加して、プロバイダーを宣言的に登録することもできます。

@Path("resource")
@RegisterProvider(MyClientResponseFilter.class)
@RegisterProvider(MyMessageBodyReader.class)
public interface TestResourceIntf2 {
   @Path("test/{path}")
   @Consumes("text/plain")
   @Produces("text/html")
   @POST
   public String test(@PathParam("path") String path, @QueryParam("query") String query, String entity);
}

MyClientResponseFilter クラスと MyMessageBodyReader クラスをアノテーションで宣言すると、RestClientBuilder.register() メソッドを呼び出す必要がなくなります。

2.19.4. ヘッダーの宣言的仕様

HTTP リクエストのヘッダーは、以下の方法で指定できます。

  • リソースメソッドパラメーターのいずれかにアノテーションを付けます。
  • org.eclipse.microprofile.rest.client.annotation.ClientHeaderParam アノテーションを宣言で使用。

以下の例では、@HeaderValue アノテーションを持つリソースメソッドパラメーターのいずれかにアノテーションを付け、ヘッダーの設定を示しています。

@POST
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
String contentLang(@HeaderParam(HttpHeaders.CONTENT_LANGUAGE) String contentLanguage, String subject);

以下の例は、org.eclipse.microprofile.rest.client.annotation.ClientHeaderParam アノテーションを使用してヘッダーを設定する例になります。

@POST
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
@ClientHeaderParam(name=HttpHeaders.CONTENT_LANGUAGE, value="{getLanguage}")
String contentLang(String subject);

default String getLanguage() {
   return ...;
}

2.19.5. サーバー上のヘッダーの伝搬

org.eclipse.microprofile.rest.client.ext.ClientHeadersFactory のインスタンスが有効であれば、受信ヘッダーの送信要求に一括転送できます。デフォルトのインスタンス org.eclipse.microprofile.rest.client.ext.DefaultClientHeadersFactoryImpl は、コンマ区切りの設定プロパティー org.eclipse.microprofile.rest.client.propagateHeaders に一覧表示される着信ヘッダーで設定されるマップを返します。ClientHeadersFactory インターフェイスをインスタンス化するルールは次のとおりです。

  • JAX-RS リクエストのコンテキストで呼び出される ClientHeadersFactory インスタンス は、@Context アノテーションが付けられたフィールドおよびメソッドの挿入をサポートする必要があります。
  • CDI によって管理される ClientHeadersFactory インスタンス は、適切な CDI 管理インスタンスを使用する必要があります。@Inject インジェクションもサポートする必要があります。

org.eclipse.microprofile.rest.client.ext.ClientHeadersFactory インターフェイスは以下のように定義されます。

public interface ClientHeadersFactory {

/**
 * Updates the HTTP headers to send to the remote service. Note that providers
 * on the outbound processing chain could further update the headers.
 *
 * @param incomingHeaders - the map of headers from the inbound JAX-RS request. This will
 * be an empty map if the associated client interface is not part of a JAX-RS request.
 * @param clientOutgoingHeaders - the read-only map of header parameters specified on the
 * client interface.
 * @return a map of HTTP headers to merge with the clientOutgoingHeaders to be sent to
 * the remote service.
 */
MultivaluedMap<String, String> update(MultivaluedMap<String, String> incomingHeaders,
                                      MultivaluedMap<String, String> clientOutgoingHeaders);
}

ClientHeadersFactory インターフェイスの詳細は、ClientHeadersFactory Javadoc を参照してください。

2.19.6. ResponseExceptionMapper

org.eclipse.microprofile.rest.client.ext.ResponseExceptionMapper クラスは、JAX-RS で定義される javax.ws.rs.ext.ExceptionMapper クラスのクライアント側のクラスです。つまり、ExceptionMapper.toResponse () メソッドは、サーバー側の処理中に出力された Exception クラスを Response に変えるため、ResponseExceptionMapper.toThrowable() メソッドは HTTP エラーステータスとともにクライアント側で受信された Response クラスを Exception クラスに変換します。

ResponseExceptionMapper クラスは、プログラム上または宣言的に登録できます。登録済みの ResponseExceptionMapper クラスがない場合、デフォルトの ResponseExceptionMapper クラスは、ステータス >= 400 の応答を WebApplicationException クラスにマップします。

2.19.7. CDI の統合

MicroProfile REST クライアントでは、CDI bean として管理されるインターフェイスに @RegisterRestClient クラスを付ける必要があります。例を以下に示します。

@Path("resource")
@RegisterProvider(MyClientResponseFilter.class)
public static class TestResourceImpl {
      @Inject TestDataBase db;

      @Path("test/{path}")
      @Consumes("text/plain")
      @Produces("text/html")
      @POST
      public String test(@PathParam("path") String path, @QueryParam("query")
      String query, String entity) {
         return db.getByName(query);
      }
   }
   @Path("database")
   @RegisterRestClient
   public interface TestDataBase {

      @Path("")
      @POST
      public String getByName(String name);
   }

ここで、MicroProfile REST クライアント実装は TestDataBase クラスサービスのクライアントを作成し、TestResourceImpl クラスによるアクセスを容易にします。ただし、TestDataBase クラス実装へのパスに関する情報は含まれません。この情報は、オプションの @Reg- isterProvider パラメーター baseUri で提供されます。

@Path("database")
@RegisterRestClient(baseUri="https://localhost:8080/webapp")
public interface TestDataBase {
   @Path("")
   @POST
   public String getByName(String name);
}

これは、https://localhost:8080/webappTestDataBase 実装にアクセスできることを示しています。以下のシステム変数を外部に提供することもできます。

<fully qualified name of TestDataBase>/mp-rest/url=<URL>

たとえば、以下は、https://localhost:8080/webapp で com.bluemonkeydiamond.TestDatabase クラスの実装にアクセスできることを示しています。

com.bluemonkeydiamond.TestDatabase/mp-rest/url=https://localhost:8080/webapp
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.