Adolphe Francois Julien Marmel Dominique Perlat Olivier Printemps

SOAP
Simple Object Access Protocol

Encadrant : Chantal Taconet

Sommaire
Sommaire ....................................................................................................................... 2 Premire Partie : Prsentation Gnrale de SOAP...................................................... 3 1. 2. 3. 4. 5. 6. 7. Prsentation et fonctionnement SOAP........................................................... 3 Prsentation et fonctionnement des Webservices.......................................... 4 Le protocole WSDL.......................................................................................... 4 Le protocole UDDI ........................................................................................... 4 Diffrence entre IIOP et SOAP....................................................................... 5 Protocoles utiliss par SOAP........................................................................... 5 Problmes poss par SOAP :........................................................................... 8 a) Problmes HTTP ............................................................................................ 8 b) Problmes XML ............................................................................................. 8 c) Problmes lis SOAP .................................................................................. 9 a) b) c) d) e) 1. a) b) 2. a) b) 3. a) b) 4. 1. 2. Les fichiers WSDL ........................................................................................... 9 Services ........................................................................................................ 10 Port ............................................................................................................... 10 Message........................................................................................................ 11 Port Type et Oprations................................................................................ 12 Bindings ....................................................................................................... 13 Apache SOAP ................................................................................................. 14 Installation.................................................................................................... 14 Exemple dutilisation ................................................................................... 15 NuSoap ............................................................................................................ 18 Installation.................................................................................................... 18 Exemples dutilisation.................................................................................. 18 SOAP::Lite...................................................................................................... 20 Installation.................................................................................................... 20 Exemple dutilisation : ................................................................................. 21 Tests dinteroperabilit.................................................................................. 22 Exemple de Web Service : Google Web Service...................................... 23 Exemple du gestionnaire dimprimante....................................................... 24 a) Exemple 1 : limprimante HP....................................................................... 24 b) Exemple 2 : le gestionnaire dimpression .................................................... 33 c) Exemple 3 : le gestionnaire dimpression et WSDL ................................... 36 d) Excution des exemples ............................................................................... 36

8.

Deuxime Partie : Installation et mise en uvre ....................................................... 14

Troisime Partie : Exemples dutilisation .................................................................. 23

Bibliographie ............................................................................................................... 37

SOAP Simple Access Protocol

Premire Partie : Prsentation Gnrale de SOAP

1. Prsentation et fonctionnement SOAP
SOAP (Simple Object Access Protocol) est un protocole dinvocation de mthodes sur des services distants. Bas sur XML, SOAP est un format de communication pour assurer communication de machine machine. Le protocole permet dappeler une mthode RPC (Remote Procedure Call) et denvoyer des messages aux machines distantes via HTTP. Ce protocole est trs bien adapt lutilisation des services web car il permet de fournir au client une grande quantit dinformations rcupres sur un rseau de serveurs tiers. La version actuelle de SOAP est la 1.1. Cette version a t propose au W3C en 2000 par UserLand, Ariba, Commerce One, Compaq, Developmentor, HP, IBM, IONA, Lotus, Microsoft, SAP. Le W3C travaille actuellement sur la version 1.2 de SOAP, elle devrait sortir fin 2002 et pour but de supprimer lutilisation des RPC au profit des messages. SOAP permet donc lchange dinformation dans un environnement dcentralis et distribu, comme Internet par exemple. Il permet linvocation de mthodes, de services, de composants et dobjets sur des serveurs distants et peut fonctionner sur de nombreux protocoles (des systmes de messagerie lutilisation de RPC). Cependant, il fonctionne particulirement bien avec le protocole HTTP, protocole trs souvent utilis avec SOAP. SOAP utilise les protocoles HTTP et XML. HTTP comme mcanisme dinvocation de mthodes en utilisant un des balises spcifiques pour indiquer la prsence de SOAP comme <SOAP-ENV> . Cela permet de franchir aisment les firewalls et proxy et facilite le traitement en cas de filtrage. XML pour structurer les requtes et les rponses, indiquer les paramtres des mthodes, les valeurs de retours, et les ventuelles erreurs de traitements. XML joue un rle prpondrant dans SOAP, on peut distinguer plusieurs lments : une enveloppe, expliquant comment la requte doit tre traite et prsentant les lments contenus dans le message. un ensemble de rgles de codage, permettant de diffrencier les types de donnes transmises. une convention de reprsentation, permettant de reprsenter les appels aux procdures de traitement et les rponses. Mme si SOAP ressemble beaucoup en termes de fonctionnalits des protocoles comme IIOP pour CORBA, ORPC pour DCOM, ou JRMP (Java Remote Method Protocol) pour JAVA, il possde un avantage indniable. En effets, SOAP utilise un mode texte alors que les autres fonctionnent en mode binaire, cela facilite le passage des quipements de scurit.

SOAP Simple Access Protocol

2. Prsentation et fonctionnement des Webservices

Prsentation : Les Webservices permettent de faire communiquer deux sous-systmes ensembles et cela indpendamment des architectures utilises. Ces systmes vont pouvoir schanger des services ou des traitements applicatifs. Les Webservices constituent un moyen de distribuer un service de manire standard grce XML tout en respectant un modle de dveloppement ayant dj fait ses preuves comme CORBA ou DCOM (Microsoft). Un des avantages des Webservices est de regrouper tous les acteurs derrire un seul et mme standard. Fonctionnement : Pour expliquer le fonctionnement des webservices, il convient de distinguer plusieurs tapes : ! Recherche dans un annuaire UDDI : le client cherche un service particulier, il sadresse un annuaire qui va lui fournir la liste des prestataires habilits satisfaire sa demande. Lannuaire UDDI peut tre compar un moteur de recherche sauf que les documents sont remplacs par des services. ! Recherche de linterface du composant contacter : une fois la rponse reue (en XML) de lannuaire, le client va chercher communiquer via une interface. Cette interface dcrite en langage WSDL fournit lensemble des services disponibles. Elle offre la possibilit de vrifier que le contrat correspond bien aux besoins demands. ! Invocation du service : le client doit maintenant passer les paramtres attendus par le service et assurer la communication avec le serveur. Loutil utilis pour cela est le Proxy, cest lobjet qui permet la communication entre le client et le serveur. Il est gnr par le client en utilisant linterface WSDL.

3. Le protocole WSDL
WSDL (Web Service Definition Langage) est un format de reprsentation des interfaces de services Web en XML. Une analogie avec CORBA peut tre faite, en effet WSDL est la reprsentation XML du langage IDL (description dinterfaces). WSDL a deux rles prpondrants: ! Il sert de rfrence la gnration de Proxies. ! Il assure le couplage entre le client et le serveur par le biais des interfaces.

4. Le protocole UDDI
UDDI (Universal Description Discovery and Integration) est un protocole bas sur XML qui sert la publication et l'exploration d'annuaires de Web Services. Il permet de situer un service Web, de le dcrire, et de lintgrer. Ce protocole a t ralis par IBM, Microsoft et Ariba. Cependant UDDI est assez complexe et a t qualifi par certains dusine gaz . Cest la raison pour laquelle IBM et Microsoft travaille actuellement sur un autre protocole dannuaire de services : Web Services Inspection (WS-Inspection). Lobjectif de WS-Inspection est de permettre une entreprise de dcrire facilement les services Web dont elle dispose.

