Déploiement d'un Web Service avec Spring WS

Récemment, SpringSource a annoncé que la prochaine version majeure de Spring WS était en préparation et qu'elle apporterait son lot de nouveautés :

• support de Spring 2.5 : les endpoint ne devront plus être déclarés automatiquement, mais pourront être configurés via l'annotation @Endpoint ;
• support natif de Java 6 ;
• nouveau transport : JMS et Email en plus de HTTP ;
• gestion des intercepteurs au niveau client ;
• un namespace Spring dédié à Spring WS ;
• un support de WS-Adressing.

La facilité de Spring WS commence déjà à l'étape de la création du projet, en effet, afin de gagner du temps, un archétype Maven 2 permet la création d'un squelette du projet.
Pas besoin donc de chercher les dépendances nécessaires, cette responsabilité étant déléguée à Maven 2.

Dès lors, la création du projet se fait simplement par la commande suivant :

mvn archetype:create -DarchetypeGroupId=org.springframework.ws
  -DarchetypeArtifactId=spring-ws-archetype \
  -DarchetypeVersion=1.0.2 \
  -DgroupId=<le groupe désiré> \
  -DartifactId=<le nom du module>

Le projet ainsi créé contient un fichier de configuration vide d'une servlet Spring MVC, ainsi que les dépendances de base nécessaires au projet.

Une fois le projet créé, il est nécessaire de définir le contrat des données transférées, et ce, sous la forme d'un schéma XML.

La requête comprendra la langue d'origine du message, la langue vers laquelle une traduction est demandée ainsi qu'évidemment le texte à traduire :

La réponse possèdera en plus du texte traduit, le nom du traducteur qui a réalisé la traduction

Voici le schéma XSD définissant ces messages :

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:traduction="http://www.hikage.be/schema/traduction"
           targetNamespace="http://www.hikage.be/schema/traduction" elementFormDefault="qualified">
    <xs:element name="TraductionRequest" type="traduction:TraductionRequestType"/>
    <xs:element name="TraductionResponse" type="traduction:TraductionResponseType"/>
    <xs:complexType name="TraductionRequestType">
        <xs:sequence>
            <xs:element name="langueOrigine" type="xs:string"/>
            <xs:element name="langueDestination" type="xs:string"/>
            <xs:element name="texte" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="TraductionResponseType">
        <xs:sequence>
            <xs:element name="auteur" type="xs:string"/>
            <xs:element name="texte" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>

La nomenclature des éléments est très importante, le fait que ce soit TraductionRequest et TraductionResponse est en effet obligatoire pour permettre à Spring WS de faire la relation entre les deux au niveau des messages SOAP.

Une fois que les messages sont définis, l'étape suivante est de réaliser un endpoint, c'est-à-dire une classe qui va interpréter les messages en entrée, appeler le service de traduction proprement dit et renvoyer la réponse sous la forme définie précédemment.

Pour ce faire, Spring fournit différentes classes abstraites de base, afin de récupérer sous différentes formes le message. En effet, le message étant de l'XML, les moyens sont nombreux pour l'interpréter : SAX, JDOM, DOM4J, StAx, JAXB, Castor…

Dans cet exemple, nous allons utiliser un endpoint de type JDOM. Pour cela, c'est la classe AbstractJDomPayloadEndpoint qu'il faut étendre.
Il est intéressant de remarquer le Payload dans la classe. C'est-à-dire que l'élément JDOM qui sera récupéré ne contiendra que le contenu du message SOAP, c'est-à-dire ici, un TraductionRequest.

Ajout de dépendances▲

  <dependency>
            <groupId>jdom</groupId>
            <artifactId>jdom</artifactId>
            <version>1.0</version>
        </dependency>
        <dependency>
            <groupId>jaxen</groupId>
            <artifactId>jaxen</artifactId>
            <version>1.1</version>
        </dependency>

Création de l'endpoint▲

public class TraductionEndpoint  extends AbstractJDomPayloadEndpoint {
    protected Element invokeInternal(Element request) throws Exception {
      Namespace namespace = Namespace.getNamespace("traduction", "http://www.hikage.be/schema/traduction");


        // Création des requêtes XPath pour récupérer les informations
        XPath langueOrigineExpression = XPath.newInstance("//traduction:TraductionRequest/traduction:langueOrigine");
        langueOrigineExpression.addNamespace(namespace);
        XPath langueDestinationExpression = XPath.newInstance("//traduction:TraductionRequest/traduction:langueDestination");
        langueDestinationExpression.addNamespace(namespace);
        XPath texteExpression = XPath.newInstance("//traduction:TraductionRequest/traduction:texte");
        texteExpression.addNamespace(namespace);

        // Récupération des informations à partir de la requête
        String langueOrigine = langueOrigineExpression.valueOf(request);
        String langueDestination = langueDestinationExpression.valueOf(request);
        String texteOriginal = texteExpression.valueOf(request);

        // Appel au service pour la traduction
        Traduction traduction = traductionService.traduitTexte(langueOrigine, langueDestination, texteOriginal);

        
        // Création de la réponse
        Element root = new Element("TraductionResponse", namespace);
        Element auteur = new Element("auteur", namespace);
        auteur.setText(traduction.getAuteur());

        Element texteTraduit = new Element("texte", namespace);
        texteTraduit.setText(traduction.getTexte());

        root.addContent(auteur);
        root.addContent(texteTraduit);

        return root;
    
      }
}

    <bean id="traductionEndpoint" class="be.hikage.spring.ws.endpoint.TraductionEndpoint">
        <property name="traductionService" ref="traductionService"/>
    </bean>

