Invocation D'un Service Web avec PL - Trivadis

Objet : Invocation d'un service web avec PL/SQL – Partie 2
Auteur : Christine Hansen, Fabrizio Fresco, Patrick Malcherek
Nature des informations : Informations à caractère technique (octobre 2002)
Source : http://otn.oracle.com/
Introduction
Si la première partie de notre article était uniquement consacrée à la théorie des services web,
la deuxième partie expliquera comment utiliser de façon pratique les services web disponibles
sur Internet. Pour cela, nous verrons comment procède Oracle PL/SQL pour interroger ce type
de services. Compte tenu de ce que nous avons appris sur Oracle dans la première partie, nous
pouvons d'ores et déjà supposer que les services web se conçoivent comme une extension
moderne des applications traditionnelles.
Notre exemple, emprunté au site Oracle TechNet, est à la portée de chaque développeur
PL/SQL. Nous pourrons l'adapter en toute simplicité pour pouvoir interroger nos propres
services web, ou ceux d'autres fournisseurs.
Les parties 3 et 4 de l'article nous apprendront à programmer nos propres services web, et nous
présenterons les conditions requises pour une telle programmation.
1. Conditions requises
La première condition nécessaire à la réalisation de notre exemple est une base de données
Oracle 9i créée sous la version Release 2 (9.2.0.1). Cette condition est importante car nous
devrons exploiter certaines caractéristiques propres à Oracle 9i Release 2, notamment le
nouveau type de données XMLTYPE ainsi que les fonctions spéciales du package UTL_HTTP. Le
compte utilisé dans notre exemple sera celui d'un utilisateur standard nommé SCOTT ; le mot
de passe de ce compte sera TIGER. Les codes, les tables et les vues seront créés sous ce compte.
Bien entendu, il nous faudra également une connexion à Internet, puisque nous devrons
invoquer le service web désiré à partir d'un site publié sur le Net.
La version actuelle de la base de données Oracle peut être téléchargée en version d'évaluation
sur le site Oracle TechNet. Le code de notre exemple est à votre disposition dans la zone de
téléchargement du site Trivadis.
2. Technique
Dans la première partie de notre article, nous avons évoqué en détail l'architecture générale des
services web, qui nous est à présent familière. Abordons maintenant les techniques spécifiques
associées au langage PL/SQL.
2.1. Principes de base
Pour invoquer un service web, nous devons envoyer un message SOAP : la Requête. Le
service web délivre en retour un autre message SOAP contenant les résultats attendus : la
Réponse. SOAP (Simple Object Access Protocole) est un mécanisme conçu pour expédier
des messages standardisés, contenant des données structurées au format XML.

Dans le cas d'une invocation de service web, SOAP exécute un appel de procédure à
distance, ou Remote Procedure Call (RPC). Cette méthode est la plus largement répandue
(sauf dans l'environnement .NET qui exploite principalement des messages de type
Document).
Pour un meilleur suivi de notre exposé sur le code PL/SQL, nous vous conseillons de
reproduire dès maintenant la requête envoyée ainsi que la réponse retournée.
Outgoing SOAP Message
94065
Return SOAP Message
7/7/2002 9:05:42 PM
Listing 1 - Requête et Réponse SOAP
2.2. Types de données
Pour créer des requêtes et des réponses en PL/SQL, il est nécessaire de les enregistrer avec
des types de données abstraits.
Pour cela, nous devons commencer par créer le type de données request en tant
qu'enregistrement (Record) de plusieurs variables.

