Contenuti

1. Introduzione

1.1 Panoramica

1.2 Convenzioni di Notazione

2. Scenari d’Uso Basico

2.1 Messaggi SOAP

2.2 Scambio di Messaggi SOAP

2.2.1 Scambi Conversazionali di Messaggi

2.2.2 Remote Procedure Calls

2.3 Scenari di Difetto

3. Modello di Processamento SOAP

3.1 L’Attributo "role"

3.2 L’Attributo "mustUnderstand"

3.3 L’Attributo "relay"

4. Usare Vari Legami di Protocolli

4.1 Il legame SOAP HTTP

4.1.1 Uso di SOAP HTTP GET

4.1.2 Uso di SOAP HTTP POST

4.1.3 Uso d’Architettura Web compatibile con SOAP

4.2 SOAP Su Email

5. Scenari d’Uso Avanzato

5.1 Usare Intermediari SOAP

5.2 Usare Altri Schemi di Codificazione

6. Differenze Tra SOAP 1.1 e SOAP 1.2

7. Riferimenti

A. Riconoscimenti

1. Introduzione

SOAP Versione 1.2 Parte 0: Introduzione è un documento non normativo inteso per fornire un tutorial facilmente comprensibile sulle caratteristiche delle specificazioni SOAP Versione 1.2. Il suo scopo è quello di aiutare una persona tecnicamente competente a capire come si può usare SOAP, descrivendo strutture di messaggi SOAP rappresentativi e modelli di scambio di messaggi.

In particolare, quest’introduzione descrive le caratteristiche del SOAP attraverso alcuni scenari d’uso, e vuole essere un complemento del testo normativo contenuto in SOAP Versione 1.2 Parte 1: Struttura di Messaggi (in futuro [SOAP Parte1]) e SOAP Versione 1.2 Parte 2: Aggiunti (in futuro [SOAP Parte2]) delle specifiche SOAP Versione 1.2.

Si aspetta dal lettore una certa familiarità con la sintassi XML basica, includendo l’uso di namespace XML ed infoset, e con concetti Web come URI e HTTP. È inteso in primo luogo per essere usato da utenti del SOAP, come progettisti d’applicazioni, piuttosto che da implementatori delle specificazioni SOAP, sebbene loro possano ricavare qualche benefizio. L’introduzione punta a mettere in rilievo le caratteristiche esenziali del SOAP Versione 1.2, non alla descrizione esauriente d’ogni sfumatura o caso marginale. Per questo non sostituisce alla specifica principale nell’ottenere una conoscenza completa del SOAP. Perciò, quest’introduzione fornisce vasti collegamenti con le specifiche principali sempre che se introducano o usino nuovi concetti.

[SOAP Parte1] definisce la busta (envelope) SOAP, che è una costruzione che definisce una struttura generale per rappresentare i contenuti di un messaggio SOAP, identificando chi dovrebbe occuparsene (di tutto o d’una parte), e se la gestione di queste parti è facoltativa od obbligatoria. Definisce anche una struttura di legame di protocolli, che descrive come si può scrivere la specificazione per un legame tra SOAP e altro protocollo sottostante.

[SOAP Parte2] definisce un modello di dati per SOAP, uno schema di codifica particolare per data type che possano usarsi per trasportare remote procedure calls (RPC), così come una realizzazione concreta della struttura di legame di protocolli sottostanti definita in [SOAP Parte1]. Questo legame permette lo scambio di messaggi SOAP tanto come payload d’una richiesta e risposta HTTP POST, quanto come un messaggio SOAP come risposta a HTTP GET.

Questo documento (l’introduzione) non è normativo, vuol dire, non provvede la specifica definitiva di SOAP Versione 1.2. Gli esempi forniti hanno l’intenzione di complementare le specificazioni formali, e in questioni d’interpretazione prevalgono naturalmente le specificazioni formali. Gli esempi che si mostrano qui forniscono un subset degli usi che si aspettano dal SOAP. Negli scenari d’uso attuali, SOAP sarà probabilmente una parte di una soluzione generale, e senza dubbi ci saranno altri requisiti, specifici d’ogni applicazione, che non si trattino in questi esempi.

1.1 Panoramica

SOAP Versione 1.2 fornisce la definizione dell’informazione basata sullo XML che può usarsi per scambiare informazione strutturata e tipificata tra diversi peer in un ambito decentralizzato e distribuito. [SOAP Parte1] spiega che un messaggio SOAP si specifica formalmente come un Infoset XML [Infoset XML], che fornisce una descrizione astratta dei suoi contenuti. Gli Infoset possono avere diverse rappresentazioni on-the-wire, delle quali un esempio comune è un documento XML 1.0 [XML 1.0].

SOAP è fondamentalmente un paradigma di scambio senza stato e di direzione unica, però le applicazioni possono creare modelli più complessi d’interazione (per esempio, richiesta/risposta, richiesta/risposte molteplici, ecc.) combinando questi scambi di direzione unica con caratteristiche fornite da un protocollo sottostante e/o informazione specifica dell’applicazione. SOAP non afferma niente sulla semantica dei dati specifici di qualsiasi applicazione che trasporti, neanche dice niente su aspetti come l’indirizzo dei messaggi SOAP, trasmissione di dati affidabili, firewall traversal, ecc. Comunque, SOAP fornisce la struttura con la quale l’informazione specifica di qualsiasi applicazione si può trasportare in maniera estensibile. Anche, SOAP fornisce una descrizione completa delle azioni richieste da un nodo SOAP quando si riceve un messaggio SOAP.

La Sezione 2 di questo documento fornisce un’introduzione alle caratteristiche basiche del SOAP, cominciando con gli scenari d’uso più semplici, vale a dire un messaggio SOAP di direzione unica, seguito da scambi molteplici tipo richiesta/risposta, includendo RPC. Si descrivono anche le situazioni di difetto.

La Sezione 3 fornisce una panoramica del modello di processamento SOAP, che descrive le regole per la costruzione iniziale del messaggio, con cui i messaggi si processano quando si ricevono in una destinazione intermedia o definitiva, regole che permettono l’inserzione, cancellazione o modificazione di di porzioni del messaggio per le azioni di un intermediario.

La Sezione 4 di questo documento descrive le vie attraverso le quali i messaggi SOAP si possono trasportare per realizzare diversi scenari d’uso. Descrive il legame SOAP HTTP specificato in [SOAP Parte2], ed un esempio di come i messaggi SOAP si possono trasportare in messaggi email. Come parte del legame HTTP, introduce due modelli di scambio di messaggi che sono disponibili per un’applicazione, uno usa il metodo HTTP POST e l’altro usa HTTP GET. Si forniscono anche esempi di come i RPC, in particolare quelli che rappresentano ricerche "sicure" d’informazione, possono rappresentarsi in scambi di messaggi SOAP di maniera che siano compatibili con i principi architettonici del World Wide Web .

La Sezione 5 di questo documento fornisce il trattamento d’alcuni aspetti del SOAP che possono usarsi in scenari d’uso più complessi, includendo meccanismi d’estensibilità offerti attraverso l’uso d’elementi header, che possono essere designati come obiettivi in nodi intermezzi specifici SOAP per fornire servizi di valore aggiunto ad applicazioni della comunicazione, e usando alcuni schemi di codifica per serializzare dati specifici secondo l’applicazione in messaggi SOAP.

La Sezione 6 di questo documento descrive i cambiamenti rispetto a SOAP Versione 1.1 [SOAP 1.1].

La Sezione 7 di questo documento fornisce riferimenti.

Per facilitare le referenze, i termini ed i concetti usati in quest’introduzione sono ipercollegati con la sua definizione nelle specifiche principali.

1.2 Convenzioni di Notazione

In tutto quest’introduzione, gli esempi di messaggi e buste SOAP si mostrano come documenti [XML 1.0]. [SOAP Part1] spiega che un messaggio SOAP è formalmente specificato come un [XML InfoSet], che è una descrizione astratta dei suoi contenuti. La distinzione tra Infoset XML SOAP e i documenti non è d’interesse per chi usi quest’introduzione come un’iniziazione nel SOAP; quelli più interessati (tipicamente chi portino SOAP a nuovi legami di protocolli in cui i messaggi possano avere rappresentazioni alternative) devono interpretare questi esempi come relativi ai corrispondenti Infoset XML. Un’ulteriore elaborazione di questo punto si fornisce nella Sezione 4 di questo documento.

I prefissi namespace "env", "enc" e "rpc" usati nelle sezioni di questo documento sono associati con i nomi namespace SOAP "http://www.w3.org/2003/05/soap-envelope" , "http://www.w3.org/2003/05/soap-encoding", e "http://www.w3.org/2003/05/soap-rpc" rispettivamente.

I prefissi namespace "xs" e "xsi" usati nelle sezioni di questo documento sono associati con i nomi namespace "http://www.w3.org/2001/XMLSchema" e "http://www.w3.org/2001/XMLSchema-instance" rispettivamente, entrambi definiti nelle specificazioni Schema XML [XML Schema Parte1], [XML Schema Parte2].

La scelta di qualsiasi altro prefisso namespace é arbitraria e non significativa semanticamente.

I namespace URI della forma generale "http://esempio.org/..." e "http://esempio.com/..." rappresentano un URI che dipende dall’applicazione o del contesto [RFC 2396].

2. Scenari d’Uso Basico

Un messaggio SOAP è fondamentalmente una trasmissione di direzione unica tra nodi SOAP, da un mittente SOAP ad un ricevente SOAP, ma si aspetta che i messaggi SOAP siano combinati dalle applicazioni per implementare modelli d’interazione più complessi, da richiesta/risposta a scambi molteplici, dietro-ed-avanti "di conversazione".

L’introduzione comincia per esporre la struttura di un messaggio SOAP ed il suo scambio in alcuni scenari d’uso semplici basati in un’applicazione di prenotazioni di viaggi. Alcuni aspetti di questo scenario d’applicazione si userà in tutto l’introduzione. In questo scenario, l’applicazione di prenotazioni di viaggi per un impiegato di una compagnia amministra una prenotazione di viaggio con un servizio di prenotazioni di viaggi per gite pianificate. L’informazione scambiata tra l’applicazione di prenotazioni di viaggi e l’applicazione del servizi di turismo si compie nella forma di messaggi SOAP.

Il destinatario definitivo di un messaggio SOAP spedito da un’applicazione per prenotazioni di viaggi è l’applicazione di servizi di turismo, ma è possibile che il messaggio SOAP possa essere "inviato" attraverso uno o più intermediari SOAP che agiscono in certa maniera sul messaggio. Alcuni esempi semplici di questi intermediari SOAP potrebbero essere quelli che registrano, verificano o, probabilmente, correggono ogni richiesta di viaggio. Gli esempi, e una discussione più dettagliata sul comportamento ed il ruolo degli intermediari SOAP, si riprende nella sezione 5.1.

