Cette section vous montre comment écrire un client SOAP en utilisant Apache SOAP pour Java. Les instructions données ici concernent les systèmes Win32 et Unix mais peuvent être adaptées à toute plate-forme applicable.

Introduction
Nous allons écrire des clients SOAP très simples qui exploitent le Service de Citations décrit et développé dans la Section 4 SOAP Côté Serveur. Si vous avez déjà parcouru le tutorial SOAP Côté Serveur, implémenté et testé le service de citations, alors vous avez déjà vu ces clients. La seule différence avec cette page est qu'il y a une explication un peu plus complète de la façon dont ils fonctionnent.

Vous pouvez incorporer le code java que vous trouvez ici dans des pages Java Server, des Servlets, des pages web opérant à partir d'applets et des clients java GUI autonomes. Mais il n'est pas dans notre intention de montrer ici des exemples détaillés de tous ces types de clients, parce que le code SOAP que vous incorporerez est, pour l'essentiel, invariable. Nous verrons donc l'essentiel au travers d' un client simplifié avec une interface utilisateur la plus dépouillée possible.

Comme c'est le cas lorsqu'on écrit des clients pour n'importe quel service SOAP, assurez vous à l'avance que vous êtes familier du service et les signatures de ses méthodes.

Nous allons construire trois clients, un pour chaque méthode du service. Les fichiers sources sont disponibles dans l'archive soapuser-1.0.zip . Si ce n'est déjà fait, sauvez ce fichier sur votre machine et extrayez le sous C:\soap [ ~/soap si vous utilisez Unix ]. Tout sera contenu dans un répertoire nommé soapuser-1.0. En particulier, les fichiers sources client java se trouvent sous soapuser-1.0\src dans une structure de répertoires qui correspond au nom du package (ie. com\soapuser\soap\client\quotation).

Vérifiez votre version de java
Dans votre IDE préféré (Interactiv Development Environment), assurez vous que vous avez JDK 1.3.0 ou plus. Si vous avez une version antérieure à 1.3, vous pouvez alors télécharger Java 1.3 gratuitement à partir de Sun Microsystems. Allez dans http://java.sun.com/j2se/1.3/, Choisissez la section de téléchargement correspondant à votre système d'exploitation dans le chapitre "Download Java 2 SDK, v 1.3.x Software...", tapez CONTINUE, lisez and ACCEPTez la license (si vous êtes d'accord avec les termes de celle-ci), ensuite, choisissez le site approprié pour le téléchargement FTP. Sauvez le fichier sur votre machine. Il s'agit d'un exécutable self-extracting (à extraction automatique). Lancez le et suivez les instructions pour extraire le package. Il se peut que vous ayez à reconfigurer votre IDE pour prendre en compte le nouveau package.

Si vous avez une version antérieure à 1.3 et que pour une raison quelconque, vous ne vouliez pas installer la 1.3 (même si deux versions Java SDK peuvent, en général, être installées en parallèle sans danger), soyez libre de continuer de toute façon mais nous ne pouvons pas garantir que ce tutorial va fonctionner dans votre cas. Certaines versions antérieures vont fonctionner mais il n'est pas dans notre intention de toutes les tester et de fournir une liste de compatibilité.

Compiler les fichiers sources
Pour développer en utilisant les fichiers source d'exemples, exécutez les étapes suivantes:

• Créer un projet dans votre IDE préféré.
• Assurez vous que le JDK utilisé pour ce projet est JDK 1.3 ou plus récent.
• Initialisez le chemin source du projet avec C:\soap\soapuser-1.0\src.
• Ajouter au projet les 3 fichiers source java dans le sous-répertoire com\soapuser\soap\client\quotation.
• Rendez disponibles les bibliothèques suivantes pour le projet. Voyez les étapes quatre et cinq dans SOAP Côté Serveur (Section 3) pour les détails sur où trouver ces packages et comment les installer sur votre machine. Note importante: Assurez vous, quelque soit le fonctionnement des priorités de votre IDE, que cet IDE emploie xerces.jar avant parser.jar dans le classpath. Voici les bibliothèques à ajouter [ remplacez C:\soap with ~/soap si vous utilisez Unix ]:
  • SOAP : C:\soap\soap-2_2\lib\soap.jar
  • JAVAMAIL : C:\soap\javamail-1.2\mail.jar
  • JAF : C:\soap\jaf-1.0.1\activation.jar
  • XERCES : C:\soap\xerces-1_2_3\xerces.jar
• Compilez le projet.

1. Obtenez la description de l'interface du service SOAP, de sorte que vous connaissiez les signatures des méthodes que vous voulez appeler.

   // Quotation[] getAllQuotations ( );
   // String[] getQuotationsByAuthor ( String author );
   // void submitQuotation ( String author, String text );
   

2. Assurez vous qu'il y a des serialiseurs enregistrés pour tous les paramètres que vous enverrez et des deserialiseurs pour toutes les informations que vous recevrez.

   // Les types standards Java (comme les entiers ou les chaînes 
   // de caractères) sont traités automatiquement. Le type 
   // complexe Quotation est enregistré en utilisant le code suivant 
   
   SOAPMappingRegistry smr = new SOAPMappingRegistry();
   BeanSerializer beanSer = new BeanSerializer();
   smr.mapTypes(Constants.NS_URI_SOAP_ENC,
                new QName("urn:QuotationService", "quotation"),
                Quotation.class, beanSer, beanSer);
   

