4.8. MicroProfile REST クライアントの開発

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

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

以下の例は、Jakarta RESTful Web Services ネイティブ方法を使用して TestResource クラスにアクセスする方法を示しています。

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}")
   @Consumes("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

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

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

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

@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() メソッドを呼び出す必要がなくなります。

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

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

@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 ...;
}

org.eclipse.microprofile.rest.client.ext.ResponseExceptionMapper クラスは、Jakarta RESTful Web Services で定義される javax.ws.rs.ext.ExceptionMapper クラスとは逆のクライアント側です。ExceptionMapper.toResponse() メソッドは、サーバー側の処理中に発生する Exception クラスを Response クラスに変換します。ResponseExceptionMapper.toThrowable() メソッドは、HTTP エラーステータスでクライアント側で受信した Response クラスを Exception クラスに変換します。

ResponseExceptionMapper クラスは、プログラムまたは宣言で登録できます。登録された ResponseExceptionMapper クラスがない場合、デフォルトの ResponseExceptionMapper クラスはステータス >= 400 のレスポンスを WebApplicationException クラスにマップします。

MicroProfile REST クライアントでは、@RegisterRestClient クラスで、Jakarta Contexts and Dependency Injection(Jakarta Contexts and Dependency Injection)Bean として管理されるインターフェイスにアノテーションを付ける必要があります。以下に例を示します。

@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 クラス実装へのパスに関する情報は含まれません。この情報は、オプションの @RegisterProvider パラメーター baseUri で指定できます。

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

これは、https://localhost:8080/webapp で TestDataBase の実装にアクセスできることを示しています。MicroProfile 設定を使用して情報を外部で提供することもできます。

<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

Jakarta Contexts and Dependency Injection クライアントに他のプロパティーを多数指定できます。たとえば、com.mycompany.remoteServices.MyServiceClient/mp-rest/providers と、クライアントに含める完全修飾プロバイダークラス名のコンマ区切りリスト。