Service Web - Client

Depuis la V6R1 de l’OS (V5R4 avec PTF), il est possible d’appeler (consommer) un service web depuis un programme ILE. Pour ceci, IBM fourni un client de service web.

1. Pré-requis

Produit	5.4	6.1
ILE C++ - Compilateur C++ (*)	5722WDS - 52	5761WDS - 52
ILE C - Compilateur C	5722WDS - 51	5761WDS - 51
Java Developer Kit 1.4	5722JV1 - 6	5761JV1 - 6
Digital Certificate Manager (pour le GSKit – Global Security Kit)	5722SS1 - 34	5761SS1 - 34

(*) Uniquement pour utilisation du langage C++ en tant que client du service web. Inutile si vous travaillez en langage procédural comme RPG ou COBOL.

Pour vérifier ces éléments : GO LICPGM puis option 10 « Affichage des logiciels sous licence installés »

2. Principe

Le produit est installé dans l’IFS : \QIBM\ProdData\OS\WebServices\V1\client\

Le produit embarque les éléments suivants :

- La librairie AXIS (http://ws.apache.org/axis/cpp/index.html) de la fondation APACHE. Cette librairie Open Source contient toutes les fonctions nécessaires à l’appel d’un service web : prise en charge du protocole SOAP et de la couche de transport HTTP.

- Une commande shell qui permet de générer les stubs (ensemble des éléments nécessaires à la connexion et à l’appel du service web) en langage C ou C++

C’est ensuite au développeur d’utiliser les stubs générés dans un programme RPG ILE.

Vous trouverez directement sur l’IFS de votre machine différents éléments :

- Le Red Book du produit : \QIBM\ProdData\OS\WebServices\V1\client\docs\WebServicesClient.pdf

- Restrictions techniques : \QIBM\ProdData\OS\WebServices\V1\client\readme.txt

- Documentation Axis : \QIBM\ProdData\OS\WebServices\V1\client\docs\api\index.html

Remarque :

Une connaissance des éléments suivants est un avantage : IFS, procédure ILE, pointeur en RPG, syntaxe C.

Exemple 1 : conversion de température

Nous allons appeler le service web suivant dans un programme RPG ILE.

Ce service permet de convertir une température de Fahrenheit en Celsius, il est fourni par IBM en exemple, le client RPGLE également.

La description du service est disponible ici : http://orion.wirtanen.net:10010/web/services/ConvertTemp?wsdl

Le zip disponible contient l’intégralité des sources décrits ci-dessous : télécharger l’exemple 1. Vous pouvez le télécharger et le regarder directement, ou effectuer vous-même les manipulations décrites.

1. Test du service

Avant de coder l’appel en RPG, testez le service web avec un outil externe (tel que SOAPUI, Eclipse for J2EE, RDi pour SOA …) afin de mieux comprendre son fonctionnement.

Il vous faut d’abord enregistrer le fichier WSDL : http://orion.wirtanen.net:10010/web/services/ConvertTemp?wsdl

Ensuite, avec votre outil de test (ici l’explorateur de Services Web intégré à RDi et Eclipse for J2EE), réalisez l’invocation du service « ConvertTemp » comme indiqué ici :

Ajoutez un paramètre et indiquez la température Fahrenheit.

Cliquez sur « OK », le résultat suivant s’affiche :

Via le bouton « Source » vous pouvez obtenir le flux SOAP complet :

2. Réalisation d’un client du Service Web

Nous allons maintenant réaliser un client RPG ILE.

a) Etape 1 : préparation

- Vous allez avoir besoin d’un répertoire dans l’IFS pour travailler. Si vous n’en disposez pas, vous pouvez en créer un. Par exemple :

o CRTDIR DIR('/home/vous/demows') : création d’un répertoire demows dans le répertoire /home/vous (celui-doit déjà exister, sinon créer le par CRTDIR …)

o Nous allons créer également un sous-répertoire pour les fichiers sources à générer : CRTDIR DIR('/home/vous/demows/module')

- Enregistrer dans ce répertoire le fichier WSDL disponible ici : http://orion.wirtanen.net:10010/web/services/ConvertTemp?wsdl, sous le nom « ConvertTemp.wsdl ».

b) Etape 2 : génération des stubs

- Positionnez vous dans le shell : commande QSH ou STRQSH

- Tapez la commande « /QIBM/prodData/OS/webservices/v1/client/bin/wsdl2ws.sh –h » afin d’afficher l’aide :

- Vous allez utiliser la syntaxe « wsdl2ws.sh -lc -o/home/vous/demows/module /home/vous/demows/ConvertTemp.wsdl », où :

o L’option –lc indique que l’on souhaite générer les stubs en langage C. Par défaut, ils sont générés en C++, mais le C se prête plus simplement à l’intégration avec le RPG ou le COBOL.

