# JAX-WS

JAX-WS (Java API for XML Web Services) è un insieme di interfacce (API) del linguaggio di programmazione Java dedicate allo sviluppo di servizi web. L'insieme fa parte della piattaforma Java EE. Come altre API della Java EE, JAX-WS usa annotazioni, introdotte nella Java SE 5, per semplificare lo sviluppo e implementazioni di client e terminali di servizi web. JAX-WS fa parte del kit di sviluppo Java per Web service (Java Web Service Development Pack – JWSDP) e include Java Architecture for XML Binding (JAXB) e SOAP. Uno dei grandi vantaggi di questa implementazione è quella di poter riutilizzare gran parte delle funzionalità, senza toccare server enterprise come il progetto Glassfish.

## Descrizione

JAX-WS è un nuovo modello di programmazione che semplifica lo sviluppo delle applicazioni attraverso il supporto di un modello standard, annotation-based, per sviluppare Web service application e client. Le specifiche di JAX-WS si allineano strategicamente con la tendenza attuale del settore verso un modello di messaggistica più document-centric e sostituisce il modello di chiamata di procedura remota (object-centric model) come definito da JAX-RPC.
Con un servizio document-centric, la logica di fatto viene tenuta separata dal contenuto del documento. Il servizio riceve un documento XML, che contiene solo dati. I metodi specifici non vengono richiamati, ma il Web service applica la sua logica di business al documento, il cui contenuto determina il flusso di lavoro di elaborazione. Il web service di un'agenzia di viaggi è un buon esempio di servizio document-centric. Il servizio riceve una richiesta: un documento XML che contiene i dettagli dell'itinerario di viaggio che si desidera effettuare (date, luoghi da visitare, alloggio preferito, e così via), il servizio elabora la richiesta in base al contenuto del documento. JAX-WS è il modello di programmazione strategica per lo sviluppo di servizi Web. L'implementazione dello standard di programmazione della JAX-WS fornisce importanti miglioramenti come: migliore indipendenza della piattaforma per le applicazioni Java, annotazioni, richiamare i servizi Web in modo asincrono, client dinamici e statici, Supporto per il Message Transmission Optimized Mechanism (MTOM, metodo di trasmissione di dati binari da e verso Web service), il supporto per SOAP.
Il progetto fornisce il nucleo del progetto Metro (stack di Web service di alto rendimento, espandibile, facile da usare, che raccoglie le funzionalità che racchiudono tutte le esigenze per la creazione di servizi web), all'interno della comunità GlassFish.

## Storia

I Web service, fin dalla loro comparsa, si sono proposti come la soluzione principe nella realizzazione di architetture interoperabili, interconesse e integrabili tra loro. La vera innovazione è stata quella di fare uso di standard aperti utilizzando XML e HTTP (modello SOAP), insieme alla presenza del Web Services Description Language (WSDL) e introduzione di un sistema di ricerca/pubblicazione (UDDI). Sebbene da un lato questo progetto ricevesse una spinta in avanti nello sviluppo, dall'altro vi furono forti elementi di impedimento: i vari produttori e soggetti, che partecipavano allo sviluppo di componenti e implementazioni per Web service, hanno ostacolato questo processo impedendo agli organismi preposti alla definizione di standard e specifiche di rimanere al passo. Questo portò alla creazione di specifiche e implementazioni proprietarie, contrarie e contraddittorie agli obiettivi iniziali della realizzazione di Web service.
Nel 2003 i vari produttori, ormai consapevoli di come fosse privo di senso avere Web service scritti in linguaggi diversi, si sono riuniti per cercare una soluzione a questo problema. Nasce così la WS-I Organization (Web Services Interoperability Organization) volta, come dice il nome, ad assicurare l'interoperabilità dei servizi web. Nel giro di poco tempo tutti i più importanti protagonisti del settore aderirono, al fine di creare un nuovo standard che garantisse i principi originari dei Web service. Il consorzio operò alla ricerca e selezione del sottoinsieme minimo di standard e specifiche comuni a tutte le implementazioni, che furono poi raggruppati e raccolti in profili a seconda degli obiettivi che si volevano raggiungere, opera tuttora in corso. In ambito WS-I, Sun ha prodotto recentemente una nuova implementazione chiamata WSIT, che consiste nel Java API for XML Web Services.

## Differenze tra JAX-WS e JAX-RPC

Anche se le radici di JAX-WS vengono da JAX-RPC, il primo è un componente completamente diverso da quest'ultimo. Una delle differenze principali tra i due è il modello di programmazione: un servizio web basato su JAX-WS utilizza annotazioni (ad esempio @WebService) per dichiarare endpoint di servizi web, mentre JAX-RPC usa la procedura di Invocazione remota dei metodi (RMI). JAX-WS ha il supporto per l'invio di messaggi XML su HTTP. L'uso delle annotazioni evita la necessità di deployment descriptor. Inoltre il JAX-WS presenta altre funzionalità aggiuntive come callback asincroni. Sebbene vi siano numerose differenze, JAX-WS e JAX-RPC possono coesistere senza problemi.

## Esempio