SOAP Simple Access Protocol

5. Diffrence entre IIOP et SOAP

IIOP (Internet Inter-ORB Protocol) est un protocole de transfert de mthode utilis par CORBA. Il dfinit le format des messages changs entre la machine cliente et la machine serveur. IIOP va permettre denvoyer et de recevoir des types complexes de donnes. Les clients et serveurs peuvent employer nimporte quel mlange de langages et de plateformes. IIOP est un protocole trs complet qui est capable deffectuer tous les transferts exigs par SOAP. Cependant lutilisation de SOAP peut tre parfois prfrable pour plusieurs raisons. Tout dabord, lutilisation de IIOP ncessite de compiler et distribuer des souches clients pour chaque type de clients avec qui lon communique. Ce nest videmment pas trs pratique, en particulier quand le nombre de plateformes diffrentes ou de langages diffrents est important. Dans le cas des services web, IIOP va poser des problmes pour le franchissement des quipements de filtrage (firewall, proxy). Cela va demander un travail en plus de la part de chaque personne administrant lquipement. Au contraire, lutilisation de SOAP ne pose absolument pas de problmes au niveau des firewalls. SOAP tant un protocole utilisant HTTP, il y a peu de chance quil soit bloqu lors dun filtrage. Evidemment CORBA, au travers de IIOP, est plus performant : il y a moins de donnes transitant sur le rseau, et les oprations de conversion / dconversion sont traites plus rapidement. Cependant avec SOAP les donnes circulent en format texte et en clair sur le rseau. Leur lecture en est donc facilite et le dboguage est beaucoup plus simple. SOAP est donc un trs bon protocole si lon cherche dialoguer avec des plateformes htrognes, ce qui est particulirement le cas dans toutes les applications de type Web Services . En fait, lutilisation de CORBA ou de SOAP va surtout dpendre de ce que lon doit faire : dans le cas des webservices SOAP semble tre une bonne solution, par contre si lon souhaite faire des applications distribues classiques comme du calcul distribu, on choisira plutt CORBA.

6. Protocoles utiliss par SOAP

SOAP se sert le plus souvent de deux protocoles : HTTP et XML. Un message SOAP est crit en XML. HTTP est utilis comme protocole de transport. Les messages SOAP vont donc tre encapsuls dans HTTP, ce qui permet une utilisation et une compatibilit trs importante avec les rseaux et quipements existants. HTTP est le protocole de transport le plus utilis mais il nest pas impossible de trouver des implmentations de SOAP sur dautres protocoles (avec SMTP par exemple). Un message SOAP est un document XML qui possde une enveloppe SOAP et ventuellement une dclaration XML. Lenveloppe SOAP est compose dun corps SOAP et ventuellement dun en-tte. Les rgles de syntaxe sont les suivantes : Un message SOAP MUST tre cod en XML Un message SOAP MUST avoir une enveloppe SOAP Un message SOAP CAN avoir un entte SOAP (header) Un message SOAP MUST avoir un corps SOAP (body)

SOAP Simple Access Protocol

Un message SOAP MUST utiliser lespace de dsignation de lenveloppe SOAP Un message SOAP MUST utiliser lespace de dsignation dencodage SOAP Un message SOAP MUST NOT contenir une rfrence une DTD Un message SOAP MUST NOT contenir des instructions de type XML Processing

Un message SOAP va tre constitu dune enveloppe et dun corps. Cest lintrieur du corps (body) que lon trouve le contenu :
//enveloppe du message <soap:Envelope //espace de nommage pour lenveloppe SOAP xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" //on dfinit le type dencodage du message SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" //espace de nommage pour les types de variables xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" //espace de nommage pour lappel de mthodes xmlns:tns="http://soapinterop.org/"> //corps <soap:Body> //espace de nommage pour la fonction getStateName <m:getStateName xmlns:m="http://soapware.org/"> //on spcifie un argument passer getStatName <statenum xsi:type="xsd:int">41</statenum> </m:getStateName> //gestion derreurs <soap:fault> </soap:fault> </soap:Body> </soap:Envelope>

<envelope> est la racine ; <header>, <body>,et <fault> sont les enfants.

SOAP Simple Access Protocol

Structure dun message SOAP

Exemple: Message SOAP encapsul dans une requte HTTP Voici une requte SOAP typique (avec les en-ttes HTTP) pour un appel une mthode RPC nomme EchoString, qui prend une chane comme paramtre :
POST /test/simple.asmx HTTP/1.1 Host: 131.107.72.13 Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://soapinterop.org/echoString" <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://soapinterop.org/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <tns:echoString> <inputString>string</inputString> </tns:echoString> </soap:Body> </soap:Envelope>

Le nom de la mthode est appel par la balise <tns:echoString> et le paramtre de type chane est dfini par <inputString>. La mthode qui est invoqu est donc de cette forme : SOAP Simple Access Protocol 7

public String echoString(String inputString);

Le serveur rponds alors:

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://soapinterop.org/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <tns:echoStringResponse> <Return>string</Return> </tns:echoStringResponse> </soap:Body> </soap:Envelope>

Les rgles de srialisation du type de donnes de chane, ainsi que la forme de l'appel une mthode, sont dfinies dans SOAP 1.1, sections 5 et 7 (http://www.w3.org/tr/soap).

7. Problmes poss par SOAP :

Ces problmes concernent principalement linteroprabilit des messages SOAP de type RPC. La plupart des problmes poss par SOAP ne concernent pas directement le protocole lui-mme mais plutt les protocoles utiliss, comme XML ou HTTP. Ils peuvent tre diviss en trois catgories : - problmes http - problmes XML - problmes lis au protocole SOAP a) Problmes HTTP HTTP est utilis pour le transport des messages SOAP en XML. Or certaines balises spcifiques SOAP ne vont pas tre bien interprtes par tous les clients HTTP. Cela va dpendre du client et ne pas fonctionner dans certains cas. On peut prendre lexemple de la fonction SOAPAction : la valeur de SOAPAction doit tre en guillemets sauf sil sagit dune valeur nulle. Exemple : SOAPAction: http://test.org/ ou SOAPAction: Cependant certains clients ne sont pas capables de fournir une valeur dentte HTTP nulle, si le serveur en attends une, lappel ne fonctionnera pas. b) Problmes XML Les problmes dinteroprabilit XML concernent lanalyse du langage XML. SOAP repose sur lutilisation de ce langage, donc si XML pose des problmes dimplmentations, ceux-ci vont poser des problmes sur SOAP.

SOAP Simple Access Protocol

c) Problmes lis SOAP En lui-mme, SOAP est relativement simple ; il requiert que les messages soient placs dans une enveloppe avec le texte du message inclus dans un lment du corps. Cependant il existe un certain nombre de problmes dinteroprabilit comme par exemple le problme li limplmentation de lattribut mustUnderstand . Les spcifications de SOAP indiquent que si cet attribut est dfini sur la valeur 1 , il devra tre trait. Pourtant certaines implmentations de SOAP ne le font pas (principalement les premires avoir t dveloppes). De nombreux autres problmes dinteroprabilit ont t dcouverts, ils sont consultables sur le forum http://groups.yahoo.com/group/soapbuilders. Cette liste contribue grandement lamlioration du protocole.