3. Créez l'objet org.apache.soap.rpc.RPCMessage.Call .

   // Notez que nous devons aussi lui linker l'objet 
   // SOAPMappingRegistry et déclarer le style d'encodage 
   // (initialisé ici avec l'encodage standard de SOAP) 
   
   Call call = new Call();
   call.setSOAPMappingRegistry(smr);
   call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
   

4. Fixez la valeur de la cible URI dans l'objet Call en utilisant la fonction setTargetObjectURI(...).

   call.setTargetObjectURI("urn:QuotationService");
   

5. Fixez le nom de la méthode que vous désirez appeler dans l'objet Call en utilisant la fonction setMethodName(...).

   call.setMethodName("getQuotationsByAuthor");
   

6. Créez tous les objets Paramètres nécessaires à l'appel RPC et fixez leurs valeurs dans l'objet Call en utilisant la fonction setParams(...).

   // Les paramètres sont rangés dans un vecteur - pour 
   // envoyer plus d'un paramètre, continuez juste à 
   // appeler addElement (comme vous pouvez le voir 
   // dans le client SubmitQuotation). 
   
   Vector params = new Vector();
   params.addElement(new Parameter("Author", String.class,
                                   "Wilde, Oscar", null));
   call.setParams(params);
   

7. Exécutez la méthode invoke(...) de l'objet Call et capturez l'objet Response qui est retourné par invoke(...). La méthode invoke(...) reçoit deux paramètres, l'un étant une URL qui identifie l'hôte chez qui le service réside, l'autre étant la valeur à placer dans l'en-tête SOAPAction (peut être vide).

   // Notez que si le système déclenche une SOAPException,  
   // cela signifie que nous avons une erreur côté client 
   // (pas du côté serveur) 
   
   Response resp;
   try
   {
       resp = call.invoke(
         "http://localhost:8080/soap/servlet/rpcrouter", "");
   }
   catch (SOAPException e)
   {
       System.err.println("Caught SOAPException (" +
         e.getFaultCode() + "): " + e.getMessage());
       return;
   }
   

8. Vérifiez l'objet Response pour voir si une erreur n'a pas été générée en utilisant la fonction generatedFault().

   if (!resp.generatedFault())
   

9. Si une erreur a été retournée, récupérez la en utilisant la fonction getFault(...), sinon, extrayez le résultat ou les paramètres retournés en utilisant les fonctions getReturnValue() et getParams() respectivement.

   if (!resp.generatedFault())
   {
       Parameter ret = resp.getReturnValue();
       Object value = ret.getValue();
       if ( value != null )
       {
           String[] tlist = (String[])value;
           System.out.println();
           for ( int i = 0; i < tlist.length; i++ )
               System.out.println(tlist[i]);
       }
   }
   else
   {
       Fault fault = resp.getFault();
       System.err.println("Generated fault: ");
       System.out.println ("  Fault Code   = "
   	                    + fault.getFaultCode());
       System.out.println ("  Fault String = "
   	                    + fault.getFaultString());
   }
   

  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\soapuser-1.0\classes
  java com.soapuser.soap.client.quotation.GetAllQuotations
    http://localhost:8080/soap/servlet/rpcrouter
  java com.soapuser.soap.client.quotation.SubmitQuotation
    http://localhost:8080/soap/servlet/rpcrouter
    "Kennedy, John F." "Forgive your enemies, but never forget their names."
  java com.soapuser.soap.client.quotation.GetQuotationsByAuthor
    http://localhost:8080/soap/servlet/rpcrouter "Wilde, Oscar"
  pause

  #!/bin/sh
  CLASSPATH=~/soap/soap-2_2/lib/soap.jar
  CLASSPATH=${CLASSPATH}:~/soap/javamail-1.2/mail.jar
  CLASSPATH=${CLASSPATH}:~/soap/jaf-1.0.1/activation.jar
  CLASSPATH=${CLASSPATH}:~/soap/xerces-1_2_3/xerces.jar
  CLASSPATH=${CLASSPATH}:~/soap/soapuser-1.0/classes
  export CLASSPATH
  java com.soapuser.soap.client.quotation.GetAllQuotations
    http://localhost:8080/soap/servlet/rpcrouter
  java com.soapuser.soap.client.quotation.SubmitQuotation
    http://localhost:8080/soap/servlet/rpcrouter
    "Kennedy, John F." "Forgive your enemies, but never forget their names."
  java com.soapuser.soap.client.quotation.GetQuotationsByAuthor
    http://localhost:8080/soap/servlet/rpcrouter "Wilde, Oscar"

Notez que le script présenté ici présume que le service "Quotation" (de citation) s'exécute sur votre machine (sur localhost:8080). Si ce n'est pas le cas, vous pouvez exécuter ces clients par rapport à notre serveur SOAP de démonstration. Pour cela, remplacez simplement localhost:8080 par services.xmethods.net dans le script ci-dessus. Pour plus d' information sur notre serveur de démonstration, référez vous à la Section de Démo.

Conclusion
Notez qu'il y a beaucoup de détails codés en dur dans le client, qui sont des copies des informations présentées dans le deployment descriptor. Si vous avez accès au deployment descriptor du côté client, vous voulez sans doute jeter un coup d'œil à cet article sur comment simplifier le source côté client et éviter de telles répétitions de code.