TP3 : Créatin de services Web REST Maintenant que vus maitrisez la cre atin et le de pliement de services web, vus allez cre er des services web REST avec JAX-RS, les de plyer et e crire les clients qui appellent ces services. Vus allez dans un premier temps de velpper un service REST simple ensuite vus allez cre er une applicatin de re servatin d h tels permettant d invquer des services de recherche et de re servatin d h tels. Vus manipulerez plusieurs technlgies : l API JPA (Java Persistence Architecture), JAXB (Java Architecture fr XML Binding) et JAX-RS (Java API fr RESTful Services). I. Dévelpper des Services REST avec JAX-RS 1. Présentatin Jusqu à présent, vus avez vu la créatin et le dépliement de services Web basés sur le prtcle SOAP. Mais une autre apprche des services Web et qui devient de plus en plus ppulaire existe: REST. Le cncept intrduit en 2000 ne fait qu'utiliser les principes fndamentaux du Web. Utilisant le prtcle HTTP, il permet l'envi de messages sans envelppe SOAP et dans un encdage libre (XML, JSON, binaire, simple texte). Il est actuellement très utilisé par les sites cmmunautaires (u réseaux sciaux) leur permettant de prpser à leurs clients une API facile à utiliser. Des sites cmme Flickr, Facebk, Last.fm, Amazn prpsent ainsi de telles API évitant à leurs clients de devir passer par la case SOAP. 2. Architecture L infrmatin de base, dans une architecture REST, est appele e ressurce. On accède à une ressurce (par sn URI unique) pur prcéder à diverses pératins (GET lecture / POST écriture / PUT mdificatin / DELETE suppressin), pératins supprtées nativement par HTTP. 3. Créatin d un premier service web REST Les services REST snt spe cifie s par le JCP (Java Cmmunity Prcess) sus le nm JAX- RS 1 (Java API fr RESTful Services). Cette spe cificatin pre cise ce que peut u dit faire une imple mentatin, cmme pur tutes ces spe cificatins. L'imple mentatin de re fe rence que l'n utilise est Jersey 2. Jersey est installe en standard dans un serveur JEE (tel que Glassfish u JBss), et peut s'installer dans un serveur Tmcat. Vus allez cre er un premier service web Rest. Vus allez suivre les e tapes suivantes : Créer un nuveau prjet : Java Web Web Applicatin que vus nmmerez «WebServiceRest», vus chisirez Glassfish cmme serveur. Créer un nuveau package que vus nmmerez cmme vus le suhaitez. Créer un service web Rest en cliquant sur NewOtherWebServiceRESTful WebServices frm Pattern. Sélectinner "Simple Rt Resurce". 1 https://jax-rs-spec.java.net/ 2 https://jersey.java.net/ Page 1
Mdifier MIME Type en sélectinnant «text/plain». Une nuvelle classe est créée par défaut «GenericResurce». Vus allez supprimer le cde par défaut et le remplacer par le cde suivant : imprt javax.ws.rs.cre.cntext; imprt javax.ws.rs.cre.uriinf; imprt javax.ws.rs.pathparam; imprt javax.ws.rs.cnsumes; imprt javax.ws.rs.put; imprt javax.ws.rs.path; imprt javax.ws.rs.get; imprt javax.ws.rs.prduces; @Path("Mypath") public class GenericResurce { @GET @Prduces("text/plain") public String gettext() { return "Mn premier service REST"; Il s agit d un service REST simple qui invque la méthde gettext qui returne une répnse sus frmat texte "Mn premier service REST. L anntatin @Path 3 désigne d'une part l'uri d'accès au service et à ses sus-services, et d'autre part la présence de paramètres dans cette URI. Cinq anntatins snt définies, qui peuvent annter certaines méthdes d'un service REST : @GET, @POST, @PUT, @DELETE, et @HEAD. Elles crrespndent aux cinq méthdes HTTP qui prtent le même nm. On ne peut pser chaque anntatin qu'une seule fis sur une unique méthde dans une classe dnnée, pur un chemin d'accès dnné. Faire un clean and build de vtre prjet et faire un deply. Faire un clic drit sur le service «GenericResurce» et sélectinner «Test Resurce Uri». Quel résultat btenez-vus? Purqui? Vus allez maintenant faire clic drit sur le prjet Test Restful Web services, ensuite vus sélectinnez «web test client in the prject» et sélectinnez vtre prjet. Vus allez uvrir le fichier WADL et décrire sn cntenu. Vus allez mdifier le frmat de répnse du service de telle srte qu il returne le message sus frmat XML. Tester vtre service. Vus allez ajuter une nuvelle méthde permettant de calculer le prduit de deux entiers. Le chemin de la ressurce dit être../prduit et le type de MIME sera sit du JSON sit du XML permettant d afficher un message de type «le prduit de deux entiers est». 3 https://jersey.java.net/dcumentatin/latest/jaxrs-resurces.html Page 2
II. Dévelppement d un service REST pur la réservatin d un hôtel L bjectif de cet exercice est le de velppement de services REST a partir de classes Java pur la recherche et la re servatin d h tels a partir d une base de dnne es. Vus allez de velpper un service de recherche et de réservatin d h tels. Vus allez cre er une base de dnne es d h tels et ge ne rer des classes entite s (gra ce a l API JPA). On suhaite y dnner l acce s via des services web. Le service Web REST dit puvir lister l'ensemble des h tels, rechercher des h tels seln des crite res de de recherche (ville, prix), de cre er, de mdifier, de supprimer et de lister une re servatin d h tel pur un client dnne. L applicatin que vus de velpperez se basera sur l architecture suivante (fig.1) : Figure 1 JAX-RS Cmmunicatin Client serveur 4 Vus allez : Créer une base de dnnées et générer des classes entités grâce à l API JPA (e.g EclipseLink) Créer les services web REST à partir de la base de dnnées Déplyer les services web dans un serveur d applicatin (e.g Glassfish) Tester les services dévelppés Créer un client pur cnsmmer le service web 1. Créatin de la base de dnnées et génératin des entités grâce à JPA a) Créatin de la base de dnnées Pur cre er une base de dnne es sus Netbeans, il suffit de : Se psitinner sur le panel «Services», de sélectinner «Databases», de faire clic drit sur «Java DB» Create Database. Nmmer vtre base de dnnées «HtelsBD» et vus renseignez les champs username et passwrd. Vus puvez vus cnnecter à la base de dnnées. 4 http://www.develper.cm/java/creating-restful-web-services-with-jax-rs.html Page 3
b) Génératin des entités avec JPA Vus allez créer un nuveau prjet de type Java Web Applicatin que vus nmmerez «HtelRes» et vus sélectinnerez Glassfish cmme serveur. Vus allez : Créer une classe entité (New Entity Class) que vus nmmerez «Htel» représentant les hôtels par leur identifiant (idhtel), leur nm (nm_htel), leur adresse (adresse), leur cde pstal (cde_pstal), leur ville (ville), le nmbre d étiles (NbreEtiles) et le prix (prix) d une nuitée. Lrs de la créatin de l entité, vus allez chisir EclipseLink cmme Furnisseur de persistence 5 (Persistence Prvider). Vus sélectinnerez ensuite cmme Data Surce la base de dnnées que vus venez de créer. Vus nmmerez le package ENTITE. Ajuter les attributs ainsi que les méthdes manquantes (cnstructeurs, les getters et les setters) dans la classe Htel.java. Quelle est la différence entre une classe Java et une classe entité? 2. Créatin, dépliement et test du service de recherche d hôtels Créer un service web REST à partir de la classe entité «Htel». Pur cela, vus allez sélectinner NewRestful Web Services frm Entity Classes, chisir l entité que vus avez créée et générer le service. Que remarquez-vus?. Déplyer (clic drit sur le prjetdeply) et tester le web service Rest (clic drit sur le prjet Test Restful Web Services. Quel résultat btenez-vus et purqui? Insérer des dnnées dans la table de vtre base de dnnées et vérifier que vtre cntexte de persistence (fichier «persistence.xml») est en mde create. Refaire le test des services web. Sélectinner GET (applicatin/xml) et cliquer sur Test. Quel résultat btenez-vus et purqui? Cmme vus avez pu le remarquer, il existe 5 nglets dans la sectin Output : La vue Tabular qui affiche tutes les URIs dans le dcument résultant. La vue Raw affiche les dnnées returnées. En fnctin du type de MIME sélectinné (applicatin/xml u applicatin/jsn), les dnnées affichées sernt respectivement sit au frmat XML sit au frmat JSON. La sectin Sub Resurce affiche tutes les URIs. L nglet Headers qui affiche les infrmatins sur le serveur, la date, etc.. Le HTTP Mnitr affiche les requêtes et les répnses HTTP envyées et reçues. Tester les différentes méthdes HTTP : GET : pur récupérer tus les hôtels et rechercher les hôtels par leur id. POST : pur créer un nuvel hôtel PUT : pur mdifier un hôtel 5 Les furnisseurs de persistance snt des imple mentatins de la spe cificatin Java Persistence API (JPA) et peuvent e tre de plye s dans le serveur d'applicatins cmpatible Java EE qui prend en charge la persistance JPA. Page 4
DELETE : pur supprimer un hôtel Créer deux méthde de recherche d hôtels : une méthde de recherche par ville et une méthde de recherche par prix et tester le service. Pur cela vus allez suivre les indicatins suivantes : Définir dans la classe entité Htel une requête nmmée de recherche d hôtels par prix grâce au langage JPQL 6. Le langage JPQL est un langage de requête dnt la grammaire est définie par la spécificatin JPA. Il ressemble au langage SQL mais ffre une apprche bjet. JPQL permet de déclarer des requêtes dites requêtes nmmées. Ces requêtes nmmées snt déclarées dans des anntatins, et dnc analysées par l'implémentatin JPA au chargement de la classe. Elles peuvent dnc être cnverties en cde SQL au mment de ce chargement, et ne pas surcharger l'exécutin de l applicatin. Une requête nmmée est déclarée dans une anntatin @NamedQuery. Cette anntatin prend deux attributs : name, qui prte le nm de la requête, et query, qui prte la requête JPQL. Plusieurs anntatins @NamedQuery peuvent être regrupées dans une anntatin @NamedQueries, qui prend un tableau de @NamedQuery en attribut. Ces deux anntatins divent être psées sur la classe d'une entité JPA. Exemple : Une requête pur déterminer tus les hôtels : @NamedQuery( name="findallhtels", query="select c frm Htel c") Définir dans la classe du service «HtelFacadeREST.java» les méthdes qui vnt respectivement returner la liste des hôtels par leur prix et la ville. La méthde de recherche par prix prendra cmme paramètre le prix d une nuitée d hôtel grâce à l anntatin @PathParam, exécutera la requête définie précédemment grâce à la méthde EntityManager.createNamedQuery() en lui passant le nm de la requête tel qu il est défini dans les anntatins. Cette méthde renvie un bjet Query. L'bjet EntityManager est respnsable de la gestin des entités et de leurs états. Il va ainsi permettre les pératins de base ffertes par le langage relatinnel que snt : l'ajut ; la lecture ; la mise à jur et la suppressin. Vus allez dnc cmpléter le cde suivant : //cmpléter la méthde HTTP utilisée pur déclencher cette méthde.. //spécifier le type MIME de la répnse du service. //cmpléter le chemin.. 6 http://dcs.racle.cm/cd/e17904_01/apirefs.1111/e13946/ejb3_langref.html Page 5
public List<Htel> findhtelsbyville(@pathparam("ville") String ville) { Query query = em.createnamedquery("cmpléter par le nm de la requête nmmée"); query.setparameter("ville", ville); // La méthde setparameter() permet de furnir une valeur à chaque paramètre. return query.getresultlist(); Sauvegarder et tester le service. 3. Lcalisatin des hôtels avec Ggle Map NetBeans met a dispsitin les acce s a diffe rents web services cmme GgleMap, FaceBk, Twitter, Yutube, Zillw 7... Il en existe e galement qui snt accessibles sur la tile directement via leur fichier de descriptin WSDL. Vus allez dans un premier temps tester le service Ggle Map et dans un secnd temps faire appel a ce service afin de lcaliser les h tels. a) Ggle Map Vus allez suivre les instructins suivantes : Vérifiez que vtre serveur est bien en marche en allant sur http://lcalhst:8080. Vus aurez besin d une clé pur Ggle Map API. Vus allez vus rendre sur le site suivant : https://develpers.ggle.cm/maps/dcumentatin/javascript/tutrial#api_key et de bien suivre les instructins pur la créatin de la clé. Sauvegardez la clé btenue, vus en aurez besin. N ubliez pas d ajuter l url http://lcalhst:8080 en tant que dmaine (dans Referers). Dans la classe «HtelFacadeREST», vus allez ajuter une nuvelle méthde «getgglemap» : @GET @Prduces("text/html") public String getgglemap() { // Drag and drp the getgglemap peratin here return ""; Pur ajuter le service web Ggle Map, vus allez sur l nglet Services et uvrez le nœud Web ServicesGgleMap Service (vir figure suivante). 7 https://netbeans.rg/kb/dcs/websvc/zillw.html Page 6
Faites un drag et drp de getgglemap dans la méthde «getgglemap» que vus venez de créer. Vus puvez mdifier les paramètres par défaut qui apparaissent dans le pp-up u les garder tels quels en cliquant sur OK. Remplacer la ligne suivante : ut.println("the SaasService returned: "+result.getdataasstring()); par return result.getdataasstring(); et sauvegardez la classe. Vtre prjet a été mdifié. En effet, 4 classes nt été créées : GgleMapService.java : permet de vérifier la clé dans le fichier prperties et returne un texte HTML pur accéder à GgleMap. RestCnnectin.java : permet d établir la cnnexin avec les serveurs Ggle. RestRespnse.java : récupère les dnnées returnées par Ggle. GgleMapsService.java : représente la classe utilisée par vtre servlet pur interagir avec les autres classes et Ggle Vus allez mdifier le fichier «gglemapservice.prperties» qui se truve sus le package «rg.netbeans.saas.ggle» en ajutant la clé que vus avez récupérée. Ouvrez dans l éditeur «GgleMapService.java» et mdifiez la classe GeCder en ajutant un nuvel argument à RestCnnectin. La ligne de cde devra ressembler à ceci : RestCnnectin cl = new RestCnnectin(GEOCODE_URL, params, null); Tester (il suffit de rafraîchir la page http://lcalhst:8080/htels/test-resbeans.html car le de pliement se fait autmatiquement). Page 7
b) Lcaliser les hôtels avec Ggle Map Ggle Map a affiché une adresse par défaut (Menl Park) pur tus les hôtels de la base de dnnées. Pur afficher l adresse de chaque hôtel, il faut créer une instance d hôtel et mdifier l adresse pur qu elle sit égale à l adresse de l hôtel (ville, adresse et cde pstal). 4. Dévelppement d un service REST pur la réservatin d hôtels Vus allez cre er un service Rest pur la re servatin d un h tel. Vus allez cre er une classe entite «Reservatin» dans le package ENTITE qui repre sente la re servatin d un h tel. Le mde le de base de dnne es est de crit dans le MCD ci-dessus. Le service devra permettre de lister tutes les re servatins, ajuter une re servatin, mdifier une re servatin et supprimer une re servatin. Il ne faut pas ublier de de finir l assciatin entre les deux tables (anntatins @OnetMany et ManytOne). a) Définitin des relatins entre les entités Il faut définir l assciatin entre les deux tables en définissant les anntatins @OnetMany et ManytOne. Il faut gérer la cascade en définissant une cascade de type ALL. En effet, n suhaite que quand n supprime un hôtel, sa réservatin sit également supprimée. b) Mapping des entités à XML grâce à JAXB Ajuter l anntatin JAXB @XmlRtElement pur chaque classe entité. Ajuter l anntatin JAXB @XmlTransient pur chaque les getters. Page 8
5. Dévelppement d un client du service REST : réservatin d hôtels Maintenant, vus allez de finir un client pur l invcatin des services de recherche d h tels et de re servatin d h tels. a) Créatin d une applicatin client pur l invcatin du service Hôtel Vus allez : Cre er un nuveau prjet de type Java applicatin que vus nmmerez «HtelClient» (de cchez la cre atin de la classe main). Générer les classes entité à partir de la base de dnnées : NewEntity Classes frm Databases. Vus sélectinnerez la base de dnnées HtelsBD et ajuterez les tables de la base de dnnées. Vus nmmerez le package «ENTITE». Invquer l pératin de créatin d un hôtel à partir du client. Pur cela, vus allez faire NewOtherWeb ServicesRestful Java Client. Vus nmmerez la classe «HtelCreateClient» et vus sélectinnerez la ressurce REST crrespndante. L'API client de Jersey permet l'interpérabilité avec des web services Rest. Que cmprte la nuvelle classe générée? Ajuter une méthde main dans la classe «HtelCreateClient». public static vid main(string args[])thrws UnifrmInterfaceExceptin { HtelCreateClient client=new HtelCreateClient (); ClientRespnse respnse=client.findall(clientrespnse.class); GenericType<List<Htel>> generictype = new GenericType<List<Htel>>() {; // Returne un tableau d hôtels à partir du service web List<Htel> data= new ArrayList<Htel>(); data=(respnse.getentity(generictype)); Htel H=new Htel(); //ajuter les dnnées sur l hôtel que vus allez insérer H.setAdresse("."); p.setnmhtel(" "); ; client.create(p); Exe cuter la classe et ve rifier que l h tel a bien e te cre e. Invquer les autres pératins du service : recherche de tus les hôtels, recherche des hôtels par prix, suppressin d un hôtel, etc. b) Créatin d une applicatin client pur l invcatin du service Réservatin Vus allez cre er un client pur l invcatin du service Re servatin pur l ajut d une re servatin pur un h tel dnne, l affichage de tutes les re servatins, etc. Page 9