8. Les fichiers WSDL

Afin des dcrire les services disponibles sur un serveur, un langage de description de service a t mis en place : le WSDL (Web Service Description Langage). Ce langage est bas sur XML. Les fichiers WSDL contiennent donc la description de laccs des Web services ainsi que des messages qui seront changs avec les services en question. (Arguments, types de donne). Une fois muni de cette description, appele aussi parfois contrat , le client va pouvoir dialoguer avec les services de manire adquate. On peut par exemple gnrer automatiquement partir du fichier WSDL un client ou un proxy pour ce service. Pour comprendre les diffrentes zones dun descripteur WSDL, le schma suivant o se situent les diffrents lments dcrits dans un fichier WSDL.

Diffrents lments dun fichier WSDL (source : LearnXmlws, http://www.learnxmlws.com/tutors/wsdl/wsdl.aspx)

SOAP Simple Access Protocol

Un fichier WSDL commence par <definition> et finit par </definition>. Cest lintrieur de cette espace que lon va dclarer tous les lments constituant la description. Nous allons prendre lexemple du Web Service de Google pour montrer comment se construit un fichier WSDL.
Dbut de la description des services avec dclaration des diffrents schmas utiliss Nom unique identifiant cet ensemble de service au niveau du serveur

<definitions name="urn:GoogleSearch" targetNamespace="urn:GoogleSearch" xmlns:typens="urn:GoogleSearch" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"> ... </definition>

a) Services Un service est la mise disposition dune ou plusieurs mthodes. On peut imaginer par exemple une classe avec plusieurs mthodes invocables distance. La classe sera le service, et chaque mthode sera une opration sur ce service. La dfinition dun service se fait par lutilisation de <service></service>. b) Port Pour chaque service on va dfinir des ports par lesquels ce service sera disponible. En effet, il est possible de rendre disponible un service sur plusieurs supports diffrents : HTTP GET, SOAP, SMTP
Dfinition dun service Dfinition dun port avec ladresse du service (ici une URL)

<service name="GoogleSearchService"> <port name="GoogleSearchPort" binding="typens:GoogleSearchBinding"> <soap:address location="http://api.google.com/search/beta2"/> </port> </service>

SOAP Simple Access Protocol

10

c) Message Les messages sont les lments changs entre le client et le serveur lors dune opration sur le port dun service. Ces messages sont constitus de plusieurs parties (part) qui reprsentent chacune une donne avec un type associ.

<message name="doGoogleSearch"> <part name="key" <part name="q" <part name="start" <part name="maxResults" <part name="filter" <part name="restrict" <part name="safeSearch" <part name="lr" <part name="ie" <part name="oe" </message>

type="xsd:string"/> type="xsd:string"/> type="xsd:int"/> type="xsd:int"/> type="xsd:boolean"/> type="xsd:string"/> type="xsd:boolean"/> type="xsd:string"/> type="xsd:string"/> type="xsd:string"/>

Dfinition dun message Chaque part du message a un nom et un type. Ici un type simple

Utilisation dun type complexe

<message name="doGoogleSearchResponse"> <part name="return" type="typens:GoogleSearchResult"/> </message>

Ainsi, il est possible dfinir ses propres types en se basant sur les types de base. En lisant cette dfinition dans le fichier WSDL, le client pourra gnrer ventuellement automatiquement une structure ou une classe refltant cette description. Voici un exemple de type complexe qui reprsente le rsultat dune recherche sur le Web service de Google :
Dfinition dun type complexe Lien vers un autre type complexe

<type> <xsd:complexType name="ResultElement"> <xsd:all> <xsd:element name="summary" type="xsd:string"/> <xsd:element name="URL" type="xsd:string"/> <xsd:element name="snippet" type="xsd:string"/> <xsd:element name="title" type="xsd:string"/> <xsd:element name="cachedSize" type="xsd:string"/> <xsd:element name="relatedInformationPresent" type="xsd:boolean"/> <xsd:element name="hostName" type="xsd:string"/> <xsd:element name="directoryCategory" type="typens:DirectoryCategory"/> <xsd:element name="directoryTitle" type="xsd:string"/> </xsd:all> </xsd:complexType> </type>

SOAP Simple Access Protocol

11

d) Port Type et Oprations Une mthode peut tre reprsente par une opration qui prend un message en entre et renvoie un message en sortie. Ainsi chaque opration reprsente par <operation></operation> indique les flux de messages en entre et en sortie correspondants en dfinissant les lment <input/> et <output/>. Enfin, la collection de toutes les oprations dun service est rassemble dans un port type.

Dfinition dune opration (mthode) <portType name="GoogleSearchPort"> <operation name="doGetCachedPage"> <input message="typens:doGetCachedPage"/> <output message="typens:doGetCachedPageResponse"/> </operation> <operation name="doSpellingSuggestion"> <input message="typens:doSpellingSuggestion"/> <output message="typens:doSpellingSuggestionResponse"/> </operation> <operation name="doGoogleSearch"> <input message="typens:doGoogleSearch"/> <output message="typens:doGoogleSearchResponse"/> </operation> </portType> On indique le nom des messages en entre et en sortie

SOAP Simple Access Protocol

12

e) Bindings Enfin, pour complter la description, il faut relier certains lments entre eux. Cest le rle des bindings reprsents par les balises <binding></binding>. On va spcifier notamment tout ce qui concerne lencodage des donnes dans les messages en indiquant les rgles que lon utilise.

Dfinition de la couche transport utilise

Pour chaque opration, on dfini les rgles dencodage des donnes

<binding name="GoogleSearchBinding" type="typens:GoogleSearchPort"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="doGoogleSearch"> <soap:operation soapAction="urn:GoogleSearchAction"/> <input> <soap:body use="encoded" namespace="urn:GoogleSearch" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </input> <output> <soap:body use="encoded" namespace="urn:GoogleSearch" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </output> </operation> </binding>

SOAP Simple Access Protocol

13

Deuxime Partie : Installation et mise en uvre

Un des avantages de SOAP est sa capacit faire communiquer des plateformes htrognes. Cest pourquoi plusieurs implmentations de SOAP on t dveloppes (ou sont encore en dveloppement). Nous en avons test quelques unes, utilisant chacune un langage diffrent : Apache SOAP pour une implmentation Java, NuPHP pour le PHP, et SOAP::Lite pour le langage Perl. Pour chacune, nous allons prsenter brivement les procdures dinstallation, et quelques exemples de mise en uvre.

