L'implementazione di JBoss dello stack JAXWS (java api per webservice) mette a disposizione diversi tool (JAX-WS Tools) per automatizzare i processi di generazione degli artefatti.
JAXWS è una specifica Java che mette insieme uno stack di tecnologie utile a definirne una nuova, ovvero Java Web Services: come si evince dall’acronimo, i package Java Web Services sono organizzati sotto il package javax.
Gli artefatti costituiscono l'insieme dei prodotti derivanti dal ciclo di sviluppo del software, dai diagrammi UML agli stubs e agli skeleton (gli oggetti che convogliano le richieste rispettivamente lato client e lato server assumendosi la responsabilità di implementare i meccanismi di comunicazione e risolvendo le relative problematiche), passando per quanto occorre per il deployng di un web service.
I principali tool sono
- JBossWS – wsprovide per generare gli artefatti e il contratto astratto partendo dal codice Java, usato nello sviluppo bottom-up
- JBossWS – wsconsume per generare gli artefatti lato client e lato server partendo dal contratto WSDL e dagli XML Schema, usato nello sviluppo top-down, quello che approfondiremo.
Come detto, JAXWS è una specifica Java e in quanto tale è stata implementata in diversi progetti: oltre all’implementazione di JBoss è possibile annoverare tra le implementazioni di rilievo quella offerta da Apache CXF. (Per ulteriori informazioni si prega di fare riferimento alle pagine del progetto seguendo il link Apache CXP Project Page).
L’articolo sarà costituito dalle seguenti sezioni:
- L'approccio Top-Down
- Precondizioni
- Creazione e consumo del contratto con relativo schema
- Creazione ed esecuzione del servizio e del client
- L’address location
L'Approccio Top-Down per i webservice
Un’istanza di Web Service può essere intesa come un sistema software predisposto a supportare l’interoperabilità tra elaboratori dislocati in rete; da un punto di vista ingegneristico, parliamo di un pattern tecnologico per implementare Service Oriented Architecture (SOA).
Tra i principali obiettivi dei sistemi service-oriented si annovera sicuramente la capacità di deployare sistemi su larga scala, a basso costo e di facile manutenzione. I Web Services costituiscono un enabler per l’approccio service-oriented, principalmente mediante l’utilizzo del protocollo applicativo HTTP come protocollo di comunicazione.
First Contract
La caratteristica fondamentale di un Web Service è quella di offrire un’interfaccia software, detta contratto (da ciò deriva l’altro nome dell’approccio qui presentato, First Contract), descritta in un formato elaborabile automaticamente: il WSDL (Web Services Description Language). Il contratto descrive l’interfaccia che astrae la Business Logic implementata dal servizio e abilita la comunicazione su di un protocollo standard quale è SOAP (Simple Object Access Procotol), che consente lo scambio di messaggi in formato XML sul protocollo di livello applicativo HTTP (con tutti i vantaggi che ne conseguono).
Sviluppando i Service Provider (costituiscono i fornitori di servizi, in contrapposizione con i Service Consumer che li utilizzano), è possibile partire dalla programmazione, ad esempio in Java, e si ha l’approccio bottom-up, o da un contratto astratto, il WSDL, che definisce cosa offre il servizio, e si ha l’approccio top-down.
Entrambi gli approcci hanno dei pro e dei contro.
L’approccio bottom-up è utile in caso di semplici servizi e se non si ha già il contratto (il framework JAXWS avrà la responsabilità di generare automaticamente il contratto partendo dal codice annotato), è un approccio rapido e offre il vantaggio di metter mano direttamente al codice (aspetto da non trascurare e che nei primi tempi può risultare utile).
Di contro, ad esempio nel caso di servizi più complessi, può risultare utile partire dal contratto e utilizzare appositi tool per la realizzazione delle interfacce e delle classi di base che utilizzeremo per sviluppare il servizio, con notevole risparmio di tempo con il crescere della complessità dell’endpoint e della logica di business dietro le scene.
Riassumendo, l’approccio bottom-up è usabile quando si vuole:
- esporre un EJB3 bean come un Web Service
- fornire un servizio generando il contratto partendo dal codice
L’approccio top-down, invece, è impiegabile se si vuole:
- rimpiazzare un Web Service esistente senza perdere la compatibilità con i vecchi clients
- esporre un servizio conforme a un contratto specificato da terze parti
- creare un servizio aderente all’XML Schema e a un WSDL posseduti
L’implementazione JAXWS1 di riferimento per questo articolo è JbossWS ovvero l’implementazione dello stack fornita dalla community JBoss. E’ possibile scaricarlo all’indirizzo http://www.jboss.org/jbossws/downloads/, oppure è già a disposizione se si è già installato JBoss AS.
(Le versioni di riferimento per l’articolo sono JBoss AS 6.X e conseguentemente JBoss WS 3.4.1 GA.)
Precondizioni
Assicurarsi di avere correttamente installato sul computer il Java Development Kit (JDK 6 Update 24 o successiva). E’ necessario avere JBoss WS e consigliato avere JBoss AS 6.X. Si assume che siano state correttamente impostate tra le variabili d’ambiente la JAVA_HOME e la JBOSS_HOME e che sia stata aggiornata la variabile di sistema Path. Si fa inoltre riferimento a Eclipse (a partire dalla versione Helios Sr2 3.6.2) e relativo kit di JBoss Tools scaricabile mediante l’Eclipse Marketplace.
E’ inoltre utile avere conoscenze basiche sull’argomento, quindi occorre aver affrontato l’argomento WSDL, consigliamo la lettura "gli elementi di un documento WSDL".
Creazione e consumo del contratto con relativo schema
Il contratto che ci apprestiamo a creare serve a definire cosa offre il servizio. Può contenere al suo interno anche la definizione dei tipi, ma spesso si preferisce (o si deve utilizzare) uno o più XML Schema Definition (XSD) che raccolgono tali definizioni.
Vediamo allora i passi per creare e consumare un contratto.
creazione della cartella di lavoro
Creazione di una cartella di lavoro, per l’esempio utilizzeremo il nome esempioDidattico.
Popoliamo la cartella appena creata con due file. Lo schema, un file XSD che chiameremo “schema”, e il contratto, un file WSDL che chiameremo “documento”. Se non si dispone di questi tipi di file creare un nuovo file txt, e tramite opzione “salva con nome” impostare i nuovi nomi avendo cura di inserire anche il tipo di file (per windows: racchiudendo il tutto tra virgolette, ossia “schema.xsd” e “documento.wsdl”).
il contenuto della cartella Esempio Didattico
il file schema.xsd
Popolare il file XSD con:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<xs:schema
xmlns:schema="http://www.prova.schema.com/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.prova.schema.com/">
<xs:import namespace="http://www.w3.org/2001/XMLSchema" />
<xs:element name="Presentazione">
<xs:complexType>
<xs:sequence>
<xs:element name="Nome" type="xs:string" />
<xs:element name="Cognome" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="PresentazioneRisposta">
<xs:complexType>
<xs:sequence>
<xs:element name="Risposta" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>Nello schema mostrato ci si è limitati a definire due tipi di dati complessi, Presentazione basato su due stringhe chiamate Nome e Cognome, e PresentazioneRisposta, basato su una semplice stringa chiamata Risposta.
il documento.wsdl
Popolare il file WSDL con:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<definitions name="ProvaTopDown"
targetNamespace="http://www.prova.documento.com/"
xmlns:tns="http://www.prova.documento.com/"
xmlns:schema="http://www.prova.schema.com/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<types>
<xsd:schema targetNamespace="http://www.prova.documento.com/">
<xsd:import namespace="http://www.prova.schema.com/" schemaLocation="schema.xsd" />
</xsd:schema>
</types>
<message name="Presentazione">
<part name="parameter" element="schema:Presentazione" />
</message>
<message name="PresentazioneResponse">
<part name="parameter" element="schema:PresentazioneRisposta" />
</message>
<portType name="ServizioPresentazioneIF">
<operation name="Presentazione">
<input message="tns:Presentazione"/>
<output message="tns:PresentazioneResponse"/>
</operation>
</portType>
<binding name="ServizioPresentazioneImplPortBinding" type="tns:ServizioPresentazioneIF">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="Presentazione">
<soap:operation soapAction=""/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
</operation>
</binding>
<service name="PresentazioneService">
<port name="ServizioPresentazioneImpl" binding="tns:ServizioPresentazioneImplPortBinding">
<soap:address location="http://localhost:8080/Presentazione/PresentazioneService/ServizioPresentazioneIF"/>
</port>
</service>
</definitions>Il servizio offerto da questo contratto si limita a inviare un messaggio di risposta nel caso arrivi al web service un messaggio di presentazione. Per la descrizione degli altri parametri impostati, ad esempio “binding style”, si rimanda alla guida WSDL precedentemente introdotta. Il messaggio di presentazione è basato sui campi Nome e Cognome, la cui descrizione è contenuta nell’XML Schema realizzato in precedenza.. Si sottolinea che nel contratto ci si è limitati a definire cosa succede, il come verrà definito successivamente.
Consumare il contratto dei webservice con wsconsume
E’ ora il momento di consumare il contratto. Per farlo, attivare una shell dei comandi (per windows: tasto Windows+R, quindi digitare cmd e premere OK o Invio da tastiera).
Spostarsi nella directory dove è contenuto il file documento.wsdl (cd [eventualePath]/esempioDidattico). E’ possibile ora inserire e lanciare il comando:
wsconsume documento.wsdl
Dopo un messaggio di warning che avverte l’utente circa l’assenza di un file per l’inizializzazione del logging log4j, sarà possibile vedere che il tool wsconsume richiama a sua volta il tool wsdl2java.
Osserviamo ora cosa è stato generato. Per prima cosa notiamo che sono state generate due cartelle, com contenente i sorgenti java e output contenente gli stessi file compilati.
A un’analisi più approfondita della cartella dei sorgenti, osserviamo che c’è una cartella “schema” e una “documento”. Vediamo cosa è possibile trovare nella prima.
Nella sottocartella prova si trovano quattro file, uno è il descrittore del package (package-info), l’Holder delle annotazioni JAXB, con la responsabilità di importare le librerie contenenti le annotazioni JAXB necessarie al Web Service descritto. Poi vi sono due file Presentazione e PresentazioneRisposta, sono le due classi che offrono la struttura dati con i relativi metodi di get e set per i tipi di dato che abbiamo definito in precedenza nell’XSD.
Infine c’è l’ObjectFactory. Costituisce l’implementazione di un design pattern (Object Factory Design Pattern) e ha lo scopo di permettere di creare oggetti a tempo d’esecuzione in risposta ad azioni dell’utente o di un flusso di informazioni, oggetti che al tempo della compilazione risultano di tipo sconosciuto. Più in dettaglio, fornisce i metodi Factory per le interfacce generate nel package com.schema.prova, permettendo la generazione di nuove istanze delle operazioni definite nello schema.
Ora invece esaminiamo il contenuto della cartella documento. Nella sottocartella prova vi troviamo i file ServizioPresentazioneIF e PresentazioneService. Le due classi rappresentano gli stubs rispettivamente lato server e lato client che permettono allo sviluppatore di implementare il servizio e la richiesta di servizio come se si stesse lavorando in locale, ossia tramite semplici operazioni su oggetti locali. Negli screenshots seguenti vengono mostrati gli artefatti che verranno generati.
sesempio didattico: artefatti, schema
sesempio didattico: artefatti, documento
Nella prossima parte vedremo come generare il codice delle classi, per completare il progetto.
Creazione del servizio e del client
Abbiamo finora provveduto alla definizione del contratto e delle informazioni che viaggeranno in rete, generando con il tool wsconsume le rispettive classi. Restano da implementare il web service che andrà ad esporre il servizio, la logica applicativa e un client.
I primi passi della creazione del servizio e del client sono per molti aspetti simili, per cui vengono presentati in parallelo. Per prima cosa si descrivono le operazioni per avviare i due progetti servizio e client. Si assume si stia usando Eclipse come specificato nelle precondizioni, visualizzando la prospettiva Java EE e avendo già impostato un Server JBoss AS 6.X
Creazione dei due progetti
Server
Selezioniamo: File -> new -> dynamic web project, chiamando il progetto Documento. Assicurarsi che il progetto punti al server JBoss già creato (voce Target Runtime).
Per questo esempio si può utilizzare per il server la configurazione default. Per la voce dynamic web module version, impostare 3.0 se necessario. Se non altrimenti specificato, il verrà effettuato il deploy del servizio nel workspace metadata di Eclipse, senza modificare la cartella di deploy di JBoss (si approfondirà questo aspetto successivamente).
Client
Selezioniamo: File -> new -> Project -> Java Project, chiamando il progetto DocumentoClient.
Scegliere NO se si apre una finestra nella quale si chiede di cambiare prospettiva.
Importazione dei file generati con wsconsume
Importare i file sorgenti creati con il comando wsconsume:
Server
Click con il tasto destro sulla directory Documento/Java Resources/src -> Import -> General/File System
Nel wizard attivato, premere su browse e selezionare la cartella che contiene i file generati automaticamente (nel nostro esempio è la cartella esempioDidattico) quindi premere ok. Tornati nella finestra Import, esplorare la directory (tasto +) e spuntare la sola voce com, quindi premere finish. Per il nostro progetto è sufficiente importare i sorgenti.
Client
Premere con il tasto destro sulla directory DocumentoClient/src -> Import -> General/File System
Nel wizard attivato, premere su browse e selezionare la cartella che contiene i file generati automaticamente per poi premere OK. Tornati nella finestra Import, esplorare la directory e spuntare la sola voce com, quindi premere finish.
Importazione manuale (opzionale)
Se vengono segnalati errori (una croce rossa sull’icona della cartella src) occorre importare manualmente due librerie. Ciò andrà fatto sia nel progetto client che in quello server:
- premere con il tasto destro sul progetto, selezionare:
Properties -> Java Build Path -> scheda Libraries -> Add External JARs. A questo punto portarsi nella cartella che contiene il JBoss installatoJBoss/lib/endorsed - importare le seguenti librerie:
- jboss-jaxb-api_[vers]_spec
- jboss-jaxws-api_[vers]_spec
- sempre nel Java Build Path accedere alla scheda
Order and Export, spuntare le due librerie appena importate e premere su Top, quindi premere su OK. Dopo qualche attimo verrà rimossa la crocetta rossa
Creazione delle classi
Creare un nuovo package lato server e client:
Server
Selezioniamo con il tasto destro sulla cartella Documento/Java Resources/src -> new -> Package, lo chiamiamo wsServer
Client
poi, con tasto destro sulla cartella DocumentoClient/src -> new -> Package, lo chiamiamo wsClient
E’ possibile che il Package appena creato non compaia nella cartella src ma sotto Libraries. Non è un problema ma se si vuole visualizare correttamente la posizione del package appena creato è sufficiente eseguire un refresh del progetto (tasto destro sul progetto e scegliere Refresh).
Creazione della classe lato server.
Con il tasto destro sulla cartella wsServer -> new -> class, la chiamiamo ServizioPresentazione:
package wsServer;
// import ...
@WebService(targetNamespace = "http://www.prova.documento.com/", name = "ServizioPresentazioneIF")
@Remote(ServizioPresentazioneIF.class)
@Stateless
@SOAPBinding (
style = SOAPBinding.Style.DOCUMENT,
use = SOAPBinding.Use.LITERAL
)
public class ServizioPresentazione implements ServizioPresentazioneIF{
@WebMethod
public String presentazione(String nome, String cognome) {
System.out.println("Web service, arrivata presentazione "+
"da parte di: "+nome+" " + cognome+"nn");
String risposta = "Ciao "+nome+"!";
return risposta;
}
}Creazione della classe lato client.
Con il tasto destro sulla cartella wsClient -> new -> class, la chiamiamo ServizioClient
package wsClient;
// import ...
public class ServizioClient {
public static void main(String[] args) throws Exception {
URL wsdlURL = new URL("http://localhost:8080/Documento/ServizioPresentazioneIF?wsdl");
QName serviceName = new QName("http://www.prova.documento.com/", "ServizioPresentazioneService");
PresentazioneService servizio = new PresentazioneService (wsdlURL, serviceName);
ServizioPresentazioneIF port = servizio.getPort(ServizioPresentazioneIF.class);
String nome = "Pippo";
String cognome = "de Pippis";
System.out.println(nome+" "+cognome+" effettua la presentazione. ");
String risposta=port.presentazione(nome, cognome);
System.out.println("Risposta ottenuta: "+risposta);
}
}deployment
Possiamo ora effettuare il deployng sul server. Tasto destro sul server JBoss nella scheda Servers, quindi selezionare Add and Remove e aggiungere il servizio Documento. Avviare il server. Il servizio aggiunto lo potremo vedere all’indirizzo:
http://localhost:8080/jbossws/services
Non appena il server ha concluso le procedure di avviamento e il servizio è deployato, potremo eseguire il client. Per farlo, nel package DocumentoClient/src/wsClient premere con il tasto destro sulla classe ServizioClient -> Run As -> Java Application.
A questo punto è possibile fare alcune osservazioni. Per prima cosa, una volta attivata la scheda Console, è possibile muoversi tra la console del server e quella del client premendo sull’icona a forma di schermo che si trova a destra della scheda. Premendo sulla piccola freccia verso il basso subito a destra dell’icona sarà possibile selezionare la console da mostrare. L’icona è indicata dal cerchietto rosso in basso a destra nello screenshot mostrato di seguito.
esempio didattico: la console
Potremo così osservare dallo standard output la sequenza dei messaggi scambiati. Ripetendo l’esecuzione del client, all’indirizzo:
http://localhost:8080/jbossws/services
(se la pagina è già caricata effettuarne un aggiornamento, tasto F5) sarà possibile osservare che il numero di richieste arrivate dal client cresce. Sono disponibili in questa schermata altre informazioni utili come il nome dell’endpoint, il contesto, i tempi minimi, medi e massimi di risposta.
Per fare qualche ulteriore prova è possibile modificare nella classe ServizioClient la variabile nome immettendo ad esempio Pluto al posto di Pippo e vedendo che il servizio si limita a rispondere come previsto.
L’implementazione decisa per il servizio descritto nel file WSDL è semplicemente consistita nel creare una stringa di saluto in risposta alla stringa di presentazione.
E’ possibile ora arrestare il server.
Deployment con Eclipse o JBoss
Si è detto in precedenza che il servizio verrà deployato usando il workspace dell’IDE Eclipse. E’ invece possibile effettuare il deployment utilizzando le cartelle di JBoss o un percorso specifico. Per far ciò, attivare la scheda Servers e cliccare due volte con il tasto sinistro del mouse sul server JBoss. Si attiverà la scheda descrittiva del server ove saranno rese disponibili diverse informazioni come il nome del server e dell’host, i porti e così via. E’ possibile passare alla scheda Deployment (le posizioni di queste schede e delle opzioni descritte sono evidenziate nella figura seguente) dove sarà possibile impostare la posizione di deployment voluta. Ipotizziamo di voler usare la cartella di JBoss. Spuntiamo la relativa voce, ricordiamo di salvare ed è possibile uscire dalla scheda aperta.
Utilizziamo l’opzione l’opzione del server “Clean”. Sempre tra le opzioni del server, premere su Show In/File Browser, verrà visualizzata la cartella di deploy di Jboss, al suo interno vi sarà la cartella Documento.war
Ora è possibile scegliere se continuare a effettuare il deployment nella cartella di JBoss o tornare ad utilizzare la cartella di Eclipse.
esempio didattico: JBoss deployment
L’address location
Abbiamo creato e consumato il contratto. Realizzato un servizio e un client che lo utilizza, verificato il funzionamento, deciso dove deployarlo. Abbiamo finito? Non necessariamente.
Perché? Osserviamo l’address location indicata dal contratto:
http://localhost:8080/Presentazione/PresentazioneService/ServizioPresentazioneIFE ora osserviamo quello effettivo, indicato nella schermata http://localhost:8080/jbossws/services alla voce Endpoint Address:
http://localhost:8080/Documento/ServizioPresentazioneIF
Le due voci sono disallineate. Questo significa che se il client volesse utilizzare il solo contratto per ottenere il percorso effettivo non potrebbe farlo.
L’endpoint address viene infatti costruito basandosi sulle informazioni del progetto, Documento non a caso è il nome scelto per il progetto. Il web service dovrebbe però essere conforme al contratto e pertanto dovrebbe esporre il servizio utilizzando il percorso indicato.
Per renderlo coerente con quanto dichiarato, nella classe ServizioPresentazione occorrerà modificare l’annotazione @WebService e aggiungerne un’altra nel seguente modo:
@WebService(targetNamespace="http://www.prova.documento.com/", serviceName="PresentazioneService",
wsdlLocation="WEB-INF/wsdl/documento.wsdl",
portName="ServizioPresentazioneImpl",
name="ServizioPresentazioneIF")
@WebContext(contextRoot="/Presentazione")L’annotazione aggiunta richiederà di importare la relativa libreria: import org.jboss.wsf.spi.annotation.WebContext
Ora proviamo a riavviare il server dopo averne effettuato il Clean. Viene sollevata un’eccezione:
faultCode=PARSER_ERROR: Problem parsing 'WEB-INF/wsdl/documento.wsdl'
L’eccezione ci informa che non è stato trovato un file. Andando a modificare l’annotazione @WebService abbiamo infatti sovrascritto le informazioni circa la posizione effettiva del contratto. Per ovviare a tale situazione occorrerà importare il contratto astratto, e conseguentmente l’XML schema, nella posizione indicata. Vedremo ora come fare.
Dopo aver arrestato il server:
- Selezioniamo con il tasto destro su
Documento/WebContent/WEB-INF -> New -> Folder, digitare wsdl e premerefinish. Verrà creata una cartella wsdl destinata ad accogliere il contratto. - tasto destro su Documento/WebContent/WEB-INF/wsdl -> import -> General/File System quindi premere su Next ed esplorare la cartella esempioDidattico. Importare i file
documento.wsdleschema.xsd, quindi premereFinish. I file di default verranno sottoposti a validazione, ma tramite le opzioni del progetto è possibile evitarlo (Properties -> Validation). - tasto destro su
Documento/WebContent/META-INF -> New -> Folder, digitare wsdl e premere FINISH. Verrà creata una cartella wsdl destinata ad accogliere lo schema. - 4. tasto destro su
Documento/WebContent/META-INF/wsdl -> import -> General/File Systemquindi premere su Next ed esplorare la cartella esempio Didattico. Tra i file, scegliere di importare il fileschema.xsd, quindi premereFinish. - Modificare nel client:
- Il wsdlURL diviene:
http://localhost:8080/Presentazione/PresentazioneService/ServizioPresentazioneIF?wsdl - Il secondo parametro del serviceName diviene invece:
PresentazioneServiceDopo la modifica dell’URL, questo ricalca la voceaddress locationcontenuta nel contratto astratto. E’ anche possibile ricavarlo automaticamente. - Rimuovere il vecchio servizio dal server e aggiungere quello modificato (
Add and Removeoppure direttamenteClean), successivamente startare il server. Sarà possibile vedere che il servizio viene attivato. Eseguire il client per riprova.
Accedendo nuovamente alla schermata di gestione del servizio è possibile notare che, al contrario del precedente URL, il nuovo URL ricalca fedelmente quello contenuto nell’address locationdel contratto wsdl. Di riflesso, il vantaggio lato client è di poter accedere al servizio facendo affidamento sulle informazioni contenute nel contratto.
Conclusioni
L’approccio top-down consiste nel realizzare un Web Service partendo da un contratto astratto, utilizzato per generare gli artefatti, realizzando successivamente la logica applicativa. Nell’articolo si è mostrato come e perché utilizzare questo approccio, descrivendo i primi passi attraverso un semplice esempio creato per l’occasione.
Svolgendo gli esempi si sono affrontati diversi aspetti complementari, come la scelta della cartella per il deployng del servizio e come e perché importare il contratto nel progetto del servizio, modificando conseguentemente le classi lato server e lato client per supportare tale modifica.
- Il wsdlURL diviene:
