Ce document est une traduction susceptible d'voluer . Toute amélioration est la bienvenue : e-mail.

La version française de cette traduction est :
http://www.w3.org/2002/07/soap-translation/soap12-part0.html

Traductrice : Carine Bournez - <[email protected]>
La version française peut contenir des erreurs. La version anglaise de cette spécification est l'unique version normative.

SOAP Version 1.2, partie 0: Prliminaire

Recommandation W3C 24 Juin 2003

Cette version :: http://www.w3.org/TR/2003/REC-soap12-part0-20030624/
Dernire version :: http://www.w3.org/TR/soap12-part0/
Version prcdente :: http://www.w3.org/TR/2003/PR-soap12-part0-20030507/
Editeurs :: Nilo Mitra (Ericsson)

Sommaire

1. Introduction

La partie 0 de SOAP Version 1.2 : Prliminaire est un document non normatif destin fournir un tutoriel facile d'accs propos des caractristiques de la spcification SOAP Version 1.2. Son but est d'aider les personnes qui ont les comptences techniques ncessaires comprendre comment SOAP peut tre utilis, en dcrivant les structures de messages SOAP reprsentatives et les squences d'change de messages.

Le lecteur est suppos tre familiaris avec la syntaxe de base de XML, notamment l'utilisation d'espaces de noms et d'infosets, et avec les concepts du Web tels que les URIs et HTTP. Ce document vise principalement les utilisateurs de SOAP, comme les concepteurs d'applications, plutt que les implmentateurs des spcifications SOAP, bien que ces derniers puissent en retirer quelque bnfice. Ce premier cours cherche souligner les caractristiques essentielles de SOAP Version 1.2 et non dcrire compltement toutes les nuances et les cas limites. Par consquent, rien ne remplace les spcifications principales pour bien comprendre l'ensemble de SOAP. C'est pourquoi ce prliminaire fournit des liens vers les spcifications principales chaque fois qu'un nouveau concept est introduit ou utilis.

[SOAP Partie 1] dfinit l'enveloppe SOAP, qui donne une structure d'ensemble pour reprsenter le contenu d'un message SOAP, en identifiant qui doit s'occuper de tout ou partie de ce contenu, que ces traitements soient obligatoires ou optionnels. Elle dfinit galement une structure de liaison sur un protocole, qui dcrit comment spcifier la liaison de SOAP au-dessus d'un autre protocole.

[SOAP Partie 2] dfinit un modle de donnes pour SOAP, un schma d'encodage particulier pour les types de donnes utilisables pour un appel de procdure distant (Remote Procedure Call, RPC), ainsi qu'une ralisation concrte de la structure de liaison sur un protocole sous-jacent dfinie dans [SOAP Partie 1]. Cette liaison permet l'change de messages SOAP soit comme quivalent d'une requte HTTP POST et d'une rponse, ou d'un message SOAP en rponse un HTTP GET.

Ce document (prliminaire) n'est pas normatif, ce qui signifie qu'il ne fournit pas de spcification complte de SOAP Version 1.2. Les exemples fournis ne se veulent pas un complment des spcifications formelles, et pour toute question d'interprtation ces dernires font naturellement rfrence. Ces exemples montrent un sous-ensemble des utilisations supposes de SOAP. Dans les scenarii rels d'utilisation, SOAP sera plutt une partie de la solution globale et il pourrait y avoir d'autres impratifs qui chapperaient ces exemples.

1.1 Aperu

La version 1.2 de SOAP inclut la dfinition d'information base sur XML utilisable pour changer des informations structures et types entre des pairs dans un environnement dcentralis et distribu. [SOAP Partie 1] explique qu'un message SOAP est formellement spcifi comme un infoset XML [XML Infoset], qui fournit une description abstraite de son contenu. Les infosets peuvent avoir des reprsentations sur-le-fil diffrentes , un document XML 1.0 [XML 1.0] en est un exemple courant. SOAP est fondamentalement un paradigme d'change de messages unidirectionnel sans tats, mais les applications peuvent crer des squences d'interaction plus complexes (par exemple requte/rponse, requte/rponses multiples, etc.) en combinant des changes unidirectionnels avec des caractristiques du protocole sous-jacent et/ou des informations propres l'application. SOAP ne dit rien sur la smantique des donnes applicatives qu'il transporte, tout comme sur les problmes tels que le routage des messages SOAP, le transfert de donnes fiable, le passage de pare-feu, etc. Cependant, SOAP offre une structure sur laquelle les informations propres une application peuvent tre transportes de manire extensible. En outre, SOAP donne une description complte des actions requises excutes par un noeud SOAP lorsqu'il reoit un message SOAP.

La section 2 de ce document fournit une introduction aux fonctions basiques de SOAP via les scenarii d'utilisation les plus simples, c'est--dire le message SOAP unidirectionnel, suivi de divers changes de type requte-rponse incluant les RPCs. Les situations de fautes sont galement dcrites.

La section 3 donne une vue d'ensemble du modle de traitement, qui dcrit les rgles pour la construction initiale d'un message, pour letraitement la rception par un intermdiaire ou rcepteur final, et pour l'insertion, la suppression ou la modification de parties du message par les actions d'un intermdiaire.

La section 4 de ce document dcrit les manires de transporter les messages SOAP pour raliser divers scenarii d'utilisation. Elle dcrit la liaison de SOAP sur HTTP spcifie dans [SOAP Partie 2], ainsi qu'un exemple de transport de message SOAP par e-mail. Elle introduit, comme parties intgrantes de la liaison sur HTTP, deux squences d'changes de messages disponibles pour les applications, une utilisant la mthode HTTP POST, l'autre utilisant HTTP GET. Des exemples montrent comment des RPCs, en particulier la rcupration d'informations "sre", peuvent tre reprsents par des messages SOAP de manire compatibles avec les principes architecturaux du World Wide Web.

La section 5 de ce document traite de divers aspects utilisables dans des scenarii plus complexes. Ceux-ci incluent le recours des lments d'en-tte comme mcanisme d'extension, qui peuvent tre adresss des noeuds SOAP intermdiaires spcifiques, pour fournir des services valeur ajoute aux applications communicantes, et l'usage de divers schmas d'encodage pour srialiser des donnes applicatives dans des messages SOAP.

Pour faciliter les rfrences, les termes et concepts utiliss dans ce prliminaire sont hyper-lis leur dfinition dans les spcifications principales.

1.2 Conventions de notation

Au long de ce prliminaire, les exemples d'enveloppes et de messages SOAP sont montrs comme des documents XML 1.0. [SOAP Partie 1] explique que les messages SOAP sont formellement spcifis comme des infosets XML [XML Infoset], qui sont des descriptions abstraites de leur contenu. La distinction entre les infosets XML SOAP et les documents n'est probablement pas susceptible d'intresser ceux qui lisent ce prliminaire comme une introduction SOAP ; ceux qui s'y intressent (typiquement ceux qui portent SOAP sur de nouvelles liaisons sur un protocole o les messages peuvent avoir plusieurs reprsentations) doivent comprendre ces exemples comme des rfrences aux infosets correspondants. Plus de dtails sur ce point sont disponibles dans la section 4 de ce document.

Les prfixes d'espaces de nommage "xs" et "xsi" utiliss dans les textes de ces sections sont associs aux noms d'espace de nommage "http://www.w3.org/2001/XMLSchema" et "http://www.w3.org/2001/XMLSchema-instance" respectivement, tous deux dfinis dans la spcification XML Schemas [XML Schema Part1], [XML Schema Part2].

Notez que le choix de tout autre prfixe d'espace de nommage est arbitraire et n'a pas de smantique.

Les URIs des espaces de noms de la forme gnrale "http://example.org/..." et "http://example.com/..." reprsentent une URI dpendante d'une application ou d'un contexte [RFC 2396].

2. Scenarii d'utilisation basiques

Un message SOAP est fondamentalement une transmission unidirectionnelle entre des noeuds SOAP, d'un metteur SOAP vers un rcepteur SOAP, mais les messages SOAP sont supposs tre combins par les applications pour implmenter les squences plus complexes d'interactions, de la requte-rponse aux changes multiples "conversationnels" dans un sens et dans l'autre.

Ce prliminaire commence par exposer la structure d'un message SOAP et son change dans un scnario d'utilisation simple bas sur une application de rservation de voyages. Divers aspects de ce scnario d'application seront utiliss au long de ce prliminaire. Dans ce scnario, l'application de rservation de voyages pour un employ d'une compagnie ngocie une rservation de voyage l'aide d'un service de rservation pour un circuit planifi. L'information changs entre le voyageur et le services des voyages prend la forme de messages SOAP.

Le rcepteur final du message SOAP envoy par l'application du voyageur est le service de rservation, mais il est possible que le message soit "drout" par un ou plusieurs intermdiaires SOAP qui agissent d'un certaine manire sur le message. Par exemple, ces intermdiaires peuvent crire une trace, auditer, ou modifier chaque requte de voyage. Des exemples et une discussion plus dtaille du comportement et du rle des intermdiaires SOAP n'arrivera qu'en section 5.1.

La section 2.1 dcrit une requte de rservation sous la forme d'un message SOAP, ce qui permet de montrer les diffrentes "parties" d'un message SOAP.

La section 2.2.1 continue le mme scnario pour montrer une rponse du services des voyages, sous la forme d'un autre message SOAP, qui fait partie d'un change de messages conversationnel puisque les divers choix satisfaisant les contraintes de la requte de voyage sont ngocies.

La section 2.2.2 suppose que les diffrents paramtres de la rservation ont t accepts par le voyageur, et qu'un change - modlis comme un appel de procdure distante (RPC) - entre le voyageur et le service de voyages confirme les points de la rservation.

2.1 Messages SOAP

L'exemple 1 montre les donnes pour une rservation de voyage exprimes dans un message SOAP.

Exemple 1

<?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 Jgvan 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>

Message d'exemple pour une rservation de voyage contenant des blocs d'en-tte et un corps.

Le message SOAP de l'exemple 1 contient deux sous-lments spcifiques SOAP l'intrieur de l'env:Envelope externe, un env:Header (en-tte) et un env:Body (corps). Les contenus de ces lments sont dfinis par l'application et ne font pas partie de la spcification de SOAP, bien que celle-ci ait quelque chose dire sur la manire dont ces lments seront traits.

L'en-tte SOAP est optionnel mais il a t inclus dans cet exemple pour expliquer certaines caractristiques. Un en-tte SOAP est un mcanisme d'extension qui donne un moyen de passer des informations dans un message SOAP sans poids pour l'application. Ces informations de "contrle" incluent, par exemple, des directives ou des informations contextuelles lies au traitement du message. Ceci permet d'tendre un message SOAP de manire spcifique l'application. Les lments fils immdiats d'un lment env:Header sont appels blocs d'en-tte et reprsentent un regroupement logique de donnes qui, comme dcrit plus loin, peuvent tre destines individuellement des intermdiaires rencontrs sur le chemin suivi par le message entre l'metteur et le destinataire final.

Les en-ttes SOAP ont t conus pour anticiper des utilisations diverses de SOAP, parmi lesquelles beaucoup impliquent la participation d'autres noeuds SOAP - appels intermdiaires SOAP - au long du cheminement d'un message depuis un metteur SOAP initial jusqu' un rcepteur SOAP final. Ceci permet ces noeuds d'changer des informations ajoutant de la valeur au service. Les en-ttes, comme montr plus loin, peuvent tre inspects, insrs, supprims ou rachemins par les noeuds SOAP rencontrs au long d'un chemin de message SOAP. (Il faut garder l'esprit que la spcification SOAP ne s'occupe pas de ce qu'est le contenu des lments d'en-ttes, ni de la faon d'acheminer les messages entre noeuds, ni de dterminer la route, etc. Ces problmes font partie de l'application dans son ensemble et pourrait faire l'objet d'autres spcifications).

Le corps SOAP est l'lment obligatoire dans l'env:Envelope, ce qui signifie qu'il contient l'information principale transporte de bout en bout par le message SOAP.

Dans l'exemple 1, l'en-tte contient deux blocs d'en-tte, chacun d'eux tant dfini dans son propre espace de nommage XML et reprsentant un aspect du traitement global du corps du message SOAP. Pour cette application de rservation de voyage, une telle "meta" information appartenant la requte globale est un bloc d'en-tte reservation qui fournit une rfrence et une date pour cette instance de rservation ; l'identit du voyageur se trouve dans le bloc passenger.