1. Apache SOAP
La distribution Apache SOAP (http://xml.apache.org/soap/) fournit les librairies ncessaires pour invoquer des services SOAP distants, et des outils ct serveur pour implmenter des services SOAP. En tant que librairie cliente, il offre une API pour invoquer des services SOAP RPC et une API pour envoyer et recevoir des messages SOAP. Pour mettre en uvre un service accessible par RPC ou par messages, Apache SOAP doit tre hberg par un conteneur de servlets comme Apache Tomcat. Le transport principal est le http, mme si le support dautres protocoles peut tre ajout (SMTP par exemple). a) Installation Prrequis ct serveur : jdk (1.2 ou ulterieur), un conteneur de servlets (tomcat par exemple), un parseur XML (xerces par exemple), les classes soap (le fichier soap.war inclus dans la distribution de soap suffit pour tomcat), classes annexes dans certains cas. Prrequis ct client : classes soap, mail.jar, activation.jar, classpath correct pour compiler le code java. Tomcat est un conteneur de servlets JSP qui intgre son propre serveur web. Il ne necessite donc pas linstallation dun serveur web spar. Linstallation de tomcat ne pose pas de problme particulier. Il suffit dextraire larchive fournie et de dmarrer le serveur pour vrifier que les exemples de servlets fonctionnent. Le serveur se lance par dfaut sur le port 8080, qui peut tre modifi dans les fichiers de configuration de tomcat. Linstallation de soap sous tomcat se fait simplement en copiant larchive web soap.war dans le repertoire dapplications web de tomcat (jakarta-tomcat-4.0.3/webapps). On peut galement crer un nouveau <Context> pour le serveur tomcat, qui indiquera o trouver les classes SOAP. Cela implique dajouter les chemins daccs vers tous les services deployer dans le classpath. Dans les deux cas, il faut systmatiquement redmarrer le serveur pour prendre en compte les modifications. Nous avons choisi de mettre en uvre Apache SOAP de la premire faon, qui utilise la configuration par dfaut du serveur tomcat. Lancement et arret du serveur :
/mci/projet/proj01/SOAP/jakarta-tomcat-4.0.3/bin/startup.sh /mci/projet/proj01/SOAP/jakarta-tomcat-4.0.3/bin/shutdown.sh

SOAP Simple Access Protocol

14

Pour tester le bon fonctionnement du serveur, il suffit douvrir les pages suivantes :
http://elaphe.int-evry.fr:8080/soap/servlet/rpcrouter http://elaphe.int-evry.fr:8080/soap/servlet/messagerouter

Le serveur doit rpondre

SOAP (RPC|Message) Router Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.

Si le client est correctement configur, la commande suivante affichera la liste des services dploys sur le serveur :
java org.apache.soap.server.ServiceManagerClient http://elaphe.intevry.fr:8080/soap/servlet/rpcrouter list

b) Exemple dutilisation Notre exemple conmprend 3 fichiers : EchoService.java Le code du serveur decho GetEcho.java le code du client charg dappeler le service decho DeploymentDescriptor.xml contient la description du service. Ce fichier facilite le dploiement dun service sur le serveur.

Compiler les sources java (javac *.java) apres avoir verifie le classpath. Placer les classes dans "/mci/projet/proj01/SOAP/jakarta-tomcat4.0.3/webapps/soap/WEB-INF/classes/samples/echo" ! serveur : EchoService.java
package samples.echo; public class EchoService { public String getEcho(String s){ return "*echo* " + s; } } Renvoi de la chaine reue

SOAP Simple Access Protocol

15

! client : GetEcho.java
package samples.echo; import import import import java.net.*; java.util.*; org.apache.soap.*; org.apache.soap.rpc.*; Importation des classes ncessaires

