In questo articolo vedremo le nuove feature introdotte da Spring-ws.

Partiamo dalla creazione del progetto, che si avvale dei nuovi archetipi rilasciati da spring-ws e vediamo come creare il solito webservice per la libreria.

mvn archetype:create 
-DarchetypeGroupId=org.springframework.ws 
-DarchetypeArtifactId=spring-ws-archetype 
-DarchetypeVersion=2.0.2.RELEASE 
-DgroupId=it.finazzo 
-DartifactId=libreriaservice

Con la direttiva indicata Spring-ws crea la directory libreriaservice

Spostiamoci all’interno della cartella e creaiamo la struttura per il nostro IDE tramite la direttiva mvn eclipse:eclipse. A questo punto possiamo importare il progetto in Eclipse. Come si può notare nel file xml associato al dispatchet spring-servlet.xml è stata esplicitata la dipendenza dalle annotation, tramite il tag <sws:annotation-driven/>

Recuperiamo lo schema xsd che abbiamo creato nei precedenti articoli e lo copiamo sotto la cartella resources.

Definiamo  il bean che si occupa della generazione del wsdl tramite il seguente tag

<sws:dynamic-wsdl 
id="libreria" 
portTypeName="Libreria" 
locationUri="http://localhost:8080/libreria/webservices" > 
<sws:xsd 
location="classpath:schema.xsd"/> 
</sws:dynamic-wsdl>

A questo punto definiamo l’endpoint che si preoccupa di gestire il servizio di Ricerca Libro. Nella definizione degli endpoint si cambia approccio, mentre prima il mapping veniva gestito tramite file xml, adesso tutto è demandato alle annotation:

l’annotazione @Endpoint definisce che una classe è un endpoint

l’annotazione @Autowired definisce il costruttore della costruttore qualora sia necessario fare l’injection di alcuni parametri