Les blocs d'en-tte reservation et passenger doivent tre traits par le prochain intermdiaire SOAP rencontr sur le chemin suivi ou, s'il n'y a pas d'intermdiaire, par le rcepteur final du message. Le fait qu'il soit adress au prochain noeud SOAP rencontr est indiqu par la prsence de l'attribut env:role avec la valeur "http://www.w3.org/2003/05/soap-envelope/role/next" (dsigne plus loin simplement par "next"), qui est un rle que tous les noeuds SOAP doivent jouer. La prsence de l'attribut env:mustUnderstand avec la valeur "true" indique que ce(s) noeud(s) traitant l'en-tte doi(ven)t absolument traiter ces blocs d'en-tte de manire cohrente avec leurs spcifications, ou sinon ne pas traiter le message du tout et renvoyer une faute. Notez que chaque fois qu'un bloc d'en-tte est trait, parce qu'il est marqu env:mustUnderstand="true" ou pour une autre raison, le bloc doit tre trait selon les spcifications de ce bloc. De telles spcifications sont dfinies dans l'application et ne font pas partie de SOAP. La section 3 donnera plus de dtails sur le traitement de message SOAP en fonction des valeurs de ces attributs.

Le choix des donnes placer dans un bloc d'en-tte ou dans le corps est une dcision de conception de l'application. Le principal point considrer est que les blocs d'en-tte peuvent tre adresss diffrents noeuds potentiellement rencontrs sur le chemin du message. De tels noeuds SOAP intermdiaires peuvent fournir une valeur ajoute au service, base sur les donnes de ces en-ttes. Dans l'exemple 1, les informations passager sont places dans un bloc d'en-tte pour illustrer l'utilisation de cette donne sur un intermdiaire SOAP pour des traitements supplmentaires. Par exemple, comme indiqu dans la section 5.1, le message sortant est modifi par l'intermdiaire SOAP, qui ajoute au message les politiques de voyage de ce passager sous la forme d'un autre bloc d'en-tte.

L'lment env:Body et ses fils itinerary et lodging sont destins changer de l'information entre l'metteur SOAP initial et le noeud SOAP qui assume le rle de rcepteur SOAP final dans le chemin du message, qui dans ce cas est le service de rservation de voyages. Donc le env:Body et son contenu sont implicitement adresss et supposs tre compris par le rcepteur final. Les moyens grce auxquels un noeud SOAP assume un tel rle ne sont pas dfinis dans la spcification SOAP mais font partie de la smantique globale de l'application et du flux de messages associ.

Notez qu'un intermdiaire SOAP peut dcider de jouer le rle de rcepteur final pour un transfert de message donn et ainsi traiter le env:Body. Cependant, si ce comportement ne peut tre vit, il ne devrait pas tre employ la lgre car il peut dtourner les intentions de l'metteur du message et avoir des effets de bord indsirables (tels que ne pas traiter les blocs d'en-tte qui seraient adresss des intermdiaires suivants dans le cheminement du message).

Un message SOAP tel que dans l'exemple 1 peut tre transport sur diffrents protocoles sous-jacents et utilis dans diverses squences d'change de messages. Par exemple, avec un accs bas sur le Web au service de voyages, il peut tre plac dans une requte HTTP POST. Dans une autre liaison de protocole, il peut tre envoy dans un message lectronique (voir section 4.2). La section 4 dcrira comment des messages SOAP peuvent tre achemins sur diffrents protocoles sous-jacents. Pour le moment, il est suppos qu'il existe un mcanisme de transfert des messages et la suite de la section se concentre sur les dtails de ces messages et de leur traitement.

2.2 Echange de messages SOAP

SOAP Version 1.2 est une simple structure de passage de messages pour transfrer de l'information spcifie sous forme d'infosets XML entre un metteur SOAP initial et un rcepteur SOAP final. Typiquement, les scenarii les plus intressants impliquent de multiples changes de messages entre ces deux noeuds. Le plus simple est la squence requte-rponse. Des utilisations premires de [SOAP 1.1] mettaient l'accent sur l'utilisation de cette squence comme moyen de vhiculer des appels de procdure distante (remote procedure calls, RPC), mais tous les changes de type requte-rponse n'ont ou ne ncessitent pas une modlisation en appels de procdure distante (RPC). Ces derniers sont utiliss quand il faut modliser un certain comportement programmatique avec des messages changs conformes une description bien dfinie pour l'appel distant et son retour.

Un panel beaucoup plus large de scenarii d'utilisation que ceux couverts par la squence de type requte-rponse peut tre modlis simplement comme des changes de contenu bas sur XML chang dans des messages SOAP pour former une conversation bidirectionnelle, o la smantique se situe au niveau des applications mettrice et rceptrice. La section 2.2.1 couvre le cas d'change de contenu bas sur XML chang dans des messages SOAP entre l'application de rservation de voyages et le service des voyages selon un modle conversationnel et la section 2.2.2 donne un exemple d'change modlis en RPC.

2.2.1 Echange de message de type Document

En continuant sur le scnario de demande de voyage, l'exemple 2 montre un message SOAP renvoy par le service de voyages en rponse la requte de rservation de l'exemple 1. Cette rponse cherche affiner des informations de la requte : le choix d'aroport de la ville de dpart.

Exemple 2

<?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 Jgvan 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>

Message SOAP envoy en rponse au message de l'exemple 1

Comme dcrit prcdemment, le env:Body renferme le contenu premier du message, qui dans l'exemple inclut une liste des alternatives pour l'aroport, conformment une dfinition de schma dans l'espace de nommage XML http://travelcompany.example.org/reservation/travel. Dans cet exemple, les blocs d'en-tte de l'exemple 1 sont retourns (avec des valeurs de sous-lments modifies) dans la rponse. Ceci permettrait une corrlation entre messages au niveau de SOAP, mais de tels en-ttes ont plus srement d'autres utilisations propres l'application.

L'change de messages des exemples 1 et 2 est un cas o des contenus bass sur XML conformes un schma dfini dans l'application sont changs via des messages SOAP. Nous diffrons de nouveau la discussion la section 4 au sujet des moyens de transfert employs.

Il est assez simple de voir comment de tels changes peuvent construire une squence "conversationnelle" multiple d'change de messages. L'exemple 3 montre un message SOAP envoy par l'application de rservation de voyages en rponse celui de l'exemple 2 pour choisir un des aroports disponibles dans la liste. Le bloc d'en-tte reservation avec la mme valeur du sous-lment reference accompagne chaque message de cette conversation, offrant ainsi un moyen d'tablir, si ncessaire, une correspondance entre eux au niveau application.

Exemple 3

<?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 Jgvan 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>

Rponse au message de l'exemple 2 continuant une squence conversationnel d'change de message

2.2.2 Appels de procdure distante (Remote procedure calls)

Un des objectifs du design de SOAP Version 1.2 est d'encapsuler la fonctionnalit d'appel de procdure distante grce l'extensibilit et la flexibilit de XML. la section 4 de SOAP partie 2 a dfini une reprsentation uniforme d'invocations et de rponses RPC transportes dans des messages SOAP. Cette section poursuit le scnario de rservation de voyages pour illustrer l'utilisation de messages SOAP dans l'appel de procdure distante et dans son retour.

Pour cela, le scnario montre le paiement du voyage par carte de crdit. (les changes conversationnels dcrits dans la section 2.2.1 sont supposs avoir abouti un itinraire confirm). Ici, il est de plus suppos se placer dans le contexte d'une transaction globale o la carte de crdit n'est dbite que lorsque le voyage et le sjour (non explicit dans les exemples ici, mais rserv probablement de la mme manire) sont confirms tous les deux. Le passager fournit les informations sur sa carte de crdit et les diffrentes activits se terminent, en cas de succs, par le dbit du montant et l'mission en retour d'un numro de rservation. Cette interaction rserve-et-dbite entre le passager et le service de voyages est modlise par un RPC SOAP.

Elles peuvent tre exprims par divers moyens, notamment un langage formel de description d'interface (IDL). Notez que SOAP ne fournit pas de langage d'IDL, formel ou non. Notez galement que les informations ci-dessus diffrent lgrement de celles gnralement ncessaires pour invoquer d'autres appels RPC non SOAP.

Concernant l'item 1 ci-dessus, d'un point de vue SOAP, il existe un noeud SOAP qui "contient" ou "supporte" la cible du RPC. C'est ce noeud SOAP qui adopte (de manire approprie) le rle de rcepteur SOAP final. Comme le requiert l'item 1, le rcepteur final peut identifier la cible de la procdure ou mthode dsigne en regardant son URI. La faon de rendre l'URI disponible dpend de la liaison au protocole sous-jacent. Une possibilit consiste vhiculer l'URI identifiant la cible dans un bloc d'en-tte SOAP. Certaines liaisons sur des protocoles, telles que la liaison SOAP sur HTTP dfinie dans [SOAP Partie 2], offrent un mcanisme de transport de l'URI en dehors du message SOAP. En gnral, la description du moyen de transporter l'URI cible dans la liaison doit tre l'une des proprits d'une spcification de liaison sur un protocole. Nous remettons la section 4.1 la discussion et des exemples concrts de manires de transporter l'URI dans le cas de la liaison standardise de SOAP sur HTTP.

Les items 4 et 5 ci-dessus sont requis pour s'assurer que les applications RPC qui emploient SOAP peuvent le faire de manire compatible avec les principes architecturaux du World Wide Web. Nous remettons la section 4.1.3 la discussion sur l'utilisation des informations fournies par les items 4 et 5.

Dans le reste de cette section, l'appel RPC est suppos tre transport dans le message SOAP, tel que dans l'exemple 4, est convenablement cibl et distribu. Notre but est maintenant de souligner les aspects syntaxiques lis aux requtes et retours RPC dans le message SOAP.

Exemple 4

<?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 Jgvan yvind      </n:name>           <o:number>123456789099999</o:number>      <o:expiration>2005-02</o:expiration>      </o:creditCard>   </m:chargeReservation>  </env:Body> </env:Envelope>

Requte RPC SOAP avec un en-tte obligatoire et deux paramtres entrants ("in")

L'appel RPC lui-mme est un fils de l'lment env:Body et est modlis par une struct qui prend le nom de la procdure ou mthode, dans ce cas chargeReservation. (Une struct est un concept du modle de donnes SOAP, dfini dans [SOAP Part2], qui modlise une structure ou un type d'enregistrement qui apparat dans des langages de programmation courants). La conception de l'appel RPC dans l'exemple (sa description n'a pas encore t explicite) prend deux paramtres d'entre (ou "in"), la reservation du voyageur et l'information creditCard. Ce dernier est aussi une struct, qui possde trois lments : le nom du titulaire de la carte (name), le numro de la carte (number) et la date d'expiration.

Dans cet exemple, l'attribut env:encodingStyle avec la valeur dans l'http://www.w3.org/2003/05/soap-encoding montre que le contenu de la structure chargeReservation a t srialis selon les rgles d'encodage SOAP, c'est--dire plus prcisment les rgles dfinies dans la section 3 de SOAP Partie 2. Mme si SOAP spcifie ce schma d'encodage particulier, son utilisation est optionnelle et la spcification indique clairement que d'autres schmas d'encodage peuvent tre utiliss pour des donnes applicatives dans un message SOAP. C'est pour cela qu'existe l'attribut env:encodingStyle pour qualifier les blocs d'en-tte et les sous-lements du corps. Le choix de la valeur de cet attribut est une dcision spcifique l'application et la capacit d'un appelant et un appel interoprer est suppose prdfinie "hors-connexion". La section 5.2 montre des exemples utilisant d'autres encodages.

Comme not dans l'item 6 ci-dessus, les RPCs peuvent aussi ncessiter de transporter des informations supplmentaires, potentiellement importantes pour le traitement de l'appel dans un environnement distribu, mais qui ne font pas partie de la description formelle de la procdure ou mthode. (Notez que ces informations supplmentaires contextuelles ne sont pas spcifiques RPC mais au traitement de n'importe quelle application distribue). Dans l'exemple, l'appel RPC est effectu dans un contexte de transaction globale impliquant plusieurs activits qui doivent toutes se terminer avec succs pour que le retour du RPC se fasse avec succs. L'exemple 4 montre comment un bloc d'en-tte transaction destin au rcepteur final (ce que l'on dduit de l'absence de l'attribut env:role) est utilis pour transporter une telle information. (La valeur "5" est un identifiant de transaction quelconque fix et comprhensible par l'application. Nous n'allons pas plus en dtails dans la smantique spcifique l'application de cet en-tte car elle ne se rapporte pas la discussion des aspects syntaxiques des messages SOAP RPC).

Supposons que l'appel RPC dans l'exemple de paiement a t conu pour avoir une description de procdure indiquant qu'il y a deux paramtres de sortie (ou "out"), l'un fournissant un numro de reference pour la rservation et l'autre une URL o les dtails de la rservation pourront tre vus. La rponse RPC est retourne dans l'lment env:Body d'un message SOAP, modlis comme une struct nomme d'aprs la procdure chargeReservation et, selon une convention, le mot Rponse ("Response") ajout. Les deux paramtres de sortie ("out") accompagnant la rponse sont le code alphanumrique identifiant la rservation en question et une URI pour l'endroit o la rservation peut tre vue (viewAt).

Ceci est illustr par l'exemple 5a, o le bloc d'en-tte identifie toujours la transaction dans laquelle l'appel RPC est ralis.

Les appels RPC ont souvent dans leur description un paramtre en sortie particulier, appel valeur de "retour" ("return" value). La convention RPC SOAP offre une manire de distinguer cette valeur de "retour" des autres paramtres en sortie dans la description de la procdure. Pour illustrer ceci, l'exemple de paiement est modifi pour obtenir une description presque identique l'exemple 5a, c'est--dire avec les mmes deux paramtres en sortie, mais avec en plus une valeur de "retour" sous la forme d'une numration de valeurs possibles : "confirm" (confirmed) ou "en attente" (pending). La rponse RPC conforme cette description se trouve dans l'exemple 5b, o l'en-tte SOAP, comme prcdemment, identifie la transaction dans laquelle a lieu l'appel RPC.

Exemple 5b

<?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:viewedAt>         http://travelcompany.example.org/reservations?code=FT35ZBQ        </m:viewedAt>     </m:chargeReservationResponse>  </env:Body> </env:Envelope>

Rponse RPC avec une valeur de "retour" et deux paramtres en sortie ("out") pour l'appel de l'exemple 4

Dans l'exemple 5b, la valeur de retour est identifie par l'lment rpc:result et contient le nom XML qualifi (XML Qualified Name, de type xs:QName) d'un autre lment de la struct qui, dans l'exemple 5b, est m:status, lment qui son tour contient la vritable valeur de retour, "confirmed". Cette technique permet de typer fortement la valeur de retour selon un schma donn. Si l'lment rpc:result est absent, comme c'est le cas dans l'exemple 5a, la valeur de retour n'est pas prsente ou est du type void.

Si en principe l'utilisation de SOAP pour RPC est indpendante du choix du moyen particulier de transfrer l'appel et le retour RPC, certaines liaisons sur un protocole supportant la squence d'change de messages de type Requte-Rponse SOAP pourraient tre plus adquates pour cela. Une liaison de protocole supportant cette squence d'change peut fournir une corrlation entre la requte et la rponse. Bien sr, le concepteur d'une application base sur RPC pourrait choisir de placer un identifiant spcial pour relier un appel et sa rponse dans un en-tte SOAP, en rendant ainsi le RPC indpendant de tout mcanisme de transfert sous-jacent. Dans tous les cas, les concepteurs d'applications doivent tre conscients de toutes les caractristiques des protocoles particuliers choisis pour transporter les RPCs SOAP, comme la latence, le synchronisme, etc.

Dans le cas courant, standardis dans la section 7 de SOAP Partie 2, d'utilisation de HTTP comme protocole de transport sous-jacent, une invocation RPC correspond naturellement une requte HTTP et la rponse RPC une rponse HTTP. La section 4.1 donne des exemples de transport de RPCs utilisant la liaison sur HTTP.

Cependant, il est bien de garder l'esprit que mme si la plupart des exemples de SOAP pour RPC utilisent la liaison sur HTTP, ce n'est pas le seul moyen.

2.3 Scenarii de faute

SOAP fournit un modle pour grer les situations de faute survenues lors du traitement d'un message. SOAP distingue les conditions qui aboutissent une faute et la capacit signaler cette faute au noeud d'origine du message fautif ou un autre noeud. Cette capacit signaler la faute dpend du mcanisme de transfert de message utilis et un des aspects de la spcification d'une liaison de SOAP sur un protocole sous-jacent est d'exprimer comment les fautes sont signales, le cas chant. Le reste de cette section suppose qu'un mcanisme de transfert est disponible pour signaler les fautes gnres lors du traitement des messages reus et se se concentre sur la structure d'un message de faute SOAP.

L'lment SOAP env:Body joue un autre rle distinct puisqu'il est l'endroit o l'on place cette information de faute. Le modle de faute SOAP (voir SOAP Partie 1, section 5.4) veut que toutes les fautes spcifiques SOAP et l'application soient rapportes en utilisant un seul lment distinct, env:Fault, transport dans l'lment env:Body. L'lment env:Fault contient deux sous-lements obligatoires, env:Code et env:Reason, et (optionnellement) des informations spcifiques l'application dans le sous-lment env:Detail de la faute. Un autre sous-lment optionnel, env:Node, identifie via une URI le noeud SOAP qui a gnr la faute, son absence dsignant le rcepteur final du message. Il existe un autre sous-lment optionnel, env:Role, qui identifie le rle que le noeud qui a gnr la faute tait en train de jouer.

Le sous-lment env:Code de env:Fault est lui-mme constitu d'un sous-lment env:Value, dont le contenu est spcifi dans la spcification SOAP (voir SOAP Part 1 section 5.4.6) ainsi que d'un sous-lment env:Subcode optionnel.

L'exemple 6a montre un message SOAP retourn en rponse la requte RPC de l'exemple 4 pour indiquer un chec du traitement de l'appel RPC.

Exemple 6a

<?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 zpracovn</env:Text>      </env:Reason>      <env:Detail>       <e:myFaultDetails          xmlns:e="http://travelcompany.example.org/faults" >         <message>Name does not match card number</message>         <errorcode>999</errorcode>       </e:myFaultDetails>      </env:Detail>    </env:Fault>  </env:Body> </env:Envelope>

Exemple de message SOAP indiquant un chec dans le traitement de l'appel RPC de l'exemple 4

Dans l'exemple 6a, l'lment de premier niveau env:Value utilise un nom qualifi en XML standard (du type xs:QName) pour indiquer qu'il s'agit d'une faute env:Sender, indiquant donc une erreur de syntaxe ou une information inapproprie dans le message. (Lorsqu'une faute env:Sender est reue par l'metteur, il est suppos effectuer une action de correction avant d'envoyer nouveau un message similaire). L'lment env:Subcode est optionnel et, s'il est prsent, comme dans cet exemple, qualifie davantage la valeur de son parent. Dans l'exemple 6a, le env:Subcode indique qu'une faute spcifique RPC, rpc:BadArguments, dfinie dans la section 4.4 de SOAP Partie 2, est la cause de l'chec du traitement de la requte.

La structure de l'lment env:Subcode a t choisie hirarchique - chaque env:Subcode fils a une env:Value obligatoire et un sous-lment env:Subcode optionnel - pour permettre de transporter des codes propres l'application. La structure hirarchique de l'lment env:Code permet un mcanisme uniforme pour faire passer plusieurs niveaux de codes de fautes. La premire env:Value est une faute de base spcifie dans SOAP 1.2 (voir SOAP Partie 1, section 5.4.6) et doit tre comprise par tous les noeuds SOAP. Les valeurs env:Value imbriques sont spcifiques l'application et reprsentent un dtail en plus ou un raffinement de la faute de base d'un point de vue de l'application. Certaines de ces valeurs peuvent galement tre standardises, comme les codes RPC standardiss dans SOAP 1.2 (voir SOAP Partie 2, section 4.3), ou d'autres standards utilisant SOAP comme protocole d'encapsulation. La seule obligation pour dfinir des valeurs de sous-codes spcifiques une application est de les qualifier dans un espace de nommage en utilisant n'importe quel espace autre que l'espace env de SOAP qui dfinit les classes principales de fautes SOAP. Il n'y a aucune obligation d'un point de vue SOAP que les applications comprennent ou mme regardent tous les niveaux des valeurs de sous-codes.

Le sous-lment env:Reason > href="http://www.w3.org/TR/2003/REC-soap12-part1-20030624/#faultstringelement"> n'a pas pour but un traitement algorithmique, mais plutt la comprhension par l'humain, donc mme si c'est un item obligatoire, la valeur choisie n'a pas besoin d'tre standardise. Par consquent tout ce qu'il faut est qu'il dcrive la situation de faute. Il doit avoir un ou plusieurs sous-lments env:Text, avec chacun un attribut xml:lang unique, permettant aux applications de donner des versions de la raison de la faute dans plusieurs langues. (Les applications pourraient ngocier la langue du texte de faute en utilisant un mcanisme base d'en-ttes SOAP ; cependant ceci sort du champ des spcifications SOAP).

