Il primo passo per la costruzione di un documento wsdl di un Web Service è quello di definirsi i tipi degli elementi in esso contenuti. Abbiamo già definto lo schema XSD di messaggio di ordine:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    
    <xs:complexType name="ordineType">
        <xs:sequence maxOccurs="unbounded">
            <xs:element name="articolo" type="articoloType"/>
        </xs:sequence>
    </xs:complexType>
    
    <xs:complexType name="articoloType">
        <xs:sequence>
            <xs:element name="nome" type="nomeType"/>
            <xs:element name="quantita" type="integer"/>
        </xs:sequence>
    </xs:complexType>
    
    <xs:simpleType name="nomeType">
        <xs:restriction base="xs:string">
            <xs:pattern value="[A-Za-z]{10}"/>
        </xs:restriction>
    </xs:simpleType>
        
</xs:schema>
            

Importiamolo e aggiungiamo i tipi mancanti per l'operazione di notifica

Nota

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ord="http://www.rivenditore.org/ordine" targetNamespace="http://www.rivenditore.org/rivenditore" <wsdl:import namespace="http://www.rivenditore.org/ordine" location="submitOrdine.xsd" /> <wsdl:types> <xsd:schema targetNamespace="http://www.rivenditore.org/ordine" <xsd:element name="ordine" type="ordineType"/> </xsd:schema> </wsdl:types> ... </wsdl:definitions>

Descritti i tipi, possiamo definire i messaggi scambiati. Il nostro servizio ha un solo messaggio SOAP scambiato, quello di consegna dell'ordine.

<wsdl:definitions 
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.rivenditore.org/ordine" ...>
    
   <wsdl:types> ... </wsdl:types>
   
   <wsdl:message name="ordineMessage">
      <wsdl:part name="ordine" element="ele:ordine"/>
   </wsdl:message>
   
</wsdl:definitions>
            

Il passo successivo sarà definire le interfacce. L'elemento portType definisce un gruppo di operazioni. Il nome portType è sviante ci riferiremo a questo elemento spesso con il nome "interfaccia". Ogni wsdl:operation dell'interfaccia contiene una combinazione di elementi wsdl:input e wsdl:output e opzionalmente un wsdl:fault. L'ordine di questi elementi definisce il Message Exchange Pattern (MEP) dell'operazione.

	Avvertimento
	La specifica WS-Interoperability fornisce una serie di line guida per garantire una maggiore interoperabilità tra diverse piattaforme, sistemi operativi e linguaggi di programmazione. Una di queste regole dice di non utilizzare i MEP Solicit-Response e Notification.

Come detto in precedenza, l'operazione esposta dal nostro servizio prevede di ricevere un messaggio contenente un ordine, ma di non inviare messaggi SOAP di risposta, quindi un MEP di tipo Oneway. Vediamo come descrivere tale operazione.

<wsdl:definitions 
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.rivenditore.org/ordine" ...>
    
    <wsdl:types> ... </wsdl:types>
    
    <wsdl:message> ... </message>
    
    <wsdl:portType name="ordineInterface">
    
        <wsdl:operation name="ordine">
            <wsdl:input message="ord:ordineMessage"/>
        </wsdl:operation>
        
    </wsdl:portType> 

</wsdl:definitions>
            

L'interfaccia è sempre considerata astratta da momento che non sa come saranno rappresentati i messaggi "sul cavo" finchè non sarà definito il binding che specifica, tra le altre cose, il protocollo di trasporto (nel nostro caso HTTP).

L'elemento wsdl:binding descrive i dettagli concreti per utilizzare una particolare interfaccia (portType) con uno specifico protocollo. La struttura di base dell'elemento binding è la seguente:

<wsdl:definitions .... >
    <wsdl:binding name=".." type=".."> 
        
        <wsdl:operation name=".."> 
           
           <wsdl:input name=".." > 
               ..
           </wsdl:input>
           <wsdl:output name=".." > 
               ..
           </wsdl:output>
           <wsdl:fault name=".."> 
               ..
           </wsdl:fault>
           
        </wsdl:operation>
    </wsdl:binding>
</wsdl:definitions>
                

L'attributo name, come per gli altri elementi, specifica un nome per riferirsi al binding nel resto del documento. Il type deve specificare un portType precedentemente definito. Nel nostro esempio possiamo inserire un binding chiamato ordineInterfaceBinding per l'interfaccia ordineInterface:

