![[18.0.0.1 and later]](../ng_v18001plus.gif)
Configuration du client MicroProfile Rest Client
Appelez le client MicroProfile Rest Client avec la fonction mpRestClient-1.0.
Avant de commencer
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
- 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.
- 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.
- Utilisez une commande ResponseExceptionMapper pour gérer les exceptions. L'exemple suivant convertit la réponse HTTP 404 en une exception spécifique.
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.@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; } }
- 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.
- 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.
- Créez une instance de l'API RestClientBuilder.
- Spécifiez l'URL baseURL du noeud final distant, qui est nécessaire avant de générer le client.
- 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.
- Générez le client et passez à la classe d'interface.
- Appelez des méthodes sur le client comme vous le feriez avec un autre objet Java™.
... 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); } } ...
- Facultatif : Utilisez CDI et MP Config pour instancier le client.
- Installez la fonction mpRestClient-1.0 dans le fichier Liberty server.xml.
- Ajoutez la fonction cdi-1.2 ou cdi-2.0.
- Ajoutez la fonction mpConfig-1.1 ou mpConfig-1.2.
- Mettez à jour l'interface MusicPlaylistService avec les annotations suivantes :
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.@Path("/playlist") @Consumes("application/json") @Dependent @RegisterRestClient @RegisterProvider(PlaylistResponseExceptionMapper.class) public interface MusicPlaylistService { ...
- 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(); ...
- 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.

Nom du fichier : twlp_mp_restclient.html