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

Introduction
Nous allons écrire un client SOAP très simple qui va exploiter le Quotation Service décrit et développé dans la Section 4 de SOAP Côté Serveur.

Bien sûr, vous pouvez incorporer le code perl que vous trouvez ici dans vos pages web CGI mais il n'est pas dans notre intention de fournir des exemples de ce genre parce que le code en relation avec SOAP que vous incorporerez est, pour l'essentiel, invariable. Nous verrons donc l'essentiel au travers d'un client simplifié avec l'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 des signatures de ses méthodes.

Nous allons construire trois clients, un pour chaque méthode du service.

Installer Perl et les modules Perl requis [ pour Win32 ]
Comme les installations sont différentes pour les systèmes Win32 et Unix, elles sont traitées séparément. Les instructions pour Unix sont plus bas dans la page..

Le moyen le plus simple, et de loin, est de partir de rien (c-à-d sans installation antérieure de Perl) et d'installer la dernière version de ActivePerl (5.6.1 ou plus) à partir de ActiveState.com. Pour le faire, allez simplement sur leur domaine de téléchargement, choisissez le package Windows/MSI et sauvez le sur votre machine. Vous allez alors avoir un fichier Microsoft Installer (msi) nommé ActivePerl-5.6.1.628-MSWin32-x86-multi-thread.msi (le numéro de version peut changer).

Si vous ne pouvez partir de rien parce que ActivePerl est déjà installé, et que la version est antérieure à 5.6.1, ou parce qu'une autre installation Perl existe, vous pouvez essayer l'une des méthodes suivantes:

• Mettez à jour votre version d'ActivePerl avec la 5.6.1 (téléchargez et installez comme décrit pour une installation nouvelle).
• Laissez votre vieille version d'ActivePerl comme elle est. Ensuite, avec ppm, vérifiez que vous avez les modules comme indiqué ci-dessous (ignorez les numéros de version pour le moment). Installez ceux que vous n'avez pas et essayez de compléter le tutorial. Si ça ne fonctionne pas, mettez à jour avec la version 5.6.1.
• Installez ActivePerl à côté de l'installation Perl non ActivePerl. Vous devrez soit modifier votre chemin pour être sûr que ActivePerl est choisi en premier quand vous tapez 'perl', soit taper le chemin de l'exécutable d'ActivePerl en entier quand vous voudrez exécuter le client SOAP plus tard au cours de ce tutorial.

Lancez le programme d'installation en double-cliquant sur le fichier msi téléchargé. Suivez les instructions pour installer ActivePerl sur votre machine. Si vous acceptez toutes les options par défaut, alors tout sera installé sous C:/Perl (d'autres répertoires de destination sont acceptables mais notez que les chemins mentionnés ci-après se basent sur le répertoire par défaut).