L'absence d'un sous-lment env:Node de env:Fault dans l'exemple 6a implique qu'elle est gnre par le rcepteur final de l'appel. Le contenu de env:Detail, comme le montre l'exemple, est spcifique l'application.

Lors du traitement d'un message SOAP, une faute peut aussi tre gnre si un lment d'en-tte obligatoire n'est pas compris ou si l'information contenue n'est pas traitable. Les erreurs dans le traitement d'un bloc d'en-tte sont aussi signales par un lment env:Fault dans le env:Body, et un bloc d'en-tte spcial diffrent, env:NotUnderstood, identifie le bloc d'en-tte fautif.

L'exemple 6b montre un cas de rponse l'appel RPC de l'exemple 4 indiquant un chec dans le traitement du bloc d'en-tte t:transaction. Notez la prsence du code de faute env:MustUnderstand dans le env:Body et l'identification de l'en-tte non compris par l'attribut qname dans le bloc d'en-tte spcial (vide) env:NotUnderstood.

S'il venait y avoir plusieurs blocs d'en-tte obligatoires non compris, alors chacun d'eux pourrait tre identifi par son attribut qname dans une srie de sous-lments env::NotUnderstood.

3. Modle de traitement SOAP

Aprs avoir vu les divers aspects syntaxiques d'un message SOAP ainsi que quelques squences basiques d'change de messages, cette section donne une vue gnrale du modle de traitement SOAP (spcifi dans la section 2 de SOAP Partie 1). Le modle de traitement SOAP dcrit les actions (logiques) effectues par un noeud SOAP la rception d'un message.

L'exemple 7a montre un message SOAP avec plusieurs blocs d'en-tte (leur contenu est enlev pour raccourcir). Des variations de celui-ci seront utilises dans la suite de cette section pour illustrer divers aspects du modle de traitement.

Le modle de traitement SOAP dcrit les actions effectues par un noeud SOAP recevant un message SOAP. Il est obligatoire pour un noeud d'analyser les parties du message qui sont spcifiques SOAP, soit les lments dans l'espace de nommage "env". Parmi ces lments figurent l'enveloppe elle-mme, l'en-tte et le corps. Une premire tape consiste bien videmment vrifier globalement que le message SOAP est syntaxiquement correct. C'est--dire qu'il est conforme l'infoset XML SOAP sujet aux restrictions d'utilisation de certaines constructions XML - Instructions de traitement (Processing Instructions) et dfinition de type de document (Document Type Definition) - comme dcrit dans la section 5 de SOAP Partie 1.

3.1 L'attribut "role"

Le traitement en profondeur des blocs d'en-tte et du corps dpend du(des) rle(s) assurs par le noeud SOAP dans le traitement d'un message donn. SOAP dfinit l'attribut (optionnel) env:role - syntaxiquement, xs:anyURI - pouvant tre prsent dans un bloc d'en-tte, qui identifie le rle jou par la cible attendue de ce bloc d'en-tte. Un noeud SOAP est oblig de traiter un bloc d'en-tte s'il assure le rle identifi par la valeur de l'URI. Trois rles standardiss ont t dfinis (voir SOAP Partie 1, section 2.2), savoir :

Dans l'exemple 7a, le bloc d'en-tte oneBlock est destin tout noeud SOAP qui joue le rle dfini dans l'application par l'URI http://example.com/Log. A des fins d'illustration, il est suppos que la spcification d'un tel bloc d'en-tte oblige tout noeud SOAP adoptant ce rle enregistre ("log") tout le message dans un journal.

