Transcript Web Services Tomcat / Axis 1.4 0. déroulement du TP 1

http://www.irit.fr/~Philippe.Truillet
Web Services
Tomcat / Axis 1.4
Ph. Truillet
Novembre 2014 – v. 1.6
0. déroulement du TP
1.
2.
3.
comprendre la philosophie et le fonctionnement de SOAP
déployer des services avec JWS
déployer des services basiques avec WSDD
1. introduction
1.1 les web services
Avec l’essor d’Internet, le développement d’applications réparties tend vers les technologies du web. Parmi celles-ci, les
Web services sont des applications modulaires basées sur Internet qui exécutent des tâches précises et qui respectent un
format spécifique. Ils permettent à vos applications de faire appel à des fonctionnalités (décrites par les web services) à
distance (soit sur le même réseau, soit sur Internet) en simplifiant ainsi l’échange de données.
Les Web services permettent ainsi aux applications de dialoguer à travers le réseau, indépendamment de leur plate-forme
d’exécution et de leur langage d’implémentation. Ils s’inscrivent dans la continuité d’initiatives telles que CORBA (Common
Object Request Broker Architecture, de l’OMG) en apportant toutefois une réponse plus simple, s’appuyant sur des
technologies et standards reconnus et maintenant acceptés de tous.
L’architecture des Web services s’est imposée (tout comme le langage XML) grâce à sa simplicité, à sa lisibilité et sa
normalisation.
L’XML (eXtended Markup Language) est à la base de tous les protocoles décrits ci-dessous. Le fait que les Web services
utilisent XML leurs procurent l’avantage d’être non propriétaire et ainsi réellement multi-plateforme. Il est donc
recommandé de posséder un minimum de bases (XML, DTD, les schémas, XSL, ...) afin de pouvoir mettre en place des Web
services réellement optimisés.
Le concept des Web services s’articule actuellement autour des trois acronymes suivants :
• SOAP (Simple Object Access Protocol) est un protocole d’échange inter-applications indépendant de toute plateforme, basé sur le langage XML. Un appel de service SOAP est un flux ASCII encadré dans des balises XML et
transporté dans le protocole HTTP.
• WSDL (Web services Description Language) donne la description au format XML des Web services en précisant les
méthodes pouvant être invoquées, leurs signatures et le point d’accès (URL, port, etc..). C’est, en quelque sorte,
l’équivalent du langage IDL pour la programmation distribuée CORBA.
• Et UDDI (Universal Description, Discovery and Integration) normalise une solution d’annuaire distribué de Web
services, permettant à la fois la publication et l’exploration (recherche) de Web services. UDDI se comporte luimême comme un Web service dont les méthodes sont appelées via le protocole SOAP.
Un avantage significatif des Web services, relativement aux autres solutions d’architecture distribuée, est son support des
pare-feux (firewalls) : l’utilisation du protocole HTTP sur le port 80, généralement ouvert, leur permet de passer sans
encombre les barrières de l’entreprise. Cette facilité engendre d’autres soucis de sécurité, l’utilisation par défaut de ces
caractéristiques est trop permissive et nécessite une prise en compte de la sécurité au niveau des protocoles. Cette gestion
est néanmoins réalisable grâce à un ensemble de librairies en Java afin d’assurer une transmission des données
transactionnelles et sécurisé.
1.2 SOAP : Simple Object Access Protocol
SOAP est un protocole à la fois simple et léger destiné à l’échange d’informations. SOAP diffère de RMI, CORBA et COM car
il concentre les informations et utilise le principe d’auto description des données. SOAP fait partie de la couche de
communication des web services. La force de ce protocole réside dans son universalité et sa flexibilité. Il définit la structure
des messages XML utilisés par les applications pour dialoguer entre elles. SOAP fait figure de pièce centrale parmi tous les
Page 2
Web services
protocoles évoqués. SOAP est très complexe si l’on voulait en détailler toutes les spécificités. Nous allons donc seulement
évoquer les plus utilisées.
L’objectif de SOAP est de lier des systèmes distribués entre eux. Les messages SOAP sont des messages XML. Ces messages
échangent de l’information structurée entre systèmes déployant SOAP.
SOAP possède deux syntaxes pour décrire les données : un, descendant du système « XML RPC » et « XML schema »,
nouvelle façon à employer.
La communication avec les web services s’effectue via le protocole SOAP. SOAP peut être utilisé :
• pour l’appel de méthodes (SOAP RPC)
• pour l’échange de messages (SOAP Messaging)
SOAP définit la structure principale du message, dite « enveloppe » qui contient deux parties :
• l’entête (Header) : facultatif
• le corps (Body) : obligatoire
Figure 1 : contenu d’un message SOAP
SOAP définit aussi l’encodage pour les différents types de données qui est basé sur la technologie schéma XML du W3C.
Les données peuvent être de type simple (chaîne, entier, flottant, ...) ou de type composé. SOAP régit le format des
données lors de leur envoi/réception. C’est ainsi que l’on désigne le trafic en plusieurs types différents :
• Les messages
• Les enveloppes
1.3 WSDL : Web Service Description Language
WSDL est un format de description des méthodes et des paramètres des composants invocables par le biais des messages
au format SOAP. WSDL (Web Service Description Language) est une grammaire dérivée d’XML. A l’arrivée des Web services il
y a quelques années, la normalisation n’était pas encore apparue ce qui a eu pour effet de voir plusieurs implémentations
propriétaires pas toujours compatibles. Maintenant les principes de fonctionnement des Web services sont beaucoup plus
normalisés ce qui les rend totalement inter-opérables. L’échange de données s’appuie sur le protocole SOAP pour
l’échange des messages et sur le langage WSDL pour la définition du contrat de l’interface.
Lorsque vous voulez avoir des informations sur un Web Service, pour pouvoir l’utiliser par exemple, vous devez faire une
référence au fichier WSDL.
WSDL comprend la définition de plusieurs données :
• type : un conteneur de la définition du type de données utilisées.
• message : description du type de données transmises lors des messages
• operation : description d’une des actions supportées par le Web Service.
• portType : description de l’ensemble des actions supportées.
• binding : protocole et format de données spécifiques pour un type de port précis.
• port : un endpoint défini comme une combinaison entre une liaison et une adresse réseau.
Web services
•
Page 3
service : une collection qui relie les endpoints
WSDL est un système de communication « point à point ». Un consommateur du Web Service interroge le serveur, sur
lequel celui-ci est disponible, et celui-ci retourne la description du Web Service demandé.
1.4 conclusions
Le client appelle un web service peut être soit un navigateur Web, soit une application cliente (Swing, …). L’appel peut
être fait expressément par l’utilisateur ou peut être automatisé (un Web Service qui en appelle un autre, …). Les appels
peuvent être complètement indépendants de l’utilisateur (procédure de tâches automatisées, threads). Le client peut être
exécuté sur une plateforme différente de la plateforme hébergeant le Web Service (PC Serveur, desktop, portable, PDA,
téléphone portable, etc.).
De même, si le Web Service a été écrit en C#, le client peut très bien être fait en Java, PHP, etc. En fait, le client n’a même
pas à savoir le langage dans lequel a été programmé le Web Service pour pouvoir l’utiliser.
2. installation de SOAP/Axis1.x (inutile pour le TP !)
Axis (acronyme de Apache eXtensible Interaction System, anciennement SOAP4J développé par IBM) implémente
notamment le standard JAX-RPC API qui permet de programmer des services java. Axis permet notamment de convertir
les objets java en données SOAP et des les envoyer et/ou recevoir. Des erreurs sont de la même façon envoyées par le
serveur quand quelque chose ne va pas : Axis les convertit en exceptions java.
Axis 1.x est livré dans le fichier jar axis.jar : il implémente l’API JAX-RPC déclarée dans les fichiers jaxrpc.jar et
saaj.jar. Il nécessite de plus diverses librairies pour l’enregistrement, l’introspection, etc.
Apache Axis est une implémentation de SOAP (« Simple Object Access Protocol ») qui fournit un certain nombre d’outils
pour créer des Web services et les déployer (pour plus d’informations vous pourrez visiter le site suivant :
http://ws.apache.org/axis). Vous devrez notamment télécharger AXIS à l’URL précisée ci-dessous afin de
l’installer dans votre serveur Tomcat.
2.1 préparation
Nous supposerons dans la suite du TP que vous possédez un serveur web Tomcat (http://axis.apache.org)
démarré sur la machine locale (localhost) sur le port 8080. Si votre serveur est lancé sur un port différent, remplacez
les références du port 8080 par le vôtre.
Si le serveur est lancé sur une autre machine que la vôtre, remplacez localhost par l’adresse IP de la machine qui
vous sera donnée sur laquelle est lancé le serveur !
Dans le répertoire d’installation de Tomcat (C:\Program Files\Apache Software Foundation\Tomcat 7.0
par défaut sous windows), vous devez trouver un répertoire nommé webapps dans lequel les applications web sont
placées.
Dans ce répertoire, copiez le répertoire webapps/axis du ficher de distribution axis
(http://axis.apache.org).
Nota : Le nom a peu d’importance mais pensez à noter le nom de votre répertoire, ce dernier composera le nom de base de l’url
par laquelle vos clients accèderont votre service.
2.2 librairies
Dans le répertoire Axis, vous allez trouver un sous–répertoire nommé WEB-INF. Ce répertoire contient des informations
de configuration, les dépendances et les services web que vous voulez déployer.
Axis doit être capable de trouver une JVM (java virtual machine), un parseur XML (disponible par défaut dans la distribution
java 1.5 et supérieure). Axis nécessite aussi le fichier activation.jar (JAF) ; optionnellement mail.jar et
xmlSec.jar.
Installez les librairies nécessaires dans le sous-répertoire lib d’Axis (./WEB-INF/lib).
Page 4
Web services
2.3 validation de l’installation
Après avoir installé l’application web et ses (multiples) dépendances, assurez-vous tout d’abord que le serveur fonctionne
(sous windows, l’icône doit ressembler à cela :
)
Lancez un navigateur et tapez l’adresse suivante : http://localhost:8080/axis. Vous devez accéder à la page de
démarrage d’Axis (cf. figure 2).
Figure 2 : Page de démarrage d’Axis
Suivez le lien « Validation » afin de valider l’installation d’Axis
(http://localhost:8080/axis/happyaxis.jsp).
Installez
arrêter/redémarrer le serveur Tomcat après chaque opération.
les
librairies
manquantes.
Pensez
à
AXIS permet d’offrir un certain nombre de fonctionnalités liées aux web services. Vous pourrez déployer et retirer des web
services sur votre serveur Tomcat très facilement. Vous pourrez effectuer des appels de méthodes, directement via votre
navigateur Web, en spécifiant simplement le nom du Web Service que vous souhaitez interroger ainsi que le nom de sa
méthode que vous voulez appeler.
Vous pourrez également créer des clients en mode console, Swing ou via des pages JSP très simplement grâce aux classes
spécifiques comprises dans AXIS qui vous faciliteront le travail.
2.4 tester un endpoint SOAP
Il est temps de tester un service !
Essayez tout d’abord l’url http://localhost:8080/axis/services qui donne la liste des services installés.
Page 5
Web services
Figure 3 : liste des services
Tapez maintenant l’url suivante :
http://localhost:8080/axis/services/Version?method=getVersion. Cela signifie que vous appelez la
méthode getVersion du service Version.
A la réponse de l’appel, vous devez obtenir ceci :
Figure 4 : appel de la méthode getVersion
3. web services
Le framework Axis permet deux façons de procéder pour implémenter des web services :
• JWS - Java Web Services
• et via WSDL – Web Service Deployment Descriptions
3.1 JWS (Java Web Service)
Java Web Services est un standard dans l’implémentation des web services. WebLogic Workshop est à l’origine de ce
standard. De plus ce nouveau standard est supporté par la JCP (Java Community Process).
Page 6
Web services
Le but principal de JWS est de proposer une implémentation facile à apprendre et facile à utiliser. AXIS se base sur ce
standard pour offrir ces fonctionnalités aidant le développeur dans sa mise en place et son utilisation des Web services.
Exemple :
Testons un service web jws. Les web services JWS sont des fichiers java déposés n’importe où dans le répertoire webapps
excepté dans le sous-répertoire WEB-INF avec l’extension .jws. Quand un client appelle ce fichier via une url, ce dernier
est compilé et exécuté.
Avec votre navigateur, ouvrez l’url : http://localhost:8080/axis/EchoHeaders.jws
Vous devriez obtenir ceci :
Figure 5 : web service activé
Ensuite, ouvrez l’url : http://localhost:8080/axis/EchoHeaders.jws?method=list
(si une erreur est levée (cf. Figure 6.), copiez tools.jar de la jdk java dans . …/webapps/axis/WEB-INF/lib)
Figure 6 : erreur levée par Tomcat/Axis
Figure 7 : message SOAP généré par Tomcat/Axis
Web services
Page 7
Le retrait d’un web Service utilisant JWS est très simple, il suffit pour cela de supprimer le fichier ayant l’extension .jws.
Note :
Pour tous les exercices qui suivent, pensez à modifier le nom de vos fichiers afin d’éviter des problèmes de conflits entre les
différents binômes de TP !
Vous aurez à utiliser deux outils au moins afin de gérer vos fichiers à distance :
• Un client SFTP (exemple pour Windows WinSCP - http://winscp.net)
• Et un client SSH (exemple sous windows – kiTTY - http://kitty.9bis.net)
Exercice :
•
•
•
•
Téléchargez à l’adresse
http://www.irit.fr/~Philippe.Truillet/ens/ens/upssitech/m2sir/id/code/Ser
viceBonjour_jws.zip
Déposez le service ServiceBonjour.jws dans le répertoire …/webapps/axis.
Ouvrez un navigateur web et tapez l’url :
http://localhost:8080/axis/ServiceBonjour.jws?method=message
Ca marche ☺ !
3.2 WSDD (Web Service Deployment Descriptions)
Afin d’utiliser des fonctionnalités avancées en terme de déploiement, vous pouvez utiliser les descripteurs de déploiement.
Ce principe implémenté par Axis permet de définir les méthodes que vous souhaitez publier dans votre Web Service, le
portType, l’encodage, … Ces éléments ne sont pas paramétrable lorsque vous déployez un Web Service en utilisant le
principe de JWS évoqué précédemment.
Vous allez devoir utiliser des fichiers WSDD (Web Service Deployment Descriptors). Créez deux fichiers spécifiques à chacun
de vos Web services, un pour le déployer et l’autre pour le retirer. Par convention, ces fichiers sont souvent appelés
deploy.wsdd et undeploy.wsdd.
Le descripteur de déploiement est en réalité un fichier XML étant utilisé pour déployer votre Web Service. Le WSDD doit
contenir les namespaces étant utilisés afin d’assurer que celui-ci soit bien valide et correctement formé.
Ensuite vous devez définir la balise « service » en spécifiant en attribut :
• le nom Web Service afin que celui-ci soit identifié par votre serveur d’application
• le mode : RPC (Remote Procedure Call)
Vous devez au minimum définir deux balises « parameter ».
• Une de ces balises doit définir le nom de la classe associé au Web Service que vous souhaitez déployer. En effet, la
particularité du descripteur de déploiement est de pouvoir spécifier un nom de service différent du nom de la
classe décrivant son comportement.
• La deuxième balise « parameter » permet de définir les méthodes accessibles à partir du Web Service.
Voici un exemple du fichier deploy.wsdd à créer pour le Web Service d’exemple (ServiceBonjour)
<deployment xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
<service name="ServiceBonjour" style="RPC">
<parameter name="className" value="ServiceBonjour"/>
<parameter name="allowedMethods" value="*"/>
</service>
</deployment>
Figure 8 : exemple de fichier deploy.wsdd
Et voici un exemple du fichier undeploy.wsdd à créer pour désinstaller le Web Service d’exemple (ServiceBonjour)
<undeployment xmlns="http://xml.apache.org/axis/wsdd/">
<service name="ServiceBonjour"/>
</undeployment>
Figure 9 : exemple de fichier undeploy.wsdd
Page 8
Web services
Exercice :
•
•
•
•
•
•
Etape 1 : renommez ServiceBonjour.jws en ServiceBonjour.java. Compilez la classe du service
ServiceBonjour
Etape 2 : définissez le descripteur de déploiement (cf. figure 8) ou téléchargez-le à l’adresse :
http://www.irit.fr/~Philippe.Truillet/ens/ens/upssitech/m2sir/id/code/dep
loy.zip
Etape 3 : déploiement. En supposant que le CLASSPATH est bien positionné, la ligne de commande est :
java org.apache.axis.client.AdminClient deploy.wsdd
Utilisez par exemple le fichier deploiement.bat
Etape 4 : installez le code du service. Pour ce faire, vous devez copier votre classe compilée dans
…/webapps/axis/WEB-INF/classes
Etape 5 : exécutez votre service. Tapez l’url suivante dans votre navigateur :
http://localhost:8080/axis/services/ServiceBonjour?method=message
Etape 6 (optionnelle) : désinstallez le service
java org.apache.axis.client.AdminClient undeploy.wsdd
Figure 10 : le service est installé
4. déploiement avancé
4.1 clients pour services web
Il est bien entendu possible d’utiliser des clients du service web écrits en java, plus adapté à l’intégration d’autres
applications !
La structure consiste en :
1. création d’un accès au service
2. création d’un appel vers le service
3. récupération de l’url du service accédé
4. récupération de la méthode à appliquer
5. mise en place des éventuelles valeurs des paramètres de la méthode
6. invocation du service
7. et récupération du résultat
Exercice :
Web services
•
•
Page 9
Téléchargez ClientServiceBonjour.zip à l’adresse :
http://www.irit.fr/~Philippe.Truillet/ens/ens/upssitech/m2sir/id/code/ClientSer
viceBonjour.zip
Ouvrez le fichier ClientServiceBonjour.java, compilez et lancez-le (fichier compile_n_go.bat ou
ant demo)
4.2 restriction des accès client
En effectuant un déploiement qui autorise l’accès à toutes les méthodes du service, nous donnons une trop grande
visibilité du service. Ainsi, il se peut que vous utilisiez des méthodes internes au service qu’il est inutile voire dangereux
d’exposer.
Pour interdire l’accès à cette méthode, il existe deux solutions :
• Soit rendre les méthodes privées (mot-clé private) ce qui rendra cette méthode invisible pour les clients.
Néanmoins, ceci n’est pas toujours possible dans la mesure où l’on veut parfois rendre accessible cette méthode
pour d’autres objets (objets serveurs entre autres) sans la rendre visible aux clients.
• Soit, afin de pallier cette difficulté, on peut conserver la méthode publique (mot-clé public) mais empêcher
l’accès aux clients. Dans ce cas, on doit le spécifier explicitement dans le contenu du descripteur de déploiement,
en précisant uniquement les méthodes accessibles aux clients.
Ex : <parameter name="allowedMethods" value="method1 method2 method3"/>
4.3 persistance des données
A chaque fois qu’une méthode de service est invoquée (en fait, à chaque utilisation du service), le serveur Axis, avant
d’invoquer le méthode demandée créé une nouvelle instance de classe. De ce fait, à chaque invocation de méthode, nous
aurons toujours une nouvelle instance qui sera obtenue avec le constructeur par défaut (correspond à la ligne de
déploiement <parameter name="scope" value="request"/>) !
Pour éviter ce problème, nous devons préciser que l’accès au service doit être associé soit à la session utilisateur (utilisation
du même navigateur par exemple) ou pour toutes requêtes provenant de n’importe quel client. Pour ce faire, vous devez
inclure dans le descripteur de déploiement du service la ligne suivante : <parameter name="scope"
value="session"/> ou respectivement <parameter name="scope" value="application"/>
4.4. exercices
1.
Créez un service web de gestion de compte ServiceCompte. Pour cela, on définit la classe java Compte dont
voici le squelette :
public class Compte {
float Solde;
// Constructeur
public Compte() {
Solde = 0.0;
}
public void deposer (float montant) {
…
}
public boolean retirer (float montant) {
// retourne true si le solde reste positif, false sinon
…
}
public float solde() {
…
}
}
Testez ensuite le service au travers d’une interface web.
http://localhost:8080/axis/services/ServiceCompte?method=Solde
http://localhost:8080/axis/services/ServiceCompte?method=deposer&montant=150
http://localhost:8080/axis/services/ServiceCompte?method=retirer&montant=100
http://localhost:8080/axis/services/ServiceCompte?method=deposer&montant=250
Page 10
Web services
http://localhost:8080/axis/services/ServiceCompte?method=Solde
2.
Créez un client java qui utilise le service ServiceCompte. On veut pouvoir effectuer des dépôts, effectuer des
retraits et visualiser le solde. Réalisez les mêmes opérations que précédemment.
3.
Créez un service web d’annuaire ServiceAnnuaire et un client utilisant ce service.
5. aller plus loin : objets complexes
5.1 le problème récurrent de la sérialisation
L’interopérabilité entre implémentation de SOAP est un grand challenge. Par défaut, Axis ne peut pas envoyer des objets
java arbitraires et s’attendre qu’ils soient compris forcément par le client. Contrairement à RMI, où de part et d’autre, on
peut envoyer et recevoir des objets sérialisés en java, Axis ne peut envoyer « par défaut » soit des objets de types primitifs,
soit des objets enregistrés par le sérialiseur Axis mais composés de types de donnée primitifs.
Voici les objets standards mappés par WDSL :
xsd:base64Binary
xsd:boolean
xsd:byte
xsd:dateTime
xsd:decimal
xsd:double
xsd:float
xsd:hexBinary
xsd:int
xsd:integer
xsd:long
xsd:QName
xsd:short
xsd:string
byte[]
boolean
byte
java.util.Calendar
java.math.BigDecimal
double
float
byte[]
int
java.math.BigInteger
long
javax.xml.namespace.QName
short
java.lang.String
Si l’objet retourné est nul, alors les types de données primitifs sont remplacés par leur classe d’encapsulation comme Byte,
Double, Boolean, etc.
Dans le cas où les objets sont composés de types de données primitifs, on peut signifier à Axis quelles classes java « se
mappent » avec quels types XML-Schema. Un ficher WSDD de configuration de déploiement ressemble alors à ceci :
<deployment
xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
<service name="ServiceAnnuaire" provider="java:RPC">
<parameter name="className" value="ServiceAnnuaire"/>
<parameter name="scope" value="application"/>
<parameter name="allowedMethods" value="*"/>
<beanMapping
qname="myNS:Fiche"
xmlns:myNS="urn:ServiceAnnuaire"
languageSpecificType="java:fr.irit.diamant.ws.annuaire.Fiche"/>
</service>
</deployment>
La balise <beanMapping> mappe une classe Java (un bean ou une classe y ressemblant) vers l’attribut XML QName. Deux
attributs sont importants : qname et languageSpecificType. Dans l’exemple ci-dessus, nous mappons
« fr.irit.diamant.ws.annuaire.Fiche » vers le QName XML ServiceAnnuaire:Fiche
Le client qui utilise la classe est bien entendu modifié ! Il faut lui indiquer comment sérialiser et désérialiser les objets
complexes …
Le client incorpore alors l’importation de javax.xml.namespace.* puis dans le code :
QName qn = new QName( "urn:ServiceAnnuaire", "Fiche" );
call.registerTypeMapping(Fiche.class, qn,
new org.apache.axis.encoding.ser.BeanSerializerFactory(Fiche.class, qn),
new org.apache.axis.encoding.ser.BeanDeserializerFactory(Fiche.class, qn));
Web services
Page 11
On peut dès lors utiliser l’objet complexe en argument d’appel ou de retour des fonctions.
Une autre méthode existe si celle-ci ne suffit pas, notamment en cas d’adaptation au dessus de classes préalablement
existantes : la sérialisation/désérialisation adaptés par les soins du programmeur. Pour plus de détails, cf. la classe
org.apache.axis.encoding.ser package. Concernant le déploiement, les attributs typeMapping ou
ArrayMapping sont alors utilisés.
5.2 exercice
1.
Créez un service web d’annuaire ServiceAnnuaire
• qui utilise un Annuaire composés de Fiches
• qui propose les méthodes suivantes :
a. add qui ajoute une fiche à l’annuaire
b. searchByName qui permet de rechercher une fiche par le nom et renvoie un vecteur composé des
fiches correspondant au critère
c. getNumFiches qui renvoie le nombre de fiches dans l’annuaire
d. getFiches qui renvoie un vecteur composé de toutes les fiches de l’annuaire
2. et un client utilisant ce service.
Pensez qu’il faut déclarer dans le fichier de déploiement comment sérialiser/désérialiser les objets de type Fiche.