[18.0.0.1 and later]

Configuration du client MicroProfile Rest Client

Appelez le client MicroProfile Rest Client avec la fonction mpRestClient-1.0.

Avant de commencer

MicroProfile Rest Client 1.0 requiert Java SDK 8.

Pourquoi et quand exécuter cette tâche

Le client MicroProfile Rest Client est construit sur des API client JAX-RS 2.0 afin de fournir une approche de type sécurisé pour appeler des services RESTful via HTTP. Vous pouvez écrire des applications client avec du code davantage centré sur le modèle. Exécutez la procédure suivante pour créer vos propres clients REST.

Procédure

  1. Créez une interface représentant le service distant. Faites correspondre les méthodes de l'interface aux API RESTful du noeud final. L'exemple suivant montre une interface exemple accédant à un service de musique en ligne.
    @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;
    }

    Tout comme JAX-RS côté serveur, l'interface exemple utilise des annotations comme @Path, @Consumes, @GET et @PathParam.

  2. Appelez des méthodes définies dans l'interface.
    L'interface exemple définit des méthodes que vous pouvez appeler.
    • Appelez la méthode getPlaylistNames pour obtenir les noms disponibles des listes de lecture. L'implémentation du client REST envoie une demande GET au noeud final à l'emplacement <URLbase>/playlist. Cet emplacement accepte le type de support application/json d'une liste de chaînes indiquant les noms disponibles des listes de lecture.
    • Appelez la méthode getPlaylist pour voir quelles chansons figurent dans une liste de lecture. Cette méthode émet une erreur UnknownPlaylistException, qui peut également être signalée sur le service distant et renvoyer une réponse HTTP 404.
  3. Utilisez une commande ResponseExceptionMapper pour gérer les exceptions. L'exemple suivant convertit la réponse HTTP 404 en une exception spécifique.
    @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;
        }
    
    }
    Dans l'exemple, les cas UnknownPlaylistException et PlaylistAlreadyExistsException sont des sous-classes du cas BasePlaylistException. La réponse toThrowable renvoie une instance de l'exception plutôt que de l'émettre.
  4. Une fois que vous avez écrit l'interface et l'associateur d'exception de réponse, générez l'implémentation et démarrez-la. Vous pouvez générer l'implémentation avec l'API RestClientBuilder ou CDI (Contexts and Dependency Injection) et MP Config.
  5. Facultatif : Utilisez l'API RestClientBuilder, qui est plus prolixe mais est utilise dans des environnements où CDI n'est pas disponibles, par exemple pour du test.
    1. Créez une instance de l'API RestClientBuilder.
    2. Spécifiez l'URL baseURL du noeud final distant, qui est nécessaire avant de générer le client.
    3. Enregistrez l'associateur d'exception de réponse. Si vous avez besoin d'enregistrer d'autres classes de fournisseur, comme MessageBodyReaders, MessageBodyWriters, filters ou interceptors, enregistrez-les avec la méthode register.
    4. Générez le client et passez à la classe d'interface.
    5. Appelez des méthodes sur le client comme vous le feriez avec un autre objet Java™.
    L'exemple suivant montre un code exemple qui génère et appelle l'implémentation avec l'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. Facultatif : Utilisez CDI et MP Config pour instancier le client.
    1. Installez la fonction mpRestClient-1.0 dans le fichier Liberty server.xml.
    2. Ajoutez la fonction cdi-1.2 ou cdi-2.0.
    3. Ajoutez la fonction mpConfig-1.1 ou mpConfig-1.2.
    4. Mettez à jour l'interface MusicPlaylistService avec les annotations suivantes :
      @Path("/playlist")
      @Consumes("application/json")
      @Dependent
      @RegisterRestClient
      @RegisterProvider(PlaylistResponseExceptionMapper.class)
      public interface MusicPlaylistService {
          ...
      L'annotation @Dependent ou une autre annotation de portée comme @ApplicationScoped ou @RequestScoped est requise pour que CDI détecte et gère l'interface client REST. L'annotation @RegisterRestClient indique à l'implémentation de MicroProfile Rest Client d'implémenter dynamiquement l'interface. L'annotation @RegisterProvider indique au code d'implémentation de MicroProfile Rest Client d'enregistrer la classe de fournisseur spécifiée. Vous pouvez répéter l'annotation @RegisterProvider sur la même interface pour autant de fournisseurs que nécessaire.
    5. Injectez le client dans un autre objet géré. Combinez l'annotation @Inject avec le décorateur @RestClient pour indiquer à CDI d'injecter une instance de l'interface 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. Utilisez MP Config pour indiquer l'URL baseUrl du noeud final distant dans l'implémentation de MicroProfile Rest Client. Spécifiez la propriété de configuration <NomInterfaceQualifiéComplet>/mp-rest/url avec MicroProfile Config. Une option consister à définir une propriété système dans le fichier jvm.options :
      -Dcom.mypkg.MusicPlaylistService/mp-rest/url=http://localhost:9080/onlineMusicService

      L'injection CDI est plus simple lorsque vous souhaitez amorcer le client. Avec MP Config, vous pouvez utiliser différentes URL pour différents environnements, par exemple une URL pour le test et une autre pour la production, sans avoir à modifier le code.


Icône indiquant le type de rubrique Rubrique Tâche

Nom du fichier : twlp_mp_restclient.html