Nous sommes de plus en plus nombreux à utiliser le client de web services ILE, qui est basé sur le produit Axis de la fondation Apache (IBM participe), et qui permet d’appeler des services web SOAP et REST depuis un programme ILE RPG.
IBM vient d’apporter une évolution, qui peut passer inaperçue, mais confère une meilleurs interopérabilité : la capacité à récupérer les « exceptions » émises par un web service SOAP, normalisées sous le nom de « fault ».
Voir l’annonce IBM ici : https://www.ibm.com/developerworks/community/wikis/home/wiki/dW%20IBM%20Integrated%20Web%20Services%20for%20i/page/Access%20SOAP%20Fault%20from%20RPG%20stubs
La fonctionnalité est livré avec le groupe de PTF HTTP, pour l’ensemble des versions 7.* :
- V7R1M0 SF99368-Level 52
- V7R2M0 SF99713-Level 26
- V7R3M0 SF99722-Level 13
soap:fault
Un service web voulant signifier une erreur à l’appelant peut renvoyer une « fault » définie dans la norme SOAP : https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383507
Bien sur, la définition diffère en SOAP 1.1 et 1.2. Seul SOAP 1.1 est entièrement implémenté actuellement.
En résumé, il est possible d’indiquer 4 composantes à une erreur :
- faultcode : obligatoire. Normalisé
- faultstring : obligatoire. Normalisé
- faultactor : sous forme d’une URI
- detail : libre
Par l’exemple :
Gestion des erreurs
Il est possible de retrouver simplement les éléments faultcode, faultstring et faultactor dans le stub, via la zone EXCSTRING :
Par contre, l’élément « detail » n’est pas disponible. Or c’est ce dernier qui contient en général l’information la plus pertinente.
Nouvelles procédures
L’implémentation RPG du client Axis apporte les nouvelles procédures suivantes :
- axiscStubGetSOAPFault : retrouve l’ensemble de l’élément fault
- axiscSoapFaultGetFaultcode : retrouve faultcode
- axiscSoapFaultGetFaultstring : retrouve faultstring
- axiscSoapFaultGetFaultactor : retrouve faultactor
- axiscSoapFaultGetSimpleFaultDetail : retrouve detail
Définies ainsi :
Utilisation
L’appel de ces procédures est simple, comme le montre l’exemple suivant, basé sur l’appel de convertTemp :
A l’exécution (debug) :
Comment tester ?
Petite astuce pour vous permettre de réaliser vos propres tests sans avoir la main sur les services que vous appelez.
Vous devez disposer de node.js : produit OPS, option 1, 5 ou 10.
Vous pouvez alors créer un script simulant un retour en anomalie d’un web service :
Ce script créé un serveur sur qui écoute sur l’IP 10.2.0.1 (celle de mon système) et sur le port 8085 (doit être libre). Il répondra systématiquement la réponse avec un code HTTP 500. La réponse est facile à modifier ici pour vos différents tests.
Dans une session QSH, lancez alors la commande suivante :
node /home/NB/nodejs/convertTemp.js
Renseignez l’IP et le port dans le endpoint de votre programme RPG et le tour est joué !
L’utilisation d’élément « detail » dans une « fault » est souvent mise en oeuvre pour les services SOAP. Cette évolution nous permet de gérer le récupération de cette information facilement.
En attendant le support de SOAP 1.2 …