Tout noeud SOAP recevant un message avec un bloc d'en-tte possdant un attribut env:role de valeur "next" doit tre capable de traiter le contenu de l'lment, puisque c'est un rle standardis que chaque noeud SOAP doit tre prt assurer. Les blocs d'en-tte pourvus de cet attribut sont ceux qui sont censs tre examins et (ventuellement) traits par le noeud SOAP suivant sur le chemin du message, en supposant qu'un tel en-tte n'a pas t enlev par suite de son traitement par un noeud antrieur sur le chemin.

Dans l'exemple 7a, le bloc d'en-tte anotherBlock est destin au noeud suivant dans le cheminement du message. Dans ce cas, le message SOAP reu par le noeud jouant le rle applicatif de "http://example.com/Log" doit aussi tre prt jouer le rle de "next". Ceci est galement vrai pour le noeud rcepteur final du message, puisqu'il joue aussi videmment (et implicitement) le rle de "next" par le fait d'tre un noeud suivant dans le chemin du message.

Le troisime bloc d'en-tte, aThirdBlock, de l'exemple 7a n'a pas d'attribut env:role. Il est destin un noeud SOAP assurant le rle "ultimateReceiver". Le rle "ultimateReceiver" (qui peut tre dclar explicitement ou est implicite si l'attribut env:role est absent d'un bloc d'en-tte) est jou par un noeud SOAP assurant le rle de rcepteur final d'un message SOAP particulier. L'absence d'un attribut env:role dans le bloc d'en-tte aThirdBlock signifie que ce bloc est destin un noeud assurant ce rle "ultimateReceiver".

Notez que l'lement env:Body n'a pas d'attribut env:role. L'lment corps est toujours destin au noeud qui joue le rle "ultimateReceiver". En ce sens, l'lment corps est juste comme un bloc d'en-tte destin au rcepteur final, mais il a t distingu des autres pour permettre des noeuds SOAP (typiquement les intermdiaires SOAP) de le sauter s'ils assument des rles autres que celui de rcepteur final. SOAP ne prescrit aucune structure pour le corps, sauf la recommandation de qualifier tout sous-lment dans un espace de nommage XML. Certaines applications, comme l'exemple 1, peuvent choisir d'organiser les sous-lments de env:Body en blocs, mais ce n'est pas un problme en rapport avec le modle de traitement SOAP.

L'autre rle particulier de l'lment env:Body, comme conteneur o l'information sur les fautes spcifiques SOAP, c-a-d les checs de traitement d'lments d'un message SOAP, est place, a t dcrit prcdemment dans la section 2.3.

Si un lment d'en-tte possde l'attribut standardis env:role avec la valeur "none", cela signifie qu'aucun noeud SOAP n'aurait le devoir de traiter le contenu, bien qu'un noeud puisse avoir besoin de l'examiner s'il contient des donnes rfrences par un autre lment d'en-tte destin ce noeud SOAP en particulier.

Si l'attribut env:role a une valeur vide, c.a.d env:role="", cela signifie que l'URI relative identifiantle rle est rsolue par l'URI de base du message SOAP en question. SOAP Version 1.2 ne dfinit pas d'URI de base pour un message SOAP, mais se repose sur le mcanisme dfini dans [XMLBase] pour driver l'URI de base, qui peut tre utilise pour rendre absolue n'importe quelle URI relative. Ce mcanisme sert la liaison au protocole pour tablir l'URI de base, par exemple en rfrence au protocole d'encapsulation dans lequel le message SOAP est embarqu pour le transport. (En fait, lorsque des messages SOAP sont transports par HTTP, la section 7.1.2 de [SOAP Part2] dfinit l'URI de base comme l'URI de la requte HTTP (Request-URI), ou bien la valeur de l'en-tte HTTP Content-Location).

Le tableau suivant rsume les rles standardiss pouvant tre jous par divers noeuds SOAP. ("Oui" et "Non" signifient que le noeud correspondant joue ou ne joue pas le rle donn).

3.2 L'attribut "mustUnderstand"

L'exemple 7b ajoute l'exemple prcdent en introduisant un autre attribut pour les blocs d'en-tte, env:mustUnderstand ("doit comprendre").

Aprs qu'un noeud SOAP a correctement identifi les blocs d'en-tte (et ventuellement le corps) qui lui sont destins grce l'attribut env:role, l'attribut optionnel env:mustUnderstand dans les lments d'en-tte dtermine les actions de traitement ultrieures raliser. Afin de s'assurer que les noeuds SOAP n'ignorent pas des blocs d'en-tte importants pour l'objectif global de l'application, les blocs d'en-ttes SOAP fournissent aussi l'attribut optionnel env:mustUnderstand, qui, si sa valeur est "true" (vrai), signifie que le noeud SOAP cibl doit traiter le bloc selon la spcification de celui-ci. Un tel bloc est couramment dsign comme bloc d'en-tte obligatoire. En fait, le traitement d'un message SOAP ne peut mme pas commencer tant que le noeud n'a pas identifi tous les blocs d'en-tte obligatoires qui lui sont destins, et ne les a pas "compris". Comprendre un en-tte signifie que le noeud doit tre prpar faire tout ce qui est dcrit dans la spcification de ce bloc. (Gardez l'esprit que les spcifications de blocs d'en-tte ne sont pas partie intgrante de la spcification de SOAP).

Dans l'exemple 7b, le bloc d'en-tte oneBlock est marqu par une valeur de env:mustUnderstand "true", ce qui signifie qu'il est obligatoire de traiter ce bloc si le noeud joue le rle identifi par "http://example.com/log". Les deux autres blocs d'en-tte ne sont pas marqus ainsi, ce qui signifie que les noeud SOAP auxquels ces blocs sont destins n'ont pas besoin de les traiter. (Parce que certainement les spcifications de ces blocs autorisent cet tat de fait).

Une valeur de env:mustUnderstand "true" signifie que le noeud SOAP doit traiter l'en-tte avec la smantique dcrite dans la spcification de celui-ci, ou sinon gnrer une faute SOAP. Traiter l'en-tte de manire appropris peut inclure de retirer cet en-tte de tout message SOAP gnr, de rinsrer l'en-tte avec la mme ou une autre valeur, ou d'insrer un nouvel en-tte. L'incapacit traiter un en-tte obligatoire oblige stopper tout traitement du message SOAP plus avant et gnrer une faute SOAP. Le message ne sera pas renvoy plus loin.

L'lment env:Body n'a pas d'attribut env:mustUnderstand mais il doit tre trait par le rcepteur final. Dans l'exemple 7b, le rcepteur final du message - le noeud qui joue le rle "ultimateReceiver" - doit traiter le env:Body et peut traiter le bloc d'en-tte aThirdBlock. Il peut aussi traiter le bloc d'en-tte anotherBlock, puisqu'il lui est destin (de par le rle "next") mais il n'est pas oblig de le faire si les spcifications pour le traitement des blocs ne l'exigent pas. (si la spcification pour anotherBlock exigeait qu'il soit trait par le rcepteur final, elle obligerait le marquer par un env:mustUnderstand="true".)

Le(s) rle(s) que joue un noeud SOAP lorsqu'il traite un message peut tre dtermin par beaucoup de facteurs. Le rle peut tre connu a priori, ou dcid par quelques procds hors-ligne, ou bien un noeud peut inspecter toutes les parties d'un message reu pour dterminer quels rles il va assumer avant de traiter le message. Un cas intressant se produit lorsqu'un noeud SOAP, pendant l'avancement du traitement d'un message, dcide qu'il y a des rles supplmentaires qu'il a besoin d'adopter. Peu importe quand cette dtermination a lieu, de l'extrieur tout doit sembler respecter le modle de traitement. C'est--dire apparatre comme si le rle avait t connu depuis le dbut du traitement du message. En particulier, d'un point de vue externe la vrification de env:mustUnderstand dans les en-ttes contenant ce rle supplmentaire doit sembler avoir prcd le dbut du traitement. De plus, si un noeud SOAP assume de tels rles supplmentaires, il doit s'assurer qu'il est prpar pour faire tout ce que les spcifications de ces rles requirent.

Le tableau suivant rsume la manire dont les actions de traitement d'un bloc d'en-tte sont qualifies par l'attribut env:mustUnderstand en fonction du noeud cibl convenablement (par son attribut env:role).

En consquence du traitement d'un message SOAP, un noeud SOAP peut gnrer une simple faute SOAP s'il choue, ou, en fonction de l'application, gnrer des messages SOAP supplmentaires consommer par d'autres noeuds SOAP. La section 5.4 de SOAP Partie 1 dcrit la structure du message de faute tandis que le modle de traitement SOAP dfinit les conditions conduisant sa gnration. Comme illustr prcdemment dans la section 2.3, une faute SOAP est un message SOAP avec un sous-lment de env:Body standardis env:Fault.

SOAP fait une distinction entre gnrer une faute et s'assurer que la faute est renvoye l'origine du message ou un autre noeud appropri qui peut se servir de cette information. Cependant, pouvoir propager une faute gnre convenablement dpend de la liaison sur protocole sous-jacent choisie pour changer les messages. La spcification ne dfinit pas ce qui se produit si des fautes sont gnres durant la propagation de messages unidirectionnels. L'autre liaison normative, qui est la liaison sur HTTP, fournit la rponse HTTP comme moyen de rapporter une faute dans le message SOAP arrivant (voir section 4 pour plus de dtails sur les liaisons de SOAP sur protocoles).

3.3 L'attribut "relay"

SOAP Version 1.2 dfinit un autre attribut optionnel pour les blocs d'en-tte, env:relay de type xs:boolean. Il indique si un bloc d'en-tte cibl sur un intermdiaire SOAP doit tre relay s'il n'est pas trait.

Notez que si ce bloc d'en-tte est trait, les rgles de traitement de SOAP (voir SOAP Partie 1, section 2.7.2) imposent de le retirer du message sortant. (Il pourrait, cependant, tre rintroduit, intact ou avec un contenu modifi, si le traitement d'autres blocs d'en-tte dterminent que ce bloc d'en-tte doit tre conserv dans le message transmis). Le comportement par dfaut pour un bloc d'en-tte non trait adress un rle jou par un intermdiaire SOAP est de le retirer avant de relayer le message.

Ce choix de dfaut est une prcaution contre d'ventuelles suppositions qu'un intermdiaire pourrait faire propos de la "survie" aprs lui d'un bloc d'en-tte adress un rle qu'il assure. Ceci ajoute une fonctionnalit de valeur supplmentaire, surtout s'il choisit de ne pas traiter le bloc d'en-tte, probablement parce qu'il ne le comprend pas. Certains blocs reprsentent des fonctionnalits de proche en proche et cela n'a pas de sens de les transporter de bout en bout. Comme un intermdiaire peut ne pas tre en mesure de dterminer ceci, il est plus sr de retirer les blocs d'en-tte non traits avant de relayer le message.

Cependant, il existe des cas o un concepteur d'application voudrait introduire une nouvelle fonctionnalit, matrialise par un bloc d'en-tte SOAP, visant tout intermdiaire capable rencontr sur le cheminement du message SOAP. Un tel bloc d'en-tte serait disponible pour les intermdiaires qui le comprendraient (understood) mais ignor et relay par ceux qui ne le comprennent pas. En tant que nouvelle caractristique, le logiciel pour traiter ce bloc d'en-tte pourrait n'tre implment, au moins initialement, que sur certains noeuds SOAP. Marquer ce bloc en tant que env:mustUnderstand = "false" semble videmment ncessaire, pour que les intermdiaires n'implmentant pas la caractristique ne gnrent pas de faute. Pour contourner la rgle par dfaut du modle de traitement, marquer le bloc d'en-tte avec l'attribut supplmentaire env:relay avec la valeur "true" autorise l'intermdiaire faire suivre le bloc d'en-tte qui lui est destin s'il ne le traite pas.