La Sezione 2.1 descrive una richiesta di prenotazione di viaggio espressa come un messaggio SOAP, che offre l’opportunità di descrivere le diverse "parti" di un messaggio SOAP.

La Sezione 2.2.1 riprende lo stesso scenario per mostrare una risposta dal servizio di viaggi nella forma d’un altro messaggio SOAP, che è parte di un scambio di messaggi conversazionale mentre le diverse opzioni che compiono le limitazioni della richiesta di viaggi si negoziano.

La Sezione 2.2.2 presuppone che i diversi parametri della prenotazione di viaggi sono stati accettati dal viaggiatore, ed uno scambio – modellato come un remote procedure call (RPC) – tra le applicazioni prenotazione di viaggio e servizi turistici conferma il pagamento della prenotazione.

La Sezione 2.3 mostra esempi di gestioni di difetto.

2.1 Messaggi SOAP

L’Esempio 1 mostra dati per la prenotazione di un viaggio espressa in un messaggio SOAP.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>
   <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <n:name>Åke Jógvan Øyvind</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary
    xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>New York</p:departing>
     <p:arriving>Los Angeles</p:arriving>
     <p:departureDate>2001-12-14</p:departureDate>
     <p:departureTime>late afternoon</p:departureTime>
     <p:seatPreference>aisle</p:seatPreference>
   </p:departure>
   <p:return>
     <p:departing>Los Angeles</p:departing>
     <p:arriving>New York</p:arriving>
     <p:departureDate>2001-12-20</p:departureDate>
     <p:departureTime>mid-morning</p:departureTime>
     <p:seatPreference/>
   </p:return>
  </p:itinerary>
  <q:lodging
   xmlns:q="http://travelcompany.example.org/reservation/hotels">
   <q:preference>none</q:preference>
  </q:lodging>
 </env:Body>
</env:Envelope>

Il messaggio SOAP in Esempio 1 contiene due sub elementi SOAP-specifici dentro il complessivo env:Envelope, cioè un env:Header ed un env:Body. I contenuti di questi elementi sono definiti per le applicazioni e non sono una parte delle specificazioni SOAP, sebbene quest’ultimo abbia qualcosa da dire su come questi elementi si devono gestire.

Un elemento header SOAP è facoltativo, ma è stato incluso nell’esempio per spiegare certe caratteristiche del SOAP. Un header SOAP è un meccanismo d’estensione che fornisce un mezzo di passare informazione in messaggi SOAP che non è un’applicazione payload. Questo "controllo" dell’informazione include, per esempio, passare direttive o informazione di contesto corrispondente al processamento del messaggio. Questo permette che un messaggio SOAP si possa estendere in maniere specificate dalle applicazioni. Gli elementi discendenti immediati dell’elemento env:Header si chiamano header blocks, e rappresentano un gruppo logico di dati che, come si mostrerà dopo, si possono etichettare (targeted) individualmente nei nodi SOAP che si possano incontrare nel percorso di un messaggio di un mittente al destinatario definitivo.

I header SOAP sono stati nominati in anticipazione di vari usi di SOAP, molti di questi usi coinvolgeranno la partecipazione d’altri nodi di processamento SOAP - chiamati intermediari SOAP - lungo il percorso del messaggio dal mittente SOAP iniziale fino al destinatario SOAP definitivo. Questo permette agli intermediari SOAP di fornire servizi con valore aggiunto. I header, come si mostra dopo, si possono ispezionare, inserire, cancellare o spingere da nodi SOAP che si trovino lungo un percorso di messaggio SOAP. (Si dovrebbe tenere presente, nonostante, che la specifica SOAP non tratta sui contenuti degli elementi header, o su come i messaggi SOAP s’indirizzano tra nodi, o la maniera in cui si determina il percorso e così via. Questo appartiene al complessivo dell’applicazione e potrebbe essere il soggetto d’altre specifiche.)

Il corpo SOAP è l’elemento obbligatorio dentro il env:Envelope, cioè il luogo in cui si deve portare l’informazione principale end-to-end trasportata in un messaggio SOAP.

Una rappresentazione illustrata del messaggio SOAP nell’Esempio 1 è come segue.

Nell’Esempio 1, il header contiene due header block, ciascuno è definito nei suoi propri namespace XML e rappresenta alcuni aspetti attinenti al processamento generale del corpo del messaggio SOAP. Per questa prenotazione di viaggio, questa "meta" informazione attinente alla richiesta complessiva è un header block reservation che fornisce una referenza ed un tempo segnalato per quest’esempio di prenotazione, e l’identità del viaggiatore nel block passenger.

I header block reservation e passenger devono essere processati dal seguente intermediario SOAP che si trovi nel percorso del messaggio o, se non c’è nessun intermediario, dal destinatario definitivo del messaggio. Il fatto che sia ettichettato nel seguente nodo SOAP incontrato en route è indicato dalla presenza dell’attributo env:role con il valore "http://www.w3.org/2003/05/soap-envelope/role/next" (in futuro semplicemente "seguente"), che è un ruolo che tutti i nodi SOAP devono essere disposti a compiere. La presenza di un attributo env:mustUnderstand con valore "vero" indica che il nodo(i) che processa il header deve assolutamente processare questi header block in una maniera coerente con le sue specificazioni, o non processare il messaggio ed indicare un difetto. Sempre che si processi un header block, sia perché è marcato come env:mustUnderstand="true" o per altre ragioni, il block deve processarsi d’accordo con le specificazioni di quel block. Queste specificazioni proprie del header block sono definite per l’applicazione e non sono parte del SOAP. La Sezione 3 elaborerà processamenti di messaggi SOAP basati nel valore di questi attributi.

La scelta dei dati a mettersi in un header block o nel corpo SOAP sono decisioni che si prendono al momento del progetto dell’applicazione. Il punto principale è che i header block si possono etichettare in vari nodi che si possono incontrare lungo il percorso del messaggio da un mittente al destinatario definitivo. Questi nodi SOAP intermedi possono provvedere servizi con valore aggiunto basati in dati di questi header. Nell’Esempio 1, i dati del viaggiatore si mettono in un header block per illustrare l’uso di questi dati in un intermediario SOAP con lo scopo di fare alcuni processamenti addizionali. Per esempio, come si mostra poi nella sezione 5.1, il messaggio a destinazione esterna è alterato dall’intermediario SOAP aggiungendo le condizioni del viaggio al messaggio con un altro header block.

L’elemento env:Body ed i suoi elementi discendenti associati, itinerary e lodging, hanno la funzione di scambiare informazione tra il mittente SOAP iniziale ed il nodo SOAP che assume il ruolo di destinatario SOAP definitivo nel percorso del messaggio, che è l’applicazione di servizi turistici. Quindi, env:Body ed i suoi contenuti sono etichettati implicitamente e devono essere compresi dal destinatario definitivo. I mezzi attraverso i cui un nodo SOAP assume quel ruolo non sono definiti nella specifica SOAP, sono determinati come parte della semantica dell’applicazione generale ed il flusso del messaggio associato.

Un intermediario SOAP può decidere di eseguire il ruolo del destinatario SOAP definitivo per il trasferimento di un certo messaggio, e così processare env:Body. Comunque, anche se questo tipo di comportamento non si può prevenire, non dovrebbe accadere leggermente, per quanto potrebbe pervertire le intenzioni del mittente del messaggio, e ha effetti collaterali non desiderabili (come il non processamento dei header block che potrebbero essere etichettati come intermediari più avanti nel percorso del messaggio).

Un messaggio SOAP come quello dell’Esempio 1 può trasferirsi per diversi protocolli sottostanti e usarsi in una varietà di modelli di scambio di messaggi. Per esempio, per l’accesso con base Web a un’applicazione di servizi turistici, si potrebbe collocare nel corpo di una richiesta HTTP POST. In un altro legame di protocolli, si potrebbe spedire in un messaggio email (vedere sezione 4.2). La Sezione 4 descrive come i messaggi SOAP si possono trasportare per una varietà di protocolli sottostanti. Mentre, si presuppone l’esistenza di un meccanismo di trasferimento di messaggi ed il resto di questa sezione tratta i particolari dei messaggi SOAP ed il suo processamento.

2.2 Scambio di Messaggi SOAP

SOAP Versione 1.2 è una struttura semplice di messaggi per trasferire informazione specificata nella forma d’un infoset XML, tra un mittente SOAP iniziale ed un destinatario SOAP definitivo. Gli scenari più interessanti generalmente coinvolgono molti scambi di messaggi tra questi due nodi. Lo scambio più semplice è un modello di richiesta-risposta.Alcuni primi usi di [SOAP 1.1] enfatizzavano l’uso di questo modello come mezzo di trasportare remote procedure calls (RPC), ma è importante notare che non tutti gli scambi SOAP richiesta-risposta si possono o si devono modellare come RPC. Quest’ultimo si usa quando c’è bisogno di modellare un certo comportamento programmatico, con i messaggi scambiati conformi a una descrizione predefinita del remote call ed il suo ritorno.

Un insieme più ampio di scenari d’uso che quello coperto dal modello richiesta-risposta si può modellare semplicemente come contenuto di base XML scambiato in messaggi SOAP per formare una “conversazione” d’andata e ritorno, in cui la semantica sia al livello delle applicazioni mittente e ricevente. La Sezione 2.2.1 tratta il caso del contenuto di base XML scambiato in messaggi SOAP fra un’applicazione di prenotazione di viaggi e un’applicazione di servizi turistici in un modello di conversazione, mentre la sezione 2.2.2 fornisce un esempio modellato come un RPC.

2.2.1 Scambi Conversazionali di Messaggi

Continuando lo scenario della richiesta di viaggio, l’Esempio 2 mostra un messaggio SOAP ritornato dal servizio di viaggi come risposta al messaggio di richiesta di prenotazione dell’Esempio 1. Questa risposta cerca di raffinare alcun’informazione della richiesta, ad esempio, la scelta dell’aeroporto della città di partenza.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>
   <m:dateAndTime>2001-11-29T13:35:00.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <n:name>Åke Jógvan Øyvind</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itineraryClarification 
    xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>
       <p:airportChoices>
          JFK LGA EWR 
       </p:airportChoices>
     </p:departing>
   </p:departure>
   <p:return>
     <p:arriving>
       <p:airportChoices>
         JFK LGA EWR 
       </p:airportChoices>
     </p:arriving>
   </p:return>  
  </p:itineraryClarification>
 </env:Body>