<wsdl:definitions 
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://www.rivenditore.org/ordine" ...>
   ...
    <wsdl:binding name="ordineInterfaceBinding" type="ordineInterface">
        ... 
        <wsdl:operation name="ordine">
            ... 
            <wsdl:input>
                ... 
            </wsdl:input>
        </wsdl:operation>
    </wsdl:binding>
    ...
</wsdl:definitions>
                

L'elemento wsdl:binding è generico. Definisce solamente il framework per descrivere i dettaggli di binding. Questi dettagli sono forniti utilizzando degli elementi estensivi. Le specifiche WSDL forniscono alcuni elementi predifiniti per descrivere il binding SOAP, anche se sono in un diverso namespace (http://schemas.xmlsoap.org/wsdl/soap/). Vediamo come fare un SOAP/HTTP binding per la nostra interfaccia:

<wsdl:definitions
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://www.rivenditore.org/ordine" ...>
   ...
  <wsdl:binding name="ordineInterfaceBinding" type="ordineInterface">
       <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
       <wsdl:operation name="ordine">
          <soap:operation soapAction=""/>
          <wsdl:input>
             <soap:body use="literal"/>
          </wsdl:input>
       </wsdl:operation>
   </wsdl:binding>
   ...
</wsdl:definitions>

l'elemento soap:binding indica lo stile usato per la rappresentazione del messaggio (i valori possibili sono document o rpc) rispetto al protocollo di trasporto richiesto (HTTP nel nostro caso). L'elemento soap:operation definisce il valore dell'header HTTP SOAPAction. Infine l'elemento soap:body descrive come i part del messaggio devono essere serializzati all'interno del messaggio (valori possibili literal o encoded).

Maggiori informazioni su queste caratteristiche sono presentate nella lezione sui web services.

L'elemento wsdl:service definisce una collezione di porte, o endpoint, che espone un particolare binding:

<wsdl:definitions .... >
    <wsdl:service name="..."> 
        <wsdl:port name="..." binding="..."> 
           ...
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

Per ogni porta dobbiamo fornire un nome da utilizzare come riferimento ed un binding tra quelli definiti in precedenza. Poi possiamo aggiungere elementi estensivi che definiscono i dettagli per l'indirizzamento specifici del binding.

<wsdl:definitions 
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:xs="http://www.w3.org/2001/XMLSchema" 
  targetNamespace="http://www.rivenditore.org/ordine" ...>
   ...
   <wsdl:service name="ordineService">
      <wsdl:port name="ordineInterfaceEndpoint" binding="ord:ordineInterfaceBinding">
         <soap:address location="http://www.rivenditore.org/ordine"/>
      </wsdl:port>
   </wsdl:service>
</wsdl:definitions>

wsdlvalidator service.wsdl

Ci sono due possibilità per scrivere applicazioni di questo tipo:

In entrambi questi casi, è quindi possibile usare i Web Services in maniera trasparente dal linguaggio di programmazione, in modo tale che per ogni operazione supportata dal servizio sia semplicemente necessario invocare un metodo java sul lato client e implementare un metodo java sul lato server.

wsdl2java -ant -impl -server -d outputDir myService.wsdl

4.3.1.2. Uso di Java2WSDL

L'altro approccio per sviluppare Web Service e' quello che prevede lo sviluppo del codice Java annotato in standard Jax-WS e di li generarne il WSDL. Vediamo un esempio. Cominciamo dal SEI:

public interface QuoteReporter{
      public Quote getQuote(String ticker);
}

ed un esempio di implementazione:

import java.util.*;

public class StockQuoteReporter implements QuoteReporter
{
  ...
public Quote getQuote(String ticker)
  {
    Quote retVal = new Quote();
    retVal.setID(ticker);
    retVal.setVal(Board.check(ticker));[1]
    Date retDate = new Date();
    retVal.setTime(retDate.toString());
    return(retVal);
  }
}

Non rimane che annotare il codice con le annotazioni fornite dallo standard JAX-WS e fornire le seguienti informazioni

• Il target namespace del servizio

• La classe che racchiude il messaggio di richiesta

• La classe che racchiude il messaggio di risposta

• Se l'operazione e' di tipo Oneway

• Il tipo di stile di Binding

• Il nome della classe usata per le eccezioni

• Il namespace dei tipi usati dal servizio

	Nota
	Molte annotazioni hanno valori predefiniti, ma specificare completamente ogni dettaglio del servizio fornisce un maggior controllo sul WSDL generato e ne migliora l'interoperabilita'.

