[18.0.0.1 and later]

Configuración de MicroProfile Rest Client

Invoque MicroProfile Rest Client con la característica mpRestClient-1.0.

Antes de empezar

MicroProfile Rest Client 1.0 necesita Java SDK 8.

Acerca de esta tarea

MicroProfile Rest Client se basa en las API de cliente JAX-RS 2.0 para proporcionar un enfoque con seguridad de tipo para invocar servicios RESTful sobre HTTP. Puede escribir aplicaciones cliente con código más centrado en el modelo. Complete los pasos siguientes para crear sus propios clientes REST.

Procedimiento

  1. Cree una interfaz que represente el servicio remoto. Haga coincidir los métodos de la interfaz con las API RESTful del punto final. El ejemplo siguiente muestra una interfaz de ejemplo que accede a un servicio de música en línea.
    @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;
    }

    Al igual que JAX-RS en el lado del servidor, la interfaz de ejemplo utiliza anotaciones como @Path, @Consumes, @GET y @PathParam.

  2. Invoque métodos que estén definidos en la interfaz.
    La interfaz de ejemplo define métodos que puede invocar.
    • Invoque el método getPlaylistNames para obtener los nombres disponibles de las listas de reproducción. La implementación de cliente REST envía una solicitud GET al punto final en la ubicación <baseUrl>/playlist. Esta ubicación acepta el tipo de soporte application/json de una lista de series que indican las listas disponibles de las listas de reproducción.
    • Invoque el método getPlaylist para ver qué canciones se incluyen en una lista de reproducción. Este método genera un error UnknownPlaylistException, que también se puede indicar en el servicio remoto y puede devolver una respuesta HTTP 404.
  3. Utilice un mandato ResponseExceptionMapper para manejar excepciones. El ejemplo siguiente convierte la respuesta HTTP 404 en una excepción específica.
    @Provider
    public class PlaylistResponseExceptionMapper implements
        ResponseExceptionMapper<BasePlaylistException> {
    
        @Override
        public boolean handles(int statusCode, MultivaluedMap<String, Object> headers) {
            return statusCode == 404  // No encontrado
                || statusCode == 409; // Conflicto
        }
    
        @Override
        public BasePlaylistException toThrowable(Response response) {
            switch(response.getStatus()) {
            case 404: return new UnknownPlaylistException();
            case 409: return new PlaylistAlreadyExistsException();
            }
            return null;
        }
    
    }
    En el ejemplo, los casos UnknownPlaylistException y PlaylistAlreadyExistsException son subclases del caso BasePlaylistException. La respuesta toThrowable devuelve una instancia de la excepción en lugar de generarla.
  4. Después de escribir el correlacionador de excepción de respuesta e interfaz, cree la implementación e iníciela. Puede crear la implementación con la API RestClientBuilder o Contexts and Dependency Injection (CDI) y MP Config.
  5. Opcional: Utilice la API RestClientBuilder, que es más detallada, pero es útil en entornos donde CDI no está disponible, como en las pruebas.
    1. Cree una instancia de la API RestClientBuilder.
    2. Especifique el URL baseURL del punto final remoto, que es necesario antes de crear el cliente.
    3. Registre el correlacionador de excepción de respuesta. Si necesita registrar otras clases de proveedor, como MessageBodyReaders, MessageBodyWriters, filters o interceptors, regístrelas con el método register.
    4. Cree el cliente y páselo en la clase de interfaz.
    5. Invoque los métodos en el cliente como lo haría con otro objeto Java™.
    El ejemplo siguiente muestra código de ejemplo que crea e invoca la implementación con la API RestClientBuilder.
    ...
    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. Opcional: Utilice CDI y MP Config para crear una instancia del cliente.
    1. Instale la característica mpRestClient-1.0 en el archivo server.xml de Liberty.
    2. Añada la característica cdi-1.2 o cdi-2.0.
    3. Añada la característica mpConfig-1.1 o mpConfig-1.2.
    4. Actualice la interfaz MusicPlaylistService con las anotaciones siguientes:
      @Path("/playlist")
      @Consumes("application/json")
      @Dependent
      @RegisterRestClient
      @RegisterProvider(PlaylistResponseExceptionMapper.class)
      public interface MusicPlaylistService {
          ...
      La anotación @Dependent u otra anotación de ámbito, como @ApplicationScoped o @RequestScoped, es necesaria para que CDI detecte y gestione la interfaz de Rest Client. La anotación @RegisterRestClient indica a la implementación de MicroProfile Rest Client que implemente dinámicamente la interfaz. La anotación @RegisterProvider indica el código de implementación de MicroProfile Rest Client para registrar la clase de proveedor especificada. Puede repetir la anotación @RegisterProvider en la misma interfaz para tantos proveedores como necesite.
    5. Inyecte el cliente en otro objeto gestionado. Combine la anotación @Inject con el decorador @RestClient para indicar a CDI que inyecte una instancia de la interfaz MusicPlaylistService:
       @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. Utilice MP Config para indicar el URL baseUrl del punto final remoto en la implementación de MP Rest Client. Especifique la propiedad de configuración <nombreInterfazCompleto>/mp-rest/url con MicroProfile Config. Una opción es establecer una propiedad de sistema en el archivo jvm.options:
      -Dcom.mypkg.MusicPlaylistService/mp-rest/url=http://localhost:9080/onlineMusicService

      La inyección de CDI es más sencilla si desea ejecutar el programa de arranque en el cliente. Con MP Config, puede utilizar diferentes URL para entornos diferentes, por ejemplo tener un URL para pruebas y otro URL para producción, sin necesidad de cambiar el código.


Icono que indica el tipo de tema Tema de tarea

Nombre de archivo: twlp_mp_restclient.html