Copyright © 2001-2007 Nicholas Quaine.
Home   Bases   Côté-Serveur   Côté-Client   Démos   FAQ   Ressources
Côté-Serveur
1. Vue générale
2. Déployer Tomcat
3. Déployer SOAP
4. Déployer des Services
Packages
Les versions à utiliser
Sun Java
Tomcat
Apache SOAP
JavaMail
JAF
Xerces

Précédent   1    2    3    4    Suivant
SOAP Côté-Serveur
3. Déployer l'application web SOAP (Webapp SOAP) sur Tomcat

Les étapes de quatre à huit couvrent le déploiement d'une application web Apache SOAP sur Tomcat (l'application web SOAP contient le servlet SOAP et des pages administrateur basées sur JSP que nous verrons bientôt). Ces instructions sont applicables aux systèmes d'exploitation Win32 et Unix. - Faites attention à suivre les instructions appropriées à votre système d'exploitation lorsque les sections comportent des différences entre systèmes d'exploitations.


ETAPE QUATRE Télécharger et installer Apache SOAP



  • Allez sur http://xml.apache.org/soap/index.html et téléchargez Apache SOAP pour Java (choisissez Download (Télécharger) puis version-2.2 et sélectionnez "soap-bin-2.2.zip" pour Win32 ou "soap-bin-2.2.tar.gz" pour UNIX et sauvegardez-le sur votre machine).
  • Décompactez-le dans le répertoire SOAP. L'ensemble sera contenu dans un sous-répertoire nommé soap-2_2. Assurez-vous qu'il y a un répertoire lib dans soap-2_2, et que ce répertoire lib contient un fichier appelé soap.jar - il s'agit du très important package soap.

ETAPE CINQ Télécharger et installer les bibliothèques nécessaires à Apache SOAP



  • Apache SOAP pour Java nécessite l'API JavaMail qui est à son tour dépendante du Framework Java Activation (JAF). Apache SOAP a également besoin du package Xerces (parser XML), donc nous devons le télécharger et l'installer. Les instructions sont les suivantes.
  • Allez sur http://java.sun.com/products/javamail (il s'agit de la page d'accueil de javamail), et dans la section intitulée "Download JavaMail API Implementation", sélectionnez CONTINUE, lisez et ACCEPTez la licence (si vous êtes d'accord avec les termes de celle-ci). Choisissez ensuite le site FTP approprié pour le téléchargement. Sauvegardez le fichier zip sur votre machine. Décompactez le dans le répertoire SOAP. L'ensemble sera contenu dans un sous-répertoire nommé javamail-1.2. Assurez vous que dans javamail-1.2, il y a un fichier mail.jar - il s'agit du package JavaMail que nous allons rendre disponible pour le package SOAP.
  • Allez sur http://java.sun.com/products/javabeans/glasgow/jaf.html (il s'agit de la page d'accueil JAF), sélectionnez CONTINUE pour obtenir la section de téléchargement, lisez et ACCEPTez la licence (si vous êtes d'accord avec les termes de celle-ci) puis choisissez le site FTP approprié pour le téléchargement. Sauvegardez le fichier zip sur votre machine. Décompactez-le dans le répertoire SOAP. Sauvegardez le fichier zip sur votre machine. Décompactez le dans le répertoire SOAP. L'ensemble sera contenu dans un sous-répertoire nommé jaf-1.0.1. Assurez vous que dans jaf-1.0.1, il y a un fichier appelé activation.jar - il s'agit du package JAF que nous allons rendre disponible pour le package JavaMail.
  • Allez sur http://xml.apache.org/index.html et téléchargez le package Xerces-J (choisissez Downloads (Téléchargements) puis xerces-j/ puis old_xerces1/ et selectionnez "Xerces-J-bin.1.2.3.zip" pour Win32 ou "Xerces-J-bin.1.2.3.tar.gz" pour UNIX, sauvegardez le sur votre machine). Décompactez le dans le répertoire SOAP. L'ensemble sera contenu dans un sous-répertoire nomme xerces-1_2_3. Assurez vous que dans xerces-1_2_3, il y a un fichier appelé xerces.jar - il s'agit du package Xerces package que nous allons rendre disponible pour le package SOAP.
    Avertissement : Ne choisissez pas une version plus récente de Xerces-J. La version 1.3.1 en particulier causerait des problèmes dûs à une incompatibilité avec le package Apache SOAP.