Heureusement, cette installation inclut tous les modules Perl nécessaires pour écrire des clients Perl qui exploitent SOAP::Lite for Perl. Pour vérifier que vous avez bien tous les modules requis, ouvrez une fenêtre de commande et exécutez le Perl Package Manager (PPM) avec la commande suivante (notez qu'il faut être connecté à internet pour que cela fonctionne).

  > ppm

  PPM interactive shell (2.1.5) - type 'help' for available commands 
  PPM>

Une fois que PPM fonctionne, tapez la commande suivante pour voir la liste des packages installés:

  PPM> query

  Archive-Tar      [0.072  ] module for manipulation of tar archives.
  Compress-Zlib    [1.08   ] Interface to zlib compression library
  Digest-MD5       [2.11   ] Perl interface to the MD5 Algorithm
  File-CounterFile [0.12   ] Persistent counter class
  Font-AFM         [1.18   ] Interface to Adobe Font Metrics files
  HTML-Parser      [3.19   ] SGML parser class
  HTML-Tagset      [3.03   ] Data tables useful in parsing HTML
  HTML-Tree        [3.11   ] HTML syntax tree builder
  MIME-Base64      [2.11   ] Encoding and decoding of base64 strings
  PPM              [2.1.5  ] Perl Package Manager: locate, install, upgrade
                             software packages.
  SOAP-Lite        [0.46   ] Library for Simple Object Access Protocol (SOAP)
                             clients and servers in Perl
  URI              [1.11   ] Uniform Resource Identifiers (absolute and relative)
  XML-Parser       [2.27   ] A Perl module for parsing XML documents
  libnet           [1.07.03] Collection of Network protocol modules
  libwin32         [0.17.2 ] A collection of extensions that aims to provide
                             comprehensive access to the Windows API.
  libwww-perl      [5.51   ] Library for WWW access in Perl

L'installation Win32 est donc terminée. Si vous ne voulez pas installer Perl et les modules Perl nécessaires sur un système Unix, vous pouvez sauter les paragraphes suivants et aller directement dans Comprendre le Code Client .

Installer Perl et les Modules Perl requis[ pour Unix ]
Vous aurez besoin de Perl 5.004 ou plus récent. Il n'est pas totalement exclus que perl soit déjà installé sur votre système UNIX (Perl 5.005_03 est livré avec Solaris 8 par exemple). Tapez "perl -v" dans une ligne de commande pour vérifier que perl est installé et voir sa version en même temps. Si avez besoin d'installer ou de mettre à jour perl, alors, un lien vers une installation téléchargeable de Perl correspondant à votre système peut être trouvé sur CPAN Binary Distributions. Trouvez le site de téléchargement approprié à votre système et téléchargez le fichier d'installation. Suivez les instructions qui viennent avec le package (elles différent selon les systèmes et nous ne pouvons fournir aucune aide ici).

Une fois que perl est installé, vous aurez aussi besoin d'installer les packages suivants. Les versions montrées ici ne sont pas strictement exigées bien que ce soient les versions que nous avons testées et confirmées, c'est pourquoi nous vous recommandons d'utiliser ces versions ou des plus récentes. Si vous n'avez aucune expérience en matière d'installation des Modules Perl, alors lisez SVP les notes d'installation ci-dessous avant de commencer.

• HTML-Tagset [3.03]
• Digest-MD5 [2.16]
• HTML-Parser [3.25]
• IO [1.20]
• libnet [1.0704]
• MIME-Base64 [2.12]
• URI [1.16]
• libwww-perl [5.53_96]
• expat (C Package) [1.95.2]
• XML-Parser [2.30]
• SOAP-Lite [0.51]

Notes d'installation : Installer les modules perl demande parfois un peu de ruse - voici quelques trucs pour vous aider à éviter ou au moins à surmonter certains obstacles. Internet abonde de FAQs sur les nombreux risques non traités ici.

• Faites les installations dans l'ordre où elles apparaissent ci-dessus de façon à ce que les tests associés à l' installation de chaque module fonctionnent correctement.
• Exécuter toutes les installations en tant que utilisateur root.
• Vous aurez besoin d'un compilateur standard (comme gcc) installé avant d'installer les modules. Si vous n'avez pas un tel compilateur, alors un lien vers un programme d'installation gcc téléchargeable peut être trouvé sur gnu.org.
• Pour chaque installation, Téléchargez l'archive, décompactez la à un endroit pratique, lisez le fichier README qui se trouve dans le répertoire qui vient d'être créé. Typiquement, vous serez chargé d'accomplir les instructions suivantes:-

    > perl Makefile.PL
    > make
    > make test
    > make install
  

  La première commande "perl Makefile.PL" va créer un Makefile. Si vous utilisez gcc comme compilateur, il se peut que vous ayez à modifier le Makefile pour éviter des erreurs de compilation. En particulier, changez l'option "-KPIC" en "-fPIC" et effacez tous les flags d'optimisation (tels que "-x03 -xdepend")
• L'exception à la règle est le package expat qui un package c (et non perl). Le fichier README dans ce cas vous chargera de d'exécuter les commandes suivantes:-

    > ./configure
    > make
    > make install
  

Comprendre le Code Client
Comme vous le verrez, le code Perl pour appeler un service est extrêmement laconique. Ci-dessous se trouve une liste des étapes à suivre et un bout de code tiré de getAllQuotations.pl, qui est presenté au complet un peu plus loin.

• Declarez l'utilisation de SOAP::Lite package

    use SOAP::Lite;

• Definissez le service

    $service = SOAP::Lite -> uri('urn:QuotationService')
                 -> proxy('http://localhost:8080/soap/servlet/rpcrouter');

• Invoquer la méthode du service et sauvegarder le résultat. Notez qu'en Perl, il n'y a que trois types de données : scalars (scalaires), arrays (tableaux) et hashes (tables de hachage) (et des combinaisons de ceux-ci) et que le résultat d'un appel SOAP sera l'un d'entre eux. Les types complexes seront retournés sous forme de tables de hachage, les tableaux sous forme de tableaux et les types primitifs sous forme de scalaires.

    $result = $service -> getAllQuotations() -> result();

• Parcourez et interprétez votre résultat selon son type. Vous aurez besoin de connaître le type de la valeur de retour pour le faire. Dans le cas de GetAllQuotations, nous savons que le type de la valeur de retour est un tableau d'objets Quotation (c-à-d . un tableau de types complexes), et conformément à la règle établie, il nous sera retourné sous la forme d'un tableau de tables de hachage. Nous pouvons donc parcourir le résultat comme suit:

    $i = -1;
    while ( ref $result->[++$i] )
    {
      print "$result->[$i]{'text'} ($result->[$i]{'author'})\n";
    }

Ecrire les Clients
Voici le code source pour les trois clients (le code est identique pour les systèmes Win32 et UNIX). Notez qu'il n'y a pas de valeur de retour pour la méthode du service submitQuotation donc nous ne mémorisons ni n'interprétons un résultat.

getAllQuotations.pl

use SOAP::Lite; $service = SOAP::Lite -> uri('urn:QuotationService') -> proxy('http://localhost:8080/soap/servlet/rpcrouter'); $result = $service -> getAllQuotations() -> result(); $i = -1; while ( ref $result->[++$i] ) { print "$result->[$i]{'text'} ($result->[$i]{'author'})\n"; }

submitQuotation.pl

use SOAP::Lite; $service = SOAP::Lite -> uri('urn:QuotationService') -> proxy('http://localhost:8080/soap/servlet/rpcrouter'); $service -> submitQuotation('Kennedy, John F.', 'Forgive your enemies, but never forget their names.');

getQuotationsByAuthor.pl

use SOAP::Lite; $service = SOAP::Lite -> uri('urn:QuotationService') -> proxy('http://localhost:8080/soap/servlet/rpcrouter'); $result = $service -> getQuotationsByAuthor('Wilde, Oscar') -> result(); $i = -1; while ( $result->[++$i] ) { print "$result->[$i]\n"; }

Notez que les scripts perl présentés ici assume que le Service de Citations tourne 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.

Exécuter les Clients
Dans une ligne de commande, allez dans le répertoire dans lequel vous avez créé les scripts ci-dessus et tapez les commandes suivantes (ceci présume que le binaire perl est quelque part dans votre chemin):

  > perl getAllQuotations.pl
  > perl submitQuotation.pl
  > perl getAllQuotations.pl
  > perl getQuotationsByAuthor.pl

Conclusion
La simplicité du client Perl est la preuve de l'élégance de ce package Perl. Notez comment nous pouvons appeler le service presque comme si une fonction était définie localement, sans jamais avoir à déclarer le nom de la méthode. C'est une caractéristique puissante de SOAP::Lite for Perl.