Cibler le bloc d'en-tte sur le rle "next" avec l'attribut env:relay fix "true" (vrai) peut toujours servir s'assurer que chaque intermdiaire a une chance d'examiner le bloc, puisque une des utilisations probables de "next" concerne les blocs d'en-ttes vhiculant des informations supposes persister le long du chemin du message SOAP. Bien entendu, le concepteur d'application peut toujours dfinir un rle personnalis permettant de cibler des intermdiaires spcifiques jouant ce rle. Par consquent, il n'y a pas de restrictions sur l'utilisation de l'attribut env:relay avec n'importe quel rle, sauf bien sr avec "none" et "ultimateReceiver", pour lesquels cela n'a pas de sens.

Le bloc d'en-tte q:anotherBlock, adress au noeud suivant ("next") dans le cheminement du message, possde l'attribut supplmentaire env:relay="true". Un noeud SOAP recevant ce message peut traiter ce bloc s'il le comprend, le cas chant les rgles de traitement imposent de retirer le bloc ensuite avant de faire suivre le message. Cependant, si le noeud SOAP choisit d'ignorer ce bloc d'en-tte, ce qui est autoris du fait de l'absence de l'attribut env:mustUnderstand, alors il doit faire suivre le message en y laissant ce bloc.

Traiter le bloc d'en-tte p:oneBlock est obligatoire et les rgles de traitement de SOAP imposent de ne pas le relayer, sauf si le traitement d'un autre bloc requiert sa prsence dans le message sortant. Le bloc d'en-tte r:aThirdBlock n'a pas d'attribut env:relay, ce qui quivaut l'avoir avec la valeur env:relay="false". Donc ce bloc n'est pas relay s'il n'est pas trait.

SOAP1.2 Partie 1, Table 3 rsume les conditions dterminant si un intermdiaire SOAP assumant un rle donn est autoris racheminer des blocs d'en-ttes non traits.

4. Utilisation de diverses liaisons sur un protocole (protocol bindings)

Des messages SOAP peuvent tre changs grce une varit de protocoles "sous-jacents", notamment d'autres protocoles de la couche application. La spcification de la manire de passer des messages d'un noeud SOAP un autre en utilisant un protocole sous-jacent est appele une liaison sur le protocole (protocol binding). [SOAP Partie 1] dfinit un message SOAP sous la forme d'un ensemble d'informations XML [XML Infoset ], c'est--dire en termes d'items d'information lments et attributs dans un "document" appel env:Envelope (enveloppe) (voir SOAP Partie 1, section 5.1). Toute reprsentation d'infoset env:Envelope SOAP sera concrtise travers une liaison sur un protocole. L'objectif consiste notamment fournir une reprsentation srialise de l'infoset envoyer au noeud suivantsur le chemin du message, qui pourra alors reconstruire cet infoset sans perdre d'information. Dans les exemples typiques de messages SOAP et certainement dans tous les exemples de ce prliminaire, la srialisation montre est celle d'un document [XML 1.0] bien form. Cependant, il peut y avoir des liaisons sur protocoles - par exemple une liaison sur un protocole entre deux noeuds SOAP sur une bande passante limite - o une alternative, la srialisation compresse du mme infoset, peut tre prfre. Une autre liaison, choisie dans un but diffrent, pourrait fournir une srialisation en une structure chiffre reprsentant le mme infoset.

En plus d'une ralisation concrte d'un infoset SOAP entre noeuds adjacents sur un chemin, une liaison sur un protocole fournit les mcanismes supportant des fonctionnalits dont une application SOAP pourrait avoir besoin. Une caractristique est une spcification d'une certaine fonctionnalit fournie par une liaison. Une description de caractristique est identifie par une URI, pour que toutes les applications qui l'utilisent soient assures de la mme smantique. Par exemple, un scnario d'utilisation typique peut demander beaucoup d'changes requte-rponse simultans entre noeuds adjacents, auquel cas la fonctionnalit ncessaire est la capacit corrler une requte avec sa rponse. On peut citer comme autres exemples une caractristique de "canal crypt", une caractristique de "canal livraison fiable" ou une caractristique de Squence d'change de messages particulire.

Une spcification de liaison SOAP (voir SOAP Partie 1, section 4) dcrit entre autres quelles caractristiques (le cas chant) elle fournit. Certaines caractristiques peuvent tre fournies nativement par le protocole sous-jacent. Si la caractristique n'est pas disponible au travers de la liaison, elle peut tre implmente dans l'enveloppe SOAP, grce des blocs d'en-tte SOAP. La spcification d'une caractristique implmente par des blocs d'en-tte SOAP est appele module SOAP.

Par exemple, si les changes de messages SOAP taient transports sur un protocole de datagrammes, tel qu'UDP, la corrlation entre messages devrait bien videmment tre fournie ailleurs, peut-tre directement par l'application ou plus certainement dans une partie des infosets SOAP changs. Dans ce dernier cas, la corrlation prend une forme spcifique la liaison dans l'enveloppe SOAP, c'est--dire celle d'un bloc en-tte SOAP, dfini dans un module "Corrlation Requte-Rponse" identifi par une URI. Cependant, si les infosets SOAP taient changs en utilisant un protocole sous-jacent lui-mme requte-rponse, l'application pourrait implicitement "hriter" cette fonctionnalit fournie par la liaison et il n'y aurait pas besoin de support supplmentaire au niveau applicatif SOAP. (En fait, la liaison sur HTTP de SOAP tire parti juste de cette caractristique de HTTP).

Pourtant, un message SOAP peut voyager sur plusieurs bonds entre un metteur et le rcepteur final, avec une liaison sur un protocole diffrent pour chaque bond. En d'autres termes, une fonctionnalit (par ex. corrlation de message, fiabilit, etc.) supporte par la liaison sur un protocole pour un bond peut ne pas tre supporte par une autre dans le chemin suivi. SOAP lui-mme ne fournit pas de mcanisme pour cacher les diffrences de fonctionnalits des diffrents protocoles sous-jacents. Cependant, toute fonctionnalit requise par une application donne, mais qui ne serait pas disponible dans l'infrastructure sous-jacente au long du chemin anticip, peut tre compense en tant transporte comme partie de l'infoset du message SOAP, c'est--dire un bloc d'en-tte SOAP spcifi dans un module.

Il apparat donc qu'un certain nombre de problmes doivent tre rgls par le concepteur d'applications pour la smantique d'une application donne, notamment comment tirer parti des caractristiques natives des protocoles sous-jacents disponibles dans l'environnement choisi. La section 4.2 de SOAP Partie 1 donne une structure gnrale pour dcrire comment les applications bases sur SOAP peuvent choisir d'utiliser les fonctionnalits offertes par une liaison sur un protocole sous-jacent pour assurer une smantique particulire. Cette section tente aussi de dgager des grandes lignes pour crire des spcifications de liaison sur un protocole interoprable pour changer des messages SOAP.

Entre autres, une spcification de liaison doit dfinir une caractristique particulire : la(les) squence(s) d'change de messages qu'elle supporte. [SOAP Partie 2] dfinit deux de ces squences d'change de messages : une squence d'change de messages de type Requte-Rponse, o un message SOAP est chang dans chaque direction entre deux noeuds SOAP adjacents, et une squence d'change de messages de type Rponse, qui consiste en un message non-SOAP agissant comme une requte suivi d'un message SOAP inclus comme partie de la rponse.