ETAPE SIX Déployer une application web SOAP Webapp sur Tomcat



  • Nous devons tout d'abord fournir à Tomcat les modules de l'application web SOAP. Sur un système Win32, copiez simplement le fichier soap.war de C:\soap\soap-2.2\webapps vers C:\soap\jakarta-tomcat-3.2.x\webapps. Sur un système UNIX, copiez simplement le fichier soap.war de /usr/me/soap/soap-2.2/webapps vers /usr/me/soap/jakarta-tomcat-3.2.x/webapps.
  • Ensuite, nous donnons à Tomcat l'accès aux fichiers jar SOAP et à ceux qui y sont liés. Pour cela, nous modifions notre script de démarrage de façon à ce qu'il ressemble à : (les nouvelles lignes sont en gras):
    Win32 script : mystartup.bat
    
      set JAVA_HOME=C:\jdk1.3.1
      set TOMCAT_HOME=C:\soap\jakarta-tomcat-3.2.x
      set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\javamail-1.2\mail.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\jaf-1.0.1\activation.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\xerces-1_2_3\xerces.jar
      %TOMCAT_HOME%\bin\startup.bat
    
    UNIX script : mystartup.sh
    
      #!/bin/sh
      JAVA_HOME=/usr/java
      export JAVA_HOME
      TOMCAT_HOME=/home/me/soap/jakarta-tomcat-3.2.x
      export TOMCAT_HOME
      CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/javamail-1.2/mail.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/jaf-1.0.1/activation.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/xerces-1_2_3/xerces.jar
      export CLASSPATH
      $TOMCAT_HOME/bin/startup.bat
    
  • Ceci est une étape importante: VOUS DEVEZ MODIFIER LE FICHIER BATCH DE DEMARRAGE DE TOMCAT (tomcat.bat sur Win32 / tomcat.sh sur UNIX). Ce fichier est appelé par startup.bat/sh qui est à son tour appelé à la fin de votre propre script de démarrage mystartup.bat/sh pour lancer Tomcat. Nous devons modifier ce script pour être sûr que les fichiers jar tomcat sont ajoutés à la fin plutôt qu'au début du classpath (défini par vous) - la raison est que le parseur xml xerces (xerces.jar) doit être prioritaire sur le parseur xml tomcat (parser.jar) pour que SOAP fonctionne correctement. Ouvrez simplement le fichier C:\soap\jakarta-tomcat-3.2.x\bin\tomcat.bat (sur Win32) or /home/me/soap/jakarta-tomcat-3.2.x/bin/tomcat.sh (sur UNIX) et modifiez la ligne comme indiqué ci-dessous:
    Win32 script : tomcat.bat
    
      .
      .
      .
      :chkClasspath
      if "%CLASSPATH%" == "" goto noClasspath
      set CP=%CP%;%CLASSPATH%
      :noClasspath
      .
      .
      .
    
    changez la ligne indiquée par des caractères gras en:
    
      set CP=%CLASSPATH%;%CP%
    
    UNIX script : tomcat.sh
    
      .
      .
      .
      if [ "$oldCP" != "" ]; then
        CLASSPATH=${CLASSPATH}:${oldCP}
      fi
      .
      .
      .
    
    changez la ligne indiquée par des caractères gras en:
    
        CLASSPATH=${oldCP}:${CLASSPATH}
    
  • Maintenant, arrêtez et redémarrez Tomcat pour que les modifications soient prises en compte. Lorsque vous redémarrez, vous devriez voir soap indiqué comme l'un des contextes de servlet configurés (aussi connus sous le nom de webapps) comme montre en gras ci-dessous:
      2001-07-04 01:35:14 - ContextManager: Adding context Ctx( /examples )
      2001-07-04 01:35:14 - ContextManager: Adding context Ctx( /admin )
      Starting tomcat. Check logs/tomcat.log for error messages
      2001-07-04 01:35:21 - ContextManager: Adding context Ctx(  )
      2001-07-04 01:35:25 - ContextManager: Adding context Ctx( /test )
      2001-07-04 01:35:29 - ContextManager: Adding context Ctx( /soap )
      2001-07-04 01:35:33 - PoolTcpConnector: Starting HttpConnectionHandler on 8080
      2001-07-04 01:35:33 - PoolTcpConnector: Starting Ajp12ConnectionHandler on 8007
    
  • Vous pouvez tester que l'application web SOAP tourne avec un browser pointant sur http://localhost:8080/soap/servlet/rpcrouter. Vous devriez voir une page avec le message suivant. Si le message apparaît, c'est que tout s'est déroulé correctement.

    SOAP RPC Router

    Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.