o « home/vous/demows/module » est le répertoire IFS dans lequel vous voulez générer le code des stubs.

o « home/vous/demows/ConvertTemp.wsdl » est le fichier WSDL précédemment récupéré.

- Au final, tapez la commande suivante :

o /QIBM/prodData/OS/webservices/v1/client/bin/wsdl2ws.sh -lc -o/home/vous/demows/module /home/vous/demows/ ConvertTemp.wsdl

o Vous devez obtenir le message suivant :

o La commande « ls » vous permet de voir l’ensemble des fichiers sources générés :

o Rôle des sources générés :

ConvertTempPortType.c	Contient l’ensemble des procédures nécessaires pour créer la connexion et l’appel du service web
ConvertTempPortType.h	Contient les prototypes des procédures
CONVERTTEMPInput.c	Contient les procédures qui permettent de manipuler les paramètres en entrée du service web.
CONVERTTEMPInput.h	Contient les déclarations qui représentent les données en entrée du service web. Contient également les prototypes de procédures qui permettent de manipuler ces structures.
CONVERTTEMPResult.c	Contient les procédures qui permettent de manipuler les paramètres retour du service web.
CONVERTTEMPResult.h	Contient les déclarations qui représentent les données en retour du service web. Contient également les prototypes de procédures qui permettent de manipuler ces structures.

Le nom et le nombre de sources générés dépendent de la description du service (fichier WSDL).

On ne s’intéressera qu’aux fichiers .h (headers) qui contiennent l’intégralité des descriptions nécessaires à l’utilisation des procédures présentes dans les fichiers .c.

o Procédures à utiliser :

§ Fichier ConvertTempPortType.h :

· Les procédures ci-dessous sont les procédures qu’il faut obligatoirement utiliser. Les autres sont facultatives (gestion des exceptions).

· extern AXISCHANDLE get_ConvertTempPortType_Stub(const char* pchEndPointUri)

o Cette procédure permet d’allouer les resources réseau nécessaires à l’appel du service web (socket TCP/IP, protocole SOAP)

o Paramètre de retour : un AXISCHANDLE, que nous n’avons pas à connaitre. Nous nous contenterons de le récupérer sous forme de pointeur.

o Paramètre en entrée : une chaine de caractère représentant le « end point URI », c'est-à-dire l’URI à laquelle se trouve le service web. Par défaut, c’est l’URI du WSDL qui est utilisé, mais cela permet de la changer sans recompiler le code généré.

· extern void destroy_ConvertTempPortType_Stub(AXISCHANDLE pStub)

o Cette procédure permet de libérer les ressources réseau utilisées pour l’appel du service web.

o Paramètre en entrée : le AXISCHANDLE précédemment fourni par get_ConvertTempPortType_Stub

· extern CONVERTTEMPResult* converttemp(AXISCHANDLE pStub, CONVERTTEMPInput* Value0)

o Cette procédure réalise l’appel du service web

o Paramètre de retour : un pointeur vers la structure qui contient les valeurs résultats (CONVERTTEMPResult)

o Paramètres en entrée :

§ Le AXISCHANDLE précédemment fourni par get_ConvertTempPortType_Stub

§ Un pointeur vers les données en entrée du service web : CONVERTTEMPInput

§ Fichier CONVERTTEMPResult.h :

· Extern void Axis_Delete_CONVERTTEMPResult(CONVERTTEMPResult* param, int nSize)

o Cette procédure permet de libérer les ressources utilisées pour stocker le résultat du service web

o Paramètre en entrée : le pointeur vers la structure de paramètres ainsi que sa taille

3. Etape 3 : écriture du client RPG ILE

Le but est d’écrire un programme composé de plusieurs modules :

- Un module RPGLE qui est le point d’entrée du programme

- L’ensemble des modules C générés précédemment : ce sont eux qui contiennent la mécanique d’appel du service web

Nous avons repris l’exemple fourni par IBM : \QIBM\ProdData\OS\WebServices\V1\client\samples\ConvertTemp\ConvertTempClient.rpgle, afin de l’expliquer et le rendre plus lisible. Vous pouvez toutefois l’utiliser directement si vous le souhaitez. Vous pouvez le copier dans votre répertoire IFS /home/vous/demows/module.

Ce que doit faire notre programme :

- Utiliser les procédures générées dans cet ordre :

o Création de la connexion : get_ConvertTempPortType_Stub

o Appel du service : converttemp

o Exploitation du résultat

o Libération des ressources utilisées

§ Axis_Delete_CONVERTTEMPResult

§ destroy_ConvertTempPortType_Stub

- La 1^ère étape nécessaire consiste donc à créer les déclarations pour :

o Les structures de données utilisées par les procédures C

o Les prototypes RPG des procédures C que nous devons appeler

- Interprétation des structures de données :

o Fichier CONVERTTEMPInput.h :