Ecco alcune delle annotazioni introdotte dalla specifica Jax-WS.

• @XmlAccessorType: Con questa annotazione specifichiamo quali campi o proprieta' devono essere serializzati. Il valore FIELD indica che vanno serializzati tutti i campi pubblici e privati.

• @XmlType Mappa una classe al un tipo XML Schema. Se il tipo e' complesso della specie xs:all o xs:sequence si puo' specificare gli elementi inclusi e il loro ordine con la proprieta' propOrder()

• @XmlElement: Indica che il campo va serializzato e permette di specificarne il nome locale ed il namespace.

• @XmlSchemaType: Mappa un tipo Java ad un tipo semplice predefinito.

• @WebService (Required): Specifica che il metodo seguente e' l'implementazione di un endpoint.

  • name: il nome del wsdl:portType

  • targetNamespace: il namespace del WSDL e degli elementi generati (salvo diversamente imposto dalee regole di mapping di JAXB).

  • serviceName: il nome del wsdl:service

  • portName: il wsdl:portName

• @SOAPBinding: indica il tipo di binding. Di default utilizza il Wrapped.

• @WebResult: Indica il nome dell'elemento della risposta. Se non e' specificato utilizza [nomeoperazione]Response

• @Oneway: Indica che il metodo e' di tipo Oneway.

Per una lista esaustiva con utili esempi di utilizzo, consultare le specifiche.

import javax.jws.*;
@WebService(targetNamespace = "http://www.rivenditore.org/Ordine", name = "OrdineInterface")
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
public interface OrdineInterface {
    @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
    @Oneway
    @WebMethod(operationName = "Notifica")
    public void notifica(
        @WebParam(partName = "parameter", name = "notifica", targetNamespace = "http://www.rivenditore.org/ordiniElements")
        java.lang.String parameter);
    ...
}

Una volta terminata l'implementazione e' possibile verificarne la bonta' generando il WSDL associato con l'apposito comando java2wsdl

Abbiamo visto nella sezione precedente come realizzare servizi web in maniera piu' o meno trasparente rispetto ai linguaggi di programmazione utilizzati. In alcuni casi pero' questo puo' non essere conveniente, ma si puo' preferire agire direttamente sui documenti xml contenuti nei messaggi, anziche' essere costretti a convertire i messaggi in oggetti java.

Abbiamo gia' visto nelle precedenti sezioni su xml qualcosa di simile, in particolare come realizzare dei client e servlet in grado di inviare e ricevere messaggi XML su HTTP. Allo stesso modo potremmo quindi far viaggiare messaggi SOAP su HTTP. Tuttavia per il trattamento di messaggi SOAP esiste una specifica standard in java, che ne ottimizza la gestione (SAAJ: SOAP with Attachments API for Java). Vediamo quindi come servirci di questa libreria per imbustare il nostro ordine in un messaggio SOAP.

@WebServiceProvider
@ServiceMode(value=Service.Mode.MESSAGE)‏
public class OrdiniService implements Provider<SOAPMessage>{
  public SOAPMessage invoke(SOAPMessage request) {
    SOAPMessage response = null;
    ...
    return response;
  }
}

SOAPPart sp = request.getSOAPPart();
SOAPEnvelope se = sp.getEnvelope();
SOAPBody sb = se.getBody();
SOAPHeader sh = se.getHeader()‏

org.w3c.dom.Document dom =
		sb.extractContentAsDocument();
NodeList node = dom.getElementsByTagName("ordine");
...

//Istanziamo una MessageFactory
MessageFactory mf = MessageFactory.newInstance();

//Costruiamo il SOAPMessage vuoto
SOAPMessage msg = mf.createMessage();

//Popoliamo il body del SOAPMessage con i nodi necessari
SOAPElement pagamento = msg.getSOAPBody().addChildElement("pagamento", "pay", "http://www.bank.org/ns");

pagamento.addChildElement("da","pay").setNodeValue("cliente");
pagamento.addChildElement("a","pay").setNodeValue("shop");
pagamento.addChildElement("importo","pay").setNodeValue("100");

//Scriviamo il SOAPMessage nel messaggio HTTP e riceviamo la risposta

SOAPConnectionFactory scFactory = SOAPConnectionFactory.newInstance();
SOAPConnection con = scFactory.createConnection(); 
java.net.URL endpoint = new URL("http://rivenditore.com/ordina");
SOAPMessage response = con.call(message, endpoint); 
...