TYPE request IS RECORD (
method VARCHAR2(256),
namespace VARCHAR2(256),
body VARCHAR2(32767));
Listing 2 - Définition du type de données request
Nous devons ensuite définir le type de données de la réponse. Pour cela, nous utiliserons le
nouveau type de données XMLTYPE qui offre l'avantage d'être idéalement adapté aux
contraintes des documents XML. Oracle 9i présente une multitude de caractéristiques
permettant une exploitation très efficace du langage XML. Pour en apprendre davantage sur
le type de données XMLTYPE, n'hésitez pas à consulter la documentation Oracle9i
XMLType.
TYPE response IS RECORD (doc xmltype);
Listing 3 - Définition du type de données response
2.3. Création du Corps SOAP
Abordons maintenant la création du message SOAP et commençons tout naturellement par
son élément noyau : le Corps (body). Le fondement d'un RPC repose dans la création d'une
méthode et de différents paramètres.
Le listing ci-dessous contient le package demo_soap dont deux composants permettent
justement de créer ces éléments :
La fonction new_request permet d'assembler facilement l'objet req à partir des paramètres
délivrés.
La procédure add_parameter permet de visualiser une nouvelle fois la requête du listing 1,
afin de mieux comprendre de quelle façon elle est assemblée. Dans un message SOAP de
type RPC, il est nécessaire de définir les types de données des arguments délivrés en
respectant le schéma XML. C'est justement ce que fait la procédure add_parameter en
créant la définition correspondante à partir des paramètres qui lui sont transmis.
FUNCTION new_request(method IN VARCHAR2, namespace IN
VARCHAR2) RETURN request AS
req request;
BEGIN
req.method := method;
req.namespace := namespace;
RETURN req;
END;
PROCEDURE add_parameter(req IN OUT NOCOPY request,
name IN VARCHAR2, type IN VARCHAR2, value IN VARCHAR2) AS
BEGIN
req.body := req.body ||
''||value||'';
END;
Listing 4 - Méthodes de création de la requête SOAP
Pour créer la requête, ces deux composants sont appelés à l'intérieur du pack time_service
dans lequel ils reçoivent les paramètres requis.

eq := demo_soap.new_request('LocalTimeByZipCode',
'xmlns="http://www.alethea.net/webservices/"');
demo_soap.add_parameter(req, 'ZipCode', 'xsd:string', zipcode);
Listing 5 - Appel dans le package time_service
2.4. Création de l'Enveloppe SOAP
Avant de pouvoir expédier le message SOAP, il nous faut encore créer son Enveloppe. Cette
enveloppe se compose d'un En-tête standard (voir le listing 1), inscrit dans le message avant
le Corps. Le message SOAP peut contenir plusieurs En-têtes identiques pour appeler des
services web différents. Comme le montre le listing ci-dessous, il n'existe que trois éléments
variables pouvant être insérés dans l'En-tête du message. Et nous venons justement de voir
comment créer ces éléments.
PROCEDURE generate_envelope(req IN OUT NOCOPY request, env IN OUT
NOCOPY VARCHAR2) AS
BEGIN
env := '
'||
req.body||'';
END;
Listing 6 - Procédure de création d'une Enveloppe SOAP
2.5. Invocation d'un service web
Maintenant que notre message SOAP est composé, nous devons l'envoyer par HTTP à
l'adresse (URL) du service web désiré. Pour cela, nous utiliserons la fonction invoke,
présentée dans le listing 7.
Afin de pouvoir échanger des informations avec Internet, à partir de la base de données,
nous aurons recours au package UTL_HTTP d'Oracle qui intègre une gamme complète de
fonctions et de procédures permettant d'assembler, d'expédier et de réceptionner des
messages SOAP. Pour obtenir des informations détaillées sur le package UTL_HTTP, vous
pouvez consulter la documentation Oracle9i Database Release 2 disponible sur le site
d'Oracle.
Attardons-nous un instant sur la fonction sollicitée.
Dans la configuration de l'en-tête HTTP (lignes 8 à 11), il est nécessaire de définir le type du
message ainsi que le type de son contenu. Dans le cas présent, le message est de type post
tandis que son contenu est de type text/xml. La fonction write_text (ligne 12) est utilisée en
complément pour envoyer la requête HTTP contenant le message SOAP. Le contenu du
message est alors inclus dans la variable env qui est associée à la fonction en tant que
paramètre. Dès que le service web délivre une réponse, celle-ci est réceptionnée par la
fonction get_response et inscrite dans la variable env (lignes 14 à 16). Cette variable est
ensuite copiée dans l'enregistrement resp de type response (voir le listing 3). Le type
response contient le champ doc de type XMLTYPE ; ce type (XMLTYPE) permet au
développeur d'extraire le Corps de l'Enveloppe en toute simplicité (voir aussi la
documentation Oracle9i XMLType).