</env:Envelope>

Come si descrisse prima, env:Body contiene il contenuto primario del messaggio, che in quest’esempio include un elenco d’aeroporti alternativi, secondo una definizione di schema nel namespace XML http://travelcompany.esempio.org/reservation/travel. In quest’esempio, i header block dell’Esempio 1 si ritornano (con alcuni valori degli subelementi alterati) nella risposta. Questo potrebbe permettere una correlazione tra messaggi nel livello SOAP, ma è molto probabile che questi header abbiano altri usi specifici dell’applicazione.

Nello scambio di messaggi degli Esempi 1 e 2 si scambiano contenuti di base XML conformi ad alcuno schema definito da un’applicazione, via messaggi SOAP. Un’altra volta, si differisce la discussione dei mezzi per i quali questi messaggi si trasferiscono alla sezione 4.

È abbastanza facile vedere come si possono costruire questi scambi fino ad un modello molteplice di scambio convesazionale andata-e-ritorno di messaggi. L’Esempio 3 mostra un messaggio SOAP inviato per l’applicazione di prenotazione di viaggi come risposta a quello dell’Esempio 2 , scegliendo uno degli aeroporti disponibili nell’elenco. Il header block reservation con lo stesso valore del subelemento reference accompagna ogni messaggio di questa conversazione, offrendo così una via, se c’è bisogno, di correlazionare i messaggi scambiati tra loro al livello dell’applicazione.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation 
     xmlns:m="http://travelcompany.example.org/reservation" 
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>
    <m:dateAndTime>2001-11-29T13:36:50.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <n:name>Åke Jógvan Øyvind</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary 
   xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>LGA</p:departing>
   </p:departure>
   <p:return>
     <p:arriving>EWR</p:arriving>
   </p:return>
  </p:itinerary>
 </env:Body>
</env:Envelope>

2.2.2 Remote Procedure Calls

Uno degli scopi di disegno del SOAP Versione 1.2 è quello di incapsulare la funzionalità dei “remote procedure call” usando la estensibilità e la flessibilità dello XML. SOAP Parte 2 sezione 4 ha definito una rappresentazione uniforme per invocazioni e risposte RPC portate in messaggi SOAP. Questa sezione continua lo scenario della prenotazione di viaggi per illustrare l’uso di messaggi SOAP per trasportare remote procedure call ed il suo ritorno.

A questo fine, il seguente esempio mostra il pagamento del viaggio usando una carta di credito (si presuppone che gli scambi conversazionali descritti nella sezione 2.2.1 hanno avuto come risultato un itinerario confermato). Si presuppone che il pagamento si svolge nel contesto di una transazione generale nella quale la carta di credito viene addebitata soltanto quando il viaggio e l’alloggio (che non si mostra in nessun esempio, ma che presumibilmente è stato prenotato nella stessa maniera) sono confermati. L’applicazione di prenotazione di viaggi fornisce informazione sulla carta de credito e se tutte le attività riescono a completarsi si addebita la carta di credito e si ritorna un codice di prenotazione. Quest’interazione prenotazione-e-addebito tra l’applicazione di prenotazione di viaggi e l’applicazione di servizi turistici si modella come un SOAP RPC.

Per invocare un SOAP RPC, c’è bisogno della seguente informazione::

1. L’indirizzo del nodo SOAP obiettivo.
2. Il nome della procedura o metodo.
3. Le identità ed i valori d’ogni argomento che deva passare alla procedura o metodo insieme con ogni parametro output e valori di ritorno.
4. Una chiara separazione degli argomenti usati per identificare la risorsa Web che è l’obiettivo attuale per il RPC, come contrapposte a quelli che trasportano dati o informazione di controllo che si usi per il processamento del call via la risorsa obiettivo.
5. Il modello di scambio di messaggi che si userà per trasportare i RPC, insieme all’identificazione del così chiamato "Metodo Web" ad usarsi (dopo).
6. Facoltativamente, i dati che si possano portare come parte dei header block SOAP.

Quest’informazione si può esprimere in una varietà di mezzi, includendo la formale Interface Definition Languages (IDL). Si noti che SOAP non fornisce nessun IDL, né formale né informale e che l’informazione di sopra differisce sottilmente dall’informazione generalmente richiesta per invocare non-SOAP RPC.

Rispetto all’Item 1 sopra, c’è, dalla prospettiva SOAP, un nodo SOAP che "contiene" o "supporta" l’obiettivo del RPC. È il nodo SOAP che (appropriatamente) adotta il ruolo del destinatario SOAP definitivo. Come esige l’Item 1, il destinatario definitivo può identificare l’obiettivo della menzionata procedura o metodo cercando il suo URI. La forma in cui l’URI obiettivo si rende disponibile dipende del legame di protocolli sottostante. Una possibilità è portare l’URI che identifica l’obiettivo in un header block SOAP. Alcuni legami di protocolli, come il legame SOAP HTTP definito in [SOAP Part2], offrono un meccanismo per portare gli URI fuori il messaggio SOAP. Generalmente, una delle proprietà della specifica del legame di protocolli deve essere una descrizione di come si trasporta l’URI obiettivo come parte del legame. La Sezione 4.1 fornisce alcuni esempi concreti di come si trasporta l’URI nel caso del legame di protocollo SOAP standardizzato a HTTP.

L’ Item 4 e Item 5 di sopra si richiedono per assicurare che le applicazioni RPC che usano SOAP possano farlo in una maniera compatibile con i principi architetturali del World Wide Web. La Sezione 4.1.3 discute come utilizzare l’informazione fornita dagli item 4 e 5.

Per il resto di questa sezione, si presuppone che il RPC trasportato in un messaggio SOAP come il mostrato nell’Esempio 4 è appropriatamente stabilito come obiettivo ed inviato. Il proposito di questa sezione è quello di sottolineare gli aspetti sintattici delle domande e risposte RPC portate dentro un messaggio SOAP.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
 <env:Header>
   <t:transaction
           xmlns:t="http://thirdparty.example.org/transaction"
           env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true" >5</t:transaction>
 </env:Header>  
 <env:Body>
  <m:chargeReservation 
      env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
         xmlns:m="http://travelcompany.example.org/">
   <m:reservation xmlns:m="http://travelcompany.example.org/reservation">
    <m:code>FT35ZBQ</m:code>
   </m:reservation>   
   <o:creditCard xmlns:o="http://mycompany.example.com/financial">
    <n:name xmlns:n="http://mycompany.example.com/employees">
           Åke Jógvan Øyvind
    </n:name>     
    <o:number>123456789099999</o:number>
    <o:expiration>2005-02</o:expiration>
   </o:creditCard>
  </m:chargeReservation>
 </env:Body>
</env:Envelope>

Lo stesso RPC è trasportato come un discendente dell’elemento env:Body, e modellato come un struct che porta il nome della procedura o metodo, in questo caso chargeReservation. (Un struct è un concetto del Modello di Dati SOAP definito in [SOAP Parte2] che modella una struttura o record type che appare in alcuni linguaggi comuni di programmazione.) Il disegno del RPC nell’esempio (la cui descrizione formale non si fornisce esplicitamente) prende due parametri input (o "in"), reservation corrisponde al viaggio pianificato identificato dal codice della prenotazione code, e l’informazione sulla carta di credito creditCard. Quest’ultimo è anche un struct, che prende tre elementi, il nome del titolare della carta di credito name, il numero della carta di credito number e la sua data d’espirazione expiration.

In quest’esempio, l’attributo env:encodingStyle con il valore http://www.w3.org/2003/05/soap-encoding mostra che i contenuti della struttura chargeReservation sono stati serializzati d’accordo alle regole di codificazione SOAP, ad esempio, le regole particolari definite in SOAP Parte2 sezione 3. Anche se SOAP specifica questo schema particolare di codifica, il suo uso è facoltativo e la specifica rende chiaro che si possono usare altri schemi di codifica per dati specifici dell’applicazione dentro un messaggio SOAP. Per questo proposito fornisce l’attributo env:encodingStyle per qualificare gli subelementi header block e corpo. La scelta del valore di quest’attributo è una decisione specifica dell’applicazione e l’abilità di chi chiama e di chi riceve per interoperare si presuppone stabilita "out-of-band". La Sezione 5.2 mostra un esempio dell’uso di altro schema di codifica.

Come abbiamo visto nell’Item 6, i RPC possono richiedere informazione addizionale per essere trasportati, e questo può essere importante per il processamento della chiamata in un ambito distribuito, ma questo non è parte della descrizione formale della procedura o metodo. (Si noti, comunque, che la fornitura di quest’informazione contestuale addizionale non é specifica dei RPC, ma può essere richiesta in generale per il processamento di alcuna applicazione distribuita.). Nell’esempio, il RPC si trasporta nel contesto generale di una transazione che coinvolge molti attività che si devono completare con successo prima che ritorni il RPC con successo. L’Esempio 4 mostra come un header block transaction indirizzato al destinatario finale (implicato per l’assenza dell’attributo env:role) si usa per portare quest’informazione(il valore "5" è qualche set identificatore di transazioni significativo per l’applicazione). Qui non si fornisce nessun’elaborazione posteriore della semantica di questo header specifica dell’applicazione, giacché non ha da vedere con la discussione degli aspetti sintattici dei messaggi SOAP RPC.)

Presupponiamo che il RPC nell’esempio dell’addebito è stato disegnato per avere la descrizione di procedura che indica che ci sono due parametri output (o "out"), uno che fornisce il codice di referenza per la prenotazione e l’altro un URL nel quale si possano vedere i particolari della prenotazione. La risposta RPC si ritorna nell’elemento env:Body del messaggio SOAP, che è modellato come un struct che prende il nome di procedura chargeReservation e, come una convenzione, la parola "Risposta" aggiunta. I due parametri output (o "out") che accompagnano la risposta sono alfanumerici code che identificano la prenotazione, e l’URI per la posizione, viewAt, dal quale si può recuperare la prenotazione.

Questo si mostra nell’Esempio 5a, nel quale un’altra volta il header identifica la transazione dentro la quale si effettua questo RPC.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
 <env:Header>
     <t:transaction
        xmlns:t="http://thirdparty.example.org/transaction"
          env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true">5</t:transaction>
 </env:Header>  
 <env:Body>
     <m:chargeReservationResponse 
         env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
             xmlns:m="http://travelcompany.example.org/">
       <m:code>FT35ZBQ</m:code>
       <m:viewAt>
         http://travelcompany.example.org/reservations?code=FT35ZBQ
       </m:viewAt>
     </m:chargeReservationResponse>
 </env:Body>