l’annotazione @PayloadRoot(localPart = “RicercaLibroRequest”, namespace = “http://finazzo.it/libreria/schema”) definisce la regola di mapping dell’endpoint

Una volta definiti gli endpoint passiamo alla definizione del mapping degli endpoint, tramite la classe PayloadRootAnnotationMethodEndpointMapping

<bean id="payloadMapping" 
class="org.springframework.ws.server.endpoint.
mapping.PayloadRootAnnotationMethodEndpointMapping"/>

Questa è la classe responsabile di instradare i messaggi verso l’opportuno endpoint in base all’analisi del messaggi soap ricevuti e le regole definite di attivazione definite tramite annotation.

Qui trovate l’archetipo estratto dal progetto appena descritto, in modo da poter provare di persona quanto fatto.

Occorre prima di tutto definire il nostro client nei file di configurazione di Spring, tramite la solita definizione di bean.

<bean id="client" 
class="org.springframework.ws.client.core.WebServiceTemplate">
<property name="defaultUri" 
value="http://example.com/WebService" />
<property name="messageFactory" ref="messageFactory" />
</bean>

La property defautUrl indica la URL dei servizi da invocare, mentre la messageFactory individua la classe responsabile della generazione dei messaggi da inviare.

Come factory Spring mette a disposizione 2 implementazioni:

• SaajSoapMessageFactory basata su SAAJ
• AxiomSoapMessageFactory basata su Axiom

In assenza del valore Spring userà di default l’implementazione basata su SAAJ.

Nei file xml di Spring-Ws setteremo la factory desiderata come

<bean id="messageFactory" 
class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory" /> 
<bean id="messageFactory" 
class="org.springframework.ws.soap.axiom.AxiomSoapMessageFactory" />

A questo possiamo sfruttare il nostro client per invocare il servizio e gestirne il risultato.

StreamSource source = new StreamSource(new StringReader(MESSAGE));
StreamResult result = new StreamResult(System.out);
client.sendSourceAndReceiveToResult(source, result);

In source è disponibile il messaggio nel formato atteso dal servizio remoto e nella System.out verrà riversato la risposta del server.

Invocazione coclusa con minimo sforzo. A questo punto andrebbe analizzata la risposta per gestire le nuove azioni da intraprendere.

Come ulteriore aiuto Spring-Ws ci da la possibilità di sfruttare le tecniche di marshalling e unmarshalling per ottenere degli oggetti già pronti per l’uso.

Per fare cià occorre valorizzare il marshaller e l’unmarshallere all’interno del nostro client.

<bean id="client" 
class="org.springframework.ws.client.core.WebServiceTemplate">
<property name="defaultUri" value="http://example.com/WebService" />
<property name="messageFactory" ref="messageFactory" />
<property name="marshaller" ref="Marshaller" />
<property name="unmarshaller" ref="Marshaller" />
</bean>

Per la defizione del marshaller si rimanda all’articolo dedicato.

Definito il marshaller e l’unmarshaller verrà usato il seguente metodo che restituisce un oggetto valorizzato

Object response = client.marshalSendAndReceive(requestPayload);

dove requestPayload è il bean che descrive la richiesta del sistema opportunamente valorizzata.

Nel caso in cui dobbiate gestire gli header SOAP dovete definire una classe che implementi l’interfacciaWebServiceMessageCallback.

Tale interfaccia definisce il metodo public void doWithMessage(WebServiceMessage message) che consente di modificare il messaggio prima del suo invio al server.

In questo caso invocherete il metodo

client.marshalSendAndReceive(requestPayload, new WebServiceMessageCallback() {
public void doWithMessage(WebServiceMessage message) {
((SoapMessage)message).setSoapAction("action");
}
});

Le policy di sicurezza si basano su 3 aspetti:

• l’autenticazione
• la firma
• la crittografia

Implementando meccanismi di autenticazione si limita l’accesso ad utenti conosciuti dal sistema, con l’utilizzo della firma si certifica un contenuto e con la crittografia si trasforma il flusso di dati in un flusso impossibile da leggere senza l’opportuna chiave.

Nell’articolo di oggi vedremo gli strumenti che offre Spring-ws per gestire l’autenticazione.

Spring-ws mette a disposizione 2 implementazioni dell’interfaccia Interceptor:

• XwsSecurityInterceptor basato sull’implementazione della SUN XWSS Xml and Web Service Security
• Wss4jSecurityInterceptor basato sull’implementazione di Apache WSS4J

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

<bean id="wsSecurityInterceptor"
class="org.springframework.ws.soap.security.xwss.XwsSecurityInterceptor">
<property name="policyConfiguration" value="classpath:securityPolicy.xml"/>
<property name="callbackHandlers">
<list>
<ref bean="passwordValidationHandler"/>
</list>
</property>
</bean>
<bean id="passwordValidationHandler"
 class="org.springframework.ws.soap.security.xwss.
callback.SimplePasswordValidationCallbackHandler">
 <property name="users">
 <props>
 <prop key="Valerio">Finazzo</prop>
 </props>
 </property>
</bean>

<soapenv:Envelope 
xmlns:sch="http://www.example.org/schema" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header><wsse:Security 
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-14" 
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>Valerio</wsse:Username>
<wsse:Password 
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">
Finazzo</wsse:Password>
</wsse:UsernameToken></wsse:Security>
</soapenv:Header>
<soapenv:Body>
<sch:RicercaLibroRequest>
<!--Optional:-->
<sch:titolo>?</sch:titolo>
<!--Optional:-->
<sch:nome>?</sch:nome>
<!--Optional:-->
<sch:cognome>?</sch:cognome>
</sch:RicercaLibroRequest>
</soapenv:Body>
</soapenv:Envelope>

Spring mette a disposizione un gestore delle eccezioni che carica la mappa delle eccezioni e crea opportunamente i fault in corrispondenza di ogni eccezioni.

<bean id="exceptionResolver" 
class="org.springframework.ws.soap.server.endpoint.SoapFaultMappingExceptionResolver">    
<property name="defaultFault" value="SERVER"/>
<property name="exceptionMappings">
<value>it.finazzo.libreria.exception.LibroException=SERVER,Invalid request</value>
</property>
</bean>

Nel nostro esempio stiamo dicendo al gestore delle eccezioni che in corrispondenza di una eccezione LibroException deve essere creato un fault con i parametri indicati, come quello mostrato sotto.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Server</faultcode>
         <faultstring xml:lang="en">Invalid request</faultstring>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Per chi usale annotazioni e non vuole file xml con lunghe configurazione Spring mette a disposizione la annotazione @SoapFault. Una volta definita una eccezione è possibile definire il fault da lanciare e i parametri con cui configurarla

Possiamo ottenere un fault analogo a quello descritto sopra definendo così la nostra eccezione

<span style="color: #0d293f;">@SoapFault(faultCode = FaultCode.SERVER, faultStringOrReason="<span style="color: #000000;">Invalid request</span>")
</span>public class LibroException extends Exception

e aggiungendo tra i bean di Spring l’opportuna implementazione

<bean id="exceptionAnnotationResolver" 
class="org.springframework.ws.soap.server.endpoint.SoapFaultAnnotationExceptionResolver" />

Per chi ha creato il progetto tramite Maven ricordarsi di aggiungere la dipendenza dalle librerie di spring-ws che supportano le feature della jdk 1.5.

Fondamentale l’interceptor ci permette di:

• loggare le richieste e le risposte inviate
• applicare dei meccanismi di sicurezza alle richieste pervenute
• gestire i fault di sistema

Nel nostro progetto applichiamo un logger delle richieste e delle risposte e un validatore, ottenendo una configurazione di questo tipo.

<bean 
class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">
<property name="mappings">
        <props>
            <prop key="{http://www.example.org/schema}RicercaLibroRequest">ricercaLibroEndpoint</prop>
        </props>
    </property>
    <property name="interceptors">
	    <list>
              <ref bean="loggingInterceptor"/>
              <ref bean="validatingInterceptor"/>
          </list>
        </property>
    </bean>
<bean id="loggingInterceptor"  
      class="org.springframework.ws.server.endpoint.interceptor.PayloadLoggingInterceptor"/>

<bean id="validatingInterceptor" 
      class="org.springframework.ws.soap.server.endpoint.interceptor.PayloadValidatingInterceptor">
    <property name="schema" value="classpath:schema.xsd"/>
    <property name="validateRequest" value="true"/>
    <property name="validateResponse" value="true"/>
</bean>

Tutte le implementazione degli endpoint fornite dal framework prevedono 2 proprietà:

• marshaller
• unmarshaller

<bean id="jaxb2Marshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
       <property name="contextPath" value="it.finazzo.libreria.schema"/>
       <property name="schema" value="classpath:schema.xsd"/>
</bean>
<bean id="ricercaLibroEndpoint" class="it.finazzo.libreria.ws.RicercaLibroEndpoint">
      <property name="marshaller" ref="jaxb2Marshaller"></property>
      <property name="unmarshaller" ref="jaxb2Marshaller"></property>
</bean>

<plugin>
       <groupId>com.sun.tools.xjc.maven2</groupId>
       <artifactId>maven-jaxb-plugin</artifactId>
       <executions>
             <execution>
                 <phase>generate-sources</phase>
                  <goals>
                      <goal>generate</goal>
                  </goals>
             </execution>
       </executions>
       <configuration>
            <generatePackage>it.finazzo.libreria.schema</generatePackage>
       </configuration>
</plugin>

<resource> 
<directory>src/main/resources</directory> 
<filtering>true</filtering>
</resource>

public class RicercaLibroEndpoint extends AbstractMarshallingPayloadEndpoint {
protected Object invokeInternal(Object arg0) throws Exception {
return new RicercaLibroResponse();
}
}

Occorre prima di tutto scegliere la tecnica di gestione per i messaggi xml. Possiamo usare delle librerie di gestione di messaggi xml come JDOM o SAX oppure delle tecniche di marshalling per la trasformazione di flussi xml in classi java e viceversa, come JAXB e XMLBEANS.

Spring-ws supporta tutte le principali librerie per la gestione dei file xml pertanto la scelta della libreria deve essere fatta valutando anche l’ambiente a disposizione.

In questo caso ho scelto JDOM, una libreria opensource che semplifica la gestione di DOM. Occorre modificare il file pom.xml per introdurre le dipendenza dalla libreria JDOM. Nel nostro caso si traduce in questo set di dipendenze:

<dependency>
<groupId>jdom</groupId>
<artifactId>jdom</artifactId>	
<version>1.0</version>	
</dependency>	    
<dependency>	        
<groupId>jaxen</groupId>	        
<artifactId>jaxen</artifactId>	        
<version>1.1</version>	    
</dependency>	    
<dependency>	        
<groupId>javax.xml.soap</groupId>	        
<artifactId>saaj-api</artifactId>	        
<version>1.3</version>	        
<scope>runtime</scope>	    
</dependency>	    
<dependency>	        
<groupId>com.sun.xml.messaging.saaj</groupId>	        
<artifactId>saaj-impl</artifactId>	        
<version>1.3</version>	        
<scope>runtime</scope>	    
</dependency>

All’interno del file spring-ws-servlet.xml definiamo il bean che implementa il servizio di RicercaLibro.

<bean id="ricercaLibroEndpoint" class="it.finazzo.libreria.ws.RicercaLibroEndpoint"/>

Tale classe estende la classe di Spring che gestisce l’integrazione con JDOM

public class RicercaLibroEndpoint extends AbstractJDomPayloadEndpoint {
	protected Element invokeInternal(Element arg0) throws Exception {		return null;
	}
}

<bean 
class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">
<property name="mappings">
<props>
<prop key="{http://www.example.org/schema}RicercaLibroRequest">
ricercaLibroEndpoint
</prop>
</props>
</property>
</bean>

• PayloadRootQNameEndpointMapping
• SoapActionEndpointMapping

Il mapping basato su Payload prevede l’analisi della richiesta per stabilire quale servizio stiamo invocando. Tale meccanismo è più lento ma è indipendente dalla specifica SOA e pertanto può essere usato sia in caso di SOA 1.1, 1.2 o qualsiasi altro livello di trasporto.

Il secondo mapping sfrutta l’header SOAPAction, che permette di individuare il corretto routing senza analizzare tutta la risposta. Pertanto è più veloce ma è valido solo con la SOA 1.1, poichè nella SOA 1.2 tale parametro è stato reso deprecato.

A questo punto non resta che provare il nostro servizio tramite Soap Ui e verificare il corretto funzionamento del routing.

Per chi non conoscesse Maven rimando alla serie di articoli pubblicati nella sezione Documentazione.

Apriamo una shell nella directory che ospita il nostro workspace e lanciamo il seguente comando

mvn archetype:generate 
-DarchetypeGroupId=org.springframework.ws 
-DarchetypeArtifactId=spring-ws-archetype 
-DarchetypeVersion=1.5.9 
-DgroupId=it.finazzo.libreria 
-DartifactId=libreria

con questo comando stiamo dicendo a maven di creare un nuovo artefatto basato sull’archetipo di spring-ws versione 1.5.9.

A questo punto Maven ha creato una directory con l’alberatura tipica di una web application e i file xml configurati per la sua gestione.

Per semplificare i prossimi step possiamo importare il progetto tramite la direttiva eclipse:eclipse di maven. Troviamo 2 file xml pronti per essere modificati, il classico web.xml dove è definita la servlet preposta a ricevere i messaggi e il file spring-ws-servlet.xml dove definiremo le varie componenti del nostro server.

Nella directory WEB-INF inseriamo il file xsd contenente la struttura dei nostri servizi e nel file spring-ws-servlet.xml definiamo un bean che possa gestirlo.

<bean id="gestioneLibri" 
class="org.springframework.ws.wsdl.wsdl11.DefaultWsdl11Definition">
<property name="schema" ref="schema"/>                                               
<property name="portTypeName" value="Libreria"/>                           
<property name="locationUri" value="/gestioneLibri/webservices"/>                      
</bean>
<bean id="schema" class="org.springframework.xml.xsd.SimpleXsdSchema">
<property name="xsd" value="/WEB-INF/schema.xsd"/>
</bean>

Il bean ‘schema’ mappa il file xsd tramite una classe implementata da Spring e il bean ‘gestioneLibri’ si preoccupa di generare il file wsdl a partire dall’analisi dello schema xsd e dalle proprietà definite, secondo quanto indicato nel precedente articolo.

A questo punto tramite la direttiva install creiamo il file war e facciamo il deploy della nostra applicazione su tomcat.

Una volta attivato il contesto il file wsdl sarà disponibile all’indirizzo http://<server>:<port>/<context>/gestioneLibri.wsdl.

Nel prossimo articolo vedremo come gestire le chiamate ai servizi esposti.

La classe da utilizzare è la DefaultWsdl11Definition

<bean id="libreria" class="org.springframework.ws.wsdl.wsdl11.DefaultWsdl11Definition">
   <property name="schema">
     <bean class="org.springframework.xml.xsd.SimpleXsdSchema">
       <property name="xsd" value="/WEB-INF/libreria.xsd"/>
     </bean>
   </property>
   <property name="portTypeName" value="Libreria"/>
   <property name="locationUri" value="http://localhost:10000/libreria/services"/>
 </bean>

• L’attributo id determina il nome del wsdl. In questo caso esporrà il wsdl libreria.wsdl
• La proprietà schema indica il file da utilizzare per la generazione del file wsdl
• le proprietà portTypeName e locationUri indicano i parametri da inserire all’interno del wsdl per la richiesta dei servizi.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
xmlns:sch="http://www.example.org/schema" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:tns="http://www.example.org/schema" targetNamespace="http://www.example.org/schema">
<wsdl:types> 
  <schema xmlns="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" 
  elementFormDefault="qualified" targetNamespace="http://www.example.org/schema">
<complexType name="LibroType">
<sequence>
  <element name="titolo" type="string" />
<element name="nome" type="string" /> 
<element name="cognome"type="string" /> 
</sequence>
  </complexType>
<element name="RicercaLibroRequest">
<complexType>
<sequence>
  <element minOccurs="0" name="titolo" type="string" />
  <element minOccurs="0" name="nome" type="string" />
  <element minOccurs="0" name="cognome" type="string" />
</sequence>
</complexType>
</element>
<element name="RicercaLibroResponse">
<complexType>
<sequence>
  <element maxOccurs="unbounded" minOccurs="0" name="libro" type="string" />
</sequence>
  </complexType>
</element>
</schema>
</wsdl:types>
<wsdl:message name="RicercaLibroResponse">
  <wsdl:part element="tns:RicercaLibroResponse" name="RicercaLibroResponse" />
  </wsdl:message>
<wsdl:message name="RicercaLibroRequest">
  <wsdl:part element="tns:RicercaLibroRequest" name="RicercaLibroRequest" />
  </wsdl:message>
<wsdl:portType name="Libreria">
<wsdl:operation name="RicercaLibro">
  <wsdl:input message="tns:RicercaLibroRequest" name="RicercaLibroRequest" />
  <wsdl:output message="tns:RicercaLibroResponse" name="RicercaLibroResponse" />
  </wsdl:operation>
  </wsdl:portType>
<wsdl:binding name="LibreriaSoap11" type="tns:Libreria">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="RicercaLibro">
  <soap:operation soapAction=" " />
<wsdl:input name="RicercaLibroRequest">
  <soap:body use="literal" />
</wsdl:input>
<wsdl:output name="RicercaLibroResponse">
  <soap:body use="literal" />
  </wsdl:output>
  </wsdl:operation>
  </wsdl:binding>
<wsdl:service name="LibreriaService">
<wsdl:port binding="tns:LibreriaSoap11" name="LibreriaSoap11">
  <soap:address location="http://localhost:10000/libreria/webservice" />
  </wsdl:port>
  </wsdl:service>
  </wsdl:definitions>

• La sezione type presenta i tipi e gli elementi definiti nell’xsd.
• La sezione messages presenta tutti i messaggi gestibili dal nostro soa server. La nostra classe ha individuato tanti messaggi quanti sono gli elementi definiti nell’xsd con suffisso Request e Response
• La sezione operation presenta i servizi esposti dal server specificando per ogni servizio il messaggio di ingresso e di uscita.
• infine la sezione servizi indica a quale url sono disponibili i nostri servizi.

Nel nostro caso la classe ha individuato un solo servizio RicercaLibro che riceve in ingresso la RicercaLibroRequest e restituisce in uscita la RicercaLibroResponse. Tale servizio è disponibile all’url http://localhost:10000/libreria/webservice.

Per poter avere un riscontro agevole di quanto fatto possiamo caricare il nostro wsdl tramite il tool soap ui, ottimo strumento per il testing dei servizi SOA.

Nel prossimo articolo vedremo come mettere in piedi il nostro server con l’aiuto di spring-ws.

Spring Ws parte dalla definizione del contratto e solo successivamente affronta il problema dell’implementazione. Il vantaggio di questo approccio è quello di permettere allo sviluppatore di concentrarsi sul design del servizio e solo successivamente sulla stesura del codice.

Scopo di questa serie di articoli è la realizzazione di un web service per la ricerca di un libro da un catalogo. La ricerca del libro avviene per titolo o per cognome dell’autore.

Definiamo prima di tutto la struttura dati utilizzata dal web service.

Per semplificazione la struttura dati del libro è di questo tipo:

<complexType name="LibroType">
<sequence>
<element name="titolo" type="string" maxOccurs="1" minOccurs="1"></element>
<element name="nome" type="string" maxOccurs="1" minOccurs="1"></element>
<element name="cognome" type="string" maxOccurs="1" minOccurs="1"></element>
</sequence>
</complexType>

<element name="RicercaLibroRequest"> 
<complexType> <sequence> <element name="titolo" type="string" maxOccurs="1" minOccurs="0"></element> <element name="nome" type="string" maxOccurs="1" minOccurs="0"></element> <element name="cognome" type="string" maxOccurs="1" minOccurs="0"></element> </sequence> </complexType> </element>
<element name="RicercaLibroResponse"> <complexType> <sequence> <element name="libro" type="string" maxOccurs="unbounded" minOccurs="0"></element> </sequence> </complexType> 
</element>