1 FUNCTION invoke(req IN OUT NOCOPY request, url IN VARCHAR2,
action
IN VARCHAR2) RETURN response AS
2 env VARCHAR2(32767);
3 http_req utl_http.req;
4 http_resp utl_http.resp;
5 resp response;
6 BEGIN
7 generate_envelope(req, env);
8 http_req := utl_http.begin_request(url, 'POST');
9 utl_http.set_header(http_req, 'Content-Type', 'text/xml');
10 utl_http.set_header(http_req, 'Content-Length',
length(env));
11 utl_http.set_header(http_req, 'SOAPAction', action);
12 utl_http.write_text(http_req, env);
13
14 http_resp := utl_http.get_response(http_req);
15 utl_http.read_text(http_resp, env);
16 utl_http.end_response(http_resp);
17
18 resp.doc := xmltype.createxml(env);
19
20 resp.doc :=
resp.doc.extract('/soap:Envelope/soap:Body/child::node()',
21 'xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"');
22
23 check_fault(resp);
24 RETURN resp;
25 END;
Listing 7 - Invocation du service web à l'aide du package UTL_HTTP
La ligne 23 nous indique qu'une autre procédure – check_fault – a été appelée à l'intérieur
du package. Là encore, le type de données XMLTYPE est essentiel car la procédure
check_fault exécute une requête XPath (requête à l'intérieur du code XML) dans le contenu
de la réponse, afin de détecter si le service web a éventuellement retourné une quelconque
erreur. S'il est vrai qu'une requête sous forme de boucle PL/SQL (exploitant une variable
VARCHAR) aurait pu s'appliquer de la même façon, notre variante offre toutefois l'avantage
majeur de se limiter à une seule ligne de code. Si la procédure détecte une ou plusieurs
erreurs, celles-ci sont extraites et affichées dans quelques lignes de code supplémentaires,
en tant de fault_code et fault_string.
PROCEDURE check_fault(resp IN OUT NOCOPY response) AS
fault_node xmltype;
fault_code VARCHAR2(256);
fault_string VARCHAR2(32767);
BEGIN
fault_node := resp.doc.extract('/soap:Fault',
'xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/');
IF (fault_node IS NOT NULL) THEN
fault_code :=
fault_node.extract('/soap:Fault/faultcode/child::text()',
'xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/').ge
tstringval();

fault_string :=
fault_node.extract('/soap:Fault/faultstring/child::text()',
'xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/').ge
tstringval();
raise_application_error(-20000, fault_code || ' - ' ||
fault_string);
END IF;
END;
Listing 8 - Traitement des erreurs SOAP
Le listing 9 contient l'appel du service web par la fonction invoke :
resp := demo_soap.invoke(req,
'http://www.alethea.net/webservices/LocalTime.asmx',
'http://www.alethea.net/webservices/LocalTimeByZipCode');
Listing 9 - Invocation du service web LocalTimeByZipCode
2.6. Présentation finale du résultat
Traiter le document XML à l'aide de la fonctionnalité XMLTYPE permet d'économiser un
temps précieux. Toutefois, si le résultat délivré par le service web se révèle être une simple
chaîne (string), il est alors judicieux d'utiliser une autre fonction auxiliaire pour gérer le
traitement de cette chaîne et sa présentation finale (voir le listing 10). La fonctionnalité
XMLTYPE XPath est alors des plus utiles, encore une fois.
FUNCTION get_return_value(resp IN OUT NOCOPY response, name IN
VARCHAR2, namespace IN VARCHAR2) RETURN VARCHAR2 AS
BEGIN
RETURN resp.doc.extract('//'||name||'/child::text()',
namespace).getstringval();
END;
Listing 10 - Lire la chaîne de résultat dans le message SOAP
Le listing 11 présente de quelle manière la réponse SOAP est transmise à la fonction
get_return_value pour en extraire la chaîne VARCHAR.
RETURN demo_soap.get_return_value(resp,
'LocalTimeByZipCodeResult',
'xmlns="http://www.alethea.net/webservices/"');
Listing 11 - Transfert de la réponse SOAP
3. Exécution de l'exemple
Pour réaliser soi-même l'exemple de notre article, il suffit de suivre quelques étapes très
simples.
Pour commencer, exécutez le script demosoap.sql dans SQL*Plus, afin de créer le package
demo_soap mentionné précédemment.
Le listing 12 affiche le package time_service contenant le code nécessaire à l'exécution du
service web LocalTimeByZipCode. Les étapes présentées ci-dessous sont analogues aux étapes
développées dans les paragraphes précédents : l'appel de la fonction demo_soap.new_request

permet d'abord de créer la requête SOAP avec le nom des méthodes et l'espace de noms
correspondants. Puis, la fonction demo_soap.add_parameter transmet les paramètres que le
service web réceptionne. La fonction demo_soap.invoke peut dès lors invoquer le service web.
Pour finir, le résultat est retourné par l'intermédiaire de la fonction
demo_soap.get_return_value.
CREATE OR REPLACE PACKAGE time_service AS
FUNCTION get_local_time(zipcode IN VARCHAR2) RETURN
VARCHAR2;
END;
/
CREATE OR REPLACE PACKAGE BODY time_service AS
-- Location of Web service definition
-- http://www.alethea.net/webservices/LocalTime.asmx?WSDL
FUNCTION get_local_time(zipcode IN VARCHAR2) RETURN VARCHAR2
IS
req demo_soap.request;
resp demo_soap.response;
BEGIN
req := demo_soap.new_request('LocalTimeByZipCode',
'xmlns="http://www.alethea.net/webservices/"');
demo_soap.add_parameter(req, 'ZipCode', 'xsd:string',
zipcode);
resp := demo_soap.invoke(req,
'http://www.alethea.net/webservices/LocalTime.asmx',
'http://www.alethea.net/webservices/LocalTimeByZipCode');
RETURN demo_soap.get_return_value(resp,
'LocalTimeByZipCodeResult',
'xmlns="http://www.alethea.net/webservices/"');
END;
BEGIN
/* * If the Web service resides outside of the firewall, we would need to
* set the proxy in the current session before invoking the service.
*/
-- utl_http.set_proxy('www-your-proxy', NULL);
utl_http.set_persistent_conn_support(TRUE);
END;
Listing 11 - Package time_service
La fonction SET_PROXY du package UTL_HTTP ne doit être appelée que si la configuration de
l'accès Internet requiert l'utilisation d'un proxy. Si la connexion de l'utilisateur fonctionne
indépendamment d'un quelconque proxy, cette ligne peut être désactivée (elle l'est d'ailleurs
par défaut dans le code d'exemple).
Pour réaliser volontairement plusieurs invocations successives du service web, pensez à régler
le paramètre SET_PERSISTENT_CONN_SUPPORT sur TRUE. Ce paramètre empêche la

fermeture systématique de la connexion réseau et permet, par conséquent, d'améliorer la
performance de la procédure en cas d'invocations multiples. Le bénéfice est considérable si
vous invoquez souvent les mêmes services web ou si vous gérez de très nombreux utilisateurs.
Pour démarrer le service web la première fois, exécutez entièrement le script local.sql dans
SQL*Plus. Si le package time_service a déjà été créé de cette façon, vous pouvez utiliser la
variante simple de l'appel dans SQL*Plus, comme indiqué dans le listing 12.
SET serveroutput ON
exec dbms_output.put_line(time_service.get_local_time('94065'));
Listing 12 - Appel dans SQL*Plus
Résumons
Comme nous venons de le constater, il est très facile d'invoquer un service web existant par
l'intermédiaire d'Oracle PL/SQL. L'exemple que nous avons développé peut d'ailleurs servir de
modèle à l'invocation d'autres services web de type similaire.
Sur le site TechNet d'Oracle, vous trouverez un autre exemple exploitant lui aussi le package
central demo_soap. Les développeurs PL/SQL pourront utiliser cet exemple comme structure de
base de leur syntaxe SOAP, qui se distinguera uniquement par l'appel du service recherché.
Il n'est pas difficile d'imaginer qu'à l'avenir les applications basées sur Oracle (les formulaires
web, par exemple) trouveront d'avantageuses extensions dans la mise en œuvre des services
web.
Christine Hansen, Fabrizio Fresco et Patrick Malcherek
Trivadis GmbH E-mail : christine.hansen@trivadis.com
Cityforum à Eichsfeld fabrizio.fresco@trivadis.com
Ferdinand-Stuttmann-Str. 13 patrick.malcherek@trivadis.com
D-65428 Rüsselsheim Tél. : +49 6142 210 18 0
Internet : http://www.trivadis.com Fax : +49 6142 210 18 29