Vous revoilà pour développer votre premier web service.
Les méthodes Top-down et Bottom-up
Il y a deux principales méthodes pour créer un web service.
1- Top-down
Il s'agit de la méthode la plus utilisée en entreprise. Cette méthode est aussi appelée Contract First. Il s'agit d'établir avant tout un contrat qui dit tout sur le fonctionnement du service avant de l'implémenter. Ce contrat n'est rien de plus qu'un fichier WSDL.
Vous établissez donc un fichier WSDL qui décrit votre service : les opérations possibles, les paramètres à passer et leurs types, etc.
Une fois ce contrat établi, vous créez le code nécessaire à son implémentation.
Rassurez-vous, vous n'aurez pas à écrire à la main une Class à partir d'un XML indigeste, il y a heureusement des moyens pour automatiser tout cela. En Java, la solution la plus populaire est JAX-WS. Nous y reviendrons en détails.
2- Bottom-Up
Il s'agit là de la manière la plus intuitive et facile pour créer un service. Vous créez votre code qui fait les opérations que vous voulez : dans notre cas une Class qui calcule le temps restant à vivre en fonction des paramètres passés. Puis vous générez automatiquement un WSDL à partir de cette Class ; là encore, JAX-WS le fera automatiquement.
Comme tout bon informaticien qui se respecte, nous allons commencer par le plus facile : Bottom-Up.
Qu'est ce que JAX-WS ?
Java API for XML Web Services (JAX-WS) est une API de Java qui facilite la création de web services. Pour bien démystifier ce terme, sachez que JAX-WS est exactement la même chose que d'autres API que vous avez dû déjà utiliser comme java.lang (qui vous fournit justement String, Integer, etc.) , java.io (pour manipuler les fichiers, entre autres) ou encore java.sql.
JAX-WS va permettre de cacher entièrement la complexité des communications impliquant SOAP et WSDL.
Côté web service : Quand un service externe appellera votre web service, il lui passera un simple fichier XML aux normes SOAP. Sans JAX-WS, vous devriez récupérer ce fichier et le parser pour essayer de comprendre quelles méthodes on cherche à invoquer et quels sont les paramètres passés. Je vous laisse deviner les centaines de lignes de code à écrire pour parser correctement un XML et faire appel aux bonnes méthodes dans les bonnes classes !
JAX-WS vous dispense de ce travail. Quand vous recevez un appel à votre web service, il va interpréter le message SOAP et appeler la bonne méthode dans votre code, exactement comme n'importe quelle méthode appellera une autre.
Mieux encore, quand vous retournerez une réponse, JAX-WS construira une réponse SOAP conforme et l'enverra au client.
De votre côté, vous n'y verrez que du feu. :p Vous vous contenterez de créer une Class comme celle qu'on a vu plus haut et y ajouter une annotation. JAX-WS fera le plus dur.
Côté Client : Vous serez amenés à créer des clients pour appeler des web services dont vous ne connaissez rien. Vous n'aurez qu'un fichier WSDL complexe et long comme le bras pour comprendre comment les appeler, à quelle URL les trouver, quels paramètres passer et quel type de réponse recevoir. Vous imaginez bien qu'écrire du code pour parser un XML à chaque fois pour comprendre le fonctionnement d'un nouveau service est à la fois lent et fastidieux.
JAX-WS, là encore, vous dispense de tout ça. L'idée est simple : vous lui donnez l'emplacement du WSDL du nouveau service auquel vous voulez faire appel et il se charge de le parser et de créer des classes Java représentant le service en question. Vous n'avez plus qu'à appeler les classes créées comme vous appellerez n'importe quelle Class. Magique non ? :magicien:
Bien sûr, JAX-WS propose d'autres fonctionnalités. Mais ces deux-là sont les principales que nous allons aborder.
Passons à l'application !
Description du web service LifeLeft
Votre web service devra donc recevoir les paramètres suivants :
un prénom de type String ;
un sexe de type String (homme/femme) ;
une année de naissance de type Integer.
Le service retourne une réponse de type String correspondant à prénom et nombre d'années restant à vivre.
Pour calculer on se base sur l'espérance de vie en France qui est de :
Hommes : 79 ans
Femmes : 85 ans
Créer un service Bottom-Up
Allez, nous y sommes. Du code !
Créez l'implémentation du service
Revenez sur le projet vide que nous avons créé précédemment.
Vous allez maintenant créer une classe classique qui implémente les fonctionnalités dont on a parlé.
Faites un clic droit sue le Package com.lifeleft puis sélectionnez New > java Class. Nommez-la LifeLeftService.
Voici une implémentation. Celle-ci n'intègre pas la gestion des erreurs que nous verrons dans un autre chapitre, néanmoins tout est défini pour que vous puissiez plus tard gérer cela avec un minimum de code.
package com.lifeleft;
import java.time.Year;
public class LifeLeftService {
private static final Integer ESPERANCE_VIE_HOMMES = 79;
private static final Integer ESPERANCE_VIE_FEMMES = 85;
String homme = "homme";
String femme = "femme";
Integer evDeReference = 0;
public String anneeRestantesAVivre (String prenom, String sexe, Integer anneeNaissance) {
if(sexe.equals(homme)) evDeReference = ESPERANCE_VIE_HOMMES;
else evDeReference = ESPERANCE_VIE_FEMMES;
//Remarque, en cas de problème, vous pouvez changer Year.now().getValue() par Calendar.getInstance().get(Calendar.YEAR)
Integer anneeRestantes = evDeReference -(Year.now().getValue() - anneeNaissance );
return "Bonjour " + prenom + ", il vous reste " + anneeRestantes + " ans à vivre, profitez-en au maximum !";
}
}
Explications du code
En partant de la classe vide que vous avez créée, voici les explications :
Lignes 7 et 8 : On crée ici deux variables statiques et finales qui contiennent nos valeurs constantes à savoir les espérances de vie.
Lignes 10 et 11 : On définit ici les valeurs qu'on accepte pour désigner le sexe. Bien sûr dans le code à ce stade nous n'avons besoin que d'une seule valeur (homme ou femme) pour déduire par élimination le sexe. Néanmoins on définit ici les deux pour que nous puissions plus tard retourner une erreur si ce que nous avons reçu ne correspond ni à l'un ni à l'autre.
Ligne 13 : evDeReference est l'espérance de vie (ev) que nous choisirons comme référence selon que l'utilisateur soit une femme ou un homme.
Ligne 15 : on définit une simple fonction public qui accepte les 3 paramètres nécessaires.
Lignes 17 et 18 : on fixe la valeur de evDeReference selon le sexe.
Ligne 21 : on effectue le calcul. (Year.now().getValue() - anneeNaissance ) nous donne l'âge de l'utilisateur. Il suffit ensuite de le soustraire de l'espérance de vie moyenne.
Ligne 23 : On retourne une phrase pour annoncer la nouvelle ! :D
À présent, on va devoir exposer cette méthode de cette Class en tant que web service. C'est là que JAX-WS vient à la rescousse.
Voici le résultat :
package com.lifeleft;
import javax.jws.WebMethod;
import javax.jws.WebService;
import java.time.Year;
@WebService(serviceName = "LifeLeft")
public class LifeLeftService {
private static final Integer ESPERANCE_VIE_HOMMES = 79;
private static final Integer ESPERANCE_VIE_FEMMES = 85;
String homme = "homme";
String femme = "femme";
Integer evDeReference = 0;
@WebMethod
public String anneeRestantesAVivre (String prenom, String sexe, Integer anneeNaissance) {
if(sexe.equals(homme)) evDeReference = ESPERANCE_VIE_HOMMES;
else evDeReference = ESPERANCE_VIE_FEMMES;
//Remarque, en cas de problème, vous pouvez changer Year.now().getValue() par Calendar.getInstance().get(Calendar.YEAR)
Integer anneeRestantes = evDeReference -(Year.now().getValue() - anneeNaissance );
return "Bonjour " + prenom + ", il vous reste " + anneeRestantes + " ans à vivre, profitez-en au maximum !";
}
}
Vous l'avez remarqué, je n'ai eu à ajouter que 2 annotations :
@WebService : Cette annotation dit simplement à JAX-WS que cette Class est à exposer en tant que web service. Elle peut prendre plusieurs paramètres, j'ai choisi de lui en passer un seul ici : serviceNname = "LifeLeft". Ce nom qu'on vient de donner à ce service servira ensuite pour accéder à notre service via son URL.
@WebMethod : Cette annotation désigne cette méthode comme une méthode à exposer. Normalement si on ne précise pas cette annotation, toutes les méthodes de la Class seront exposées. Néanmoins, je vous recommande d'ajouter cette annotation à chaque méthode que vous voulez exposer, afin d'avoir la liberté d'ajouter d'autres méthodes supplémentaires pour votre usage interne, sans que celles-ci puissent être appelées par les services extérieurs.
2- Modifier le pom.xml
Dernière étape, nous allons ajouter 2 plugins à Maven. Voici le résultat :
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.lifeleft</groupId>
<artifactId>lifeleft</artifactId>
<packaging>war</packaging>
<version>1.0</version>
<name>lifeleft : combien vous reste-t-il à vivre?</name>
<build>
<finalName>lifeleft</finalName>
<plugins>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.7.0</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
</plugins>
</build>
</project>
Vous précisez que le format que vous souhaitez est war grâce à war.
Vous ajoutez le plugin maven-war-plugin qui permettra à Maven de déclencher les bonnes opérations qui aboutiront au packaging de votre service en .war.
Vous ajoutez le plugin maven-compiler-plugin qui est simplement le compilateur Java de Maven.
Vous avez maintenant tout ce qu'il faut pour packager votre application.
Vous pouvez bien sûr packager votre application via la ligne de commande suivante :
mvn install
Néanmoins, nous allons utiliser IntelliJ pour exécuter cette commande directement depuis l'interface graphique.
1. Sélectionnez View > Tool Windows > Maven Projects
2. Sélectionnez ensuite à gauche de la fenêtre Maven, puis déroulez Lifecycle et cliquez sur Install.
La commande est alors exécutée, et votre application est packagée ! Vous devriez avoir un message Maven indiquant le succès de la commande dans l'onglet Run en bas de la fenêtre.
Vous pouvez vérifier la présence de votre service sous le nom lifeleft.war dans le nouveau dossier Target créé dans votre projet.
Très bien, vous avez maintenant tout ce qu'il vous faut pour lancer votre premier web service SOAP !
Déployer un service sur Glassfish
Normalement votre serveur Glassfish est démarré. Pour le vérifier, rendez-vous à http://localhost:4848. Si tel n'est pas le cas, je vous invite à le démarrer en suivant les étapes précédemment citées.
1- Cliquez sur Applications dans le panneau de gauche puis cliquez sur Deploy dans la nouvelle fenêtre.
2- Sous Packaged File to Be Uploaded to the Server cliquez sur le bouton puis sélectionnez lifeleft.war sur votre ordinateur. Assurez-vous ensuite que Type: Web Application est choisi. Vous pouvez laisser tout le reste par défaut.
Cliquez sur OK.
3- Dans la nouvelle fenêtre, cliquez sur Launch en face de votre service.
4- Une page avec 2 liens s'ouvre : un lien http et l'autre en https. Sélectionnez le premier (http).
Vous devriez tomber sur une page avec le message "Hello World!". Ce message vient du fichier index.jsp généré par défaut avec votre projet Maven.
5- Pour accéder à votre service, ajoutez à votre URL LifeLeft. Celle-ci devrait alors ressembler à quelque-chose comme ça :
http://nomDeVotreOrdinateur.local:8080/lifeleft6252936251939052664/LifeLeft
Vous pouvez sans problème remplacer nomDeVotreOrdinateur.local par localhost.
Vous devriez tomber sur une page qui vous donne diverses informations sur votre service.
Glassfish génère automatiquement un WSDL qui décrit votre service à partir de votre code. Pour le consulter, cliquez sur le lien finissant par ?wsdl.
Testez votre service
À présent que votre service tourne sur le serveur, vous allez pouvoir le tester très facilement, grâce encore une fois à Glassfish.
Pour ce faire, ajoutez ?Tester à votre URL. Elle devrait ressembler à ceci :
http://nomOrdinateur.local:8080/lifeleft6252936251939052664/LifeLeft?Tester
Vous retrouverez alors votre méthode précédemment créée avec 3 champs correspondant aux trois paramètres que vous avez défini.
Renseignez alors un prénom, un sexe et une date de naissance et validez.
Vous voilà avec une page présentant différentes informations que je vais commenter en plus de votre réponse. Notez que cette page est générée par Glassfish pour vous permettre de débugger et voir ce qui s'est passé lors de l'invocation de votre service. Pour vous faciliter la compréhension des messages échangés via SOAP, je vous rappelle le début de ce cours, à consulter ici. .
Method parameter(s) ici on reprend simplement la liste des paramètres passés.
Method returned ici vous retrouvez le fruit de votre dur labeur! La réponse retournée par votre service. Assurez-vous que le résultat est correct.
SOAP Request il s'agit de la requête SOAP que Glassfish a généré en se basant sur le WSDL et les paramètres que vous avez renseigné.
<?xml version="1.0" encoding="UTF-8"?> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <S:Body xmlns:ns2="http://lifeleft.com/"> <ns2:anneeRestantesAVivre> <arg0>john</arg0> <arg1>homme</arg1> <arg2>1990</arg2> </ns2:anneeRestantesAVivre> </S:Body> </S:Envelope>Envelope : l'enveloppe du message SOAP qui délimite le début et la fin de celui-ci. Elle définit les namespaces utilisés : S et SOAP-ENV.
Header ici le header optionnel est vide.
Body : qui définit le corps du message, déclare un namespace ns2 pour identifier votre méthode anneeRestantesAVivre et les 3 paramètres qu'on lui passe.
SOAP Response
<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <S:Body xmlns:ns2="http://lifeleft.com/"> <ns2:anneeRestantesAVivreResponse> <return>Bonjour john, il vous reste 52 ans à vivre, profitez-en au maximum !</return> </ns2:anneeRestantesAVivreResponse> </S:Body> </S:Envelope>
Ceci est la fameuse réponse générée par JAX-WS. Elle a la même structure que la requête, à la différence qu'ici dans le Body nous avons la réponse obtenue. Vous remarquerez que l'on a suffixé le nom de votre méthode par Response.
Résumons
Comme vous avez pu le voir, JAX-WS a fait le plus gros du travail, vous avez seulement dû ajouter 2 annotations. Derrière, JAX-WS a interprété la requête SOAP et a invoqué votre méthode puis il a constitué une réponse SOAP en bonne et due forme qu'il a renvoyé au serveur.
Pour résumer, voici les étapes pour créer un service Bottom-Up :
Créez vos classes pour implémenter les fonctionnalités voulues comme vous le faites d'habitude.
Annotez la ou les classes que vous voulez exposer avec l'annotation @WebService.
Annotez les méthodes que vous voulez exposer grâce à l'annotation @WebMethod.
Packagez votre service au format war (faites les modifications au pom.xml si nécessaire).
Uploadez votre service dans le serveur.
Maintenant que vous savez créer un service Bottom-Up, essayons de le faire à l'envers grâce à la méthode Top-down.