</env:Envelope>

I RPC spesso hanno descrizioni nelle quali si distingue un particolare parametro output, il chiamato valore “ritorno". La convenzione SOAP RPC offre una maniera di distinguere questo valore “ritorno" dagli altri parametri output nella descrizione della procedura. Per mostrare questo, l’esempio dell’addebito si modifica per avere una descrizione RPC che sia quasi uguale a quella dell’Esempio 5a, ad esempio, con gli stessi due parametri "out", ma inoltre ha un valore "ritorno", che è un’enumerazione con valori potenziali di "confermato" e "pendente". La risposta RPC conforme a questa descrizione si mostra nell’Esempio 5b, nel quale il header SOAP, come prima, identifica la transazione in cui si eseguisce il RPC.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
 <env:Header>
    <t:transaction
       xmlns:t="http://thirdparty.example.org/transaction"
         env:encodingStyle="http://example.com/encoding"
          env:mustUnderstand="true">5</t:transaction>
 </env:Header>  
 <env:Body>
    <m:chargeReservationResponse 
       env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
           xmlns:rpc="http://www.w3.org/2003/05/soap-rpc"
             xmlns:m="http://travelcompany.example.org/">
       <rpc:result>m:status</rpc:result>
       <m:status>confirmed</m:status>
       <m:code>FT35ZBQ</m:code>
       <m:viewAt>
        http://travelcompany.example.org/reservations?code=FT35ZBQ
       </m:viewAt>
    </m:chargeReservationResponse>
 </env:Body>
</env:Envelope>

Nell’Esempio 5b, il valore di ritorno è identificato dall’elemento rpc:result, e contiene il Nome Qualificato XML (del tipo xs:QName) d’altro elemento dentro il struct che è m:status. Questo, alla volta, contiene l’attuale valore di ritorno, "confermato". Questa tecnica permette all’attuale valore di ritorno essere fortemente tipificato secondo qualche schema. Se l’elemento rpc:result è assente, com’è il caso dell’Esempio 5a, il valore di ritorno non è presente oppure è del tipo void.

Mentre, in principio, usare SOAP per RPC è indipendente della decisione di usare un mezzo particolare per trasferire le chiamate RPC e i suoi ritorni, alcuni legami di protocolli che supportano SOAP modello di scambio di messaggi Richiesta-Risposta possono essere più naturalmente adatti per questi propositi. Un legame di protocolli che supporti questo modello di scambio di messaggi può fornire la correlazione tra una richiesta e una risposta. Certamente, il progettista di un’applicazione di base RPC può scegliere mettere una correlazione ID corrispondente ad una chiamata e la sua risposta in un header SOAP, facendo così il RPC indipendente di qualsiasi meccanismo sottostante di trasferimento. In ogni modo, i progettisti d’applicazione devono essere consapevoli di tutte le caratteristiche dei protocolli scelti per trasferire SOAP RPC, come latenza, sincronia, ecc.

Nel caso più comune d’uso, standardizzato in SOAP Parte2 sezione 7, usare HTTP come protocollo sottostante di trasferimento, un’invocazione RPC è indirizzata naturalmente verso la richiesta HTTP e una risposta RPC verso la risposta HTTP. La Sezione 4.1 fornisce esempi di come portare RPC usando il legame HTTP.

In ogni modo, è meglio sapere che sebbene la maggioranza degli esempi di SOAP per RPC usino il legame di protocollo HTTP, non è questo lùnico mezzo possibile.

2.3 Scenari di Difetto

SOAP fornisce un modello per maneggiare situazioni in cui sorgano difetti nel processamento di un messaggio. SOAP distingue tra le condizioni che determinano un difetto, e l’abilità di segnare questo difetto a chi ha originato il messaggio difettoso o ad altro nodo. L’abilità per segnare il difetto dipende dal meccanismo usato per il trasferimento del messaggio, ed un aspetto della specificazione di legame SOAP su un protocollo sottostante è specificare come si segnano i difetti, se c’è qualcuno. Il resto di questa sezione presuppone che sia disponibile un meccanismo di trasferimento per segnare difetti generati mentre si processano i messaggi ricevuti, e si concentra nella struttura del messaggio SOAP difettoso.

L’elemento SOAP env:Body ha un altro ruolo importante: è il luogo in cui si mette quest’informazione difettosa. Il modello SOAP per difetti (si veda SOAP Parte 1, sezione 2.6) richiede che tutti i difetti specifici di SOAP e specifici dell’applicazione si riportino usando un singolo elemento distinto, env:Fault, portato dentro l’elemento env:Body. L’elemento env:Fault contiene due subelementi obbligatori, env:Code e env:Reason, e (facoltativamente) informazione specifica dell’applicazione nel subelemento env:Detail. Un altro elemento facoltativo, env:Node, identifica via un URI il nodo SOAP che genera il difetto, la sua assenza implica che l’ha generato il destinatario finale del messaggio. C’è anche un altro subelemento facoltativo, env:Role, che identifica il ruolo che compie il nodo che ha generato il difetto.

Il subelemento env:Code di env:Fault consiste in un subelemento obbligatorio env:Value, il cui contenuto si specifica nella specifica SOAP (vedere SOAP Parte 1 sezione 5.4.6) così come un subelemento facoltativo env:Subcode.

L’Esempio 6a mostra un messaggio SOAP ritornato come risposta alla richiesta RPC nell’Esempio 4, ed indica un fallimento nel processamento del RPC.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
            xmlns:rpc='http://www.w3.org/2003/05/soap-rpc'>
  <env:Body>
   <env:Fault>
     <env:Code>
       <env:Value>env:Sender</env:Value>
       <env:Subcode>
        <env:Value>rpc:BadArguments</env:Value>
       </env:Subcode>
     </env:Code>
     <env:Reason>
      <env:Text xml:lang="en-US">Processing error</env:Text>
      <env:Text xml:lang="cs">Chyba zpracování</env:Text>
     </env:Reason>
     <env:Detail>
      <e:myFaultDetails 
        xmlns:e="http://travelcompany.example.org/faults">
        <e:message>Name does not match card number</e:message>
        <e:errorcode>999</e:errorcode>
      </e:myFaultDetails>
     </env:Detail>
   </env:Fault>
 </env:Body>
</env:Envelope>

Nell’Esempio 6a, il top-level env:Value usa un Nome Qualificato XML standardizzato (del tipo xs:QName) per identificare un difetto env:Sender, e questo indica che il difetto corrisponde a qualche errore sintattico o a qualche informazione inappropriata nel messaggio. (Quando un difetto env:Sender è ricevuto dal mittente, è aspettabile qualche azione correttiva prima che si spedisca nuovamente un messaggio similare). L’elemento env:Subcode è facoltativo, e, se presente, come in quest’esempio, qualifica dopo il valore del parente. Nell’Esempio 6a, env:Subcode denota che un difetto specifico del RPC, rpc:BadArguments, definito in SOAP Parte 2 sezione 4.4, è la causa del fallimento nel processamento della richiest.

La struttura dell’elemento env:Subcode è stata scelta per essere gerarchica – ogni elemento discendente env:Subcode ha un subelemento env:Value obbligatorio ed un subelemento env:Subcode facoltativo – per permettere che i codici specifici dell’applicazione siano trasportati. Questa struttura gerarchica dell’elemento env:Code permette ad un meccanismo uniforme trasportare molteplici livelli di codici di difetto. Il top-level env:Value è un difetto base specificato nelle specificazioni SOAP Versione 1.2 (si veda SOAP Parte 1 sezione 5.4.6) e deve essere capito da tutti i nodi SOAP. I nidificati env:Value dipendono dell’applicazione, e rappresentano un’elaborazione ulteriore o raffinamento del difetto base dalla prospettiva dell’applicazione. Alcuni di questi valori si possono standardizzare bene, come i codi RPC standardizzati in SOAP 1.2 (vedere SOAP Parte 2 sezione 4.4), o in alcuni altri standard che usino SOAP come un protocollo d’encapsulazione. L’unico requisito per definire questi valori subcodice specifici dell’applicazione è che siano namespace qualificati usando qualsiasi namespace che non sia il namespace SOAP env che definisce le principali classificazioni dei difetti SOAP. Non c’è nessun requisito che le applicazioni devano capire da una prospettiva SOAP, nemmeno guardare tutti i livelli dei valori subcodice.

Il subelemento env:Reason non è inteso per processamento algoritmico, ma piuttosto per la comprensione umana; perciò, anche se questo è un item obbligatorio, non c’è bisogno di standardizzare il valore scelto, quindi, si richiede soltanto tutto quello che è ragionevolmente descritto in maniera esatta nella situazione di difetto. Deve avere uno o più subelementi env:Text ognuno con un unico attributo xml:lang che permette alle applicazioni di rendere disponibile in molti linguaggi la causa del difetto (le applicazioni possono negoziare il linguaggio del testo difetto usando un meccanismo costruito con header SOAP; comunque, questo è oltre lo scopo delle specificazioni SOAP).

L’assenza di un subelemento env:Node dentro ilenv:Fault nell’Esempio 6a implica che è generato dal destinatario definitivo della chiamata. I contenuti di env:Detail, come si mostra nell’esempio, sono specifici dall’applicazione.

Durante il processamento di un messaggio SOAP, un difetto può anche generarsi se un elemento header obbligatorio non è capito o l’informazione che contiene non può essere processata. Gli errori nel processamento di un header block si segnalano anche usando un elemento env:Fault dentro env:Body, ma con un particolare header block distinto, env:NotUnderstood, che identifica il header block colpevole.

L’Esempio 6b mostra un esempio di risposta al RPC dell’ Esempio 4 indicando un fallimento nel processamento del header block t:transaction. La presenza del codice di difetto env:MustUnderstand nell’env:Body, e l’identificazione del header non capito usando un attributo (non qualificato), qname, specialmente il header block (vuoto) env:NotUnderstood.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope>
 <env:Header>
    <env:NotUnderstood qname="t:transaction"
               xmlns:t="http://thirdparty.example.org/transaction"/>
 </env:Header>  
 <env:Body>
  <env:Fault>
   <env:Code>
    <env:Value>env:MustUnderstand</env:Value>
   </env:Code>
   <env:Reason>
      <env:Text xml:lang="en-US">Header not understood</env:Text>
      <env:Text xml:lang="fr">En-tête non compris</env:Text>
   </env:Reason>    
  </env:Fault>
 </env:Body>
</env:Envelope>

Se fossero molti i header block obbligatori non capiti, allora ognuno potrebbe essere identificato per il suo attributo qname in una serie di questi header block env:NotUnderstood.