public class GetEcho { public static void main (String[] args) throws Exception { if (args.length != 2 && (args.length != 3 || !args[0].startsWith ("-"))) { System.err.println ("Usage: java " + GetEcho.class.getName () + " [-encodingStyleURI] SOAP-router-URL chaine"); System.exit (1); } // Traitement des arguments. int offset = 3 - args.length; String encodingStyleURI = args.length == 3 ? args[0].substring(1) : Constants.NS_URI_SOAP_ENC; URL url = new URL (args[1 - offset]); String chaine = args[2 - offset];

Traitement des arguments

// Construction de lappel. Call call = new Call (); Construction de lappel call.setTargetObjectURI ("urn:test-myEcho"); call.setMethodName ("getEcho"); call.setEncodingStyleURI(encodingStyleURI); Vector params = new Vector (); params.addElement (new Parameter("chaine", String.class, chaine, null)); call.setParams (params); // appel: lURI action est vide (non utilise par XML-SOAP) Response resp = call.invoke (/* router URL */ url, /* actionURI */ "" ); // Check the response. if (resp.generatedFault ()) { Fault fault = resp.getFault (); System.err.println("Generated fault: " + fault); } else { Parameter result = resp.getReturnValue (); System.out.println (result.getValue ()); } } } Affichage du rsultat

Appel

Verification de la rponse

SOAP Simple Access Protocol

16

! DeploymentDescriptor.xml
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:test-myEcho"> <isd:provider type="java" scope="Application" methods="getEcho"> <isd:java class="samples.echo.EchoService"/> </isd:provider> <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener> </isd:service>

! Utilisation : Les services peuvent tre dploys laide de linterface web de la distibution Apache SOAP (http://elaphe.int-evry.fr:8080/soap), ou plus simplement en utilisant la classe ServiceManagerClient fournie :
java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter deploy DeploymentDescriptor.xml java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter undeploy urn:test-myEcho java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter list

Le client prend en paramtres ladresse du routeur RPC et le texte envoyer :

java samples.echo.GetEcho http://elaphe.intevry.fr:8080/soap/servlet/rpcrouter montexte

Apache SOAP noffre pas de support du wsdl ct client. Un utilitaire spar fourni par IBM permet toutefois de crer un code client partir dun fichier wsdl, mais son utilisation nest pas pratique.

SOAP Simple Access Protocol

17

2. NuSoap
NuSOAP est une implmentation en PHP de SOAP disponible gratuitement sur Internet (licence LGPL) : http://dietrich.ganx4.com/nusoap/. Il a t dvelopp par Dietrich Ayala pour Nusphere (IDE pour PHP : http://www.nusphere.com/). Ce kit est constitu de plusieurs classes permettant la mise en place de clients et de serveurs SOAP en utilisant le langage PHP. Ce langage est trs utilis pour construire des sites Web dynamiques, laccs aux Web Services est donc la bienvenue. a) Installation Cette implmentation de SOAP est assez simple installer et utiliser puisquaucun serveur spcifique (autre quun simple serveur Web) nest requis. Il suffit de mettre sur le serveur un simple script PHP pour avoir acces des services. La partie serveur est dmarre chaque appel de lURL du script implmentant la partie serveur pour SOAP. Cest entre autre cela qui fait la simplicit de mise en place de cette implmentation : il suffit de faire un include du fichier contenant les classe de NuSOAP pour pouvoir dployer ou invoquer des services. b) Exemples dutilisation ! Script serveur : dploiement du service myEcho
<?php require_once('../nusoap/nusoap.php'); Inclusion des classes NuSoap

$s = new soap_server; $s->register('myEcho',false,false,"urn:myEcho");

Cration dun objet serveur Enregistrement du service myEcho auprs du serveur

function myEcho($chaine){ // optionally catch an error and return a fault if($chaine == ''){ return new soap_fault('Client','','La chaine est vide.'); } $res="vous avez envoy:".$chaine; return $res; } $s->service($HTTP_RAW_POST_DATA); ?>

Fonction effectuant le service (Fonction qui sera appele par RPC)

Envoie des rponses du serveur au client : Ici, NuSoap va gnrer le message rponse du serveur en XML et lenvoyer dans la rponse http au client.

SOAP Simple Access Protocol

18

! Script Client : appel direct au service myEcho (sans utiliser le fichier WSDL)
Appel aux classes de NuSOAP Prparation du tableau contenants les paramtres passer au service $lachaine : variable contenant la chaine passer lors de lappel Cration de lobjet client avec lURL du service SOAP appeler. Ici cest lURL du script serveur crit en PHP

<?php require_once('../nusoap/nusoap.php'); if($lachaine!=NULL){ $parameters = array('chaine1'=>$lachaine); $soapclient = new soapclient('http://www.minet.net/~ospring/testsoap/rpcrouter.php'); echo $soapclient->call('myEcho',$parameters); } else echo "<- Remplir le formulaire"; ?>

Appel de la mthode distante myEcho avec passage du tableau des paramtres

! Script Client : appel direct service myEcho avec le fichier WSDL et le proxy NuSOAP permet, si lon utilise les descripteurs de services crits en WSDL, de gnrer un proxy pour service. Ce proxy permet daccder la mthode distante comme si elle tait une mthode dun objet local. Cela permet davoir un code beaucoup plus clair et moins lourd.

SOAP Simple Access Protocol

19

Exemple dutilisation :

<?php require_once('../nusoap/nusoap.php'); $soapclient= new soapclient('http://www.minet.net/~ospring/testsoap/myEcho.wsdl','wsdl' ); $proxy=$soapclient->getProxy(); $res=$proxy->myEcho($lachaine); echo $res;

Appel la procdure distante via le proxy

Cration du proxy

Cration du client partir dun fichier WSDL

3. SOAP::Lite
SOAP::Lite (http://www.soaplite.com) est un ensemble de modules Perl qui fournissent une interface simple et lgre vers SOAP, ct client et ct serveur. Il est prfrable dinstaller la distribution en tant que root bien quil soit possible dinstaller les modules dans son propre repertoire de travail. a) Installation De nombreux modules sont ncessaires SOAP::Lite MIME-Base64-2.12 IO-1.20 URI-1.19 MIME-Lite-2.117 HTML-Parser-3.26 HTML-Tagset-3.03 libnet-1.12 MIME-tools-5.411 IO-stringy-2.108 MailTools-1.46 XML-Parser-2.31 libwww-perl-5.65 Les commandes pour installer les modules dans ~/perl (pour un utilisateur normal) sont :
perl Makefile.PL LIB=~/perl make make test make install

SOAP Simple Access Protocol

20

Il faut parfois diter le fichier Makefile.PL pour indiquer le chemin daccs des modules dj ajouts (ce qui revient modifier la variable @INC). Ajouter en tte du fichier (par exemple) :
use lib '/mci/projet/proj01/perl'; use lib '/mci/projet/proj01/perl/i386-linux';

Une fois que tous les modules sont prsents, extraire la distribution SOAP::Lite et modifier le fichier Makefile.PL (ajouter use lib '/mci/projet/proj01/perl/i386-linux'; use lib '/mci/projet/proj01/perl'; en tte du fichier). Comme pour les autres modules, lancer les commandes :
perl Makefile.PL LIB=~/perl make make test make install

b) Exemple dutilisation : ! clientEcho.pl (acces par descripteur wsdl)

#!perl -w use lib '/mci/projet/proj01/perl'; use SOAP::Lite; Emplacement des modules Perl ncessaires

my $lachaine = shift || die "usage: clientEcho <string>\n";

Rcuperation du paramtre en entre

# on appelle le service Java par sa description wsdl my $soapclient = SOAP::Lite->service("http://elaphe.intevry.fr:8080/soap/wsdl/test-myEcho.wsdl"); my $result = $soapclient->getEcho($lachaine); print "resultat (Java avec wsdl): $result\n";

Appel du service Apache par sa description wsdl

# on appelle le service Java par le serveur rpc my $soapclient2 = SOAP::Lite->uri('urn:test-myEcho') ->proxy('http://elaphe.int-evry.fr:8080/soap/servlet/rpcrouter'); my $result2 = $soapclient2->getEcho($lachaine)->result; Appel du service Apache print "resultat (Java par RPC) : $result2\n"; par le serveur RPC # on appelle le service PHP par sa description wsdl my $soapclient3 = SOAP::Lite ->service("http://elaphe.int-evry.fr:8080/soap/wsdl/myEcho.wsdl"); my $result3 = $soapclient3->myEcho($lachaine); print "resultat (PHP avec wsdl): $result3\n"; Appel du service NuSOAP par sa description wsdl # on appelle le service PHP par le serveur rpc my $soapclient4 = SOAP::Lite->uri('urn:myEcho') ->proxy('http://www.minet.net/~ospring/testsoap/rpcrouter.php'); my $result4 = $soapclient4->myEcho($lachaine)->result; print "resultat (PHP par RPC) : $result4\n"; Appel du service NuSOAP par le serveur RPC

SOAP Simple Access Protocol

21

! Utilisation La commande pour lancer le client echo est

perl clientEcho.pl montexte

Limplmentation ct serveur peut se faire par cgi ou laide dun serveur web possdant un module perl. Nous ne sommes pas parvenus mettre en uvre la solution cgi, ceci tant rendu difficile par labsence de processus de dbuggage lors dune erreur sur le serveur ( Erreur 500 ).

4. Tests dinteroperabilit
Lobjectif principal de SOAP est de permettre des applications de faire appel des mthodes distantes quelles que soient les plates-formes utilises de part et dautre. Nous avons naturellement voulu vrifier cela sur la mise en uvre simple du service Echo. Les services Echo ont t dploys en Java (avec Apache SOAP) en PHP (avec NuSOAP). Nous avons tes des clients Java, PHP, et Perl. Le client en Java accde sans difficult au service sous Java. Lappel au routeur RPC en PHP par le client Java nous a tout dabord pos problme : celui-ci nous renvoyait une erreur dont nous ne comprenions pas le sens. Nous nous sommes finalement rendus compte que le problme venait de la prsence dun accent dans la chane retourne. Aprs suppression de laccent, lappel fonctionnait parfaitement. Le client PHP et le client Perl fonctionnent sur les deux serveurs sans problme. Ces tests ne sont quun aperu des possibilits offertes par SOAP et des problmes dinteroprabilit quil peut poser. Les modes dencodage et lutilisation de types complexes notamment semblent poser des difficults lors de la mise en place de plates-formes htrognes.

SOAP Simple Access Protocol

22

Troisime Partie : Exemples dutilisation

1. Exemple de Web Service : Google Web Service
Afin, de mieux comprendre les rles que peuvent remplir les Web Services ainsi que leur fonctionnement, nous en avons test un existant et dvelopp des clients permettant de lexploiter. Google est un moteur de recherche sur le Web trs connu offrant des options de recherches assez avances. Google met disposition un Web service permettant dinterroger le moteur de recherche via SOAP. Un fichier WSDL est donn pour ce fait et donne laccs trois mthodes : doGetCachedPage : cette mthode permet de rcuprer les page Web en cache dans le moteur de recherche. doGoogleSearch : Cette mthode permet de lancer une recherche sur le moteur et den rcuprer 10 rsultats (maximum). doSpellingSuggestion : permet de traduire du texte Le client a t dvelopp en PHP. Il permet de lancer une recherche en spcifiant le nombre de rsultat, puis, pour chaque rsultat, il permet de rcuprer la page correspondante en cache dans le moteur.

Appel du Web Service de recherche sur Google

Utilisation des rsultats. La structure complexe du rsultat a t place dans des tableaux imbriqus

<?php require_once('../nusoap/nusoap.php'); if(isset($query)){ $soapclient = new soapclient('http://www.minet.net/~ospring/testsoap/GoogleSearch.wsdl','wsdl'); $proxy=$soapclient->getProxy(); $res=$proxy>doGoogleSearch("X4YaHThwrxRUii7siFP0fxXFz9XgoJrT",$query,$start_index,$numres,tru e,"",false,"","",""); ?> Nombre de rponses trouves:&nbsp; <?php echo $res['estimatedTotalResultsCount']; ?><br> Temps de recherche:&nbsp; <?php echo $res['searchTime']; ?><br> <?php for($i=0;$i< count($res['resultElements']) && $res['estimatedTotalResultsCount']>0;$i++){ ?> </td></tr> <tr> <td><?php $index=$i+$start_index;echo $index; ?></td> <td> <b><?php echo $res['resultElements'][$i]['title']; ?></b><br> <a href='<?php echo $res['resultElements'][$i]['URL'];?>'><?php echo $res['resultElements'][$i]['URL']; ?></a><br> <a href="clientCacheGoogle.php?cached_url=<?php echo htmlspecialchars($res['resultElements'][$i]['URL']);?>">cached page</a> <?php } ?>

SOAP Simple Access Protocol

23

2. Exemple du gestionnaire dimprimante

Nous avons essay dans cette partie dimplmenter lexemple du gestionnaire dimprimante en java avec SOAP et de voir ainsi les diffrences avec CORBA. Pour faciliter la comprhension nous avons effectu trois versions du gestionnaire dimprimante. a) Exemple 1 : limprimante HP Dans cet exemple le service reprsente une imprimante seule et sur laquelle on peut demander une impression et obtenir des informations sur les taches en cours.

Imprime GetInfos

SOAP (http) ImprimanteHP.class

Service Clients

Figure 1

Nous allons donc voir dans un premier comment crer le service puis nous verrons comment crire les clients.

i)

Cration du service SOAP

Lcriture dun service SOAP bas sur les RPC est trs simple et se fait en trois tapes : ! Crer la classe Java contenant le service SOAP publier ! Crer un deployment descriptor dcrivant le service ! Publier le service ! Cration du service Un service SOAP peut tre juste nimporte quelle classe Java habituelle qui expose des mthodes publiques. Lcriture de cette classe nest en rien spcifique SOAP. La seule restriction est que les paramtres des mthodes doivent tre serialisables . Les types par dfaut supports par SOAP sont les suivants : Notre service a donc la forme suivante : o Tous les types primitifs et les wrapper correspondants o Java arrays o java.lang.String o java.util.Date o java.util.GregorianCalendar o java.util.Vector SOAP Simple Access Protocol 24

o o o o o o o o o o

java.util.Hashtable java.util.Map java.math.BigDecimal javax.mail.internet.MimeBodyPart java.io.InputStream javax.activation.DataSource javax.activation.DataHandler org.apache.soap.util.xml.QName org.apache.soap.rpc.Parameter java.lang.Object (en tant que JavaBean)

SOAP Simple Access Protocol

25

package GIsoap.exemple1; import java.net.*; import java.io.*; public class ImprimanteHP { private short tacheCourante; private String nom; ImpInfos inf; public ImprimanteHP() { nom=new String("hp"); System.out.println("Instantiation de l'imprimante : } public ImpInfos getInfo() { InetAddress maMachine; String machine; try { maMachine = InetAddress.getLocalHost(); machine = maMachine.getHostName(); } catch (UnknownHostException u) { machine = new String("machine inconnue"); } inf = new ImpInfos(nom,"", machine, tacheCourante) ; return inf; } public TacheInfos envoiDocument (String n) throws TacheRefusee { int t; // ouverture du fichier // recupere taille du fichier File f=new File(n); if ( ! f.isFile() ) { throw new TacheRefusee(nom,n+" : n'est pas un fichier");} t = (int)f.length(); if (tacheCourante > 2) { System.out.println("Je suis dfinitivement surcharge, il faut me redmarre r !"); throw new TacheRefusee(nom,"surcharge"); } System.out.println("Impression du document : "+ n + " sur " + nom + " taille " + t); tacheCourante++; return (new TacheInfos(tacheCourante, t)); } }

"+ nom);

SOAP Simple Access Protocol

26

On remarque que les mthodes getInfos et envoiDocument renvoie chacun un objet que nous avons dfini. Ces objets seront transmis aux clients en rponse aux appels des mthodes. Comme nous lavons vu plus prcdemment les objets doivent tre srialisables. Nous avons donc deux possibilits soit nous crivons nos propres srialiseurs soit nous utilisons la classe BeanSerializer de JavaBean fourni avec Apache SOAP. La deuxime possibilit est en fait la plus simple. Pour cela nous devons chaque classe un constructeur par dfaut et rajouter les mthodes setXXX et getXXX pour chaque donne de la classe.
package GIsoap.exemple1; public class TacheInfos { private short tacheCourante; private int tailleFichier; public TacheInfos() {} public TacheInfos( short tacheCourante, int tailleFichier) { this.tacheCourante = tacheCourante; this.tailleFichier = tailleFichier; }

public void setTacheCourante(short tacheCourante) { this.tacheCourante = tacheCourante; } public short getTacheCourante() { return tacheCourante; } public void setTailleFichier(int tailleFichier) { this.tailleFichier = tailleFichier; } public int getTailleFichier() { return tailleFichier; } }

TacheInfos.java

SOAP Simple Access Protocol

27

public class ImpInfos { private String imprimante; private String serveur; private String machine; private short tacheEnCours;

public ImpInfos() { tacheEnCours= 2; } public ImpInfos( String imprimante, String serveur, String machine, short tacheEnCou rs) { this.imprimante = new String(imprimante); this.serveur = new String(serveur); this.machine = new String(machine); this.tacheEnCours = tacheEnCours; }

public void setImprimante(String imprimante) { this.imprimante = imprimante; } public String getImprimante() { return imprimante; } public void setServeur(String serveur) { this.serveur = serveur; } public String getServeur() { return serveur; } public void setMachine(String machine) { this.machine = machine; } public String getMachine() { return machine; } public void setTacheEnCours(short tacheEnCours) { this.tacheEnCours = tacheEnCours; } public short getTacheEnCours() { return tacheEnCours; }

public String toString() { return imprimante + " "+ serveur + " "+ machine + tacheEnCours; } }

ImpInfos.java

SOAP Simple Access Protocol

28

Voil cest fini en ce qui concerne la cration du service. ! Cration du deployment descriptor Pour dployer un service on peut soit utiliser linterface de dploiement fourni le serveur Apache en utilisant le navigateur soit utiliser les commandes de gestion de services pour lequel il faut un fichier XML dcrivant le service. Voici ce fichier pour notre exemple :
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:ImprimanteHP"> <isd:provider type="java" scope="Application" methods="getInfo envoiDocument"> <isd:java class="GIsoap.exemple1.ImprimanteHP" static="false"/> </isd:provider> <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener> <isd:mappings> <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:x="urn:imprimanteHP-demo" qname="x:ImpInfos" javaType="GIsoap.exemple1.ImpInfos" java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer" xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/> <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:x="urn:imprimanteHP-demo" qname="x:TacheInfos" javaType="GIsoap.exemple1.TacheInfos" java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer" xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/> </isd:mappings> </isd:service>

Le descripteur de dploiement pour notre service dimprimante contient cinq lments qui nous devons regarder. Le premier lment est l'lment service, qui dfinit deux attributs, le namespace de XML et l'identification unique du service dployer. L'identification dfinie dans l'lment de service doit tre unique, puisque cet attribut est employ pour identifier un service publi avec SOAP. Le prochain lment que nous devons examiner est l'lment provider. Il dfinit limplmentation relle du service de SOAP, grce trois attributs, dont chacun est dfini comme suit: type Dfinit le type d'excution du service de SOAP. Nous avons dfini notre service comme service Java. scope Dfinit le cycle de vie du service de SOAP. Les valeurs possibles sont page, scope, session, et application. Ces valeurs correspondent directement avec celles dfinies par les spcifications de JSP. methods Dfinit les noms des mthodes qui peuvent tre appeles sur cet objet de service. Cette liste doit tre une liste de noms de mthode spars par un espace java SOAP Simple Access Protocol 29

Cet lment contient un attribut simple, la classe, qui appelle la classe entirement qualifie du service appel. mappings Cet lment annonce tous les objets que nous avons serialiss. Les attributs java2XMLClassName et xml2JavaClassName indiquent respectivement une classe pour convertir de Java en XML et de XML en Java. ! Publication du service Pour publier le service il suffit dexcuter la commande suivante :
javaorg.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter deploy DeploymentDescriptor.xml

ii)

Cration dun client soap

Maintenant que nous avons dfinit le service et quon la dploy, crivons un client qui excutera une des mthodes du service. Le projet de SOAP d'Apache fournit une API ct client qui permet de crer des clients de manire simple. Voici par exemple le client qui imprime un fichier sur limprimante HP.

SOAP Simple Access Protocol

30

package GIsoap.exemple1; import import import import import import import import import java.io.*; java.util.*; java.net.*; org.w3c.dom.*; org.apache.soap.util.xml.*; org.apache.soap.*; org.apache.soap.encoding.*; org.apache.soap.encoding.soapenc.*; org.apache.soap.rpc.*;

public class Imprime { public static void main(String[] args) throws Exception { if (args.length != 2) { System.err.println("Usage:"); System.err.println(" java " + Imprime.class.getName() + "SOAP-router-URL" + "fichier"); System.exit (1); } URL url = new URL(args[0]); String nomfic = args[1]; SOAPMappingRegistry smr = new SOAPMappingRegistry(); BeanSerializer beanSer = new BeanSerializer(); // Map the types. smr.mapTypes(Constants.NS_URI_SOAP_ENC, new QName("urn:imprimanteHP-demo", "TacheInfos"), TacheInfos.class, beanSer, beanSer); // Build the call. Call call = new Call(); call.setSOAPMappingRegistry(smr); call.setTargetObjectURI("urn:ImprimanteHP"); call.setMethodName("envoiDocument"); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC); Vector params = new Vector(); params.addElement(new Parameter("n", String.class, nomfic, null)); call.setParams(params); // Invoke the call. Response resp; try { resp = call.invoke(url, ""); } catch (SOAPException e) { System.err.println("Caught SOAPException (" + e.getFaultCode() + "): " + e.getMessage()); return; } if (!resp.generatedFault()) { Parameter ret = resp.getReturnValue(); Object value = ret.getValue(); TacheInfos tache = (TacheInfos) value; if (tache!=null) System.out.println("\nImpression envoye sur HP" + ", tche " + tache.getTacheCourante() + ", taille "+ tache.getTailleFichier() + " : "+ nomfic); else System.out.println("I don't know."); } else { Fault fault = resp.getFault(); System.err.println("Generated fault: " + fault); } } }

SOAP Simple Access Protocol

31

Ce client suit un processus simple qui est commun la plupart des clients RPC SOAP. Il cre d'abord une URL mettant en rfrence le rpcrouter (que nous avons pass en argument) sur le localhost de serveur de HTTP.
URL url = new URL(args[0]); (http://localhost:8080/soap/servlet/rpcrouter)

Ensuite nous avons besoin que le client sache quels serializer et deserializer employer. Cest que la classe SOAPMappingRegistry permet. La mthode mapTypes() prend en entr une chane d encodage, et des informations sur le type de paramtre que devra utiliser une srialisation particulire. D'abord, un QName est fourni. Vous devez indiquer la mme URN ici, ainsi que le nom local de l'lment (dans ce cas-ci "TacheInfos"), puis de classe Java srialiser (TacheInfos.class), et finalement linstance de la classe ncessaire la serialisation et la desrialisation. Dans le cas du BeanSerializer, la mme instance fonctionne pour tous les deux. Une fois que tout ceci est indiqu dans l'enregistrement, il ne reste plus qua en informer lobjet call par la mthode setSOAPMapping-Registry().
SOAPMappingRegistry smr = new SOAPMappingRegistry(); BeanSerializer beanSer = new BeanSerializer(); // Map the types. smr.mapTypes(Constants.NS_URI_SOAP_ENC, new QName("urn:imprimanteHP-demo", "TacheInfos"), TacheInfos.class, beanSer, beanSer); // Build the call. Call call = new Call(); call.setSOAPMappingRegistry(smr);

La prochaine tape excute par le client est de crer une instance de org.apache.soap.rpc.RPCMessage.Call. L'objet call est l'interface principale utilise lors de lexcution d une invocation RPC SOAP. Pour employer l'objet call, il faut lui indiquer quel service nous voulons utiliser. Nous faisons ceci en appelant setTargetObjectURI, et en lui passant le nom du service que nous voulons excuter. Nous avons alors plac le nom de la mthode de service que nous voulons excuter en utilisant la mthode setMethodName(). La prochaine tape est dindiquer le modle dencodage utilis dans lappel RPC. L'tape finale est d'ajouter les paramtres attendus en excutant la mthode demande. Ceci est fait en crant un vecteur dobjets parameter et en les ajoutant l'objet call en utilisant la mthode setParams().

call.setTargetObjectURI("urn:ImprimanteHP"); call.setMethodName("envoiDocument"); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);

Vector params = new Vector(); params.addElement(new Parameter("n", String.class, nomfic, null));

call.setParams(params);

La prochaine tape excute par le client est d'appeler la mthode de service qui nous intresse. Ceci est fait en utilisant invoke() avec l URL que nous avons cr plus tt.

SOAP Simple Access Protocol

32

resp = call.invoke(url, "");

La valeur de retour de la mthode invoke() est un objet response. L'objet response renvoie un code d'erreur et la valeur retourne de la mthode excute du service. On peut vrifier si erreur sest produite en appelant la mthode generatedFault(). Cette mthode renverra vrai s'il une erreur est retourne; on obtient lerreur par la mthode getFault(). Si le generatedFault() renvoie faux, on peut alors obtenir la valeur retourne dans l'objet response, en utilisant la mthode Response.getReturnValue(). Dans notre exemple on voit que la mthode imprime peut gnrer une exception TacheRefusee. Cependant nous navons pas trouv comment rattrap cette exception du ct client dun manire correcte cest dire sans analyser la chane de caractres qui nous est fournit par getFaultString().

b) Exemple 2 : le gestionnaire dimpression Dans cet exemple nous voulons imprimer sur des imprimantes : HP ou CANON. Dans la version CORBA, le gestionnaire dimpression cre un objet CORBA pour chaque imprimante. Ensuite le client imprime sur limprimante dsir en obtenant la rfrence de lobjet par un fichier ou un service de nommage. Avec SOAP une telle approche nest pas possible. Du moins pas par les rfrences. On pourrait faire un service distinct pour chaque imprimante, mais ceci reviendrait rcrer l exemple 1 pour limprimante CANON et indiquer le bon URN au client en fonction de limprimante choisi. Mais une meilleure solution consiste crer un service que lon appellera GestionnaireImpression qui va jouer le rle de proxy. Les imprimantes seront adress par un nom et le proxy appellera la mthode demande de limprimante choisie.

HP
Imprimante.class

Imprime GetInfos

SOAP (http)

GestionnaireImpression.class

(Proxy) Clients Service

Figure 2

Imprimante.class

CANON

Voici donc la forme du gestionnaire dimpression :

SOAP Simple Access Protocol

33

package GIsoap.exemple2; import java.util.*; public class GestionnaireImpression {

private Hashtable imprTable = new Hashtable(); public GestionnaireImpression() { imprTable.put("canon", new Imprimante("canon")); imprTable.put("hp", new Imprimante("hp")); }

public ImpInfos getInfo(String nomimp) { Imprimante imp=(Imprimante) imprTable.get(nomimp); return imp.getInfo(); } public TacheInfos envoiDocument( String nomimp, String nomfic) throws TacheRefusee { Imprimante imp=(Imprimante) imprTable.get(nomimp); return imp.envoiDocument(nomfic); } }

Et voil un client :

SOAP Simple Access Protocol

34

package GIsoap.exemple2; import import import import import import import import import java.io.*; java.util.*; java.net.*; org.w3c.dom.*; org.apache.soap.util.xml.*; org.apache.soap.*; org.apache.soap.encoding.*; org.apache.soap.encoding.soapenc.*; org.apache.soap.rpc.*;

public class Imprime { public static void main(String[] args) throws Exception { if (args.length != 3) { System.err.println("Usage:"); System.err.println(" java " + Imprime.class.getName() + "SOAP-router-URL" + "imprimante" + "fichier"); System.exit (1); } URL url = new URL(args[0]); String nomimp = args[1]; String nomfic = args[2]; SOAPMappingRegistry smr = new SOAPMappingRegistry(); BeanSerializer beanSer = new BeanSerializer(); // Map the types. smr.mapTypes(Constants.NS_URI_SOAP_ENC, new QName("urn:gestionimprimante-demo", "TacheInfos"), TacheInfos.class, beanSer, beanSer); // Build the call. Call call = new Call(); call.setSOAPMappingRegistry(smr); call.setTargetObjectURI("urn:GestionImprimante"); call.setMethodName("envoiDocument"); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC); Vector params = new Vector(); params.addElement(new Parameter("nomimp", String.class, nomimp, null)); params.addElement(new Parameter("nomfic", String.class, nomfic, null)); call.setParams(params); // Invoke the call. Response resp; try { resp = call.invoke(url, ""); } catch (SOAPException e) { System.err.println("Caught SOAPException (" + e.getFaultCode() + "): " + e.getMessage()); return; } if (!resp.generatedFault()) { Parameter ret = resp.getReturnValue(); Object value = ret.getValue(); TacheInfos tache = (TacheInfos) value; if (tache!=null) System.out.println("\nImpression envoye sur " + nomimp + ", tche " + tache.getTacheCourante() + ", taille "+ tache.getTailleFichier() + " : "+ nomfic); else System.out.println("I don't know."); } else { Fault fault = resp.getFault(); System.err.println("Generated fault: " + fault); } } }

SOAP Simple Access Protocol

35

c) Exemple 3 : le gestionnaire dimpression et WSDL Dans les exemples prcdent nous avons vu que lappel de lobjet distant dans le client ntait pas tout fait transparente. En effet il faut mettre tous les paramtres dans un vecteur en indiquant leur types, puis positionn la mthode que lon souhaite appeler et enfin faire invoke. Lide est donc cette fois ci de disposer du ct client dun proxy qui nous rendrait les appels transparents. Dautre part ce proxy peut tre gnre automatiquement. Pour cela il faut dans premier temps crer un fichier WSDL qui va dcrire le service dune manire indpendante du langage qui limplmente. Puis partir du fichier WSDL il faut gnrer le proxy client (en java dans notre cas).

HP
Imprimante.class

Imprime GetInfos

Gestionnaire ImpressionProxy.class

SOAP (http)

Gestionnaire Impression.class

Imprimante.class

Clients

Service

CANON

Figure 3

d) Excution des exemples Aller dans le rpertoire GIsoap et excuter une seule fois pour tout les exemples : . ./setclasspath Puis dans chaque rpertoire dexemple : ./testit.sh

SOAP Simple Access Protocol

36

Bibliographie
1. Articles Gnraux sur SOAP
! Articles sur SOAP, tests dimplmentations et exemples de mise en uvre, http://www.soapuser.com/ ! Tutoriel WSDL: http://www.learnxmlws.com/tutors/wsdl/wsdl.aspx ! Standard SOAP par le W3C: http://www.w3.org/TR/SOAP/

2. Implmentations et installation
! Une liste dimplmentations sur Soapware.org : http://www.soapware.org/directory/4/implementations ! XML Apache Project: http://xml.apache.org ! Apache SOAP: http://xml.apache.org/soap ! NuSOAP: http://dietrich.ganx4.com/nusoap/ ! SOAP::Lite: http://www.soaplite.com ! Installer Perl sans tre super-utilisateur : http://www.perl.com/pub/a/2002/04/10/mod_perl.html?page=1

3. Divers outils pour SOAP

! Outils AXIS : http://xml.apache.org/axis/index.html ! Outils SOAP en ligne: http://www.soapclient.com/SoapTools.html

4. Exemples de Web Services

! APIs web Google: http://www.google.com/apis/index.html ! Xmethods: http://www.xmethods.com/

SOAP Simple Access Protocol

37