[SOAP Partie 2] offre galement au concepteur d'application une fonctionnalit gnrale appele spcification de Mthodes Web qui permet aux applications de contrler totalement le choix des mthodes dites Web - GET, POST, PUT, DELETE, dont la smantique est dfinie dans les spcifications de [HTTP 1.1] - utilisables sur la liaison. Cette fonctionnalit est dfinie pour s'assurer que les applications utilisant SOAP peuvent le faire de manire compatible avec les principes architecturaux du World Wide Web. (Trs brivement, la simplicit et le passage l'chelle du Web sont largement dus aux quelques mthodes gnriques (GET, POST, PUT, DELETE) utilisables pour interagir avec toute ressource disponible sur le Web via une URI). La caractristique de spcification de mthode Web est supporte par la liaison SOAP HTTP, bien que, en principe, elle soit disponible dans toutes les liaisons.

La section 7 de SOAP Partie 2 spcifie une liaison standardise un protocole en utilisant la structure de [SOAP Partie 1] pour les liaisons : comment SOAP est utilis en conjonction avec HTTP comme protocole sous-jacent. SOAP Version 1.2 se restreint dfinir une liaison sur HTTP permettant d'utiliser la mthode POST avec la squence d'change de messages de type Requte-Rponse et la mthode GET avec la squence de type Rponse. D'autres spcifications pourraient dfinir dans le futur des liaisons de SOAP HTTP ou d'autres transports utilisant les autres mthodes Web (c-a-d PUT, DELETE).

Les prochaines sections montrent des exemples de deux liaisons sur protocole pour SOAP, [HTTP 1.1] et l'e-mail. Il convient de souligner nouveau que la seule liaison normative pour les messages SOAP 1.2 est celle sur [HTTP 1.1]. Les exemples de la section 4.2 montrant l'e-mail comme mcanisme de transport est simplement destin suggrer que d'autres choix sont possibles pour transporter des messages SOAP, bien que cela ne soit pas standardis actuellement. Une note du W3C [SOAP Email Binding] offre une application de la structure de liaison sur un protocole spcifie dans [SOAP Partie 1] en dcrivant une liaison exprimentale au transport par e-mail, spcifiquement bas sur la RFC 2822.

4.1 Liaison SOAP sur HTTP

HTTP a un modle de connexion bien connu et une squence d'change de messages. Le client identifie le serveur grce une URI, s'y connecte par le rseau TCP/IP sous-jacent, met un message de requte HTTP et reoit un message de rponse HTTP sur la mme connexion TCP. HTTP relie implicitement son message de requte au message de rponse, par consquent une application utilisant cette liaison peut dcider d'en dduire une corrlation entre un message SOAP envoy dans le corps d'une requte HTTP et le message SOAP retourn dans la rponse HTTP. De la mme manire, HTTP identifie l'extrmit serveur par une URI, Request-URI, qui peut aussi servir d'identifiant du noeud SOAP sur le serveur.

HTTP autorise de multiples intermdiaires entre le client initial et le serveur d'origine (origin server) identifi par la Request-URI de la requte, auquel cas le modle requte/rponse est une srie de telles paires. Notez cependant que les intermdiaires HTTP sont diffrents des intermdiaires SOAP.

La liaison sur HTTP dans [SOAP Partie 2] utilise la caractristique de mthodes Web SOAP pour permettre aux applications de choisir la dite "mthode Web" - en la restreignant soit GET soit POST - employer dans l'change de message HTTP. De plus, elle utilise deux squences d'change de messages qui offrent aux applications deux manires d'changer les messages SOAP via HTTP : 1) utiliser la mthode HTTP POST pour transporter des messages SOAP dans les corps de requtes et rponses HTTP, et 2) utiliser la mthode HTTP GET dans une requte HTTP pour retourner un message SOAP dans le corps de la rponse HTTP. La premire de ces squences est une instanciation spcifique HTTP de la caractristique d'une liaison appele squence d'change de message SOAP de type requte-rponse, alors que la seconde utilise la caractristique appele squence d'change de messages SOAP de type rponse.

L'objectif de ces deux types d'utilisation est de combiner les deux paradigmes d'interaction bien tablis dans le World Wide Web. Le premier type d'interaction permet l'utilisation de donnes dans le corps d'un HTTP POST pour crer ou modifier l'tat d'une ressource identifie par une URI laquelle la requte HTTP est destine. Le second type de structure d'interaction offre la possibilit d'utiliser une requte HTTP GET pour obtenir une reprsentation d'une ressource sans toucher son tat d'aucune manire. Dans le premier cas, l'aspect spcifique SOAP qui nous intresse est de placer dans le corps de la requte HTTP POST un message SOAP traiter (en suivant le modle de traitement SOAP) comme partie d'un traitement applicatif ncessaire pour respecter la smantique de POST. Quant au second, il est prvu pour le cas o la reprsentation de la ressource demande n'est pas renvoye en HTML, ou en fait un document XML gnrique, mais un message SOAP. En pratique, l'en-tte HTTP Content-Type du message de rponse l'identifie comme du type de media "application/soap+xml". Des diteurs de ressources sur le Web dtermineront probablement si telle ou telle ressource devrait tre rcupre et publie sous forme de messages SOAP. Notez cependant que des ressources peuvent, en gnral, tre publies sous plusieurs reprsentations et que la reprsentation voulue ou prfre est indique par l'application mettant la requte, grce l'en-tte HTTP Accept.

Un autre aspect de la liaison SOAP HTTP concerne la manire dont une application dtermine laquelle des deux squences d'change de messages utiliser. [SOAP Partie 2] fournit un guide sur les circonstances dans lesquelles les applications devraient utiliser l'une ou l'autre. (Il s'agit de conseils - mme s'ils sont trs recommands - puisque formuls avec la forme conditionnelle "DEVRAIT (SHOULD)" dans les spcifications au lieu d'obligations absolues, identifies par le terme "DOIT (MUST)", ces termes tant interprter comme dfinis dans la "RFC 2119 de l'IETF). La squence d'change de messages SOAP de type rponse avec la mthode GET est utilise lorsqu'une application est sre que l'change a pour but la rcupration d'informations, sans toucher la ressource dans l'interaction. Ce type d'interaction est dit sr et idempotent dans la spcification HTTP. Comme l'utilisation de HTTP GET dans SOAP n'autorise pas de message SOAP dans la requte, les applications qui ont besoin de fonctionnalits de l'interaction sortante seulement supporte par une expression spcifique la liaison dans l'infoset SOAP (c'est--dire des blocs d'en-tte SOAP) ne peuvent l'vidence pas utiliser cette squence d'change de messages. Notez que la liaison sur HTTP POST est disponible dans tous les cas.

Les sous-sections suivantes donnent des exemples d'utilisation de ces deux squences d'change de messages dfinies pour la liaison sur HTTP.

4.1.1. Utilisation de HTTP GET pour SOAP

L'utilisation de la liaison sur HTTP avec la squence d'change de messages SOAP de type Rponse est restreint la mthode HTTP GET. Ce qui signifie que la rponse une requte HTTP GET mise par un noeud SOAP est un message SOAP dans la rponse HTTP.

L'exemple 8a montre un HTTP GET dirig par l'application du voyageur (dans la continuation de l'exemple de scnario de rservation) vers l'URI http://travelcompany.example.org/reservations?code=FT35ZBQ o l'itinraire du voyageur peut tre visualis. (La manire dont l'URL a t donne est visible dans l'exemple 5a).

L'en-tte HTTP Accept sert indiquer la reprsentation prfre de la ressource demande, qui dans l'exemple est un type de media "application/soap+xml" l'usage de la machine client, plutt que le type de media "text/html" pour l'affichage dans un client navigateur l'usage de l'humain.

L'exemple 8b montre la rponse HTTP au GET de l'exemple 8a. Le corps de la rponse HTTP contient un message SOAP avec les dtails du voyage. Nous reportons la section 5.2 la discussion du contenu du message SOAP, puisqu'il ne se rapporte pas pour le moment la comprhension de l'utilisation de la liaison HTTP.

Exemple 8b

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 Jgvan 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>

Message SOAP retourn en rponse au HTTP GET de l'exemple 8a

Notez que les dtails de rservation auraient pu aussi tre renvoys sous forme d'un document (X)HTML, mais le but tait de montrer un cas o l'application de rservation retourne l'tat de la ressource (la rservation) sous une forme de media centre sur les donnes (un message SOAP), que la machine peut traiter, au lieu du (X)HTML qui aurait t trait par un navigateur. En effet, dans les utilisations prvues pour SOAP, il est plus probable que l'application cliente ne sera pas un navigateur.

En outre, comme indiqu dans l'exemple, l'utilisation de SOAP dans le corps de la rponse HTTP offre la possibilit d'exprimer des caractristiques spcifiques l'application au travers d'en-ttes SOAP. Grce SOAP, l'application bnficie d'une structure cohrente et d'un modle de traitement pour exprimer de telles caractristiques.

4.1.2 Utilisation de HTTP POST pour SOAP

L'utilisation de la liaison sur HTTP avec la squence d'change de messages SOAP de type Requte-Rponse est restreinte la mthode HTTP POST. Notez que l'utilisation de cette squence d'change de messages dans la liaison SOAP sur HTTP est disponible toutes applications, qu'elles soient changes axs donnes gnrales XML ou axs RPCs (comme dans les exemples) encapsuls dans des messages SOAP.

Les exemples 9 et 10 sont des utilisations de liaison sur HTTP avec la squence d'change de messages de type Requte-Rponse, sur le mme scnario que pour les exemples 4 et 5a respectivement, c'est--dire transport d'un appel RPC et sa rponse dans le corps d'un message SOAP. Les exemples et la discussion dans cette section se concentre seulement sur les en-ttes HTTP et leur rle.

L'exemple 9 montre une requte RPC destine l'application de service de voyages. Le message SOAP est envoy dans le corps d'une mthode HTTP POST destine l'URI identifiant la ressource "rservations" sur le serveur travelcompany.example.org. Lorsque l'on utilise HTTP, l'URI de la requte (Request-URI) indique la ressource laquelle l'invocation est "poste". Outre le fait d'tre une URI valide, SOAP n'impose aucune restriction formelle sur la forme d'une adresse (voir [RFC 2396] pour plus d'informations sur les URIs). Cependant, un des principes de l'architecture du Web est que toutes les ressources importantes sont identifies par des URIs. Ceci implique que la plupart des services SOAP bien construits seront incarns par un grand nombre de ressources, chacune ayant sa propre URI. En effet, beaucoup de ces ressources seront probablement cres dynamiquement durant l'excution du service, comme la rservation de voyage spcifique de l'exemple. Donc une application de rservation de voyages bien construite aura une URI diffrente pour chaque rservation et les requtes SOAP pourront les rcuprer ou les manipuler directement leur URI et non une seule URI "Reservations" monolithique, comme montr dans l'exemple 9. L'exemple 13 de la section 4.1.3 montre la manire privilgie d'adresser des ressources telles qu'une rservation de voyage particulire. Par consquent, nous laissons pour la section 4.1.3 la discussion dtaille de l'utilisation de SOAP/HTTP compatible avec l'archivtecture du Web.

Lorsqu'on place des messages SOAP dans des corps HTTP, le type de contenu (en-tte "Content-type") doit tre "application/soap+xml". (Le paramtre optionnel "charset", qui peut prendre la valeur "utf-8" ou "utf-16", apparat dans cet exemple, mais lorsqu'il est absent, les rgles de jeu de caractres pour [XML 1.0] seul s'appliquent au corps de la requte HTTP).

Exemple 9

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>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 Jgvan yvind     </n:name>         <o:number>123456789099999</o:number>     <o:expiration>2005-02</o:expiration>     </o:creditCard>    </m:chargeReservation>   </env:Body> </env:Envelope>

RPC de l'exemple 4 plac dans une requte HTTP POST

L'exemple 10 donne la rponse RPC (les dtails sont omis) envoye par le service de voyages dans la rponse HTTP correspondant la requte de l'exemple 5a. SOAP utilisant le transport HTTP suit la smantique des codes d'tat HTTP pour communiquer les informations d'tat dans HTTP. Par exemple, la srie de codes d'tat HTTP 2xx indique que la requte du client (incluant la composante SOAP) a t correctement reue, comprise, accepte, etc.

Si une erreur se produit au cours du traitement de la requte, la spcification de la liaison sur HTTP oblige utiliser une erreur HTTP 500 "Internal Server Error" (erreur interne du serveur) avec un message SOAP encapsul contenant une faute SOAP indiquant une erreur de traitement ct serveur.

L'exemple 11 est le mme message de faute SOAP que dans l'exemple 6a, mais avec des en-ttes HTTP en plus.

Exemple 11

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 zpracovn</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>

Exemple de message SOAP dans une rponse HTTP indiquant un chec dans la manipulation du corps SOAP de l'exemple 4

La section 7.4.1.2 de SOAP Partie 2 fournit le comportement dtaill de gestion des diffrents codes de rponse HTTP, c'est--dire les 2xx (succs), 3xx (redirection), 4xx (erreur client) et 5xx (erreur server).

4.1.3 Utilisation de SOAP compatible avec l'architecture du Web

Un des concepts centraux du World Wide Web est celui d'une URI comme identifiant d'une ressource. Des services SOAP utilisant la liaison sur HTTP et souhaitant interoprer avec d'autres logiciels du Web devraient utiliser des URIs pour donner une adresse toutes les ressources importantes de leur service. Par exemple, une utilisation trs importante - en fait prdominante - du World Wide Web est la rcupration d'informations pure, o la reprsentation d'une ressource disponible, identifie par une URI, est ramene par une requte HTTP GET sans toucher la ressource d'aucune faon. (C'est ce que l'on appelle une mthode sre et idempotente (safe and idempotent method) dans la terminologie HTTP). Publier une ressource rend disponible son URI, sur lesquelles des clients pourront faire un "GET", c'est le point important.

Dans de nombreux cas les messages SOAP sont conus seulement pour rcuprer des informations, comme une requte sur l'tat d'une ressource (ou d'un objet, en termes de programmation), au contraire d'utilisations qui excutent des manipulations de la ressource. Dans ce type de cas, l'utilisation d'un corps SOAP pour transporter la requte sur l'tat, avec un corps SOAP reprsentant l'objet en question, est perue comme contraire l'esprit du Web car la ressource n'est pas identifie par la Request-URI de la requte HTTP GET. (Dans certaines implmentations de SOAP/RPC, la Request-URI HTTP est souvent une entit intermdiaire qui doit valuer le message SOAP pour identifier la ressource, et non lidentifiant de la ressource elle-mme).

Pour souligner les changements ncessaires, l'exemple 12a montre la manire dconseille pour rcuprer de l'information de manire sre sur le Web. C'est un exemple d'appel RPC transport dans un message SOAP, toujours sur le thme de la rservation de voyages, o la requte vise rcuprer l'itinraire d'une rservation donne, identifie par un des paramtres de l'appel RPC : reservationCode. (Pour les besoins de la discussion, il est suppos que l'application utilisant cette requte RPC ne ncessite pas de fonctionnalits qui oblige utiliser des en-ttes SOAP).

Notez que la ressource rcuprer n'est pas identifie par l'URI cible de la requte HTTP mais doit tre obtenue en regardant dans l'enveloppe SOAP. Il est donc impossible, comme ce serait le cas avec d'autres URIs "GETables" sur le Web, de rendre ceci disponible via HTTP seul des clients sur le World Wide Web.

La section 4.1 de SOAP Partie 2 offre des recommandations pour dfinir des appels RPCs constituant des rcuprations sres et idempotentes d'informations de manire respectueuse du Web. Ceci en distinguant les aspects de la mthode et les paramtres spcifiques dans la dfinition RPC qui servent identifier les ressources de ceux qui servent d'autres buts. Dans l'exemple 12a, la ressource rcuprer est identifie par deux choses : la premire est qu'il s'agit d'un itinraire (partie du nom de la mthode), la seconde est la rfrence une instance particulire (un paramtre de la mthode). Dans un tel cas, il est recommand de placer ces parties identifiant la ressource quelque part dans la Request-URI de la requte HTTP, comme ceci : http://travelcompany.example.org/reservations/itinerary?reservationCode=FT35ZBQ.

En outre, lorsque la dfinition d'un RPC est telle que toutes les parties de sa description de mthode peuvent tre dcrites comme identifiant la ressource, ainsi la ressource en entier peut tre identifie par une URI et son fournisseur peut tre assur de la sret de la rcupration, SOAP 1.2 recommande le choix de la proprit de Mthode Web GET et l'utilisation de la squence d'change de messages SOAP de type Rponse comme dcrit dans la section 4.1.1, qui assurent que le RPC SOAP est excut de manire respectueuse du Web. L'exemple 12b montre la manire prfrable pour un noeud SOAP de demander la rcupration sre de la ressource.

Il est noter que SOAP Version 1.2 ne spcifie aucun algorithme pour dduire une URI de la dfinition d'un RPC reprsentant une rcupration pure d'information.

Notez cependant que si l'application requiert l'utilisation de fonctionnalits exprimables seulement par rapport une liaison donne dans l'infoset SOAP, c'est--dire grce des blocs d'en-tte SOAP, alors l'application doit choisir la mthode HTTP POST avec un message SOAP dans le corps de la requte.

Elle ncessiterait aussi l'utilisation de la squence d'change de messages SOAP de type Requte-Rponse implmente par un HTTP POST si la description RPC incluait des donnes (paramtres) qui n'identifiaient pas la ressource. Mme dans ce cas, HTTP POST avec un message SOAP peut tre reprsent de manire respectueuse du Web. Comme pour GET, [SOAP Partie 2] recommande dans le cas gnral que toute partie du message qui identifie la ressource recevant la requte POST figure dans la Request-URI de la requte HTTP. Les mmes paramtres peuvent videmment tre repris dans l'lment SOAP env:Body. (Les paramtres doivent tre repris dans le Body dans le cas d'un RPC bas sur SOAP puisqu'ils sont lis la description de procdure/mthode attendue par l'application rceptrice).

L'exemple 13 est similaire l'Exemple 9, excepte la modification de la Request-URI HTTP pour inclure le code de la rservation, qui sert identifier la ressource (la rservation en question, confirme et paye).

Exemple 13

POST /Reservations?code=FT35ZBQ 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:charge Reservation         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 Jgvan yvind       </n:name>       <o:number>123456789099999</o:number>       <o:expiration>2005-02</o:expiration>      </o:creditCard>     </m:chargeReservation>   </env:Body> </env:Envelope>

RPC de l'exemple 4 transport dans une requte HTTP POST de manire respectueuse du Web

Dans l'exemple 13, la ressource manipuler est identifie par deux choses : la premire est que c'est une rservation (partie du nom de la mthode), et la seconde est que c'est une instance donne de rservation (qui est la valeur du paramtre code de la mthode). Le reste des paramtres de l'appel RPC n'identifient pas la ressource mais sont des donnes auxilliaires traiter par la ressource. [SOAP Partie 2] recommande que les ressources accessibles par RPC bas sur SOAP placent, si possible, toute information identifiant la ressource dans une partie de l'URI identifiant la cible de l'appel RPC. Il est noter cependant que la [SOAP Partie 2] ne donne pas d'algorithme pour ce faire. De tels algorithmes pourront tre dvelopps dans le futur. Notez aussi que tous les lments identifiants de la ressource ont t repris comme dans l'Exemple 9 sous leur forme encode dans l'lment SOAP env:Body.

En d'autres termes, comme vu dans les exemples ci-dessus, la recommandation dans les spcifications de SOAP est d'utiliser les URIs en respectant la compatibilit avec l'architecture du Web - donc les identifiants de ressources - que ce soit avec GET ou POST.

4.2 SOAP sur e-mail

Les dveloppeurs d'applications peuvent utiliser l'infrastructure de l'e-mail Internet pour dplacer des messages SOAP soit comme texte de messages lectroniques soit comme attachements. Les exemples qui suivent donne une technique pour transporter les messages SOAP et ne devraient pas tre considrs comme la manire standard de procder. Les spcifications de SOAP 1.2 ne spcifient pas de telle liaison. Cependant, il existe une note du W3C non normative [SOAP Email Binding] dcrivant une liaison email pour SOAP, son but principal tant de dmontrer l'application de la structure gnrale pour les liaisons SOAP sur protocole dcrite dans [SOAP Part 1].

L'exemple 14 montre un message de requte de rservation de voyage de l'exemple 1 transport comme message lectronique entre agents utilisateurs de courrier, un metteur et un rcepteur. Le noeud rcepteur possde implicitement des fonctions SOAP, auxquelles le corps du courrier lectronique est dlivr pour tre trait. (Il est galement suppos que l'metteur possde des fonctions SOAP pour traiter les ventuelles fautes SOAP reues en rponse ou pour corrler tout message SOAP reu en rponse celui-ci).

Exemple 14

From: [email protected] To: [email protected] Subject: Travel to LA Date: Thu, 29 Nov 2001 13:20:00 EST Message-Id: <[email protected]>  Content-Type: application/soap+xml  <?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</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 Jgvan 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>

Message SOAP de l'exemple 1 transport dans un message SMTP

L'en-tte dans l'exemple 14 a la forme standard [RFC 2822] des messages lectroniques.

Si l'e-mail est un change de message unidirectionnel et qu'aucune garantie de livraison n'est fournie, des infrastructures de courrier lectronique telles que la spcification de SMTP (Simple Mail Transport Protocol) [SMTP] offrent un mcanisme de notification de livraison - dans le cas de SMTP, notification d'tat de livraison (Delivery Status Notification, DSN) et notification de classement du message (Message Disposition Notification, MDN). Ces notifications prennent la forme de messages lectroniques envoys l'adresse donne dans l'en-tte du courrier. Les applications ainsi que les utilisateurs finaux de l'e-mail peuvent utiliser ces mcanismes pour donner l'tat d'une transmission de message mais ceux-ci, s'ils sont dlivrs, sont des notifications au niveau SMTP. Le dveloppeur d'applications peut parfaitement comprendre les fonctions et les limitations de ces notifications de livraison ou risquer de supposer une donne dlivre avec succs alors qu'elle ne l'a pas t.

Les messages d'tat de livraison SMTP sont carts du traitement de messages par la couche SOAP. Les rponses SOAP aux donnes SOAP contenues seront retournes au travers d'un nouveau message lectronique qui peut ou non avoir un lien avec la requte de dpart au niveau SMTP. L'utilisation de l'en-tte In-reply-to: de la [RFC 2822] permet de faire la relation au niveau SMTP mais n'offre pas ncessairement de lien au niveau SOAP.

L'exemple 15 est exactement le mme scnario que dcrit pour l'exemple 2, qui montre le message SOAP (les dtails du corps sont omis pour abrger) envoy par l'application de service de voyages l'application de rservation du passager demandant des prcisions sur la rservation, mais transmis cette fois comme un message lectronique. Dans cet exemple, le Message-Id du message lectronique d'origine figure dans un en-tte supplmentaire In-reply-to: du message lectronique, ce qui relie les messages au niveau SMTP mais ne fournit pas de corrlation spcifique SOAP. Dans cet exemple, l'application s'appuie sur le bloc d'en-tte reservation pour corrler les messages SOAP. L encore, les fonctions qui ralisent cette corrlation dpendent de la conception des applications et ne sont pas du ressort de SOAP.

Exemple 15

From: [email protected] To: [email protected] Subject: Which NY airport? Date: Thu, 29 Nov 2001 13:35:11 EST Message-Id: <[email protected]> In-reply-to:<[email protected]> Content-Type: application/soap+xml  <?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</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 Jgvan yvind</n:name>   </n:passenger>  </env:Header>  <env:Body>   <p:itinerary      xmlns:p="http://travelcompany.example.org/reservation/travel">    <p:itineraryClarifications> 	... 	...    </p:itineraryClarifications>   </p:itinerary>  </env:Body> </env:Envelope>

Message SOAP de l'exemple 2 transport dans un message lectronique avec un en-tte le reliant un prcdent message

5. Scnarii d'utilisation avancs

5.1 Utilisation d'intermdiaires SOAP

Le scnario d'application de rservation de voyages donne l'opportunit d'exposer quelques utilisations d'intermdiaires SOAP. Rappelez-vous que l'change de base tait une rservation de voyage entre une application de rservation de voyages et service de voyages. SOAP ne spcifie pas comment un tel cheminement de message est dtermin et suivi. Cela sort du cadre de la spcification SOAP. Elle dcrit cependant comment un noeud SOAP devrait se comporter la rception d'un message dont il n'est pas le destinataire final. SOAP Version 1.2 dcrit deux types d'intermdiaires : les intermdiaires de racheminement et les intermdiaires actifs.

Un intermdiaire de racheminement est un noeud SOAP qui, en fonction de la smantique d'un bloc d'en-tte dans un message SOAP reu ou en fonction de la squence d'change de messages utilise, rachemine le message SOAP vers un autre noeud SOAP. Par exemple, le traitement d'un bloc d'en-tte "routage" dcrivant une caractristique de cheminement dans un message SOAP arrivant peut dicter le racheminement du message SOAP vers un autre noeud SOAP, identifi par des donnes dans ce bloc d'en-tte. Le format de l'en-tte SOAP du message SOAP sortant, c-a-d le placement de blocs d'en-ttes insrs ou rinsrs, serait dtermin par le traitement global cet intermdiaire de racheminement (forawrding intermediary) bas sur la smantique des blocs d'en-tte traits.

Un intermdiaire actif effectue quant lui un traitement supplmentaire sur un message SOAP arrivant avant de faire suivre le message, selon des critres non dcrits dans des blocs d'en-tte SOAP arrivant ou par la squence d'change de messages utilise. Des cas de telles interventions actives sur un noeud SOAP pourraient, par exemple, chiffrer certaines parties d'un message SOAP et fournir des informations sur la cl de chiffrement dans un bloc d'en-tte, ou inclure des informations supplmentaires dans un nouveau bloc d'en-tte pour horodater ou annoter le message sortant, par exemple, l'intention de noeuds suivants correctement cibls.

Un mcanisme via lequel un intermdiaire actif peut dcrire les modifications effectues sur un message consiste insrer des blocs d'en-tte dans le message SOAP sortant. Ces blocs d'en-tte peuvent informer les noeuds SOAP suivants jouant un role ncessitant de recevoir cette information. Dans ce cas, la smantique des blocs d'en-tte insrs devrait galement appeler la (r)insertion de blocs d'en-tte identiques ou autres au niveau des intermdiaires suivants, puisque c'est ncessaire pour assurer que le message puisse tre trait sans problme par des noeuds encore plus loin. Par exemple, si un message avec des blocs d'en-tte supprims pour tre chiffrs passe au travers d'un second intermdiaire (sans que le bloc d'origine soit dcrypt et reconstruit), alors l'indication du chiffrement doit tre conserve dans le second relais de message.

Dans l'exemple suivant, un noeud SOAP est introduit dans le cheminement de la requte entre les applications de rservation de voyage et de service de voyages, qui intercepte le message montr dans l'exemple 1. Un exemple d'un tel noeud pourrait tre un noeud qui enregistre toutes les demandes de voyages pour revue hors-ligne par un bureau des voyages de la socit. Notez que les blocs d'en-tte reservation et passenger dans cet exemple sont destins au(x) noeud(s) jouant le rle "next", c'est--dire tout noeud SOAP suivant dans le cheminement qui reoit le message. Les blocs d'en-ttes sont obligatoires (l'attribut mustUnderstand a pour valeur "true"), ce qui signifie que le noeud doit savoir qu'en faire (au travers d'une spcification externe de la smantique de ces blocs d'en-tte). Une spcification d'enregistrement pour de tels blocs d'en-tte peut simplement obliger enregistrer divers dtails du message chaque noeud le recevant et relayer le message inchang sur le chemin. (Notez que les spcifications des blocs d'en-tte doivent obliger rinsrer les mmes blocs d'en-tte dans le message sortant, car sinon le modle de traitement SOAP imposerait de les retirer). Dans ce cas, le noeud SOAP agit comme un intermdiaire de racheminement.

Un scnario plus complexe consiste modifier le message SOAP reu d'une certaine manire non prvue par l'metteur initial. Dans l'exemple qui suit, il est suppos que l'application de voyages de la socit sur l'intermdiaire SOAP attache un bloc d'en-tte au message SOAP de l'Example 1 avant de le relayer sur son chemin vers le service de voyages - destinataire final. Le bloc d'en-tte contient les contraintes imposes par une politique de dplacements pour le voyage demand. La spcification d'un tel bloc d'en-tte peut ncessiter que le destinataire final (et seulement lui, comme implicitement indiqu par l'absence de l'attribut role) utilise l'information qu'il contient lors du traitement du corps du message.

L'exemple 16 montre un intermdiaire actif insrant un bloc d'en-tte supplmentaire, travelPolicy, destin au rcepteur final et incluant des informations qualifiant le traitement de cette demande de voyage au niveau application.

Exemple 16

<?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</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 Jgvan yvind</n:name>   </n:passenger>   <z:travelPolicy      xmlns:z="http://mycompany.example.com/policies"        env:mustUnderstand="true">    <z:class>economy</z:class>    <z:fareBasis>non-refundable<z:fareBasis>    <z:exceptions>none</z:exceptions>   </z:travelPolicy>  </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>

Message SOAP de l'exemple 1 pour une rservation de voyage, aprs qu'un intermdiaire actif a insr un bloc obligatoire destin au rcepteur final du message

5.2 Utilisation d'autres schmas d'encodage

Si SOAP spcifie un schma d'encodage particulier (voir la section 3 de SOAP Partie 2), son utilisation est optionnelle et la spcification dit clairement que d'autres schmas d'encodage peuvent tre utiliss pour des donnes spcifiques une application dans un message SOAP. Pour cela, elle fournit l'attribut env:encodingStyle, de type xs:anyURI, pour qualifier les blocs d'en-tte, tout lment fils de l'lment SOAP env:Body et tout lment fils de env:Detail et sa descendance. Il signale un schma de srialisation pour le contenu englob ou au moins jusqu' ce qu'un autre lment indique un autre style d'encodage pour ses contenus englobs. Le choix de la valeur de l'attribut env:encodingStyle est spcifique l'application et la capacit interoprer est suppose dfinie "hors-ligne". Si cet attribut n'est pas prsent, alors rien ne permet de dire quel encodage est utilis.

Nous prsentons une utilisation de schma d'encodage alternatif dans l'exemple 17. A la suite du thme de rservation de voyage, cet exemple montre un message SOAP qui pourrait tre envoy au passager par le service de voyages aprs confirmation de la rservation, avec les dtails du voyage. (Le mme message a t utilis dans l'exemple 8b dans un autre contexte).

Exemple 17

<?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 Jgvan 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>

Message SOAP montrant l'utilisation d'un encodage alternatif pour l'lment Body

Dans l'exemple 17, le corps du message SOAP contient une description de l'itinraire utilisant l'encodage d'un graphe de ressources et leurs proprits dans le langage RDF (Resource Description Framework) [RDF]. (Trs brivement, puisque la syntaxe de RDF n'est pas le sujet de ce prliminaire, un graphe RDF relie des ressources - telles que la ressource de rservation de voyage disponible http://travelcompany.example.org/reservations?code=FT35ZBQ - d'autres ressources (ou valeurs) via des proprits, telles que passenger, et les dates de voyages outbound et return. L'encodage RDF pour l'itinraire peut avoir t choisi par exemple pour permettre au passager de le stocker dans une application de calendrier supportant RDF, qui pourrait alors tre interroge de manire complexe).

6. Changements entre SOAP 1.1 et SOAP 1.2

La version 1.2 de SOAP prsente un certain nombre de modifications dans la syntaxe et fournit de la smantique supplmentaire (ou clarifie) ce que dcrit SOAP 1.1 [SOAP 1.1]. Voici une liste de caractristiques o les deux spcifications diffrent. Le but de cette liste est de donner au lecteur un rsum concis et facilement accessible des diffrences entre les deux spcifications. Les changements suivants ont t prsents en catgories simplement pour faciliter les rfrences et, dans certains cas, un item pourrait aussi bien se placer dans une autre catgorie.

L'annexe A de SOAP Partie 1 fournit des rgles de gestion de version pour un noeud SOAP pouvant suuporter la transition de version depuis [SOAP 1.1] to SOAP la Version 1.2. En particulier, elle dfinit un bloc d'en-tte env:Upgrade qui peut tre utilis par un noeud SOAP 1.2 la rception d'un message [SOAP 1.1] pour envoyer un message de faute SOAP l'metteur pour signaler quelle version de SOAP il supporte.

7. Rfrences

[SOAP Partie 1] W3C Proposed Recommendation "SOAP 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 7 May 2003 (Voir http://www.w3.org/TR/soap12-part1).

[SOAP Partie 2] W3C Proposed Recommendation "SOAP 1.2 Part 2: Adjuncts", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 7 May 2003 (Voir http://www.w3.org/TR/soap12-part2).

[RFC 2396] IETF "RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998. (Voir http://www.ietf.org/rfc/rfc2396.txt).

[HTTP 1.1] IETF "RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, January 1997. (Voir http://www.ietf.org/rfc/rfc2616.txt).

[XML 1.0] W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. (Voir http://www.w3.org/TR/REC-xml).

[Namespaces in XML] W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. (Voir http://www.w3.org/TR/REC-xml-names/).

[XML Schema Part1] W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. (Voir http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/).

[XML Schema Part2] W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. (Voir http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/).

[SMTP] SMTP is defined in a series of RFCs:

RFC 2822 Internet Message Format. (Voir http://www.ietf.org/rfc/rfc2822.txt).
RFC 2045 Multipurpose Internet Mail Extensions (MIME) Part One:Format of Internet Message Bodies. (Voir http://www.ietf.org/rfc/rfc2045.txt).
RFC 2046 Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. (Voir http://www.ietf.org/rfc/rfc2046.txt).
RFC 1894 An Extensible Message Format for Delivery Status Notifications. (Voir http://www.ietf.org/rfc/rfc1894.txt).
RFC 2852 Deliver By SMTP Service Extension. (Voir http://www.ietf.org/rfc/rfc2852.txt.)
RFC 2298 An Extensible Message Format for Message Disposition Notifications. (Voir http://www.ietf.org/rfc/rfc2298.txt).

[RDF] W3C Recommendation "Resource Description Framework (RDF) Model and Syntax Specification", O. Lassila and R. Swick, Editors. World Wide Web Consortium. 22 February 1999. (Voir http://www.w3.org/TR/1999/REC-rdf-syntax-19990222.

[SOAP 1.1] W3C Note "Simple Object Access Protocol (SOAP) 1.1", Don Box et al, 8 May, 2000 (Voir http://www.w3c.org/TR/SOAP/)

[XML Infoset] W3C Recommendation "XML Information Set", John Cowan, Richard Tobin, 24 October 2001. (Voir http://www.w3.org/TR/xml-infoset/)

[SOAP MediaType] IETF Internet Draft "The 'application/soap+xml' media type", M. Baker, M. Nottingham, "draft-baker-soap-media-reg-03.txt", May 29, 2003. Voir http://www.ietf.org/internet-drafts/draft-baker-soap-media-reg-03.txt (notez que ce brouillon expire en novembre 2003)

[SOAP Email Binding] W3C Note "SOAP Version 1.2 Email Binding", Highland Mary Mountain et al, draft June 13, 2002. (Voir http://www.w3.org/TR/2002/NOTE-soap12-email-20020626.)

[XML Base] W3C Recommendation "XML Base", Jonathan Marsh, 27 June 2001. (Voir http://www.w3.org/TR/2001/REC-xmlbase-20010627/)

A. Remerciements

Highland Mary Mountain (Intel) a fourni la base de la section sur la liaison sur SMTP. Paul Denning a fourni un travail pour un scnario d'utilisation, qui a depuis t dplac dans le brouillon Scnarii d'utilisation. Stuart Williams, Oisin Hurley, Chris Ferris, Lynne Thompson, John Ibbotson, Marc Hadley, Yin-Leng Husband et Jean-Jacques Moreau ont fait des commentaires dtaills sur des versions prcdentes de ce document, tout comme bien d'autres personnes pendant la revue de brouillon de dernier appel. Jacek Kopecky a donn une liste de changements pour RPC et l'encodage SOAP.

Les membres du groupe de travail sont (au moment de la rdaction de ce document et par ordre alphabtique) : Carine Bournez (W3C), Michael Champion (Software AG), David Chappell (Sonic Software), Glen Daniels (Macromedia, formerly of Allaire), Colleen Evans (Sonic Software), David Fallside (IBM), Dietmar Gaertner (Software AG), Tony Graham (Sun Microsystems), Martin Gudgin (Microsoft Corporation, formerly of DevelopMentor), Marc Hadley (Sun Microsystems), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), John Ibbotson (IBM), Ryuji Inoue (Matsushita Electric), Kazunori Iwasa (Fujitsu Limited), Mario Jeckle (DaimlerChrysler R. & Tech), Mark Jones (AT&T), Anish Karmarkar (Oracle), Jacek Kopecky (Systinet/Idoox), Yves Lafon (W3C), Michah Lerner (AT&T), Noah Mendelsohn (IBM, formerly of Lotus Development), Jeff Mischkinsky (Oracle), Nilo Mitra (Ericsson), Jean-Jacques Moreau (Canon), Don Mullen (Tibco), Masahiko Narita (Fujitsu Limited), Eric Newcomer (IONA Technologies), Mark Nottingham (BEA Systems, formerly of Akamai Technologies), David Orchard (BEA Systems, formerly of Jamcracker), Andreas Riegg (DaimlerChrysler R. & Tech), Hervé Ruellan (Canon), Jeff Schlimmer (Microsoft Corporation), Miroslav Simek (Systinet/Idoox), Nick Smilonich (Unisys), Lynne Thompson (Unisys), Pete Wenzel (SeeBeyond), Volker Wiechers (SAP AG).

Ont t membres : Bill Anderson (Xerox), Vidur Apparao (Netscape), Camilo Arbelaez (WebMethods), Mark Baker (Idokorro Mobile (Planetfred), formerly of Sun Microsystems), Philippe Bedu (EDF (Electricité de France)), Olivier Boudeville (EDF (Electricité de France)), Don Box (Microsoft Corporation, formerly of DevelopMentor), Tom Breuel (Xerox), Dick Brooks (Group 8760), Winston Bumpus (Novell), David Burdett (Commerce One), Charles Campbell (Informix Software), Alex Ceponkus (Bowstreet), Miles Chaston (Epicentric), David Clay (Oracle), David Cleary (Progress Software), Conleth O'Connell (Vignette), Ugo Corda (Xerox), Paul Cotton (Microsoft Corporation), Fransisco Cubera (IBM), Jim d'Augustine (eXcelon), Ron Daniel (Interwoven), Dug Davis (IBM), Ray Denenberg (Library of Congress), Paul Denning (MITRE), Frank DeRose (Tibco), Mike Dierken (DataChannel), Andrew Eisenberg (Progress Software), Brian Eisenberg (DataChannel), John Evdemon (XMLSolutions), David Ezell (Hewlett-Packard), Eric Fedok (Active Data Exchange), Chris Ferris (Sun Microsystems), Daniela Florescu (Propel), Dan Frantz (BEA Systems), Michael Freeman (Engenia Software), Scott Golubock (Epicentric), Rich Greenfield (Library of Congress), Hugo Haas (W3C), Mark Hale (Interwoven), Randy Hall (Intel), Bjoern Heckel (Epicentric), Erin Hoffman (Tradia), Steve Hole (MessagingDirect Ltd.), Mary Holstege (Calico Commerce), Jim Hughes (Fujitsu Software Corporation), Yin-Leng Husband (Hewlett-Packard, formerly of Compaq), Scott Isaacson (Novell), Murali Janakiraman (Rogue Wave), Eric Jenkins (Engenia Software), Jay Kasi (Commerce One), Jeffrey Kay (Engenia Software), Richard Koo (Vitria Technology Inc.), Alan Kropp (Epicentric), Julian Kumar (Epicentric), Peter Lecuyer (Progress Software), Tony Lee (Vitria Technology Inc.), Amy Lewis (TIBCO), Bob Lojek (Intalio), Henry Lowe (OMG), Brad Lund (Intel), Matthew MacKenzie (XMLGlobal Technologies), Murray Maloney (Commerce One), Richard Martin (Active Data Exchange), Highland Mary Mountain (Intel), Alex Milowski (Lexica), Kevin Mitchell (XMLSolutions), Ed Mooney (Sun Microsystems), Dean Moses (Epicentric), Rekha Nagarajan (Calico Commerce), Raj Nair (Cisco), Mark Needleman (Data Research Associates), Art Nevarez (Novell), Henrik Nielsen (Microsoft Corporation), Kevin Perkins (Compaq), Jags Ramnaryan (BEA Systems), Vilhelm Rosenqvist (NCR), Marwan Sabbouh (MITRE), Waqar Sadiq (Vitria Technology Inc.), Rich Salz (Zolera), Krishna Sankar (Cisco), George Scott (Tradia), Shane Sesta (Active Data Exchange), Lew Shannon (NCR), John-Paul Sicotte (MessagingDirect Ltd.), Simeon Simeonov (Allaire), Simeon Simeonov (Macromedia), Aaron Skonnard (DevelopMentor), Soumitro Tagore (Informix Software), James Tauber (Bowstreet), Patrick Thompson (Rogue Wave), Jim Trezzo (Oracle), Asir Vedamuthu (WebMethods), Randy Waldrop (WebMethods), Fred Waskiewicz (OMG), David Webber (XMLGlobal Technologies), Ray Whitmer (Netscape), Stuart Williams (Hewlett-Packard), Yan Xu (DataChannel), Amr Yassin (Philips Research), Susan Yee (Active Data Exchange), Jin Yu (Martsoft).

Nous souhaitons galement remercier toutes les personnes qui ont contribu aux discussions dans [email protected].