3. Modello di Processamento SOAP

Stabiliti gli aspetti sintattici di un messaggio SOAP e alcuni modelli basici di scambio di messaggi, questa sezione fornisce una panoramica generale del modello di processamento SOAP (specificato in SOAP arte 1, sezione 2). Il modello di processamento SOAP descrive le azioni che compie un nodo SOAP quando riceve un messaggio SOAP.

L’Esempio 7a mostra un messaggio SOAP con molti header block (con i suoi contenuti omessi per brevità). Variazioni di quest’esempio si useranno nel resto di questa sezione per illustrare alcuni aspetti del modello di processamento.

<?xml version="1.0" ?>
 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
   <env:Header>
     <p:oneBlock xmlns:p="http://example.com" 
            env:role="http://example.com/Log">
     ...
     ...
     </p:oneBlock>
     <q:anotherBlock xmlns:q="http://example.com"
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next">
     ...
     ...
     </q:anotherBlock>
     <r:aThirdBlock xmlns:r="http://example.com">
     ...
     ...
     </r:aThirdBlock>
   </env:Header>
   <env:Body >
     ...
     ...
   </env:Body>
 </env:Envelope>

Il modello di processamento SOAP descrive le azioni (logiche) che compie un nodo SOAP che riceve un messaggio SOAP. Il nodo deve analizzare le parti del messaggio che siano specifiche del SOAP, vale a dire quelli elementi del namespace SOAP "env". Questi elementi sono la busta (envelope) stessa, l’elemento header e l’elemento corpo. Un primo passo è, certo, l’esame complessivo per determinare se il messaggio SOAP è corretto sintatticamente, cioè, se è conforme all’infoset SOAP XML soggetto alle restrizioni d’uso di certe costruzioni XML- Istruzioni di Processamento e Definizioni di Tipo – come si definisce in SOAP Parte 1, sezione 5.

3.1 L’Attributo "role"

Il processamento ulteriore dei header block e del corpo dipende dal ruolo(i) assunti dal nodo SOAP nel processamento di un certo messaggio. SOAP definisce l’attributo (facoltativo) env:role attribute - sintatticamente, xs:anyURI - che può essere presente in un header block, che identifica il ruolo che compie l’obiettivo inteso di quel header block. Si richiede un nodo SOAP per processare un header block se questo assume il ruolo identificato dal valore dell’URI. Non è parte della specifica SOAP spiegare come un nodo SOAP assume un ruolo particolare.

Si definiscono tre ruoli standardizzati (si veda SOAP Parte 1, sezione 2.2), che sono

• "http://www.w3.org/2003/05/soap-envelope/role/none" (in futuro semplicemente "nessuno")
• "http://www.w3.org/2003/05/soap-envelope/role/next" (in futuro semplicemente "seguente"), e
• "http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver" (in futuro semplicemente "Destinatariodefinitivo").

Nell’Esempio 7a, il header block oneBlock si prende come obiettivo da ogni nodo SOAP che compia il ruolo, determinato per l’applicazione, definito dall’URI http://esempio.com/Log. Per propositi d’illustrazione, si presuppone che la specificazione di questo header block richiede che ogni nodo SOAP adotti questo ruolo tronco durante tutto il messaggio.

Qualsiasi nodo SOAP che riceva il messaggio con un header block avente un attributo env:role di "seguente" deve essere capace di processare i contenuti dell’elemento, giacché quello è un ruolo standardizzato che ogni nodo SOAP deve essere capace d’assumere. Un header block così attribuito è aspettabile che sia esaminato e (possibilmente) processato dal prossimo nodo SOAP lungo il percorso del messaggio, assumendo che questo header non è stato rimosso prima come risultato del processamento in un certo nodo anteriore nel percorso del messaggio.

Nell’Esempio 7a, il header block anotherBlock si prende come obiettivo nel seguente nodo del percorso del messaggio. In questo caso, il messaggio SOAP ricevuto dal nodo che compio il ruolo determinato per l’applicazione di "http://esempio.com/Log", deve anche essere disposto a compiere il ruolo determinato per SOAP di "seguente". Questo è vero anche per il nodo che è il destinatario definitivo del messaggio, che ovviamente (e implicitamente) compie il ruolo "seguente" perché è il prossimo nel percorso del messaggio.

Il terzo header block, aThirdBlock, nell’Esempio 7a non ha l’attributo env:role. È presso come obiettivo in nodo SOAP che assume il ruolo "Destinatariodefinitivo". Un nodo SOAP che assume il ruolo di destinatario definitivo di un certo messaggio SOAP compie il ruolo"Destinatariodefinitivo" (che può dichiararsi esplicitamente o è implicito se manca l’attributo env:role in un header block). La mancanza di un attributo env:role nel header block aThirdBlock significa che questo elemento header è presso come obiettivo nel nodo SOAP che assume il ruolo "Destinatariodefinitivo".

Si noti che l’elemento env:Body non ha un attributo env:role. L’elemento corpo è sempre l’obiettivo nel nodo SOAP che assume il ruolo "Destinatariodefinitivo". In questo senso, l’elemento corpo è proprio come un header block obiettivo del destinatario definitivo, ma è stato distinto per permettere ai nodi SOAP (generalmente intermediari SOAP) saltellarlo si assumono ruoli diversi a quello del destinatario definitivo. SOAP non prescrive nessuna struttura per l’elemento env:Body, soltanto raccomanda che i subelementi siano namespace qualificati XML. Alcune applicazioni, come quella dell’Esempio 1, possono scegliere di organizzare i subelementi di env:Body in block, ma questo non appartiene al modello di processamento SOAP.

L’altro ruolo distinto per l’elemento env:Body, come il contenitore in cui si mette l’informazione sui difetti che siano specifici di SOAP, ad esempio, fallimenti nel processamento degli elementi di un messaggio SOAP, è stato descritto prima nella sezione 2.3.

Se un elemento header ha l’attributo standardizzato env:role con valore "nessuno", significa che nessun nodo SOAP dovrebbe processare i contenuti, benché un nodo possa avere il bisogno di esaminarlo se il contenuto sono dati riferiti da un altro elemento header che sia obiettivo di un nodo SOAP particolare.

Se l’attributo env:role ha un valore vuoto, ad esempio, env:role="", significa che l’URI relativo che identifica il ruolo si risolve per l’URI base del messaggio SOAP in questione. SOAP Versione 1.2 non definisce un URI base per un messaggio SOAP, ma lo differisce ai meccanismi definiti in [XMLBase] per derivare l’URI base, che si può usare per fare assoluto qualsiasi URI relativo. Uno di questi meccanismi permette al legame di protocollo stabilire un URI base, possibilmente per referenza al protocollo d’encapsulazione in cui sta incorporato il messaggio SOAP per il trasporto (di fatto, quando i messaggi SOAP si trasportano usando HTTP, SOAP Parte 2 sezione 7.1.2 definisce l’URI base come l’URI Richiesta della richiesta HTTP, o il valore del header HTTP Contenuto-Posizione).

La tabella seguente compendia i ruoli standardizzati applicabili che si possono assumere in vari nodi SOAP. ("Si" e "No" vogliono dire che un nodo compie o non compie, rispettivamente, il ruolo del titolo).

3.2 L’Attributo "mustUnderstand"

L’Esempio 7b aumenta l’esempio precedente introducendo un altro attributo (facoltativo) per i header block, l’attributo env:mustUnderstand.

<?xml version="1.0" ?>
 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
   <env:Header>
     <p:oneBlock xmlns:p="http://example.com" 
           env:role="http://example.com/Log" 
               env:mustUnderstand="true">
     ...
     ...
     </p:oneBlock>
     <q:anotherBlock xmlns:q="http://example.com"
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next">
     ...
     ...
     </q:anotherBlock>
     <r:aThirdBlock xmlns:r="http://example.com">
     ...
     ...
     </r:aThirdBlock>
   </env:Header>
   <env:Body >
     ...
     ...
   </env:Body>
 </env:Envelope>

Una volta identificati i header block (e possibilmente il corpo) obiettivi dal nodo SOAP usando l’attributo env:role, l’attributo addizionale, env:mustUnderstand, negli elementi header determina le azioni ulteriori di processamento che si devano eseguire. Per rendere sicuro che i nodi SOAP non ignorino i header block che siano importanti per i propositi generali dell’applicazione, i header block SOAP forniscono anche un attributo facoltativo addizionale, env:mustUnderstand, che, se "vero", significa che i nodi SOAP obiettivo devono processare il block secondo la specificazione di quel block, chi colloquialmente chiamiamo header block obbligatorio. Di fatto, il processamento del messaggio SOAP nemmeno deve incominciare fino a che il nodo non abbia identificato tutti i header block obbligatori che abbia come obiettivo, e li abbia "capito". Capire un header vuol dire che il nodo deve essere pronto a fare qualsiasi cosa descritta nella specificazione del header (si ricordi che le specificazioni dei header block non sono parte delle specificazioni SOAP).

Nell’Esempio 7b, il header block oneBlock è marcato con un valore env:mustUnderstand "vero", che significa che è obbligatorio processare quel block se il nodo SOAP ha il ruolo identificato da "http://esempio.com/Log". Gli altri due header block non sono marcati, vuol dire che i nodi SOAP che sono l’obiettivo di questi block non bisognano processamento (Probabilmente le specificazioni di questi block lo consentono).

Un valore env:mustUnderstand "vero" vuol dire che il nodo SOAP deve processare il header con la semantica descritta nella sua specificazione, altrimenti generare un difetto SOAP. Il processamento appropriato del header può includere la rimozione del header di qualsiasi messaggio SOAP generato, reinserire il header con il medesimo valore o un valore alterato, o inserire un nuovo header. L’inabilità di processare un header obbligatorio richiede la cessazione del processamento ulteriore del messaggio SOAP, e che si generi un difetto SOAP. Il messaggio non si spedisce.

L’elemento env:Body non ha nessun attributo env:mustUnderstand ma deve essere processato dal destinatario definitivo. Nell’Esempio 7b, il destinatario definitivo del messaggio- il nodo SOAP che ha il ruolo "Destinatariodefinitivo" - deve processare env:Body e potrebbe processare il header block aThirdBlock. Potrebbe anche processare il header block anotherBlock, come è il suo obiettivo (nel ruolo di "seguente") ma non è obbligatorio farlo se le specificazioni per il processamento dei block non lo richiede (Se la specificazione per anotherBlock richiedesse il processamento nello destinatario seguente, avrebbe richiesto la marcatura con un env:mustUnderstand="vero".)