ETAPE SEPT Déployer un des services de démo



  • Apache SOAP est fourni avec quelques services de démo que vous pouvez déployer. Nous allons en déployer pour vérifier que tout fonctionne correctement avant d'écrire et de déployer nos propres services. Clarifions cependant quelques points avant de commencer. Premièrement, pourquoi disons nous parfois service et d'autres fois méthode de service? Pour évoquer rapidement une méthode de service, il est facile (et acceptable) de parler de service mais du point de vue d'un déployeur de serveur SOAP basé sur Apache comme vous l'êtes, ces termes sont différents. Une méthode de service est la version "Services du Web" d'une fonction (ou méthode en java). Alors qu'un service est en fait un groupe d'une ou plusieurs méthodes liées. Nous verrons clairement la différence quand nous déploierons le service de démo urn:AddressFetcher plus bas dans cette page. Deuxièmement, que voulons nous dire par "déployer un service"? Simplement, ceci correspond à déclarer au servlet SOAP une méthode de service de telle façon qu'il puisse la référencer plus tard quand le service est appelé. En d'autres termes, le servlet SOAP ne peut invoquer que des méthodes de service qu'il connaît et déployer un service est le moyen de lui faire connaître le service. Par chance, lorsque nous déployons un service, un certain fichier (nommé DeployedServices.ds) sera mis à jour avec les spécificités du service et ce fichier est lu par le servlet SOAP lors de l'initialisation, donc nous n'avons pas à redéployer à chaque fois que nous redémarrons Tomcat. Si vous voulez jeter un coup d'œil à ce fichier, vous pourrez le trouver sous le directory C:\soap\jakarta-tomcat-3.2.x\webapps\soap pour les systèmes Win-32 ou le directory /home/me/soap/jakarta-tomcat-3.2.x/webapps/soap pour les systèmes Unix - mais seulement après que vous ayez déployé un service.
  • La première chose à apprendre sur le déploiement de services est qu'il y a deux façons de le faire:
    1. La façon manuelle (pénible) est de remplir une page web et de la soumettre. La page web fait partie de l'application web SOAP et est disponible sous http://localhost:8080/soap/admin/index.html. A partir de cette page, vous pouvez lister, déployer et supprimer vos services (si vous choisissez "List", vous devriez recevoir un message annonçant qu'il n'y a pour le moment aucun service déployé). En optant pour "Deploy", vous pouvez visualiser la page web dans laquelle vous pouvez décrire au servlet SOAP un service. Ceci fonctionne bien mais le problème est qu'il faudra refaire cette manipulation à chaque fois que vous modifierez ou créerez un nouveau serveur SOAP. Il est assez évident que ce n'est pas souhaitable - vous voulez une approche plus rigoureuse pour le moment où vous mettrez votre serveur SOAP en production par exemple.
    2. La deuxième façon (meilleure) est de faire un script de déploiement. Dans ce but, les développeurs de Apache SOAP nous ont donné un utilitaire java (java org.apache.soap.server.ServiceManagerClient), qui accepte pour paramètres l'URL du servlet SOAP et un fichier XML décrivant le service (notez que le fichier XML peut en fait contenir plus qu'une unique méthode de service). Ces fichiers XML sont appelés des descripteurs de déploiement (Deployment Descriptors). Le service de démo que nous allons déployer est l'exemple addressbook et peut être trouvé dans C:\soap\soap-2_2\samples\addressbook (sur Win32) ou /home/me/soap/soap-2_2/samples/addressbook (sur UNIX). Dans ce répertoire, vous trouverez le descripteur de déploiement approprié (nom de fichier DeploymentDescriptor.xml).
  • Nous allons implémenter la seconde méthode. Créez un autre script comme ci-dessous pour lancer le déploiement concrètement (nommez le mydeployer.bat sur Win32, mydeployer.sh sur UNIX). Notez que dans le script Win32, nous ajoutons une pause à la fin de façon à pouvoir lire les messages d'erreurs éventuels. Notez également que la flèche ( ) indique que cette ligne est la continuation de la ligne précédente mais que nous avons dû la couper juste pour des raisons d'affichage à l'écran.
    Win32 script : mydeployer.bat
    
      set JAVA_HOME=C:\jdk1.3.1
      set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\javamail-1.2\mail.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\jaf-1.0.1\activation.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\xerces-1_2_3\xerces.jar
      java org.apache.soap.server.ServiceManagerClient
        http://localhost:8080/soap/servlet/rpcrouter deploy %1
      pause
    
    UNIX script : mydeployer.sh
    
      #!/bin/sh
      JAVA_HOME=/usr/java
      export JAVA_HOME
      CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/javamail-1.2/mail.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/jaf-1.0.1/activation.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/xerces-1_2_3/xerces.jar
      export CLASSPATH
      java org.apache.soap.server.ServiceManagerClient
        http://localhost:8080/soap/servlet/rpcrouter deploy $1
    
  • Nous donnons à Tomcat l'accès aux classes échantillons en ajoutant la ligne suivante (en gras) dans mystartup.bat:
    Win32 script : mystartup.bat
    
      set JAVA_HOME=C:\jdk1.3.1
      set TOMCAT_HOME=C:\soap\jakarta-tomcat-3.2.x
      set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\javamail-1.2\mail.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\jaf-1.0.1\activation.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\xerces-1_2_3\xerces.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\soap-2_2
      %TOMCAT_HOME%\bin\startup.bat
    
    UNIX script : mystartup.sh
    
      #!/bin/sh
      JAVA_HOME=/usr/java
      export JAVA_HOME
      TOMCAT_HOME=/home/me/soap/jakarta-tomcat-3.2.x
      export TOMCAT_HOME
      CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/javamail-1.2/mail.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/jaf-1.0.1/activation.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/xerces-1_2_3/xerces.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/soap-2_2
      export CLASSPATH
      $TOMCAT_HOME/bin/startup.bat
    
  • Arrêtez et redémarrez Tomcat, ce qui lui permettra de prendre en compte le nouveau classpath.
  • Une fois que Tomcat a fini son démarrage, lancez le script de déploiement en donnant le fichier descripteur de déploiement (Deployment Descriptor) comme paramètre, comme ceci:
      Win32
      > mydeployer.bat C:\soap\soap-2_2\samples\addressbook\DeploymentDescriptor.xml
    
      UNIX
      > mydeployer.sh /home/me/soap/soap-2_2/samples/addressbook/DeploymentDescriptor.xml
    
  • Une erreur très commune est signalée lors de cette étape:
      Exception in thread "main" java.lang.NoClassDefFoundError: org/w3c/dom/Node
    
    Cette erreur se produit quand xerces n'est pas avant les autres parseurs XML dans votre classpath ou si vous avez une version incompatible de xerces (1.3.1 par exemple). Si vous rencontrez cette erreur, vérifiez que vous avez modifié correctement tomcat.bat comme montré précédemment et que vous avez la version correcte de xerces comme spécifiée ci-dessus.
  • Si aucune erreur ne s'est produite, le service a été déployé avec succès. Vous pouvez le voir listé en tant que urn:AddressFetcher sur la page d'administration SOAP http://localhost:8080/soap/admin/index.html. Cliquez dessus pour visualiser les détails du déploiement que, sinon, vous auriez dû entrer à la main. Notez qu'en fait, il y a quatre méthodes de service déployées (getAddressFromName, addEntry, getAllListings et putListings) et qu'elles sont toutes groupées sous un service ou URN (Uniform Resource Name) appelé urn:AddressFetcher. Vous pouvez comparer cette URN à une façon de grouper des méthodes de service liées entre elles sous un unique nom de service. Une importante remarque est que toutes les méthodes du service sont implémentées par la même et unique classe.

