Rimando ai vari tutorial che ci sono sulla rete per la configurazione dei componenti.

Transcript

1 Questo è un tutorial BASICO, scritto pensando anche a chi non ha mai avuto a che fare con lo sviluppo di Wss. Per questo motivo le definizioni di alcuni concetti potrebbero essere approssimative in quanto ho privilegiato la chiarezza alla correttezza formale. Inoltre io stesso non sono un esperto di questi argomenti. Ancora un ultimo avviso: io sono un fan dei layer nelle applicazioni, e quindi tendo tendo a suddividerle. Nessuna eccezione in questo tutorial. Infatti quello che troverete qui, sono due progetti: un progetto web che conterrà tutti i file di configurazione e la definizione del WS un progetto libreria che conterrà tutte le implementazioni necessarie Perchè questo articolo? Ultimamente mi sono trovato a dover affrontare lo sviluppo di un web service, cosa che mi era capitata solo una volta in precedenza. Inoltre, mentre nella precedente occasione ho potuto utilizzare un approccio contract last, questa volta era indispensabile utilizzare l'approccio inverso contractfirst (questo per motivi architetturali). C'è una grande differenza fra i due approcci, e il passaggio da uno all'altro comporta un radicale cambiamento nel modo di pensare al servizio. Con un approccio contract last si pensa come un classico programmatore in termini di moduli, classi, metodi delegando poi a qualche tool esterno, come ad esempio Axis2, la pubblicazione del servizio (vedremo appena sotto cosa pubblicazione significa). Al contrario, con l'approccio contract first la vostra prima preoccupazione deve essere la pubblicazione. Quindi, cosa ci serve per pubblicare un WS? Un WSDL! Un WSDL è in effetti un contratto che descrive interamente il servizio in termini di tipi (richieste e risposte) e operazioni. Questa è la via più formale di sviluppare un WS. Sfortunatamente, come spesso succede, è anche la più complicata. Inoltre è necessario tenere a mente che un servizio è la sua definizione, non la sua implementazione. In altri termini, il focus primario in questo caso è l'interfaccia di comunicazione fra il mondo e il nostro servizio. Più avanti in questo articolo, supporrò una fondamentale differenza fra i termini metodo e operazione: un metodo è relativo ad una classe, un'operazione ad un WS. Devo dire che ho trovato piuttosto duro il passaggio da un approccio all'altro, per questo ho deciso di scrivere questo articolo, pensando che sia un argomento che merita di essere ben descritto. Questo è il perchè, ora passiamo al cosa. Quello che ci serve Eclipse Ganymede java 1.6 Maven Apache Tomcat XJC eclipse plugin (tool di generazione di classi a partire da un XSD) SoapUI (il plugin per eclipse mi ha creato parecchi problemi, ho optato quindi per la versione stand alone) Rimando ai vari tutorial che ci sono sulla rete per la configurazione dei componenti. Perchè Spring WS? Approaching WS development thinking at the contract, means defining its WSDL and then develop the code (java, C#,...) to fullfill the requests. L'approccio contract first, come visto, impone che si pensi prima al contratto che all'implementazione; significa che bisogna prima definire il WSDL e quindi pensare

2 all'implementazione (java, C#,...) che soddisfi le richieste. Ma un file WSDL + abbastanza complicato e certamente di non istantanea comprensione. Spring WS aiuta molto in questo, in quanto ci permette di pensare in termini di XSD piuttosto che di WSDL. In altri termini, ci si può concentrare nella definizione dei tipi, Inoltre, devo dire che trovo Spring un framework davvero valido. L'ho conosciuto nell'ultimo mese per fare sicurezza (Spring Security); da lì ho conosciuto Springbeans e il contenitore IoC. Quindi ho visto anche l'aop. Ora come ora, il mo progetto (nato come semplice servizio contract last con Axis2) è diventato un progetto che si basa quasi interamente su Spring utilizzando security, beans, aop e ws. Cosa vogliamo costruire? Quello che intendiamo sviluppare in questo articolo è un WS che esponga due operazioni 1. Hello(): che risponda con hello! 2. HelloTo(string): che risponda con hello + string Creazione di un nuovo progetto web Creare un nuovo progetto Selezionare Maven Maven project Siete liberi di mettere i nomi che volete al progetto, ma selezionate spring ws archetype come archetipo. Creazione del progetto libreria Come prima create un nuovo progetto. Siete sempre liberi di mettere i nomi che volete, ma selezionate come archetipo maven archetypequickstart. Usando Maven, aggiungete a questo la dipendenza al pacchetto spring ws (consiglio il jar completo). Sempre con Maven referenziate il progetto libreria all'interno del progetto web. Implementazione Abbiamo creato la struttura base dei nostri progetti. Visto che stiamo utilizzando un approccio contract first, cominciamo dal progetto web. If we look at the content of the WEB INF folder, we can see that along with web.xml there is one more file: spring ws servlet.xml. Se osserviamo il contenuto della cartella WEB INF, possiamo vedere che assieme al classico web.xml, c'è un altro file (lo ha messo Maven): spring ws servlet.xml Apriamo questi due file. In web.xml notiamo che è definita una servlet chiamata spring ws che mappa tutti i percorsi. Possiamo anche chiudere web.xml, non ci servirà più (può essere modificato, per esempio per far sì che la servlet risponda solo su alcuni percorsi, ma non è questo il nostro scopo al momento). The second is an empty XML file, except for the root element <schema> and the namespace definition. Il secondo è un file xml vuoto, a parte per il tag radice <schema> che contiene la definizione del namespace. Il nome del file qui è importante, in quanto per convezione deve essere [nome servlet] servlet.xml (in realtà, è possibile cambiare questa convenzione aggiungendo qualcosa al web.xml, ma nemmeno questo è il nostro scopo)