Une fois l'endpoint créé et configuré, il faut encore que les requêtes de traduction soient routées vers celui-ci.
Pour cela, Spring WS fournit une classe, qui va réaliser un mapping entre le type XML du message d'entrée et l'endpoint qui le gère.

Dans notre cas, cette configuration serait :

  <bean class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">
        <property name="mappings">
            <props>
                <prop key="{http://www.hikage.be/schema/traduction}TraductionRequest">traductionEndpoint</prop>
            </props>
        </property>
        <property name="interceptors">
            <list>
                <bean class="org.springframework.ws.server.endpoint.interceptor.PayloadLoggingInterceptor">
            </list>
        </property>
    </bean>

En clair, lorsque le corps d'un message SOAP contiendra un élément TraductionRequest, du namespace http://www.hikage.be/schema/traduction, celui-ci sera envoyé vers l'endpoint traductionEndpoint.

On remarque que la classe qui s'occupe du routage permet de configurer des intercepteurs. Un intercepteur est un objet qui a la possibilité d'agir sur un message AVANT qu'il ne soit interprété par un endpoint, mais aussi d'agir sur la réponse créée par celui-ci.
Dans l'exemple ci-dessus, il n'y a aucune action spécifique, cela ne fait qu'écrire dans les fichiers de logs les messages d'entrées et de sorties.
Mais il sera montré plus loin dans cet article l'utilité des intercepteurs, notamment dans la validation et la sécurité.

À ce stade, le service web est fonctionnel, c'est-à-dire que si les bons messages sont envoyés à la bonne adresse, ils seront traités correctement.
Cependant, les clients ne disposent pas encore du WSDL, et donc il est quasi impossible d'y accéder correctement.

Il est donc nécessaire de mettre à disposition le WSDL, et pour cela c'est via la classe DynamicWsdl11Definition que cela est possible :

<bean id="traduction" class="org.springframework.ws.wsdl.wsdl11.DynamicWsdl11Definition">
        <property name="builder">
            <bean
                    class="org.springframework.ws.wsdl.wsdl11.builder.XsdBasedSoap11Wsdl4jDefinitionBuilder">
                <property name="schema" value="/WEB-INF/traduction.xsd"/>
                <property name="portTypeName" value="traduction"/>
                <property name="locationUri" value="http://localhost:9090/traductionService/"/>
            </bean>
        </property>
    </bean>

Détaillons un peu cette configuration. L'identifiant traduction spécifie que le WSDL généré sera accessible en ajoutant traduction.wsdl à l'URL de déploiement du service.
La propriété schema spécifie le chemin vers le schéma XML sur lequel Spring WS doit se baser pour générer le WSDL.
La propriété portTypeName spécifie le nom du portType dans le document WSDL.
La propriété locationUri spécifie l'URL à laquelle sera accessible le service. Cette propriété ne vérifie pas que l'URL correspond réellement à la configuration réelle. Il faut donc s'assurer de donner la bonne URL.

Le service Web nécessite de déployer le projet sous forme d'un WAR dans un serveur Tomcat ou autres.

Dans le projet fourni, il suffit de lancer la commande suivante pour tester :

mvn jetty:run

Une fois cela fait, il est possible de tester le service via SoapUI :

Par défaut, Spring WS ne valide pas les messages ni en entrée ni en sortie. C'est-à-dire que si un message TraductionRequest contient autre chose que les langues d'origine et de destination et le message à traduire, cela sera tout de même envoyé vers l'endpoint, au risque d'effectuer un mauvais traitement.

Afin de gérer cela, un intercepteur est proposé : PayloadValidatingInterceptor. Sa configuration est complètement gérée dans le contexte Spring :

<bean id="traductionValidatingInterceptor"
        class="org.springframework.ws.soap.server.endpoint.interceptor.PayloadValidatingInterceptor">
    <property name="schema" value="/WEB-INF/traduction.xsd"/>
    <property name="validateRequest" value="true"/>
    <property name="validateResponse" value="true"/>
</bean>

Il prend en paramètre le schème XSD utilisé pour la validation, et permet la validation indépendamment sur les messages en entrée et en sortie.
Cela permettrait ainsi d'être flexible sur les messages d'entrée, mais d'être rigide en ce qui concerne les réponses (qui doivent être comprises correctement par les clients, et donc doivent absolument être valides).