Il ruolo(i) che compie un nodo SOAP quando processa un messaggio SOAP può essere determinato da molti fattori. Il ruolo potrebbe essere conosciuto a priori, o posto per alcuni mezzi out-of-band, o un nodo potrebbe aver ispezionato tutte le parti di un messaggio ricevuto per determinare che ruoli assumerà prima di processare il messaggio. Un caso interessante sorge quando un nodo SOAP, durante il processamento di un messaggio decide che ci sono ruoli addizionali che si devono adottare. Senza importare quando accade questa determinazione, esternamente deve sembrare come se il modello di processamento fosse stato rispettato, cioè, deve sembrare che come se il ruolo fosse stato conosciuto dall’inizio del processamento del messaggio. In particolare, l’apparenza esterna deve essere come se il controllo env:mustUnderstand di qualsiasi header con quelli ruoli addizionali assunti fosse stato eseguito prima dell’inizio di qualsiasi processamento. Anche, se un nodo SOAP assume questi ruoli addizionali, deve assicurare che sia preparato per fare qualsiasi cosa richiesta per le specificazioni di questi ruoli.

La seguente tabella riassume come le azioni di processamento per un header block sono qualificate dall’attributo env:mustUnderstand rispetto a un nodo che è stato presso appropriatamente come obiettivo (via l’attributo env:role).

Come risultato del processamento di un messaggio SOAP, un nodo SOAP può generare un singolo difetto SOAP se non riesce a processare il messaggio, o, secondo l’applicazione, a generare messaggi SOAP addizionali per consumo negli altri nodi SOAP. SOAP Parte 1 sezione 5.4 descrive la struttura del messaggio con difetto mentre il modello di processamento SOAP definisce le condizioni in cui si genera. Come si è detto prima nella sezione 2.3, un difetto SOAP è un messaggio SOAP con un subelemento env:Body standardizzato chiamato env:Fault.

SOAP fa una distinzione fra generare un difetto e assicurare che il difetto sia ritornato a chi ha originato il messaggio o ad un altro nodo appropriato che si possa beneficiare con quest’informazione. In ogni modo, se un difetto generato si può propagare appropriatamente dipende del legame di protocollo sottostante scelto per lo scambio di messaggi SOAP. La specifica non definisce che succede se i difetti si generano durante la propagazione di messaggi di unico senso. L’unico legame di protocollo sottostante normativo, legame SOAP HTTP, offre la risposta HTTP come mezzo di riportare un difetto nell’entrante messaggio SOAP. (Si veda la Sezione 4 per i particolari del legame di protocollo SOAP.)

3.3 L’Attributo "relay"

SOAP Versione 1.2 definisce un altro attributo facoltativo per i header block, env:relay del tipo xs:boolean, che indica se un header block obiettivo in un intermediario SOAP deve essere ripetuto se non è processato.

Se un header block è processato, le regole di processamento SOAP (vedere SOAP Parte 1 sezione 2.7.2) richiede che sia rimosso dal messaggio a destinazione esterna (può, comunque, essere reinserito, senza cambiamenti o con i suoi contenuti alterati, se il processamento degli altri header block determina che il header block sia ritenuto nel messaggio posteriore). Il comportamento per default per un header block non processato presso come obiettivo in un ruolo compiuto da un intermediario SOAP, è che deve essere rimosso prima della ripetizione del messaggio.

La ragione per questa scelta di default è la sicurezza, assicurando che un intermediario SOAP non faccia presupposizioni sul grado di sopravvivenza, dopo di esso, di un header block obiettivo di un ruolo da esso assunto, e rappresentando alcuna caratteristica aggiunga valore, particolarmente se sceglie non processare il header block, molto probabilmente perché non lo “capisce”. Questo accade perché alcuni header block rappresentano caratteristiche hop-by-hop, e potrebbe non essere ragionevole propagarle inconsapevolmente end-to-end. Siccome un intermediario può non essere in una posizione che gli consenta di fare questa determinazione, si pensò che fosse più sicuro se i header block non processati fossero rimossi prima di ripetere il messaggio.

Comunque, ci sono esempi in cui un progettista d’applicazione potrebbe desiderare introdurre una nuova caratteristica, manifestata attraverso un header block SOAP, stabilito come obiettivo in qualsiasi intermediario capace che possa incontrarsi nel percorso del messaggio SOAP. Questo header block sarebbe disponibile per quelli intermediari che lo “capiscano”, ma sarebbe ignorato e ripetuto avanti da quelli che non lo “capiscano”. Come caratteristica nuova, il software di processamento per questo header block si può implementare, almeno inizialmente, in alcuni ma non in tutti i nodi SOAP. Ovviamente si deve marcare il tale header block con env:mustUnderstand = "falso", affinché gli intermediari che non abbiano implementato la caratteristica non generino un difetto. Per circonvenire la regola di difetto del modello di processamento, il marcare un header block con l’attributo addizionale env:relay permette all’intermediario di spedire avanti il header block obiettivo di sé stesso nel caso che scegliesse non processarlo.

Stabilire come obiettivo il header block nel ruolo "seguente" insieme all’attributo env:relay posto a "vero" può servire sempre per assicurare che ogni intermediario abbia una possibilità di esaminare il header, perché uno degli usi anticipati del ruolo “seguente" è con header block che portino informazione che si aspetta possa persistere lungo il percorso del messaggio SOAP. Certamente, il progettista dell’applicazione può sempre definire un uso abituale che permetta stabilire come obiettivi gli intermediari specifici che assumano questo ruolo. Quindi, non ci sono restrizioni nell’uso dell’attributo env:relay con nessun ruolo, salvo i ruoli di "nessuno" e "Destinatariodefinitivo", per i quali non ha senso.

L’Esempio 7c mostra l’uso dell’attributo env:relay.

<?xml version="1.0" ?>
 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
   <env:Header>
     <p:oneBlock xmlns:p="http://example.com" 
           env:role="http://example.com/Log" 
               env:mustUnderstand="true">
     ...
     ...
     </p:oneBlock>
     <q:anotherBlock xmlns:q="http://example.com"
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
       env:relay="true">
     ...
     ...
     </q:anotherBlock>
     <r:aThirdBlock xmlns:r="http://example.com">
     ...
     ...
     </r:aThirdBlock>
   </env:Header>
   <env:Body >
     ...
     ...
   </env:Body>
 </env:Envelope>

Il header block q:anotherBlock, stabilito come obiettivo nel nodo "seguente" nel percorso del messaggio, ha l’attributo addizionale env:relay="vero". Un nodo SOAP che riceve questo messaggio può processare questo header block se lo "capisce", ma si fa questo le regole di processamento richiedono che questo header block sia rimosso prima di spedirlo avanti. Comunque, se il nodo SOAP sceglie ignorare questo header block, e lo può fare perché non è obbligatorio processarlo, come indica la mancanza dell’attributo env:mustUnderstand poi lo deve spingere avanti.

Il processamento del header block p:oneBlock è obbligatorio e le regole di processamento SOAP richiedono che non sia ripetuto, a meno che il processamento di un altro header block richieda che sia presente nel messaggio con destinazione esterna. Il header block r:aThirdBlock non ha un attributo env:relay, che è equivalente a averlo con il valore env:relay="falso". D’adesso, questo header non sarà spedito avanti se non è processato.

SOAP 1.2 Parte 1 Tabella 3 compendia le condizioni che determinano quando un intermediario SOAP che abbia assunto un certo ruolo può spedire avanti header block non processati.

4. Usare Vari Legami di Protocolli

I messaggi SOAP si possono scambiare usando una varietà di protocolli “sottostanti”, includendo altri protocolli dello strato delle applicazioni. La specificazione di come i messaggi SOAP possono passare di un nodo SOAP ad altro usando un protocollo sottostante si chiama un legame SOAP. [SOAP Parte1] definisce un messaggio SOAP nella forma di un [XML Infoset], cioè, in termini d’item elemento dell’attributo e dell’informazione di un “documento” astratto chiamato env:Envelope (si veda SOAP Parte 1, sezione 5). Qualsiasi rappresentazione dell’infoset SOAP env:Envelope si renderà concreta attraverso un legame di protocolli, il cui compito, tra altre cose, è fornire una rappresentazione serializzata dell’infoset che si può portare al seguente nodo SOAP nel percorso del messaggio in una maniera che permetta ricostruire l’ infoset senza perdita d’informazione. Negli esempi tipici dei messaggi SOAP, e certamente in tutti gli esempi di quest’introduzione, la serializzazione mostrata è quella di un documento [XML 1.0] ben formato. Comunque, possiamo trovare altre legami di protocolli– per esempio un legame di protocollo tra due nodi SOAP su una bandwidth interface limitata – in cui una serializzazione alternativa e compressa dello stesso infoset si possa scegliere. Un altro legame, scelto per un proposito diverso, può provvedere una serializzazione che sia una struttura encriptata rappresentando lo stesso infoset.

Oltre a provvedere una serializzazione concreta dell’infoset SOAP tra nodi SOAP adiacenti lungo il percorso di un messaggio SOAP, un legame di protocollo fornisce i meccanismi per supportare le caratteristiche che necessita un’applicazione SOAP. Una caratteristica è una specificazione di una certa funzionalità fornita da un legame. Una descrizione di caratteristica è identificata da un URI, e con questo tutte le applicazioni che si riferiscano ad essa garantiscono la stessa semantica. Per esempio, un tipico scenario d’uso può richiedere molti scambi richiesta-risposta simultanei tra nodi SOAP adiacenti, in questo caso la caratteristica richiesta è l’abilità di correlare una richiesta con una risposta. Altri esempi includono una caratteristica "canale encriptato", o una caratteristica "canale di distribuzione affidabile", o una particolare caratteristica modello di scambio di messaggio SOAP.

Una specificazione di legame SOAP (vedere SOAP Parte 1 sezione 4) descrive, tra altre cose, quale (se c’è qualcuna) caratteristica fornisce. Alcune caratteristiche possono essere fornite originariamente dal protocollo sottostante. Se la caratteristica non è disponibile nel legame, si può implementare dentro la busta SOAP, usando header block SOAP. La specificazione di una caratteristica implementata usando header block SOAP si chiama un modulo SOAP.

Ad esempio, se gli scambi di messaggi SOAP fossero trasportati direttamente su un protocollo datagram come UDP, ovviamente la caratteristica correlativa al messaggio dovrebbe fornirsi altrove, direttamente per l’applicazione o più probabilmente come una parte degli infoset SOAP che si scambiano. In quest’ultimo caso la caratteristica correlativa al messaggio ha un’espressione specifica del legame dentro la busta SOAP, ad esempio, come un header block SOAP, definito in un modulo "Correlazione Richiesta-Risposta" identificato da un URI. Comunque, se gli infoset SOAP si stanno scambiando usando un protocollo sottostante che è in sé stesso richiesta/risposta, l’applicazione potrebbe implicitamente "ereditare" questa caratteristica fornita dal legame, e non ci avrebbe bisogno di nessun altro supporto fornito a livello applicazione o SOAP. (Di fatto, il legame HTTP per SOAP prende vantaggio precisamente di questa caratteristica del HTTP).

