WebServices With Tomcat And Java 1.6 Auteur: Frank Sauvage. 1 \ Rappels sur les services web 1.1 \ Architectures SOA Concues et definies à l'origine par le Gartner Group, les architecture orientées services (SOA) sont une solution nouvelles à la complexité induite par la taille toujours plus importantes des applications et structures composant les systémes d'information d'aujourd'hui. Alors que la programmation orientée objet à permis une évolution majeure dans les developpements informatiques, cette avancée se limitait cependant principalement à la reutilisation des librairies induisant la conception de larges applications basées sur des briques toujours plus performantes, mutualisées et maintenues par des communautés ou groupes de developpeurs. Avec l'arrivée des SOA, l'une des premieres avancées fut la possibilité de concentrer les codes metiers la où ils etaient produits, et de permettre leur utilisation à distance via un protocole standardisé SOAP. Reprenant le concept des RMI, les services webs permettent cependant une plus grande flexibilitée dans leur utilisation. Chaque service est maitre de ses données et et des régles metiers qui y sont associées. Cela permet alors de considerer la possibilité de mettre en place de grandes applications distribuées composées de services dialoguant entre eux. Le principe de base est donc que chaque service peut etre utilisé grace à WSDL et SOAP qui sont des protocoles basés sur XML et HTTP. Quant à la recherce d'un service, cela peut etre effectué grace au protocol UDDI, mais cette méthode n'est pas encore très repandue.
1.2 \ WSDL Web Service Description Language (WSDL) est le protocole utilisé pour decrire un service web. C'est un format basé sur XML standardisé par le W3C qui permet principalement de decrire : Le fournisseur du WebService. Les informations que le WebService peut fournir. Le format des requêtes. Voici un exemple de fichier WSDL : <definitions targetnamespace="http://ws/" name="addnumberimplservice"> <import location="http://www.okeo.org:80/directory/addnumber?wsdl=1" namespace="http://www.okeo.org"/> <binding name="addnumberimplportbinding" type="ns1:addnumber"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="add"> <soap:operation soapaction="urn:addnumber"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> <fault name="addnumberexception"> <soap:fault name="addnumberexception" use="literal"/> </fault> </operation> </binding> <service name="addnumberimplservice"> <port name="addnumberimplport" binding="tns:addnumberimplportbinding"> <soap:address location="http://www.okeo.org:80/directory/addnumber"/> </port> </service> </definitions> Ce fichier est extrémement important pour les services web même si il n'est plus neccessaire aujourd'hui d'en avoir une connaissance précise pour les utiliser. En effet, comme nous le verrons plus loin, les outils fournis avec Java 1.6 sont desormais capables de les generer a partir d'interface Java annotées, et inversement pour l'utilisation du service web dans un client java. La definition du standard est disponible sur le site du W3C à l'adresse suivante : http://www.w3.org/tr/wsdl
1.3 \ SOAP Simple Object Access Protocol (SOAP) est le successeur designé de XML-RPC l'ancienne norme d'accés à des web service. Le principal inconvient de XML-RPC étant son unique support du jeu ASCII, les transfert de type unicode pour les données non textes etaient alors tributaires d'extension au format. SOAP regle ce probleme et fourni une maniere efficace d'acceder à un service distant. SOAP herite donc des avantage de XML-RPC en corrigeant ses principaux defaut hormis bien entendu la nature d'xml qui rend ce type de format plus gourmands. Un autre avantage de SOAP, est sa capacité a transporter des exceptions. Tout bon developpeur java appreciera cette fonctionnalité qui permettra d'eviter de longues heures de debogage. De même que pour WSDL, le W3C est chargé de sa standardisation qui est disponible à l'addresse suivante : http://www.w3.org/tr/soap 1.4 \ UDDI Unniversal Description, Discovery and Integration (UDDI) est un protocole géré par l'oasis ( http://www.oasis-open.org ) qui est un consortium principalement principalement composé par Microsoft, IBM et Ariva. Il s'agit en fait d'un annuaire de service très performant mais qui dans la realité seduit peu. En effet, la tendance interne veut que les webservices soit plutôt utilisés en interne dans les organismes et leurs partenaires plutôt que publiquement sur le net. Il existe cependant de nombreux services interressant tels que le très connu Google qui offre un accés à son moteur par ce biais.
2 \ Java 1.6 et les services Web 2.1 \ Présentation des API L'une des principales avancées apportées par la nouvelle machine virtuelle java est l'integration de JAX-WS 2.0. cette api, Java Api for XML WebServices (JAX-WS) offre une integration poussée des services web au sein de Java. Principalement developpée pour J2EE 5, elle succéde à l'api JAX-RPC changeant de dénomination au passage afin de refleter sa plus large integration de fonctionnalitées (d'ou le 2.0). JAX-WS 2.0 se base sur l'api JAXB pour permettre le mapping Objet/XML où JAX-RPC integrait ses propres methodes. De plus, il n'est plus neccessaire de s'occuper des descriptifs WSDL dans la mesure où des annotations specifiques ont été introduites afin de definir les parametres directement au sein du code Java qui permettront de generer gràce à Xdoclet les classes et fichiers neccessaires à leur utilisation. Concernant la securité, Les XML Digital Signatures sont egalement presentes. 2.2 \ JAX-WS 2.0 JAX-WS 2.0 fait partie du projet GlassFish, serveur open-source developpée en collaboration avec Sun pour le support de J2EE 5. Il est possible de telecharger l'implementation de reference sur le site suivant https://jax-ws.dev.java.net Nous utiliserons par ailleurs dans ce document cette implémentation.
3 \ configurer tomcat pour prendre en charge les web services 3.1 \ Ajout des libraires partagées Pour pouvoir utiliser les WebService et particulierement JAX-WS 2.0 avec un container tomcat, il est neccessaire d'ajouter à ce dernier les librairies neccessaires. Le repertoire Lib de l'installation de JAXWS-RI (l'implementation de reference) contient tous les jar neccessaires. Il est donc neccessaire de copier ces derniers dans le repertoire $TomcatHome/share/lib/, ce qui permettra d'utiliser une servlet speciale. Les fichiers suivants doivent donc etre dans le repertoire : -rw-r--r-- 1 tomcat tomcat 54829 jui 8 02:23 activation.jar -rw-r--r-- 1 tomcat tomcat 264213 jui 8 02:23 FastInfoset.jar -rw-r--r-- 1 tomcat tomcat 76346 jui 8 02:23 http.jar -rw-r--r-- 1 tomcat tomcat 73081 jui 8 02:23 jaxb-api.jar -rw-r--r-- 1 tomcat tomcat 778939 jui 8 02:23 jaxb-impl.jar -rw-r--r-- 1 tomcat tomcat 2978657 jui 8 02:23 jaxb-xjc.jar -rw-r--r-- 1 tomcat tomcat 23618 jui 8 02:23 jaxws-api.jar -rw-r--r-- 1 tomcat tomcat 616742 jui 8 02:23 jaxws-rt.jar -rw-r--r-- 1 tomcat tomcat 489662 jui 8 02:23 jaxws-tools.jar -rw-r--r-- 1 tomcat tomcat 46047 jui 8 02:23 jsr173_api.jar -rw-r--r-- 1 tomcat tomcat 7995 jui 8 02:23 jsr181-api.jar -rw-r--r-- 1 tomcat tomcat 6165 jui 8 02:23 jsr250-api.jar -rw-r--r-- 1 tomcat tomcat 68177 jui 8 02:23 resolver.jar -rw-r--r-- 1 tomcat tomcat 18817 jui 8 02:23 saaj-api.jar -rw-r--r-- 1 tomcat tomcat 274208 jui 8 02:23 saaj-impl.jar -rw-r--r-- 1 tomcat tomcat 331341 jui 8 02:23 sjsxp.jar Un redemarage de tomcat est ensuite neccessaire pour la prise en compte de ces jar. En effet, il ne s'agit pas ici de librairies gérées par le ClassLoader de tomcat, mais par le classpath de la machine virtuelle associée. 3.2 \ Configuration d'un contexte pour les webservices Comme tout contexte, la configuration principale est effectuée dans le fichier web.xml. L'exemple suivant montre les principales directives de configuration. <?xml version="1.0" encoding="utf-8"?> <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"> <display-name>addnumber</display-name> <description>addnumber</description> <listener> <listener-class>com.sun.xml.ws.transport.http.servlet.wsservletcontextlistener</listener-class> </listener> <servlet> <servlet-name>addnumber</servlet-name> <display-name>addnumber</display-name> <description>jax-ws endpoint - addnumber</description> <servlet-class>com.sun.xml.ws.transport.http.servlet.wsservlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>addnumber</servlet-name> <url-pattern>/addnumbers</url-pattern> </servlet-mapping> </web-app>
Les habitués de tomcat reconnaitront aisément les particularités de ce fichier. Tout d'abord, afin que le contexte puisse hebergé des WebService, il est neccessaire d'initialiser un listener specifique <listener> <listener-class>com.sun.xml.ws.transport.http.servlet.wsservletcontextlistener</listener-class> </listener> Ce listener est utilisé par JAX-WS pour reagir aux differents evenements de contexte, tels que les redemarrages ou les initialisations. Il s'agit d'une directive obligatoire qui permet à JAX-WS de demarer et entre autre savoir quand lire son fichier de configuration propre. Ensuite, la declaration de la servlet suivante permet d'initialiser les web services. <servlet> <servlet-name>addnumber</servlet-name> <display-name>addnumber</display-name> <description>jax-ws endpoint - addnumber</description> <servlet-class>com.sun.xml.ws.transport.http.servlet.wsservlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> Comme pour toute servlet, apparaissent le nom, la description et la classe principale, ici : <servlet-class>com.sun.xml.ws.transport.http.servlet.wsservlet</servlet-class> cette classe est presente dans les Jar installés plus haut dans le repertoire share/lib de tomcat. 3.3 \ le fichier sun-jaxws.xml le fichier sun-jaxws.xml est le fichier de configuration des web service de l'implementation sun de JAX-WS 2.0. Il contient en particulier la liste des endpoints ou WebServices disponibles dans ce contexte. Un endpoint est une adresse finale ou un service web peut être appelé. L'exemple suivant illustre la configuration : <?xml version="1.0" encoding="utf-8"?> <endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime' version='2.0'> <endpoint name='addnumberwebservice' implementation='annotations.server.addnumbersimpl' url-pattern='/addnumbers'/> </endpoints> Comme on peut le constater, un service web est defini par : un nom Le nom du service est defini par le programmeur. Il doit étre coherent une implementation L'implementation est la classe qui implemente l'interface du WebService. Cela sera etudié plus tard. une url-pattern L'url pattern est le moyen qu'utilise la servlet pour savoir quoi ecouter. Il doit étre le même que dans le web.xml afin d'eviter tout probléme.
4 \ Un premier WebService Pour debuter, nous allons voir un premier service web qui additionne deux nombres. Nous aurions pu faire un HelloWorld, mais cela n'aurait pas permis d'illustrer les avantages de JAX-WS 2.0. La création d'un service web reponds à diverses étapes importantes : Création d'une interface representant le service web. Implémentation du service web Build avec ant. Deploiement 4.1 \ L'interface AddNumber Voici l'interface AddNumber : package ws; import java.rmi.remote; import java.rmi.remoteexception; import javax.jws.webmethod; import javax.jws.webparam; import javax.jws.webresult; import javax.jws.webservice; import javax.jws.soap.soapbinding; @WebService(targetNamespace = "http://www.okeo.org", name="addnumber") @SOAPBinding(style=SOAPBinding.Style.DOCUMENT, use=soapbinding.use.literal) public interface AddNumbers extends Remote { @WebMethod(operationName="add", action="urn:addnumber") @WebResult(name="result") public int addnumbers( @WebParam(name="nb1")int number1, @WebParam(name="nb2")int number2) throws RemoteException, AddNumberException; Comme on peut le constater, l'utilisation des annotations est importante et prends enormément de place. De plus, chaque annotation neccessite des imports qui lui sont propres. Le repertoire docs de l'implementation de sun contient une documentation html des differentes annotations existantes.
Tout d'abord afin que l'interface soit reconnue comme service web, il est neccessaire d'heriter de l'interface Remote, qui signifie que les methodes seront utilisables à distance. Cette interface provient en fait de RMI qui reste toujours la base de ce type de fonctionnalités. Exemple : public interface AddNumbers extends Remote { l'annotation @WebService elle permet de specifier que l'interface est un WebService. exemple : @WebService(targetNamespace = "http://www.okeo.org", name="addnumber") targetnamespace est l'espace de nommage utilisé dans le WSDL et autres fichiers XML générés par le service. name represente le nom du service web. Ce nom doit etre le meme que dans le fichier sunjaxws.xml et corresponds au wsdl:service. l'annotation @SOAPBinding elle permet de specifier comment seront transformés les objets en xml exemple : @SOAPBinding(style=SOAPBinding.Style.DOCUMENT, use=soapbinding.use.literal) le parametre style permet de specifier le format de transformation. 2 choix sont possibles : SOAPBinding.Style.DOCUMENT : SOAPBinding.Style.RPC : Le format le plus ancien le parametre use quand à lui precise l'encodage. Seul LITERAL est possible avec JAX-WS 2.0 La declaration d'une methode est tout aussi simple dans notre cas, nous avons une methode qui permet d'additionner 2 nombres @WebMethod(operationName="add", action="urn:addnumber") @WebResult(name="result") public int addnumbers( @WebParam(name="nb1")int number1, @WebParam(name="nb2")int number2) throws RemoteException, AddNumberException; L'annotation @WebMethod permet de specifier le nom de la methode et l'action WS associée L'annotation @WebResult permet quand à elle de nommer le resultat de la methode. L'annotation @WebParam permet pour finir de nommer chaque paramétre de la methode. Concernant les exceptions, chaque methode destinée à etre une WebMethode doit permettre de propager des RemoteException. Ces exceptions permettent de prevenir les erreurs de connections diverses dues au reseau. Une seconde exception, AddNumberException à été rajoutée afin de permettre d'illustrer le fonctionnement des exceptions dans les WebService.
4.2 \ L'implementation du Service il est ensuite neccessaire d'implementer l'interface afin que le service renvoi les informations que nous desirons. Il n'y a aucune particularité ici, si ce n'est l'emploi d'une AddNumberException dans le cas ou l'un des nombres serait negatif. Cela n'a en fait aucune neccessité particuliere, mais permettra d'utiliser une exception personnalisée. La classe AddNumberImpl : package ws; import javax.jws.webservice; @WebService(endpointInterface="ws.AddNumber") public class AddNumberImpl { public int addnumber(int nb1, int nb2) throws AddNumberException { if (nb1 < 0 nb2 < 0){ throw new AddNumberException("Ne peut Ajouter des nombres negatifs", "Nombres : " + nb1 + ", " + nb2); else{ return nb1 + nb2; La classe AddNumberException : package ws; public class AddNumberException extends Exception { private static final long serialversionuid = 1L; private String detail; public AddNumberException(String message, String detail) { super(message); this.detail = detail; public String getdetail() { return detail;
4.3 \ Script Ant : le build.xml Maintenant que nous avons specifier et implementé l'interface, il va nous falloir generer et compiler les classes supplementaires neccessaire au webservice. Pour cela Ant est un très bon outil qui offre fonctionne comme un langage de scripts sequentiel, où des taches sont effectuées les unes aprés les autres. Nous allons donc utiliser l'outil APT (Annotation Processing Tool) via une tache Ant pour parcourir les classes Annotées et effectuer les operations neccessaires. Le fichier build.xml suivant est un exemple minimum pour effectuer cette operation : <?xml version="1.0" encoding="utf-8"?> <project basedir="." default="server" name="annotations"> <!-- classpath additionnel pour APT --> <path id="build.classpath"> <pathelement location="${java.home/../lib/tools.jar"/> <pathelement location="jaxws-tools.jar"/> </path> <!-- definition des taches supplementaires --> <taskdef name="apt" classname="com.sun.tools.ws.ant.apt"> <classpath refid="build.classpath"/> </taskdef> <!-- build du webservice --> <target name="server" > <apt </apt> </target> </project> fork="true" debug="${debug" verbose="${verbose" destdir="." sourcedestdir="." sourcepath="."> <classpath> <path refid="build.classpath"/> <pathelement location="."/> </classpath> <option key="r" value="."/> <source dir="."> <include name="ws/*.java"/> </source>
4.4 \ Déploiement et Accés au service Pour deployer notre service web, nous n'avons plus qu'a copier les repertoires contenant les classes compilées sur le serveur tomcat dans notre contexte. De plus nous avons aussi besoin des deux fichiers web.xml et sun-jaxws.xml ce qui nous donneras la structure suivante : WEB-INF \ - web.xml - sun-jaxws.xml - classes \ - ws \ - jaxws\ L'accés au service peut ensuite se faire via l'url du contexte en y ajoutant l'urn /addnumber Par exemple si l'addresse de votre contexte est www.okeo.org/directory/, le webservice est alors disponible a l'url suivante : http://www.okeo.org/directory/addnumber. Dans notre cas, notre premier WebService, JAX-WS 2.0 affichera donc la page suivante :
5 \ Utilisation d'un WebService Il apparaît donc que la création d'un webservice en Java devient desormais une tache extrement simple et ne neccessitant plus de se soucier des problématiques inhérentes à la création de classes de transport ou de handler XML Il nous reste maintenant à etudier la maniére dont nous pouvons acceder à ce même webservice. Dans ce chapitre nous allons donc
X \ Securisation des services Web Web Services Message Security API X \ references : http://www.w3.org/tr/wsdl http://www.w3.org/tr/soap http://www.oasis-open.org http://ant.apache.org http://jax-ws.dev.java.net JSR 175 JSR 181 JSR 109 JSR 183