[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는 HTTP를 통한 RESTful 서비스 호출에서 유형-안전(type-safe) 접근 방식을 제공하기 위해 JAX-RS 2.0 Client API를 기반으로 빌드합니다. 더욱 모델 중심적 코드로 클라이언트 애플리케이션을 작성할 수 있습니다. 사용자 자신의 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;
        }
    
    }
    이 예제에서, UnknownPlaylistExceptionPlaylistAlreadyExistsException 경우 둘 다 BasePlaylistException 경우의 서브클래스입니다. toThrowable 응답은 이를 처리하는 대신 예외 인스턴스를 리턴합니다.
  4. 인터페이스와 응답 예외 맵퍼를 쓴 후, 구현을 빌드하고 시작하십시오. RestClientBuilder API 또는 CDI(Contexts and Dependency Injection) 및 MP 구성으로 구현을 빌드할 수 있습니다.
  5. 옵션: 다소 장황하지만 CDI를 사용할 수 없는 환경(예: 테스트 환경)에서 유용한 RestClientBuilder API를 사용하십시오.
    1. RestClientBuilder API의 인스턴스를 작성하십시오.
    2. 클라이언트를 빌드하기 전에 원격 엔드포인트의 baseURL URL을 지정하십시오.
    3. 응답 예외 매퍼를 등록하십시오. MessageBodyReaders, MessageBodyWriters, filters 또는 interceptors 등의 기타 제공자 클래스를 등록해야 하는 경우 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 구성을 사용하십시오.
    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. 클라이언트를 다른 관리 오브젝트에 삽입하십시오. MusicPlaylistService 인터페이스의 인스턴스에 삽입하도록 CDI에 지시하려면 @Inject 어노테이션을 @RestClient 데코레이터와 결합하십시오.
       @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 Rest Client 구현에서 원격 엔드포인트의 baseUrl URL을 표시하려면 MP 구성을 사용하십시오. MicroProfile 구성으로 <fullyQualifiedInterfaceName>/mp-rest/url 구성 특성을 지정하십시오. 하나의 옵션은 jvm.options 파일에서 시스템 특성을 설정하는 것입니다.
      -Dcom.mypkg.MusicPlaylistService/mp-rest/url=http://localhost:9080/onlineMusicService

      클라이언트를 부트스트랩하려는 경우 CDI 인젝션은 더 단순합니다. MP 구성을 사용하여 코드를 변경할 필요없이 테스트용으로 하나의 URL을, 프로덕션용으로 다른 URL을 보유하는 것 같이 다른 환경에 대해 다른 URL을 사용할 수 있습니다.


주제의 유형을 표시하는 아이콘 태스크 주제

파일 이름: twlp_mp_restclient.html