In ogni modo, un messaggio SOAP può viaggiare su molti hop tra un mittente ed il destinatario definitivo, e ogni hop può essere un legame di protocollo diverso. In altre parole, una caratteristica (correlazione del messaggio, affidabilità, ecc.) che sia supportata dal legame di protocollo in un hop può non essere supportata da altro lungo il percorso del messaggio. Lo stesso SOAP non fornisce nessun meccanismo per nascondere le differenze delle caratteristiche provvedute per diversi protocolli sottostanti. Comunque, qualsiasi caratteristica che sia richiesta da una particolare applicazione, ma che possa non essere disponibile nell’infrastruttura sottostante lungo il percorso anticipato del messaggio, si può compensare portandola come una parte dell’infoset del messaggio SOAP, ad esempio, come un header block SOAP specificato in alcun modulo.

Così è evidente che ci sono molti temi che il progettista dell’applicazione dovrebbe curare per completare la semantica dell’applicazione in particolare, includendo come prendere vantaggio delle caratteristiche originali di protocolli sottostanti che siano disponibili per l’uso nell’ambito scelto. SOAP Parte 1 sezione 4.2 fornisce una ossatura generale della descrizione di come le applicazioni con base SOAP possono scegliere l’uso di caratteristiche fornite da un legame di protocollo sottostante per completare la semantica particolare dell’applicazione. Si vuole fornire linee guida per scrivere specificazioni di legame di protocollo interoperabili per lo scambio di messaggi SOAP.

Tra altre cose, la specificazione di un legame deve definire una caratteristica particolare, cioè il modello(i) di scambio di messaggi che supporta. [SOAP Parte2] definisce due di questi modelli di scambio di messaggi, un modello di scambio Richiesta-Risposta di messaggi SOAP in cui un messaggio SOAP si scambia in ogni direzione tra due nodi SOAP adiacenti, e un modello di scambio Risposta di messaggi SOAP che consiste in un messaggio non-SOAP agendo come una richiesta seguita da un messaggio SOAP incluso come parte della risposta.

[SOAP Parte2] offre anche al progettista di applicazioni una caratteristica generale chiamata la caratteristica Metodo Web SOAP che permette alle applicazioni un controllo completo sulla scelta del così chiamato "Metodo Web”, uno di GET, POST, PUT, DELETE le cui semantiche si definiscono nelle specificazioni [HTTP 1.1] che si possono usare sul legame. Questa caratteristica assicura che le applicazioni che usino SOAP lo possano usare in una forma compatibile con i principi architetturali del World Wide Web (in poche parole, la semplicità e la facoltà di selezionare del Web si devono basicamente al fatto che ci sono pochi metodi “generici” (GET, POST, PUT, DELETE) che si possano usare per interagire con qualsiasi risorsa che si renda disponibile nel Web via URI). La caratteristica Metodo Web SOAP è supportata dal legame SOAP HTTP, sebbene, in principio, è disponibile per tutti i legami di protocollo sottostante SOAP.

SOAP Parte 2 sezione 7 specifica un legame di protocollo standardizzato usando la struttura di legame di [SOAP Parte1], vale a dire, come si usa SOAP in congiunzione a HTTP come il protocollo sottostante. SOAP Versione 1.2 si restringe alla definizione di un legame HTTP che soltanto permetta l’uso del metodo POST in congiunzione con il modello di scambio di messaggi Richiesta-Risposta ed il metodo GET con il modello di scambio di messaggi SOAP Risposta. Altre specificazioni in futuro potrebbero definire legami SOAP con HTTP o altri trasporti che usino altri metodi Web (PUT, DELETE, ecc.).

Le prossime sezioni mostreranno esempi di due legami di protocollo sottostante per SOAP, quelli con [HTTP 1.1] e email. Si dovrebbe enfatizzare un’altra volta che l’unico legame normativo per messaggi SOAP 1.2 è con [HTTP 1.1]. Gli esempi della sezione 4.2 che mostrano email come un meccanismo di trasporto per SOAP soltanto suggeriscono che sono possibili altre opzioni per il trasferimento di messaggi SOAP, anche se non siano ancora standardizzate. Una Nota W3C [SOAP Email Binding] offre un’applicazione della struttura del legame di protocollo SOAP di [SOAP Parte1] descrivendo un legame sperimentale per trasporto di SOAP ad email, specificamente trasporti di messaggi con base [RFC 2822].

4.1 Il Legame SOAP HTTP

HTTP ha un modello di connessione ben conosciuto ed un modello di scambio di messaggi. Il cliente identifica il server via URI, fa la connessione usando il network sottostante TCP/IP, seleziona un messaggio richiesta HTTP e riceve un messaggio risposta HTTP sulla stessa connessione TCP. HTTP implicitamente correlaziona il messaggio richiesta con il suo messaggio risposta, poi, un’applicazione usando questo legame può scegliere di inferire una correlazione tra un messaggio SOAP inviato nel corpo di un messaggio richiesta HTTP e un messaggio SOAP ritornato nella risposta HTTP. Similmente, HTTP identifica il server endpoint via URI, la Richiesta-URI, che serve anche come l’identificazione di un nodo SOAP nel server.

HTTP permette molti intermediari tra il cliente iniziale e il server d’origine identificato dalla Richiesta-URI, in questo caso il modello richiesta/risposta è una serie di queste coppie. Si noti, comunque, che gli intermediari HTTP sono diversi agli intermediari SOAP.

Il legame HTTP in [SOAP Parte2] usa la caratteristica Web Metod SOAP affinché le applicazioni possano scegliere i così detti Metodi Web – restringendoli ad uno di GET o POST – per usarli in uno scambio di messaggi HTTP. Inoltre, usa due modelli di scambio di messaggi, offrendo alle applicazioni due maniere di scambiare messaggi SOAP via HTTP: 1) l’uso del metodo HTTP POST per trasportare messaggi SOAP nei corpi dei messaggi HTTP richiesta e risposta, e 2) l’uso del metodo HTTP GET in una richiesta HTTP per ritornare un messaggio SOAP nel corpo di una risposta HTTP. Il primo modello d’uso è l’istantaneità specifica HTTP di una caratteristica di legame chiamata modello di scambio di messaggi SOAP richiesta-risposta, mentre il secondo usa una caratteristica chiamata modello di scambio di messaggi SOAP risposta.

Il proposito di fornire questi due tipi d’usi è facilitare i due paradigmi d’interazione che sono ben stabiliti nel World Wide Web. Il primo tipo d’interazione permette l’uso di dati dentro del corpo di un HTTP POST per creare o modificare lo stato di una risorsa identificata dall’URI di destinazione della richiesta HTTP. Il secondo tipo di modello d’interazione offre l’abilità d’usare una richiesta HTTP GET per ottenere una rappresentazione di una risorsa senza alterare in niente il suo stato. Nel primo caso, il primo aspetto specifico del SOAP che ci deve interessare è che il corpo della richiesta HTTP POST è un messaggio SOAP che si deve processare (per il modello di processamento SOAP) come parte del processamento specifico dell’applicazione richiesto per conformare la semantica POST. Nel secondo caso, l’uso tipico che si prevede è il caso in cui la rappresentazione della risorsa richiesta si ritorna non come un HTML, o davvero un documento XML generico, ma come un messaggio SOAP, cioè il header HTTP tipo di contenuto del messaggio di risposta identificato come media type "application/soap+xml". Presumibilmente, ci saranno divulgatori di risorse nel Web che potrebbero determinare che queste risorse si ricuperano e si rendono disponibili meglio nella forma di messaggi SOAP. Si noti, comunque, che in genere le risorse si possono rendere disponibili in molti rappresentazioni, e la rappresentazione desiderata o preferita è indicata dall’applicazione che richiede usando il header HTTP Accept.

Un aspetto ulteriore del legame SOAP HTTP è la questione di come un’applicazione determina quale di questi due tipi di modelli di scambio di messaggi userà. [SOAP Parte2] offre una guida in circostanze in cui le applicazioni possano usare uno dei due tipi di modelli specificati di scambio di messaggi (è una guida, sebbene sia una guida forte, nel senso in cui si usa la forma "DOVREBBE" nelle specifiche piuttosto che un requisito assoluto identificato per la parola "DEVE", nel senso in cui queste parole si interpretano in IETF [RFC 2119].) Il modello di scambio di messaggi SOAP risposta con il metodo HTTP GET si usa quando un’applicazione si assicura che lo scambio di messaggi ha il proposito di ricerca d’informazione, e la risorsa dell’informazione rimane “intatta” come risultato dell’interazione. A queste interazioni si riferisce la specifica HTTP come safe and idempotent. Come l’uso HTTP SOAP GET non consente un messaggio SOAP nella richiesta, le applicazioni che bisognino caratteristiche nell’interazione con destinazione esterna che possano soltanto essere supportate da una espressione specifica del legame dentro l’infoset SOAP(ad esempio, header block SOAP) ovviamente non possono usare questo modello di scambio di messaggi. Si noti che il legame HTTP POST è disponibile per l’uso in tutti i casi.

Le seguenti subsezioni forniscono esempi d’uso di questi due modelli di scambio di messaggi definiti per il legame HTTP.

4.1.1. Uso SOAP HTTP GET

L’uso del legame HTTP con il modello di scambio di messaggi SOAP è costretto al metodo HTTP GET. Questo significa che la risposta ad una richiesta HTTP GET da un nodo SOAP richiedente è un messaggio SOAP nella risposta HTTP.

L’Esempio 8a mostra un HTTP GET diretto dall’applicazione del viaggiatore (sempre nel scenario di una prenotazione di viaggio) nel URI http://travelcompany.example.org/reservations?code=FT35ZBQ in cui si può vedere l’itinerario del viaggiatore (Si può vedere come si rende disponibile questo URL nell’Esempio 5a.)

GET /travelcompany.example.org/reservations?code=FT35ZBQ  HTTP/1.1
Host: travelcompany.example.org
Accept: text/html;q=0.5, application/soap+xml

Il header HTTP Accept si usa per indicare la rappresentazione preferita della risorsa che si richiede, che in quest’esempio è un media type "application/soap+xml" per consumo di una macchina cliente, piuttosto che il media type "text/html" per l’interpretazione di un cliente browser per consumo umano.