ETAPE HUIT Vérifiez que le service de démo fonctionne correctement



  • C'est le moment de tester le service. Bien sûr, vous aurez besoin d'un client SOAP qui est capable de formuler une requête SOAP et de comprendre une réponse SOAP fournie par le serveur, avant que vous puissiez consommer le service que vous venez juste de déployer. Heureusement, les développeurs Apache SOAP ont justement fourni ce client (écrit en java et utilisant Apache SOAP pour les packages Java - le même package qu'on a utilisé du côté serveur). Nous allons à nouveau écrire un petit script pour faire tourner le client. Nommons-le getaddress.bat sur Win32 / getaddress.sh sur UNIX parce qu'il appellera la méthode getAddressFromName du service. Il ressemble à (notez que dans le script Win32, nous ajoutons à nouveau une pause à la fin, cette fois-ci pour lire le résultat de l'appel du service):
    Win32 script : getaddress.bat
    
      set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\javamail-1.2\mail.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\jaf-1.0.1\activation.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\xerces-1_2_3\xerces.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\soap-2_2
      java samples.addressbook.GetAddress
        http://localhost:8080/soap/servlet/rpcrouter "John B. Good"
      pause
    
    UNIX script : getaddress.sh
    
      #!/bin/sh
      CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/javamail-1.2/mail.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/jaf-1.0.1/activation.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/xerces-1_2_3/xerces.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/soap-2_2
      export CLASSPATH
      java samples.addressbook.GetAddress
        http://localhost:8080/soap/servlet/rpcrouter "John B. Good"
    

    Faites tourner le script. Vous devriez voir le résultat suivant:

      123 Main Street
      Anytown, NY 12345
      (123) 456-7890
    
  • Maintenant que votre service fonctionne, vous voulez peut-être regarder le dialogue SOAP entre le client et le serveur. Une fois encore, les développeurs Apache SOAP ont fourni un utilitaire pour le faire. Il s'appelle TcpTunnelGui et est inclus dans le package soap.jar. Le concept est le suivant: vous démarrez le tunnel, ce tunnel écoute sur un certain port les requêtes TCP/IP, les affiche à l'écran, et ensuite, les réexpédie vers le port qui traite les requêtes. Quand il reçoit la réponse, il l'envoie également à l'écran, avant de la réexpédier au client. Nous démarrons le tunnel sur le port 5555 et modifions ensuite le processus client pour qu'il adresse ses requêtes à ce port plutôt que le port 8080. Le script qui suit démarre le tunnel:
    Win32 script : tunnel.bat
    
      set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar
      java org.apache.soap.util.net.TcpTunnelGui 5555 localhost 8080
    
    UNIX script : tunnel.sh
    
      #!/bin/sh
      CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar
      export CLASSPATH
      java org.apache.soap.util.net.TcpTunnelGui 5555 localhost 8080
    

    Il n' y a plus qu'à changer votre client (getaddress.bat) pour envoyer les requêtes au port 5555 au lieu de 8080:
    Win32 script : getaddress.bat
    
      set CLASSPATH=C:\soap\soap-2_2\lib\soap.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\javamail-1.2\mail.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\jaf-1.0.1\activation.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\xerces-1_2_3\xerces.jar
      set CLASSPATH=%CLASSPATH%;C:\soap\soap-2_2
      java samples.addressbook.GetAddress
        http://localhost:5555/soap/servlet/rpcrouter "John B. Good"
      pause
    
    UNIX script : getaddress.sh
    
      #!/bin/sh
      CLASSPATH=/home/me/soap/soap-2_2/lib/soap.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/javamail-1.2/mail.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/jaf-1.0.1/activation.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/xerces-1_2_3/xerces.jar
      CLASSPATH=${CLASSPATH}:/home/me/soap/soap-2_2
      export CLASSPATH
      java samples.addressbook.GetAddress
        http://localhost:5555/soap/servlet/rpcrouter "John B. Good"
    

    Démarrez le tunnel en lançant tunnel.bat/sh, ensuite lancez getaddress.bat/sh pour appeler le service. Vous devriez voir le dialogue SOAP apparaître sur l'interface utilisateur graphique (GUI) du tunnel - un volet montre toutes les requêtes faites au port 5555, un autre montre les réponses.


Vous avez maintenant le serveur d'application Tomcat mis en marche, l'application web SOAP déployée et un service SOAP de démo opérationnel. Vous pouvez aller plus loin, déployer et tester n'importe lequel des services de démo fournis par les développeurs d'Apache SOAP. Quand vous aurez fini, la section suivante vous apprendra à écrire et déployer vos propres services.

[ Nicholas Quaine ]

Suivant

Copyright © 2001-2007 Nicholas Quaine. Tout droit reservé.