3 Questo file è il context della servlet e sarà usato più avanti per istanziare i vari oggetti e collegarli tra loro all'interno del'ioc container di Spring. Ci preoccuperemo di editare questo file una volta che avremo definito il servizio e implementato le classi necessarie. Adesso, la domanda che dobbiamo porci è: Cosa vogliamo che il nostro servizio faccia? Cosa deve esporre al mondo e come il mondo può comunicare con lui? Come già detto, il WS deve esporre due operazioni: Hello HelloTo(string) La definizione di un servizio gira tutta intorno a requests e responses (uso i termini inglesi in quanto sono termini tecnici riconosciuti a livello internazionale). Adesso dirò una cosa che dovrete dimenticare subito, ma è giusto per farmi capire da chi non ha mai visto un WS: una request ad un WS è assimilabile alla chiamata di un metodo di una classe in OOP. La request viaggerà sulla rete, tipicamente con il protocollo SOAP, e sarà qualcosa di simile a questo: <soapenv:envelope xmlns:soapenv=" xmlns:spr=" ws annotations"> <soapenv:header/> <soapenv:body> <spr:hellorequest/> </soapenv:body> </soapenv:envelope> Come già detto, vogliamo un servizio con due operazioni: segnifica che dobbiamo creare due request. Per prima cosa, creiamo la loro descrizione in XSD. Creiamo il file tutorial.xsd nella cartella WEB INF ed editiamolo subito per apportare una modifica e poi aggiungere le nostre request. Inizialmente il notro file sarà qualcosa di simile a questo: <?xml version="1.0" encoding="utf-8"?> <schema xmlns=" targetnamespace=" xmlns:tns=" elementformdefault="qualified"> </schema> Dobbiamo cambiare il namespace di destinazione. Suppongo che il namespace sia ws annotations (è una scelta assolutamente arbitraria) Il risultato sarà: <?xml version="1.0" encoding="utf-8"?> <schema xmlns=" targetnamespace=" xmlns:tns=" elementformdefault="qualified">