L’Esempio 8b mostra la risposta HTTP al GET nell’Esempio 8a. Il corpo della risposta HTTP contiene un messaggio SOAP che mostra i particolari del viaggio. Una discussione dei contenuti del messaggio SOAP si differisce fino alla sezione 5.2 , per quanto non è importante adesso per capire l’uso del legame HTTP GET.

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>
   <m:dateAndTime>2001-11-30T16:25:00.000-05:00</m:dateAndTime>
  </m:reservation>
 </env:Header>
 <env:Body>
  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
            xmlns:x="http://travelcompany.example.org/vocab#"
     env:encodingStyle="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
   <x:ReservationRequest 
 rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ">
      <x:passenger>Åke Jógvan Øyvind</x:passenger>
      <x:outbound>
       <x:TravelRequest>
        <x:to>LAX</x:to>
        <x:from>LGA</x:from>
        <x:date>2001-12-14</x:date>
       </x:TravelRequest>
      </x:outbound>
      <x:return>
       <x:TravelRequest>
        <x:to>JFK</x:to>
        <x:from>LAX</x:from>
        <x:date>2001-12-20</x:date>
       </x:TravelRequest>
      </x:return>
    </x:ReservationRequest>
  </rdf:RDF>
 </env:Body>
</env:Envelope>

Si noti che i particolari della prenotazione si sarebbero potuto ritornare come un documento (X)HTML, ma quest’esempio vuole mostrare un caso in cui l’applicazione prenotazione ritorna lo stato della risorsa (la prenotazione) in un data-centric media form (un messaggio SOAP) che può essere processato da una macchina, invece di un (X)HTML che potrebbe essere processato da un browser. Di fatto, negli usi più probabilmente anticipati di SOAP, l’applicazione consumatore non sarà un browser.

Anche, come si mostra nell’esempio, l’uso di SOAP nel corpo della risposta HTTP offre la possibilità di manifestare alcune caratteristiche specifiche dell’applicazione attraverso l’uso di header SOAP. Usando SOAP, si fornisce all’applicazione una struttura utile e consistente ed un modello di processamento per esprimere queste caratteristiche.

4.1.2 SOAP HTTP POST Usage

L’uso del legame HTTP con il modello di scambio di messaggi SOAP Richiesta-Risposta è ristretto al metodo HTTP POST. Si noti che quest’uso del modello di scambio di messaggi nel legame SOAP HTTP è disponibile per tutte le applicazioni, se coinvolgono lo scambio di dati XML generali o RPC (come nei seguenti esempi) incapsulati in messaggi SOAP.

Gli esempi 9 e 10 mostrano come un legame HTTP usa il modello di scambio di messaggi SOAP Richiesta-Risposta, usando lo stesso scenario degli Esempio 4 e Esempio 5a, rispettivamente, vale a dire, trasportando un RPC ed il suo ritorno nel corpo di un messaggio SOAP. Gli esempi e la discussione in questa sezione si concentrano soltanto nei header HTTP ed il loro ruolo.

POST /Reservations HTTP/1.1
Host: travelcompany.example.org
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
 <env:Header>
   <t:transaction
           xmlns:t="http://thirdparty.example.org/transaction"
           env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true" >5</t:transaction>
 </env:Header>  
 <env:Body>
  <m:chargeReservation 
     env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
          xmlns:m="http://travelcompany.example.org/">
   <m:reservation xmlns:m="http://travelcompany.example.org/reservation">
    <m:code>FT35ZBQ</m:code>
   </m:reservation>    
    <o:creditCard xmlns:o="http://mycompany.example.com/financial">
     <n:name xmlns:n="http://mycompany.example.com/employees">
           Åke Jógvan Øyvind
     </n:name>    
     <o:number>123456789099999</o:number>
     <o:expiration>2005-02</o:expiration>
    </o:creditCard>
   </m:chargeReservation>
  </env:Body>
</env:Envelope>

L’Esempio 9 mostra una richiesta RPC diretta verso l’applicazione di servizi di viaggi. Il messaggio SOAP è inviato nel corpo di un metodo HTTP POST diretto verso l’URI che identifica la risorsa "Prenotazioni" nel server travelcompany.esempio.org. Quando si usa HTTP, l’URI-Richiesta indica la risorsa a cui l’invocazione si "attacca". Senza richiedere che sia un URI valido, SOAP non ha restrizioni formali per la forma della richiesta URI (si veda [RFC 2396] per più informazione su URI). In ogni modo, uno dei principi dell’architettura Web è quello che dice che tutti le risorse importanti sono identificate da URI. Questo implica che i servizi SOAP più ben formati architettonicamente saranno incorporati come un vasto numero di risorse, ognuna con il suo proprio URI. Certamente, molte di queste risorse probabilmente saranno create dinamicamente durante l’operazione di un servizio, come per esempio, la prenotazione di viaggio mostrata nell’esempio. Perciò, un’applicazione di servizi turistici ben formata architettonicamente dovrebbe avere diversi URI per ogni prenotazione, e i requisiti SOAP per ricercare o manipolare queste prenotazioni saranno guidati ai suoi URI, e non a un singolo e monolitico URI "Prenotazioni", come si mostra nell’Esempio 9. Esempio 13 nella sezione 4.1.3 mostra la via preferita per indirizzare risorse come una prenotazioni di viaggio. Quindi, differiamo fino alla sezione 4.1.3 la discussione sull’architettura Web compatibile con l’uso SOAP/HTTP.

Quando si mettono messaggi SOAP in corpi HTTP, il header HTTP Content-type deve essere scelto come "application/soap+xml" (Il parametro charset facoltativo, che può prendere il valore di "utf-8" o "utf-16", si mostra in quest’esempio, ma si manca le regole del set di caratteri per freestanding [XML 1.0] si applica al corpo della richiesta HTTP.)

L’Esempio 10 mostra il ritorno RPC (con i dettagli omessi) inviato dall’applicazione del servizio di turismo nella corrispondente risposta HTTP alla richiesta dell’Esempio 5a. SOAP, usando trasporto HTTP, segue la semantica dei codici di stato HTTP per comunicare lo stato dell’informazione in HTTP. Per esempio, la serie 2xx dei codici di stato HTTP indica che la richiesta del cliente (includendo il componente SOAP) è stata ricevuta con successo, capitata, accettata, ecc.

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
 <env:Header>
       ...
       ...
 </env:Header>  
 <env:Body>
       ...
       ...
 </env:Body>
</env:Envelope>

Se durante il processamento della richiesta accade un errore, la specificazione di legame HTTP richiede che un HTTP 500 "Internal Server Error" sia usato con un messaggio SOAP incorporato contenendo un difetto SOAP che indica l’errore di processamento nel server.

L’Esempio 11 è lo stesso messaggio di difetto SOAP dell’Esempio 6a, ma con i header HTTP aggiunti.

HTTP/1.1 500 Internal Server Error
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <env:Fault>
     <env:Code>
       <env:Value>env:Sender</env:Value>
       <env:Subcode>
        <env:Value>rpc:BadArguments</env:Value>
       </env:Subcode>
     </env:Code>
     <env:Reason>
      <env:Text xml:lang="en-US">Processing error</env:Text>
      <env:Text xml:lang="cs">Chyba zpracování</env:Text>
     </env:Reason>
     <env:Detail>
      <e:myFaultDetails 
        xmlns:e="http://travelcompany.example.org/faults" >
        <e:message>Name does not match card number</e:message>
        <e:errorcode>999</e:errorcode>
      </e:myFaultDetails>
     </env:Detail>
   </env:Fault>
 </env:Body>
</env:Envelope>

SOAP Parte 2 Tabella 16 fornisce il comportamento dettagliato del maneggio di vari possibili codici di risposte HTTP, ad esempio, 2xx (riuscito), 3xx (riindirizzamento), 4xx (errore del cliente) e 5xx (errore del server).

4.1.3 Uso d’Architettura Web Compatibile con SOAP

Uno dei concetti più centrali del World Wide Web è quello dell’URI come identificatore di risorse. I servizi SOAP che usino il legame HTTP e vogliano interoperare con altri software Web dovrebbe usare gli URI per indirizzare tutte le risorse importanti nel suo servizio. Per esempio, un uso molto importante, di fatto, predominante, del World Wide Web è la pura ricerca d’informazione, nella quale la rappresentazione di una risorsa disponibile, identificata da un URI, si recupera usando una richiesta HTTP GET senza affettare la risorsa in modo alcuno (questo si chiama nella terminologia HTTP safe and idempotent method.) La chiave è che il divulgatore di una risorsa rende disponibile il suo URI, che i consumatori possono ottenere ("GET").

Ci sono molti casi in cui i messaggi SOAP sono designati per usi che sono puramente di ricerca informativa, come quando lo stato d’alcuna risorsa (od oggetto, in termini di programmazione) è richiesto, come l’opposto a manipolare questa risorsa. In questi casi, l’uso di un corpo SOAP per portare la richiesta allo stato, con un elemento del corpo rappresentando l’oggetto in questione, si vede come contrario allo spirito del Web perché la risorsa non è identificata dall’Uri-Richiesta del HTTP GET (In alcune implementazioni SOAP/RPC, l’URI-Richiesta HTTP non è spesso l’identificatore della risorsa, ma alcuna entità intermedia che deve valutare il messaggio SOAP per identificare la risorsa.)

Per sottolineare i cambiamenti necessari, l’Esempio 12a mostra la via non raccomandabile per ricerca sicura d’informazione nel Web. Quest’è un esempio di un RPC portato in un messaggio SOAP, usando nuovamente il tema della prenotazione di viaggio, nel quale la richiesta vuole ricercare l’itinerario di una particolare prenotazione identificata da uno dei parametri, reservationCode, del RPC (si presuppone, per questa discussione, che l’applicazione che usa questa richiesta RPC non ha bisogno di caratteristiche che richiedano l’uso di header SOAP).

POST /Reservations HTTP/1.1
Host: travelcompany.example.org
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
  <env:Body>
    <m:retrieveItinerary 
        env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
             xmlns:m="http://travelcompany.example.org/">
      <m:reservationCode>FT35ZBQ</m:reservationCode>
    </m:retrieveItinerary>
  </env:Body>
</env:Envelope>

Si noti che la risorsa che si ricerca non è identificata dal URI obiettivo nella richiesta HTTP, si deve ottenere osservando la busta SOAP. Così, non è possibile, come sarebbe il caso con altri URI "ottenibili” (“gettable") nel Web, renderla disponibile via HTTP soltanto per consumatori del World Wide Web.