Ora vediamo un breve esempio di creazione di un semplice Web service JAX-WS. Scriviamo ad esempio un semplice programma che calcoli l'area e il perimetro di un poligono regolare, creiamo quindi una classe “FunzioniPoligoniRegolari”, in cui definiamo l'interfaccia astratta “MioWs” al cui interno dichiariamo i metodi che andremo ad implementare; poi creiamo il nostro main.
Endpoint.Publish(String address, Object implementor) è un metodo che crea e pubblica un endpoint per l'oggetto “implementor” al dato indirizzo “address”.
Da notare che lo schema WSDL viene così creato automaticamente. Creiamo inoltre la classe “Implementazione” dove implementeremo i metodi dichiarati nella precedente classe astratta.
Una volta compilato il codice sorgente usando il comando javac, bisogna effettuare un ulteriore passo: chiamare il tool Wsgen come di seguito:
Il main attiva un server http sulla porta fissata (nel nostro caso 8080). Quando l'applicazione viene eseguita, Java SE 6 ha una piccola applicazione server web che pubblicherà il Web service all'indirizzo dato http://localhost:8080/funzioncerchio mentre la JVM è in esecuzione. Possiamo verificare che il Web service è in esecuzione visualizzando il file Web Services Description Language (WSDL) del Web service “funzionicerchio”. Mentre la JVM è in esecuzione, apriamo un browser e andiamo al seguente indirizzo: http://localhost:8080/funzionicerchio?WSDL Se si vede un gran ammontare di righe XML che descrivono le funzionalità dietro a questo servizio web, allora la realizzazione ha avuto successo.

## Annotazioni

Alcune delle annotazioni più utilizzate sono:
* @WebService Marca una classe o un'interfaccia Java rispettivamente come una implementazione o una definizione di un Web service. A questa possono essere specificati alcuni attributi come:
** name: nome del wsdl: portType (nome della classe Java priva di package)
** portName: nome del wsdl: portName (nome del WebService concatenato a Port)
** serviceName: nome del servizio (wsdl:service) (nome della classe concatenato alla Stringa “Service”)
** endpointInterface: (es. endpointInterface = "package.MioSOAP.MioWS") specifica il nome completo della SEI (“Service endpoint Interface”, interfaccia Java che dichiara i metodi che un client può invocare sul servizio) endpointInterface: (classe java, comprensiva del package, concatenata alla Stringa “ServicePortType”)
** targetNamespace: namespace di riferimento per il WSDL e gli XML generati (nome del package java)
** wsdlLocation: l'indirizzo documento WSDL del Web service. L'indirizzo può essere relativo o assoluto.
* @WebMethod Posta sopra la firma del metodo, dice all'interprete Java che si intende pubblicare questo metodo come un Web service. Il corrispettivo metodo dovrà essere dichiarato “public” e dovrà restituire qualcosa (nel nostro caso restituisce un double). Anche questa ha alcuni attributi come:
** action: definisce l'azione per l'operazione. ( = al nome del metodo)
** exclude: specifica se il metodo va escluso dalla pubblicazione del Web service. (es. ”false”) (Booleano)
** operationName: specifica il nome di wsdl: operation per il metodo (nome del metodo)
* @SOAPBinding Specifica la mappatura del Web service nel protocollo di messaggi SOAP. In particolare si vede nel costrutto tra parentesi lo stile dei messaggi scelto. In caso i metodi del Web service utilizzino tipi semplici come String o int è possibile utilizzare l'annotazione “@SOAPBinding(style=Style.RPC)” come nel nostro esempio.

## Wsgen

Il comando della riga comandi wsgen genera gli artefatti portatili usati nei servizi web JAX-WS. Questo strumento legge una classe endpoint di un servizio web e genera tutti gli artefatti richiesti per la generazione e invocazione del Web service. Wsgen genererà un file WSDL solo quando viene richiesto. L'opzione -cp specifica dove trovare la classe di implementazione del servizio. Questo tool genererà un certo numero di file sorgenti in una sottocartella chiamata wsgen, che poi compila. Sebbene non sia richiesto modificare questi file, è possibile vedere come il JAX-WS crei i file stub che usa nella pubblicazione del Web service cercando i loro codici sorgenti. I file originali devono trovarsi nel rispettivo package quando si chiama lo strumento Wsgen. In caso contrario è possibile che si manifesti un errore che dice che la classe in cui è presente l'annotazione “@WebService”, come FunzioniCerchio, debba dichiarare separatamente javax.jws.Webservice.targetNamespace element perché i file dei codici sorgenti non fanno parte del package.

## JAX-WS handlers

Gli handler (gestori) JAX-WS sono intercettori che possono essere collegati all'ambiente di esecuzione JAX-WS per fare ulteriori elaborazioni dei messaggi in entrata e in uscita. Essi sono indipendenti dal codice di livello di applicazione e in grado di fornire funzionalità di basso livello di elaborazione dei messaggi. JAX-WS definisce due tipi gestore di base: i gestori di logica e i gestori di protocollo. I primi sono in grado di elaborare il payload del messaggio e le proprietà di memorizzazione nel contesto del messaggio. I secondi operano sulle proprietà del contesto del messaggio e i messaggi di specifici protocolli. Sono limitati a configurazioni specifiche di SOAP e sono spesso indicati come "gli handler SOAP". Un handler è assemblato in una catena di gestori conosciuta come catena di handler. Sul lato client, è possibile configurarle programmaticamente. Sul lato server si utilizza l'annotazione @HandlerChain per fare riferimento a un file di configurazione XML che descrive i gestori che sono inclusi.