4 </schema> Adesso aggiungiamo la definizione delle nostre request: la prima sarà vuota, la seconda conterrà un elemento (una stringa nella fattispecie) <element name="hellorequest"> <complextype></complextype> </element> <element name="hellotorequest"> <complextype> <all> <element name="to" type="string"></element> </all> </complextype> </element> Grazie a Spring, questo è tutto ciò che ci è richieste per creare il contratto del WS (sembra banale, me pensate ad un WS reale: quante operazioni dovrà esporre?) Possiamo quindi cominciare a pensare all'impementazione. Le prime cose da implementare sono le nostre request (vanno implementate perchè poi noi lavoreremo con un linguaggio di programmazione, quindi anche lui deve conoscere la loro struttura). Possiamo farlo a mano, ma consiglio di usare il plugin XJC per Eclipse in quanto le classi vanno annotate in una maniera particolare. Una volta installato il plugin (molto semplice. Scaricare il jar, copiarlo nella cartella plugin e riavviare Eclipse) possiamo generare le classi cliccando col destro sul nostro file.xsd e selezionando JAXB 2.1 Run XJC : ci sarà richiesto la cartella dove generare i file e il loro package. Supponiamo di scegliere la cartella del sorgente del progetto libreria e come package it.innove.life.tutorials.spring.ws.schema. Osserviamo adesso il progetto libreria: potete notare che sono state create delle classi nel package specificato: due di loro implementano in linguaggio Java i tipi definiti nell'xsd. Adesso che abbiamo considerato le request, dobbiamo considerare le response. Entrambe le operazioni danno come response una stringa. Sfortunatamente, Jaxb non riesce a serializzare java.lang.string in quanto non presenta le annotazioni necessarie. Dobbiamo quindi creare un wrapper alla classe String package it.innove.life.tutorials.spring.ws.types; import javax.xml.bind.annotation.xmlaccesstype; import javax.xml.bind.annotation.xmlaccessortype; import javax.xml.bind.annotation.xmlelement; import javax.xml.bind.annotation.xmlrootelement; /** stefano public class private String value;

5 public StringType() public StringType(String value) this.setvalue(value); public void setvalue(string value) this.value = value; public String getvalue() return value; Non c'è molto da dire su questa classe: solo, date un occhio alle annotazioni. Procediamo con l'implementazione dei restanti oggetti. Per prima cosa, l'implementazione del servizio package it.innove.life.tutorials.spring.ws.services; /** stefano * */ public class HelloService public String hello() return "hello!"; public String helloto(string to) return "hello " + to; Niente da dire. Fa quello che ci si aspetta che faccia. Adesso siamo alla parte centrale: gli endpoint. Questo sono gli autentici punti di comunicazione fra il contratto e l'implementazione del nostro servizio. Parliamo un attimo degli endpoint. Per ogni request deve esistere un endpoint (li potete vedere come handlers). L'implementazione del servizio non sarà mai chiamata direttamente, ma sarà responsabilità degli endpoint di instradare la richiesta al servizio adatto. Inoltre, ogni endpoint è mappato per una particolare request, e quindi la molteplicità fra request e endpoint è 1:1. E' responsabilità di Spring mappare le request sugli endpoint. In generale, quindi, ci dovrebbe essere una classe endpoint per ogni singola request. Ma, visto che usiamo Spring WS con le annotazioni, possiamo rilassare questo vincolo ottenendo che le request hanno una molteplicità 1:1 con i metodi (cosicchè una classe può mappare più endpoint). Diamo innanzitutto uno sguardo al codice che commenteremo poi.

