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.

• 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.

• 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.

• 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.