Tutoriel sur le dveloppement de services WebREST avec JAX-RS et Netbeans : Leon 3Par Mickael BARONDate de publication : 7 septembre 2011 Dernire mise jour : 15 janvier 2013 Lebutdecettetroisimeleonestd'apprendremanipulerl'APIJAX-RSpourledveloppement de services Web REST partir de la plateforme de dveloppement Java.La leon insiste sur les dveloppements serveur et client d'un service Web REST.Butspdagogiques:transformationd'uneclasseJavaenserviceWebREST,manipulation des annotations JAX-RS, gnration de fichier WADL, utilisation de SOAP-UI pour invoquer un service Web REST partir de WADL, utilisation de l'implmentationJERSEY, utilisation de l'API cliente de JERSEY.Pour ragir au contenu de ce tutoriel, un espace de dialogue vous est propos sur le forum .Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 2 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/Exercice 1 - Dvelopper un Service Web REST : Bonjour ENSMA........................................................................... 3But........................................................................................................................................................................... 3Description.............................................................................................................................................................. 3tapessuivre.......................................................................................................................................................3Exercice 2 - Dvelopper un Service Web REST : Interrogation et rservation de train..............................................6But........................................................................................................................................................................... 6Description.............................................................................................................................................................. 6tapessuivre.......................................................................................................................................................6Exercice 3 - Dvelopper un client de Service Web REST : Interrogation et rservation de train..............................11But......................................................................................................................................................................... 11Description............................................................................................................................................................ 11tapessuivre.....................................................................................................................................................11Remerciements.......................................................................................................................................................... 14Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 3 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/Exercice 1 - Dvelopper un Service Web REST : Bonjour ENSMABut Dvelopper un service web REST partir d'une classe Java. Dployer sous Glashfish, tester le service web avec CURL. Tester le service web avec SOAP-UI. Tester le service web avec les outils de Netbeans.DescriptionLe service Web de type REST de ce premier exercice consiste fournir un accs la ressource Bonjour ENSMA quipermet de donner des messages diffrents selon la date du jour. Les services proposs n'autorisent que la lecture la ressource (GET). Ces services de rcupration peuvent possder des paramtres. Enfin, le format de rcuprationde la ressource est du XML.tapes suivreDmarrer l'environnement de dveloppement NetBeans.Crer un nouveau projet File -> New Project... puis Java Web et choisir Web Application, faire Next.Dans le nom du projet choisir le nom HelloENSMAWebServiceRestExercice1.Comme type de serveur d'application, choisir GlassFish 3 et comme version Java EE choisir la version 7 puis faireNext.Ne rien choisir dans les options de Frameworks, puis faire Finish. L'initialisation d'un projet Web est en cours.CrerunserviceWebRESTpartirdel'assistantdecrationWebServices->RESTfulWebServicesfromPatterns puis faire Next.Choisir par la suite, l'option Simple Root Resource puis faire Next. Dans le champ Resource Package dfinir lavaleur soa.jaxrslabs.helloensmawebservicerestexercice1, dans le champ Path saisir la valeur helloensma, dans lechamp Class Name saisir la valeur HelloEnsma, puis faire Finish.Par la suite, il est demand la manire dont les ressources sont gres par l'application, choisir la troisime proposition(Create default REST servlet adaptor in web.xml). Notez que pour accder toutes les ressources il faudra prfixerles chemins par /resources.DepuislanouvelleclassecreHelloEnsma,supprimerlamthodecorrespondantlacrationd'uneressourceHelloEnsma (mthode putXml).Dans le corps de la mthode String getXml() utilise pour rcuprer la ressource Bonjour ENSMA, recopier le contenusuivant1.@GET2.@Produces("application/xml")3.public String getXml() {4. return "Bonjour ENSMA";5.}Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 4 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/FaireunCleanandBuildpartirduprojetHelloENSMAWebServiceRestExercice1ets'assurerqueleprojetseconstruit correctement.Faire un Deploy partir du projet. Le serveur Glassfish doit dmarrer. Sur la console de Glassfish, un Web Servicedoit avoir t dcouvert, un message similaire doit tre prsent :Ouvrir une fentre d'un navigateur Web et tester la rcupration de la ressource Bonjour ENSMA (requte GET vial'URL http://localhost:8080/HelloENSMAWebServiceRestExercice1/resources/helloensma).AjouterunenouvellemthodeJavagetXmlWithParamsdanslaclasseHelloEnsmaquipermetdercuprerlaressource Bonjour ENSMA via des paramtres de requtes. Ces paramtres seront donns via le chemin et via l'en-tte de la requte en utilisant respectivement les annotations @PathParam et @HeaderParam. Recopier le codesuivant :1. @GET2. @Path("{id}")3. @Produces("application/xml")4. public String getXmlWithParams(5. @PathParam("id") String id,6. @DefaultValue("all") @HeaderParam("name") String name) {7. System.out.println(id);8. System.out.println(name);9. return "Bonjour ENSMA de la part de " + name + "";10. }Saisir l'URL suivante depuis votre navigateur Web pour tester la rcupration de la ressource Bonjour ENSMA : http://localhost:8080/HelloENSMAWebServiceRestExercice1/resources/helloensma/27022011.LemessageauformatXML est retourn au navigateur.Pour envoyer des paramtres au niveau de l'en-tte de la requte, nous utiliserons l'outil CURL qui est un outil enligne de commande pour construire des requtes HTTP. Tlcharger et installer l'outil partir de l'URL suivante :http://curl.haxx.se/.Depuis une invite de commande saisir la commande suivante :partird'unnavigateurWeb,afficherlecontratdedescriptionWADLvial'URLsuivante:http://localhost:8080/HelloENSMAWebServiceRestExercice1/resources/application.wadl.Utiliser l'outil de test de service Rest fourni par Netbeans (menu contextuel du projet et choisir l'lment Test RESTfulWeb Services).Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 5 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/Envoyer une requte HTTP de type GET pour rcuprer une ressource Bonjour ENSMA. Noter qu'il n'est pas possibleavec cet outil de modifier l'en-tte d'une requte HTTP.Tlcharger et installer l'outil SOAP-UI partir de l'URL suivante : http://www.soapui.org/. Ouvrir SOAP-UI et crerun projet partir de ce contrat de description.Envoyer une requte HTTP de type GET pour rcuprer une ressource Bonjour ENSMA. Modifier cette requte defaon transmettre galement les paramtres via le chemin et via l'en-tte de la requte HTTP.Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 6 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/Exercice 2 - Dvelopper un Service Web REST : Interrogation et rservation de trainBut Dvelopper un service web REST partir d'une classe Java. Utilisation d'un Sub-Resource Locator. Mise en place d'un CRUD complet. Dployer sous GlassFish et tester le service web avec CURL.DescriptionLeserviceWebRESTdecedeuximeexerciceconsistecrerunsystmeCRUDpourl'interrogationetlarservation de trains. Les ressources manipules par les services sont donc un train et une rservation. Le serviceWebRESTdoitpouvoirlisterl'ensembledestrains,listerlestrainsquisatisfontuncritrederecherche(villededpart, ville d'arrive, jour de dpart et un intervalle de temps), de crer, de modifier, de supprimer et de lister unerservation pour un client donn. Nous insisterons sur l'accessibilit des services et non sur le code mtier.tapes suivreCrer un nouveau projet File -> New Project... puis Java Web et choisir Web Application, faire Next.Dans le nom du projet choisir le nom BookTrainWebServiceRestExercice2.Comme type de serveur d'application, choisir GlassFish 3 et comme version Java EE choisir la version 6 puis faireNext.Ne rien choisir dans les options de Frameworks, puis faire Finish. L'initialisation d'un projet Web est en cours.Crer la classe Train (dans le package soa.jaxrslabs.booktrainwebservicerestexercice2) qui modlise le concept deTrain et qui contient un attribut String numTrain (identifiant fonctionnel d'un train), un attribut String villeDepart (la villede dpart du train), un attribut String villeArrivee (la ville d'arrive du train), un attribut int heureDepart (heure de dpartdepuis la ville de dpart). Ajouter des modificateurs et des accesseurs sur tous les attributs. Voir le code suivant1. @XmlRootElement(name = "train")2. public class Train {3. 4. private String numTrain;5. private String villeDepart;6. private String villeArrivee;7. private int heureDepart; // Format : 1230 = 12h308. 9. public Train() {10. }11. 12. public Train(String numTrain, String villeDepart, String villeArrivee, int heureDepart) {13. this.numTrain = numTrain;14. this.villeDepart = villeDepart;15. this.villeArrivee = villeArrivee;16. this.heureDepart = heureDepart;17. }18. 19. public int getHeureDepart() { 20. return heureDepart;21. }22. 23. public void setHeureDepart(int heureDepart) {24. this.heureDepart = heureDepart;25. }26. Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 7 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/27.... // A complter...28. }Crer la classe BookTrainBD qui sert persister toutes les informations concernant le service Web de cet exercice.1. public class BookTrainBD {2. 3. private static List trains = new ArrayList();4. 5. static {6. trains.add(new Train("TR123", "Poitiers", "Paris", 1250));7. trains.add(new Train("TR127", "Poitiers", "Paris", 1420));8. trains.add(new Train("TR129", "Poitiers", "Paris", 1710));9. }10. 11. public static List getTrains() {12. return trains;13. }14. }Crer la classe TrainResource (dans le package soa.jaxrslabs.booktrainwebservicerestexercice2) permettant l'accsaux services Web REST de la ressource Train. Dfinir comme chemin de ressource racine la valeur /trains (utilisationde l'annotation @Path) puis ajouter trois mthodes qui permettent respectivement de retourner la liste des trains,un train en fonction de son identifiant fonctionnel et une recherche de trains par critres passs en paramtre de larequte (ville de dpart, ville d'arrive et heure de dpart). Pour cette dernire mthode, le sous-chemin associ est/search. Noter que le format de retour des services est du XML.1. @Path("/trains")2. // Complter le format de reprsentation des services3. public class TrainResource {4. 5. public TrainResource() {6. }7. 8.// Complter la mthode HTTP utilise pour dclencher cette mthode9. public List getTrains() {10. System.out.println("getTrains");11. 12. return BookTrainBD.getTrains();13. }14. 15.// Complter la mthode HTTP utilise pour dclencher cette mthode16.// Complter le chemin suivant ce template numTrain-TR123 o TR123 est une chaine variable17. public Train getTrain(@PathParam("id") String numTrain) {18. System.out.println("getTrain");19. 20. for (Train current : BookTrainBD.getTrains()) {21. if (numTrain.equals(current.getNumTrain())) {22. return current;23. }24. }25. return null;26. }27. 28.// Complter la mthode HTTP utilise pour dclencher cette mthode29.// Complter de faon dfinir le chemin suivant /trains/search pour invoquer cette mthode30. public List searchTrainsByCriteria(@QueryParam("departure") String departure, @QueryParam("arrival")31. String arrival, @QueryParam("arrivalhour") String arrivalHour) {32. System.out.println("searchTrainsByCriteria");33. 34. return BookTrainBD.getTrains().subList(0, 2);35. }36. } partir d'un navigateur Web invoquer les trois services dfinis ci-dessus.Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 8 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/ http://localhost:8080/BookTrainWebServiceRestExercice2/resources/trains http://localhost:8080/BookTrainWebServiceRestExercice2/resources/trains/numTrain-TR123 http://localhost:8080/BookTrainWebServiceRestExercice2/resources/trains/search?departure=poitiers&arrival=paris&arrivalhour=1250Crer la classe BookTrain (toujours dans le package soa.jaxrslabs.booktrainwebservicerestexercice2) qui modlisele concept de rservation de Train et qui contient un attribut String numBook (identifiant fonctionnel de la rservationd'untrain),unattributTraincurrentTrain(associationsurletraindelarservation),unattributintnumberPlaces(nombre de places rserves). Ajouter des modificateurs et des accesseurs sur tous les attributs.1. @XmlRootElement(name = "booktrain")2. public class BookTrain {3. 4. private String bookNumber;5. 6. private Train currentTrain;7. 8. private int numberPlaces;9. 10. public String getBookNumber() {11. return bookNumber;12. }13. 14. public void setBookNumber(String bookNumber) {15. this.bookNumber = bookNumber;16. }17. 18. public Train getCurrentTrain() {19. return currentTrain;20. }21. 22....23. }Complter la classe BookTrainBD de faon persister les informations concernant les services lis la rservationde train.1. public class BookTrainBD {2. 3. private static List trains = new ArrayList();4. 5. private static List bookTrains = new ArrayList();6. 7. static {8. trains.add(new Train("TR123", "Poitiers", "Paris", 1250));9. trains.add(new Train("TR127", "Poitiers", "Paris", 1420));10. trains.add(new Train("TR129", "Poitiers", "Paris", 1710));11. }12. 13. public static List getTrains() {14. return trains;15. }16. 17. public static List getBookTrains() {18. return bookTrains;19. }20. }Crer la classe BookTrainResource (dans le package soa.jaxrslabs.booktrainwebservicerestexercice2) permettantl'accsauxservicesWebRESTdelaressourceRservation.Quatremthodessontdfinir.LapremirecreateBookTrainestinvoquepourlacrationd'uneressourceRservation(mthodePOST).LadeuximegetBookTrains(mthodeGET)estutilisepourlisterl'ensembledesrservations.LatroisimegetBookTrain(mthodeGET)permetderetournerlesinformationsd'unerservationpartird'unnumroderservation.Finalement removeBookTrain (mthode DELETE) permet de supprimer une rservation.Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 9 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/1. public class BookTrainResource {2. 3.// Complter la mthode HTTP utilise pour dclencher cette mthode4. public String createBookTrain(String numTrain, int numberPlaces) {5. Train currentTrain = null;6. for (Train current : BookTrainBD.getTrains()) {7. if (current.getNumTrain().equals(numTrain)) {8. currentTrain = current;9. }10. }11. if (currentTrain == null) {12. return "";13. }14. 15. BookTrain newBookTrain = new BookTrain();16. newBookTrain.setNumberPlaces(numberPlaces);17. newBookTrain.setCurrentTrain(currentTrain);18. newBookTrain.setNumBook(Long.toString(System.currentTimeMillis()));19. BookTrainBD.getBookTrains().add(newBookTrain);20. 21. return newBookTrain.getNumBook();22. }23. 24. // Complter la mthode HTTP utilise pour dclencher cette mthode25. public List getBookTrains() {26. System.out.println("getBookTrains");27. return BookTrainBD.getBookTrains();28. }29. 30. // Complter la mthode HTTP utilise pour dclencher cette mthode31.// Complter le chemin de faon intgrer un template parameter (id) 32. @Path("{id}")33. public BookTrain getBookTrain(@PathParam("id") String bookNumber) {34. List bookTrains = BookTrainBD.getBookTrains();35. 36. for (BookTrain current : bookTrains) {37. if (current.getNumBook().equals(bookNumber)) {38. return current;39. }40. }41. return null;42. }43. 44.// Complter la mthode HTTP utilise pour dclencher cette mthode45. // Complter le chemin de faon intgrer un template parameter (id)46. public void removeBookTrain(@PathParam("id") String bookNumber) {47. BookTrain currentBookTrain = null;48. for (BookTrain current : BookTrainBD.getBookTrains()) {49. if (current.getNumBook().equals(bookNumber)) {50. currentBookTrain = current;51. }52. }53. BookTrainBD.getBookTrains().remove(currentBookTrain);54. }55. }L'accs la ressource Rservation (via la classe BookTrainRessource) est obtenu via l'utilisation d'un sub-resourcelocator. Complter la classe TrainResource.public class TrainResource {public TrainResource() {}// Complter de faon dfinir le chemin suivant /trains/booktrains pour invoquer cette mthodepublic BookTrainResource getBookTrainResource() {return new BookTrainResource();}}Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 10 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/ partir de CURL et SOAP-UI, invoquer chaque service (cration d'une rservation, liste les rservations, obtenir lesinformations d'une rservation et supprimer la rservation cre).Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 11 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/Exercice 3 - Dvelopper un client de Service Web REST : Interrogation et rservation de trainBut Dvelopper un client de service web REST partir de l'API JERSEY. Cration des requtes via le patron Builder.DescriptionCe troisime exercice se propose de fournir un client pour l'accs au service Web REST dfini dans l'exercice 2. Uneinterface graphique en Java/Swing permet de contrler les appels aux diffrents services.tapes suivreCrer un nouveau projet File -> New Project... puis Java et choisir Java Application, faire Next.Pour le nom du projet choisir le nom BookTrainClientWebServiceRestExercice3.Pourlenomdelaclasseprincipalechoisirsoa.jaxrslabs.booktrainclientwebservicerestexercice3.BookTrainClientMain (Create Main Class).Ajouter les bibliothques Jersey (JAX-RS RI) et la bibliothque dcrivant l'API JAX-RS.Complter la classe BookTrainClientMain partir du code ci-dessous. Noter que les traitements des trois boutonsseront complter par la suite (callGetTrains(), callGetBookTrains(), createBookTrains())1. public class BookTrainClientMain extends JFrame {2. 3. public BookTrainClientMain() {4. super("Client Rservation Train");5. 6. this.initializeService();7. this.setLayout(new GridLayout(3,1,10,10));8. JPanel panelTrains = new JPanel();9. panelTrains.setLayout(new GridLayout(1,1));10. 11. JButton getTrains = new JButton("GetTrains");12. panelTrains.add(getTrains);13. getTrains.addActionListener(new ActionListener() {14. public void actionPerformed(ActionEvent e) {15. callGetTrains();16. }17. });18. 19. JPanel panelBookTrains = new JPanel();20. panelBookTrains.setLayout(new GridLayout(1,1));21. 22. JButton getBookTrains = new JButton("GetBookTrains");23. panelBookTrains.add(getBookTrains);Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 12 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/24. getBookTrains.addActionListener(new ActionListener() {25. public void actionPerformed(ActionEvent e) {26. callGetBookTrains();27. }28. });29. 30. JPanel createBookTrainFormPanel = new JPanel();31. createBookTrainFormPanel.setLayout(new GridLayout(1,3));32. final JTextField numTrain = new JTextField();33. final JTextField numberPlaces = new JTextField();34. JButton createBookTrains = new JButton("CreateBookTrain");35. createBookTrains.addActionListener(new ActionListener() {36. public void actionPerformed(ActionEvent e) {37. createBookTrains(numTrain.getText(), numberPlaces.getText());38. }39. });40. createBookTrainFormPanel.add(createBookTrains);41. createBookTrainFormPanel.add(numTrain);42. createBookTrainFormPanel.add(numberPlaces);43. 44. 45. this.add(panelTrains);46. this.add(panelBookTrains);47. this.add(createBookTrainFormPanel);48. 49. this.pack();50. this.setVisible(true);51. }52. 53. public static void main(String[] args) {54. new BookTrainClientMain();55. }56. }AjouterunemthodeinitializeService()quipermetd'initialiserl'accsauserviceWebREST.Adapterl'URLselonl'emplacement dtermin par l'exercice 2.1. private void initializeService() {2.ClientConfig config = new DefaultClientConfig();3.Client client = Client.create(config);4.service = client.resource(5. UriBuilder.fromUri("http://localhost:8080/BookTrainWebServiceRestExercice2/resources/").build());6. }Ajouter galement un attribut service de type WebResource.Ajouter une mthode callGetTrains() qui permet de lister l'ensemble des trains.private void callGetTrains() { List result = service.path("trains").accept(MediaType.APPLICATION_XML).get(new GenericType() {}); for(Train current : result) {System.out.println(current.getNumTrain() + " - " + current.getVilleDepart() + " - " + current.getVilleArrivee() + " - " + current.getHeureDepart());}}RecopierdansleprojetBookTrainClientWebServiceRestExercice3laclasseTraindepuisleprojetBookTrainWebServiceRestExercice2enrespectantlepackage(soa.jaxrslabs.booktrainclientwebservicerestexercice3).Ajouter une mthode createBookTrains(String numTrain, String numberPlaces) qui permet de crer une rservationd'un train. Complter le code ci-dessous de faon prendre en compte les paramtres de requtes et l'appel unemthode HTTP POST. Pour rappel, le service de cration retourne un numro de rservation (type String).Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 13 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/private void createBookTrains(String numTrain, String numberPlaces) { String numBook = service.path("trains").path("booktrains").???.???.??? System.out.println(numBook);}Ajouter une mthode callGetBookTrains() qui permet de rcuprer l'ensemble des rservations qui ont t cres.Complter le code ci-dessous.private void callGetBookTrains() { List result = service.path("trains").path("booktrains").accept(MediaType.APPLICATION_XML).get(new GenericType() {}); for(BookTrain current : result) {System.out.println(current.getNumBook() + " - " + current.getCurrentTrain().getNumTrain() + " - "+ current.getNumberPlaces()); }}RecopierdansleprojetBookTrainClientWebServiceRestExercice3laclasseBookTraindepuisleprojetBookTrainWebServiceRestExercice2enrespectantlepackage(soa.jaxrslabs.booktrainclientwebservicerestexercice3).ExcuterleprogrammeenvousassurantqueleserviceWebRESTdfinidansl'exercice2estdployetoprationnel.Tutoriel sur le dveloppement de services Web REST avec JAX-RS et Netbeans : Leon 3 par Mickael BARON- 14 -http://mbaron.developpez.com/tutoriels/soa/developpement-services-web-rest-jaxrs-netbeans/Remerciements http://mbaron.developpez.com/soa/soapuilesson1 : Tests fonctionnels de Web Services avec SOAP-UI. http://mbaron.developpez.com/soa/jaxwslesson2 : Dveloppement de Web Services avec JAX-WS etNetbeans.Je tiens remercier Claude Leloup pour sa relecture orthographique attentive de cet article.