Comme tout intercepteur, il est ensuite nécessaire de l'ajouter en tant que tel :

  <bean class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">
        <property name="mappings">
            <props>
                <prop key="{http://www.hikage.be/schema/traduction}TraductionRequest">traductionEndpoint</prop>
            </props>
        </property>
        <property name="interceptors">
            <list>
                <bean class="org.springframework.ws.server.endpoint.interceptor.PayloadLoggingInterceptor">
                <!-- Ajout de l'intercepteur de validation -->
                <ref bean="traductionValidatingInterceptor"/>
            </list>
        </property>
    </bean>

Dès lors, si un client tente d'envoyer une requête mal formée, il se verra recevoir une faute SOAP :

   <faultcode>SOAP-ENV:Client</faultcode>
         <faultstring xml:lang="en">Validation error</faultstring>
         <detail>
            <spring-ws:ValidationError xmlns:spring-ws="http://springframework.org/spring-ws">
            cvc-complex-type.2.4.a: Invalid content was found starting with element 'trad:MauvaiseBalise'.
            One of '{"http://www.hikage.be/schema/traduction":langueOrigine}' is expected.
            </spring-ws:ValidationError>
         </detail>

Un autre exemple où les intercepteurs sont intéressants est la gestion de WS-Security.

Mais avant de mettre en œuvre cela, il est nécessaire d'ajouter une dépendance au projet POM :

     <!--
            Nécessaire pour l'utilisation de WS-Security
        -->
        <dependency>
            <groupId>org.springframework.ws</groupId>
            <artifactId>spring-ws-security</artifactId>
            <version>1.0.2</version>
        </dependency>

Une fois cela fait, il est possible de configurer un intercepteur :

  <bean id="wsSecurityInterceptor" class="org.springframework.ws.soap.security.xwss.XwsSecurityInterceptor">
        <property name="policyConfiguration" value="classpath:/wss-server-config.xml"/>
        <property name="callbackHandlers">
            <list>
                <bean id="passwordValidationHandler"
                      class="org.springframework.ws.soap.security.xwss.callback.SimplePasswordValidationCallbackHandler">
                    <property name="users">
                        <props>
                            <prop key="hikage">password</prop>
                            <prop key="cafe">babe</prop>
                        </props>
                    </property>
                </bean>
            </list>
        </property>
    </bean>

La première chose à configurer est la politique de configuration, qui prend un fichier de configuration WS Security en paramètre.
Voici un exemple qui prend en compte l'authentification :

   <xwss:SecurityConfiguration xmlns:xwss="http://java.sun.com/xml/ns/xwss/config">
   <xwss:RequireUsernameToken passwordDigestRequired="false" nonceRequired="false"/>
   </xwss:SecurityConfiguration>

Il demande un token d'authentification, mais pas obligatoirement chiffré.

Ensuite, il faut configurer les handlers qui vont s'occuper de l'authentification, ou encore de vérifier les signatures ou déchiffrer les messages lorsque cela est configuré.

Dans l'exemple, un seul handler est configuré, qui va vérifier les couples utilisateurs/mot de passe (basé sur une liste d'utilisateurs spécifiée directement). Il en existe d'autres plus évolués qui utilisent Spring Security pour ces vérifications.

Il faut ensuite ajouter l'intercepteur dans la chaine, AVANT la validation :

   <bean class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">
        <property name="mappings">
            <props>
                <prop key="{http://www.hikage.be/schema/traduction}TraductionRequest"
                        >traductionEndpoint
                </prop>
            </props>
        </property>
        <property name="interceptors">
            <list>
                <bean class="org.springframework.ws.server.endpoint.interceptor.PayloadLoggingInterceptor"/>
                <!-- Il est nécessaire de mettre l'intercepteur de sécurité avant la validation -->
                <ref bean="wsSecurityInterceptor"/>
                <ref bean="traductionValidatingInterceptor"/>
            </list>
        </property>
    </bean>

Ici, le fait de le mettre avant ou après la validation n'a pas d'incidence, mais si le chiffrement était activé, l'intercepteur de validation ne comprendrait pas le message chiffré. Une fois que celui-ci sera passé dans l'intercepteur WS-Security, il sera déchiffré et compréhensible par la suite de la chaine d'interception.

Dès lors, tout appel au service sans utiliser les entêtes WS-Security donnera :

<SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Client</faultcode>
         <faultstring xml:lang="en">
         com.sun.xml.wss.XWSSecurityException: Message does not conform to configured policy
         [ AuthenticationTokenPolicy(S) ]: No Security Header found; nested exception is
         com.sun.xml.wss.XWSSecurityException: com.sun.xml.wss.XWSSecurityException:
         Message does not conform to configured policy [ AuthenticationTokenPolicy(S) ]:  No Security Header found
         </faultstring>
      </SOAP-ENV:Fault>