6 package it.innove.life.tutorials.spring.ws.endpoints; import it.innove.life.tutorials.spring.ws.schema.hellorequest; import it.innove.life.tutorials.spring.ws.schema.hellotorequest; import it.innove.life.tutorials.spring.ws.services.helloservice; import it.innove.life.tutorials.spring.ws.types.stringtype; import org.springframework.ws.server.endpoint.annotation.endpoint; import org.springframework.ws.server.endpoint.annotation.payloadroot; /** stefano * public class HelloServiceEndpoint private HelloService service; HelloServiceEndpoint(HelloService service) this.service = namespace=" public StringType hello(hellorequest request) return new StringType( service.hello() namespace=" public StringType helloto(hellotorequest request) return new StringType( service.helloto(request.getto())); Tre cose importanti da notare: 1. tutti i metodi ritornano dei POJO annotati secondo JAXB 2. La classe è annotata questo dice a Spring che deve guardare all'interno della classe per ricercare gli endpoint 3. I metodi sono annotati I parametri corrispondono rispettivamente ai nomi dei tipi definiti nell'xsd e al targetnamespace sempre dell'xsd. Ci siamo quasi! Abbiamo implementato tutto quello che ci serve (veramente manca una cosa, ma la vedremo dopo in quanto qui non riuscirei a spiegare perchè ci sia l'esigenza di estendere una classe di Spring). Focalizziamoci ora sul servlet context. Quindi ritorniamo al progetto libreria e apriamo il file spring ws servlet.xml. Stiamo per popolare il contesto e il contenitore IoC di Spring, collegando tra loro gli oggetti in modo da costruire il contesto della servlet. Faremo qui un uso pesante degli Spring beans: se non conoscete l'argomento, raccomando che leggiate la documentazione e che facciate qualche test. Questo argomento è troppo importante per

7 poterne parlare qui in poche parole. Procediamo passo passo. La prima cosa da aggiungere è la definizione dell'implementazione del servizio: <bean id="helloservice" class="it.innove.life.tutorials.spring.ws.services.helloservice" /> Niente da dire. Tenete a mente l'id del bean perchè sarà referenziato più sotto. Passo successivo, dobbiamo predisporre il meccanismo di marshalling <bean id="marshaller" class="org.springframework.oxm.jaxb.jaxb2marshaller"> <property name="classestobebound"> <list> <value>it.innove.life.tutorials.spring.ws.schema.hellorequest</value> <value>it.innove.life.tutorials.spring.ws.schema.hellotorequest</value <value>it.innove.life.tutorials.spring.ws.types.stringtype</value> </list> </property> Vale la pena di spendere due parole su questo. Stiamo instanziando un oggetto responsabile del [un]marshalling, basato su Jaxb e lo stiamo istruendo sui tipi di cui deve occuparsi. Dovrete aggiungere qui tutti i tipi che saranno oggetto di marshalling (serializzazione e deserializzazione per essere chiari) Finora abbiamo creato due oggetti che vivono di vita propria. Adesso dobbiamo cominciare a mettere insieme i pezzi. Definiamo l'endpoint (ne abbiamo solo uno) <bean id="helloserviceendpoint" class="it.innove.life.tutorials.spring.ws.endpoints.helloserviceendpoint"> <constructor-arg ref="helloservice" /> Notate che il costruttore è invocato passandogli come parametro l'implementazione del servizio. Andiamo avanti col puzzle <bean id="helloserviceendpointadapter" class="org.springframework.ws.server.endpoint.adapter.genericmarshallingmethode dnpointadapter"> <constructor-arg ref="marshaller" /> This bean calls the methods on the endpoint and needs to know the marshaller to delegate the serialization / deserialization of objects. Questo bean è responsabile delle chiamate agli endpoint, ma ha necessità di conoscere che meccanismo di marshalling utilizzare. Quindi <bean

8 class="org.springframework.ws.server.endpoint.mapping.payloadrootannotationmeth odendpointmapping" /> This object enables Spring to use code annotations (Spring will search the beans to find the classes annotated and he will use them to map requests). Questo oggetto abilita le annotazioni di Spring WS (Spring cercherà all'interno dei bean le classi annotate e le userà per mappare le request). Vedete la luce in fondo al tunnel? Non è né un miraggio né un treno. Un ultimo sforzo. Non abbiamo mai parlato WSDL, avete notato? Questo perchè Spring è in grado di generarlo automaticamente, ma deve essere istruito allo scopo. Dobbiamo definire altri due bean <bean id="schema" class="org.springframework.xml.xsd.simplexsdschema"> <property name="xsd" value="/web-inf/tutorial.xsd" /> <bean id="contract" class="org.springframework.ws.wsdl.wsdl11.defaultwsdl11definition"> <property name="schema" ref="schema" /> <property name="porttypename" value="tutorial" /> <property name="locationuri" value=" [nome_progetto_web]/services/" /> <property name="targetnamespace" value=" /> Il primo definisce il nostro schema XSD. Il secondo definisce la classe responsabile della generazione del WSDL. Osservate l'id del bean: quello sarà il nome del WSDL. In parole povere, una volta pubblicato il servizio su Tomcat, il WSDL sarà accessibile all'url id].wsdl E' praticamente tutto, ma manca ancora quella cosa che avevo lasciato volutamente indietro. Se provate ad eseguire il progetto così com'è andrete incontro ad un errore a runtime. Il problema sta nella definizione del bean helloserviceendpointadapter. Dopo un bel po' di ricerche su web, ho trovato la soluzione sul forum della SpringCommunity. Sfortunatamente però non riesco più a ritrovarlo e non posso citare come merita l'autore della soluzione. Se per caso lo scoprite, fatemelo sapere. La soluzione è estendere una classe di Spring package it.innove.life.tutorials.spring.ws.marshalling.endpoints.adapters; import org.springframework.oxm.marshaller; import org.springframework.ws.server.endpoint.methodendpoint; import org.springframework.ws.server.endpoint.adapter.marshallingmethodendpointadapter; import org.springframework.ws.server.endpoint.annotation.payloadroot; public class PayloadMarshallingMethodEndpointAdapter extends MarshallingMethodEndpointAdapter public PayloadMarshallingMethodEndpointAdapter(Marshaller marshaller) super(marshaller);

9 @Override protected boolean supportsinternal(methodendpoint methodendpoint) return methodendpoint.getmethod().isannotationpresent(payloadroot.class); e sostituite quindi la classe specificata nel bean helloserviceendpointadapter con questa. Adesso è veramente tutto. Spero vi possa essere utile. Stefano stefano.cazzola@innove.it Note Nel codice sorgente allegato, i file e le classi potrebber chiamarsi in maniera differente Infine, voglio sottolineare che questo tutorial nasce dall'esperienza accumulata solo nell'ultima settimana, quando mi sono scontrato con molti tutorial ma tutti davano per contate molte cose e quindi sono stati per difficili da digerire. Voglio dire che sto ancora imparando anch'io e sono solo agli inizi; di conseguenza alcuni concetti potrebbero essere formalmente non del tutto corretti (o non corretti e basta...) nonostante che l'esempio sia funzionante. Qualsiasi correzione, osservazione, precisazione sarà molto gradita. Per maggiori informazioni (e spiegazioni più profonde) su Spring e Spring WS vi rimando al sito ufficiale dal quale è liberamente scaricabile tutta la documentazione