Exemple appel SOAP
Sommaire
Appel et configuration d’un service SOAP en JXML
La modélisation d’un service SOAP en JXML permet de connecter un projet à un service web externe pour échanger des données de manière automatisée et sécurisée. Grâce à l’élément WebService, il est possible de définir la logique d’appel, les conditions d’exécution et le stockage des résultats. Cette configuration repose sur trois fichiers essentiels — template, mapping et properties — qui encadrent respectivement la construction de la requête, le traitement de la réponse et la configuration technique de l’appel.
Modélisation JXML
Pour l'appel d’un service de type SOAP, vous devez ajouter à votre projet un élément WebService comme suit :
<WebService Id="webServicePays"
CallOnInputChangeOnly="true" StoreOutputInDatastore="true"
Type="Soap" IsEnabled="existsAndNotEmpty($(monInput))" />
Type : à positionner sur SOAP
CallOnInputChangeOnly (true ou false) : Effectue l’appel uniquement si les paramètres d'entrée du service ont changé depuis le dernier appel. (information stockée dans le DataStore défini par StoreOutput).
StoreOutputInDatastore (true ou false) : Indique si les données doivent être stockées dans le DataStore Draft. Si true, elles sont enregistrées dans Draft, sinon dans External.
IsEnabled (Expression) : Permet d’activer l’appel au service seulement dans certaines conditions. Dans l’exemple, l’appel s’effectuera uniquement si la valeur donnée en entrée de ce service est non nulle (attention aux éventuels recouvrements avec CallOnInputChange).
L’élément WebService de type Soap s’accompagne d’un groupe de trois fichiers (${id} correspond à l’attribut Id de l’élément WebService précédemment évoqué, ici webServicePays) :
APPLI.REF/common/extensions/webservice/${id}.template.
APPLI.REF/common/extensions/webservice/${id}.mapping.
APPLI.REF/common/extensions/webservice/${id}.properties.
Template
Ce fichier permet de définir le corps de la requête qui sera envoyée au service. L'enveloppe d'appel doit être constituée manuellement (à partir d’un exemple de requête attendue par le service ou depuis le WSDL le décrivant, par exemple à l'aide d'un outil externe comme SOAPUI).
Exemple :
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header />
<soap:Body>
<ws:getPrevision xmlns:ws="http://webservice.portal.jway.lu/">
<!--The Element below can be repeated an unlimited number of times.-->
<?foreach p in $(controlServiceSoapInput|pays)?>
<ListePays><?data $(p)?></ListePays>
<?end-foreach?>
<!--End of Iteration.-->
</ws:getPrevision>
</soap:Body>
</soap:Envelope>Il est possible d’injecter des données issues du formulaire dans l'enveloppe grâce à l’utilisation des processing instructions data.
Il est également possible de conditionner la présence de certains éléments grâce à des paires de processing instructions if / end-if (éventuellement accompagnées de else-if), ou encore d’effectuer des itérations (foreach / end-foreach), comme illustré dans l’exemple ci-dessus.
Mapping
Ce fichier permet de définir les données à extraire de la réponse du service pour les injecter dans le dataStore défini précédemment.
Exemple :
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:getPrevisionResponse xmlns:ns1="http://webservice.portal.jway.lu/">
<Prevision>
<!--The Element below can be repeated an unlimited number of times.-->
<pays>
<chiffreAffaire>{controlServiceSoapResult|Pays[]|CA}</chiffreAffaire>
<nom>{controlServiceSoapResult|retourPays[]|nom}</nom>
<!--The Element below can be repeated an unlimited number of times.-->
<villes>
<chiffreAffaire>{controlServiceSoapResult|retourPays[]|villes[]|CA}</chiffreAffaire>
<nom>{controlServiceSoapResult|retourPays[]|villes[]|nom}</nom>
</villes>
<!--End of Iteration.-->
</pays>
<!--End of Iteration.-->
</Prevision>
</ns1:getPrevisionResponse>
</soap:Body>
</soap:Envelope>Pour chaque donnée que vous souhaitez extraire et ajouter dans le dataStore, il faut utiliser un tag {XXXX}. Ce tag représente le nom de la variable qui recevra la valeur extraite.
La grammaire Jway est utilisée pour définir les chemins de données. Toutefois, pour mapper des éléments itératifs, le symbole [ ] est employé afin de désigner une liste.
Properties
Ce fichier sert à définir les headers et les paramètres utilisés lors de l'appel du service.
Tout comme pour le fichier template, il est possible d’utiliser des processing instructions pour injecter des données issues du formulaire.
Exemple :
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="Method">POST</entry>
<entry key="Transport">http://152.228.230.4/jwayServicesHub/previsionnelServer</entry>
<entry key="Accept-Encoding">gzip,deflate</entry>
<entry key="Content-Type">text/xml;charset="utf-8"</entry>
<entry key="SOAPAction"></entry>
<entry key="User-Agent">Jakarta Commons-HttpClient/3.1</entry>
</properties>Method : est utilisée pour définir le type d’appel (POST)
Transport : est utilisée pour définir l’URL d’appel du service
Sécurisation des services
Pour définir une sécurisation particulière à mettre en œuvre lors de l'appel d’un service SOAP, il faut ajouter une propriété de publication comme suit :
jway.webservice.security.${id}.classname=XXXX où ${id} est l’id du WebService et XXXXX le nom du filtre de sécurité qui sera appliqué.
Le filtre de sécurité Java est ajouté dans le répertoire suivant : APPLI.REF/common/extensions/lu/jway/services/security avec le nom : XXXXXXSecurityFilter.java
Ce filtre de sécurité permet des manipulations lors de la phase de templating ou de mapping selon 3 méthodes illustrées ci dessous.
/*=======================================================*/
package lu.jway.services.security;
import lu.jway.webapp.ds.DataStore;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.IOException;
import java.io.InputStream;
public class XXXXXXXSecurityFilter implements SecurityFilter {
private static final Logger LOG = LoggerFactory.getLogger(XXXXXXXSecurityFilter.class);
@Override
public String securityTemplateFilter(String id, String soapEnveloppe,
DataStore[] dss) throws IOException {
return soapEnveloppe;
}
@Override
public InputStream securityMappingFilter(String id, InputStream answer,
DataStore[] dss) throws IOException {
LOG.info("securityMappingFilter not implemented, returning answer unmodify");
return answer;
}
@Override
public String securityMappingFilter(String id, String answer,
DataStore[] dss) throws IOException {
LOG.info("securityMappingFilter not implemented, returning answer unmodify");
return answer;
}
}
/*=======================================================*/