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 - <carine@w3.org>
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: Pr�liminaire

Recommandation W3C 24 Juin 2003

Cette version :: http://www.w3.org/TR/2003/REC-soap12-part0-20030624/
Derni�re version :: http://www.w3.org/TR/soap12-part0/
Version pr�c�dente :: http://www.w3.org/TR/2003/PR-soap12-part0-20030507/
Editeurs :: Nilo Mitra (Ericsson)

Copyright � 2003 W3C^� (MIT, ERCIM, Keio), Tous Droits R�serv�s. W3C liability, trademark, document use, and software licensing rules apply.

Sommaire

1. Introduction

La partie 0 de SOAP Version 1.2 : Pr�liminaire est un document non normatif destin� � fournir un tutoriel facile d'acc�s � propos des caract�ristiques de la sp�cification SOAP Version 1.2. Son but est d'aider les personnes qui ont les comp�tences techniques n�cessaires � comprendre comment SOAP peut �tre utilis�, en d�crivant les structures de messages SOAP repr�sentatives et les s�quences 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, plut�t que les impl�mentateurs des sp�cifications SOAP, bien que ces derniers puissent en retirer quelque b�n�fice. Ce premier cours cherche � souligner les caract�ristiques essentielles de SOAP Version 1.2 et non d�crire compl�tement toutes les nuances et les cas limites. Par cons�quent, rien ne remplace les sp�cifications principales pour bien comprendre l'ensemble de SOAP. C'est pourquoi ce pr�liminaire fournit des liens vers les sp�cifications principales � chaque fois qu'un nouveau concept est introduit ou utilis�.

[SOAP Partie 1] d�finit l'enveloppe SOAP, qui donne une structure d'ensemble pour repr�senter 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 d�finit �galement une structure de liaison sur un protocole, qui d�crit comment sp�cifier la liaison de SOAP au-dessus d'un autre protocole.

[SOAP Partie 2] d�finit un mod�le de donn�es pour SOAP, un sch�ma d'encodage particulier pour les types de donn�es utilisables pour un appel de proc�dure distant (Remote Procedure Call, RPC), ainsi qu'une r�alisation concr�te de la structure de liaison sur un protocole sous-jacent d�finie dans [SOAP Partie 1]. Cette liaison permet l'�change de messages SOAP soit comme �quivalent d'une requ�te HTTP POST et d'une r�ponse, ou d'un message SOAP en r�ponse � un HTTP GET.

Ce document (pr�liminaire) n'est pas normatif, ce qui signifie qu'il ne fournit pas de sp�cification compl�te de SOAP Version 1.2. Les exemples fournis ne se veulent pas un compl�ment des sp�cifications formelles, et pour toute question d'interpr�tation ces derni�res font naturellement r�f�rence. Ces exemples montrent un sous-ensemble des utilisations suppos�es de SOAP. Dans les scenarii r�els d'utilisation, SOAP sera plut�t une partie de la solution globale et il pourrait y avoir d'autres imp�ratifs qui �chapperaient � ces exemples.

1.1 Aper�u

La version 1.2 de SOAP inclut la d�finition d'information bas�e sur XML utilisable pour �changer des informations structur�es et typ�es entre des pairs dans un environnement d�centralis� et distribu�. [SOAP Partie 1] explique qu'un message SOAP est formellement sp�cifi� comme un infoset XML [XML Infoset], qui fournit une description abstraite de son contenu. Les infosets peuvent avoir des repr�sentations sur-le-fil diff�rentes , 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 cr�er des s�quences d'interaction plus complexes (par exemple requ�te/r�ponse, requ�te/r�ponses multiples, etc.) en combinant des �changes unidirectionnels avec des caract�ristiques du protocole sous-jacent et/ou des informations propres � l'application. SOAP ne dit rien sur la s�mantique des donn�es applicatives qu'il transporte, tout comme sur les probl�mes tels que le routage des messages SOAP, le transfert de donn�es fiable, le passage de pare-feu, etc. Cependant, SOAP offre une structure sur laquelle les informations propres � une application peuvent �tre transport�es de mani�re extensible. En outre, SOAP donne une description compl�te des actions requises ex�cut�es par un noeud SOAP lorsqu'il re�oit 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 requ�te-r�ponse incluant les RPCs. Les situations de fautes sont �galement d�crites.

La section 3 donne une vue d'ensemble du mod�le de traitement, qui d�crit les r�gles pour la construction initiale d'un message, pour letraitement � la r�ception par un interm�diaire ou r�cepteur final, et pour l'insertion, la suppression ou la modification de parties du message par les actions d'un interm�diaire.

La section 4 de ce document d�crit les mani�res de transporter les messages SOAP pour r�aliser divers scenarii d'utilisation. Elle d�crit la liaison de SOAP sur HTTP sp�cifi�e dans [SOAP Partie 2], ainsi qu'un exemple de transport de message SOAP par e-mail. Elle introduit, comme parties int�grantes de la liaison sur HTTP, deux s�quences d'�changes de messages disponibles pour les applications, une utilisant la m�thode HTTP POST, l'autre utilisant HTTP GET. Des exemples montrent comment des RPCs, en particulier la r�cup�ration d'informations "s�re", peuvent �tre repr�sent�s par des messages SOAP de mani�re 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 �l�ments d'en-t�te comme m�canisme d'extension, qui peuvent �tre adress�s � des noeuds SOAP interm�diaires sp�cifiques, pour fournir des services � valeur ajout�e aux applications communicantes, et l'usage de divers sch�mas d'encodage pour s�rialiser des donn�es applicatives dans des messages SOAP.

Pour faciliter les r�f�rences, les termes et concepts utilis�s dans ce pr�liminaire sont hyper-li�s � leur d�finition dans les sp�cifications principales.

1.2 Conventions de notation

Au long de ce pr�liminaire, les exemples d'enveloppes et de messages SOAP sont montr�s comme des documents XML 1.0. [SOAP Partie 1] explique que les messages SOAP sont formellement sp�cifi�s 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'int�resser ceux qui lisent ce pr�liminaire comme une introduction � SOAP ; ceux qui s'y int�ressent (typiquement ceux qui portent SOAP sur de nouvelles liaisons sur un protocole o� les messages peuvent avoir plusieurs repr�sentations) doivent comprendre ces exemples comme des r�f�rences aux infosets correspondants. Plus de d�tails sur ce point sont disponibles dans la section 4 de ce document.

Les pr�fixes d'espaces de nommage "xs" et "xsi" utilis�s dans les textes de ces sections sont associ�s aux noms d'espace de nommage "http://www.w3.org/2001/XMLSchema" et "http://www.w3.org/2001/XMLSchema-instance" respectivement, tous deux d�finis dans la sp�cification XML Schemas [XML Schema Part1], [XML Schema Part2].

Notez que le choix de tout autre pr�fixe d'espace de nommage est arbitraire et n'a pas de s�mantique.

Les URIs des espaces de noms de la forme g�n�rale "http://example.org/..." et "http://example.com/..." repr�sentent une URI d�pendante 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 r�cepteur SOAP, mais les messages SOAP sont suppos�s �tre combin�s par les applications pour impl�menter les s�quences plus complexes d'interactions, de la requ�te-r�ponse aux �changes multiples "conversationnels" dans un sens et dans l'autre.

Ce pr�liminaire commence par exposer la structure d'un message SOAP et son �change dans un sc�nario d'utilisation simple bas� sur une application de r�servation de voyages. Divers aspects de ce sc�nario d'application seront utilis�s au long de ce pr�liminaire. Dans ce sc�nario, l'application de r�servation de voyages pour un employ� d'une compagnie n�gocie une r�servation de voyage � l'aide d'un service de r�servation pour un circuit planifi�. L'information �chang�s entre le voyageur et le services des voyages prend la forme de messages SOAP.

Le r�cepteur final du message SOAP envoy� par l'application du voyageur est le service de r�servation, mais il est possible que le message soit "d�rout�" par un ou plusieurs interm�diaires SOAP qui agissent d'un certaine mani�re sur le message. Par exemple, ces interm�diaires peuvent �crire une trace, auditer, ou modifier chaque requ�te de voyage. Des exemples et une discussion plus d�taill�e du comportement et du r�le des interm�diaires SOAP n'arrivera qu'en section 5.1.

La section 2.1 d�crit une requ�te de r�servation sous la forme d'un message SOAP, ce qui permet de montrer les diff�rentes "parties" d'un message SOAP.

La section 2.2.1 continue le m�me sc�nario pour montrer une r�ponse 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 requ�te de voyage sont n�goci�es.

La section 2.2.2 suppose que les diff�rents param�tres de la r�servation ont �t� accept�s par le voyageur, et qu'un �change - mod�lis� comme un appel de proc�dure distante (RPC) - entre le voyageur et le service de voyages confirme les points de la r�servation.

2.1 Messages SOAP

L'exemple 1 montre les donn�es pour une r�servation de voyage exprim�es 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 J�gvan �yvind</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary
    xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>New York</p:departing>
     <p:arriving>Los Angeles</p:arriving>
     <p:departureDate>2001-12-14</p:departureDate>
     <p:departureTime>late afternoon</p:departureTime>
     <p:seatPreference>aisle</p:seatPreference>
   </p:departure>
   <p:return>
     <p:departing>Los Angeles</p:departing>
     <p:arriving>New York</p:arriving>
     <p:departureDate>2001-12-20</p:departureDate>
     <p:departureTime>mid-morning</p:departureTime>
     <p:seatPreference/>
   </p:return>
  </p:itinerary>
  <q:lodging
   xmlns:q="http://travelcompany.example.org/reservation/hotels">
   <q:preference>none</q:preference>
  </q:lodging>
 </env:Body>
</env:Envelope>

Message d'exemple pour une r�servation de voyage contenant des blocs d'en-t�te et un corps.

Le message SOAP de l'exemple 1 contient deux sous-�l�ments sp�cifiques � SOAP � l'int�rieur de l'env:Envelope externe, un env:Header (en-t�te) et un env:Body (corps). Les contenus de ces �l�ments sont d�finis par l'application et ne font pas partie de la sp�cification de SOAP, bien que celle-ci ait quelque chose � dire sur la mani�re dont ces �l�ments seront trait�s.

L'en-t�te SOAP est optionnel mais il a �t� inclus dans cet exemple pour expliquer certaines caract�ristiques. Un en-t�te SOAP est un m�canisme d'extension qui donne un moyen de passer des informations dans un message SOAP sans poids pour l'application. Ces informations de "contr�le" incluent, par exemple, des directives ou des informations contextuelles li�es au traitement du message. Ceci permet d'�tendre un message SOAP de mani�re sp�cifique � l'application. Les �l�ments fils imm�diats d'un �l�ment env:Header sont appel�s blocs d'en-t�te et repr�sentent un regroupement logique de donn�es qui, comme d�crit plus loin, peuvent �tre destin�es individuellement � des interm�diaires rencontr�s sur le chemin suivi par le message entre l'�metteur et le destinataire final.

Les en-t�tes SOAP ont �t� con�us pour anticiper des utilisations diverses de SOAP, parmi lesquelles beaucoup impliquent la participation d'autres noeuds SOAP - appel�s interm�diaires SOAP - au long du cheminement d'un message depuis un �metteur SOAP initial jusqu'� un r�cepteur SOAP final. Ceci permet � ces noeuds d'�changer des informations ajoutant de la valeur au service. Les en-t�tes, comme montr� plus loin, peuvent �tre inspect�s, ins�r�s, supprim�s ou r�achemin�s par les noeuds SOAP rencontr�s au long d'un chemin de message SOAP. (Il faut garder � l'esprit que la sp�cification SOAP ne s'occupe pas de ce qu'est le contenu des �l�ments d'en-t�tes, ni de la fa�on d'acheminer les messages entre noeuds, ni de d�terminer la route, etc. Ces probl�mes font partie de l'application dans son ensemble et pourrait faire l'objet d'autres sp�cifications).

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

Dans l'exemple 1, l'en-t�te contient deux blocs d'en-t�te, chacun d'eux �tant d�fini dans son propre espace de nommage XML et repr�sentant un aspect du traitement global du corps du message SOAP. Pour cette application de r�servation de voyage, une telle "meta" information appartenant � la requ�te globale est un bloc d'en-t�te reservation qui fournit une r�f�rence et une date pour cette instance de r�servation ; l'identit� du voyageur se trouve dans le bloc passenger.

Les blocs d'en-t�te reservation et passenger doivent �tre trait�s par le prochain interm�diaire SOAP rencontr� sur le chemin suivi ou, s'il n'y a pas d'interm�diaire, par le r�cepteur final du message. Le fait qu'il soit adress� au prochain noeud SOAP rencontr� est indiqu� par la pr�sence de l'attribut env:role avec la valeur "http://www.w3.org/2003/05/soap-envelope/role/next" (d�sign�e plus loin simplement par "next"), qui est un r�le que tous les noeuds SOAP doivent jouer. La pr�sence de l'attribut env:mustUnderstand avec la valeur "true" indique que ce(s) noeud(s) traitant l'en-t�te doi(ven)t absolument traiter ces blocs d'en-t�te de mani�re coh�rente avec leurs sp�cifications, ou sinon ne pas traiter le message du tout et renvoyer une faute. Notez que chaque fois qu'un bloc d'en-t�te est trait�, parce qu'il est marqu� env:mustUnderstand="true" ou pour une autre raison, le bloc doit �tre trait� selon les sp�cifications de ce bloc. De telles sp�cifications sont d�finies dans l'application et ne font pas partie de SOAP. La section 3 donnera plus de d�tails sur le traitement de message SOAP en fonction des valeurs de ces attributs.

Le choix des donn�es � placer dans un bloc d'en-t�te ou dans le corps est une d�cision de conception de l'application. Le principal point � consid�rer est que les blocs d'en-t�te peuvent �tre adress�s � diff�rents noeuds potentiellement rencontr�s sur le chemin du message. De tels noeuds SOAP interm�diaires peuvent fournir une valeur ajout�e au service, bas�e sur les donn�es de ces en-t�tes. Dans l'exemple 1, les informations passager sont plac�es dans un bloc d'en-t�te pour illustrer l'utilisation de cette donn�e sur un interm�diaire SOAP pour des traitements suppl�mentaires. Par exemple, comme indiqu� dans la section 5.1, le message sortant est modifi� par l'interm�diaire SOAP, qui ajoute au message les politiques de voyage de ce passager sous la forme d'un autre bloc d'en-t�te.

L'�l�ment env:Body et ses fils itinerary et lodging sont destin�s � �changer de l'information entre l'�metteur SOAP initial et le noeud SOAP qui assume le r�le de r�cepteur SOAP final dans le chemin du message, qui dans ce cas est le service de r�servation de voyages. Donc le env:Body et son contenu sont implicitement adress�s et suppos�s �tre compris par le r�cepteur final. Les moyens gr�ce auxquels un noeud SOAP assume un tel r�le ne sont pas d�finis dans la sp�cification SOAP mais font partie de la s�mantique globale de l'application et du flux de messages associ�.

Notez qu'un interm�diaire SOAP peut d�cider de jouer le r�le de r�cepteur 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 l�g�re car il peut d�tourner les intentions de l'�metteur du message et avoir des effets de bord ind�sirables (tels que ne pas traiter les blocs d'en-t�te qui seraient adress�s � des interm�diaires suivants dans le cheminement du message).

Un message SOAP tel que dans l'exemple 1 peut �tre transport� sur diff�rents protocoles sous-jacents et utilis� dans diverses s�quences d'�change de messages. Par exemple, avec un acc�s bas� sur le Web au service de voyages, il peut �tre plac� dans une requ�te HTTP POST. Dans une autre liaison de protocole, il peut �tre envoy� dans un message �lectronique (voir section 4.2). La section 4 d�crira comment des messages SOAP peuvent �tre achemin�s sur diff�rents protocoles sous-jacents. Pour le moment, il est suppos� qu'il existe un m�canisme de transfert des messages et la suite de la section se concentre sur les d�tails 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 transf�rer de l'information sp�cifi�e sous forme d'infosets XML entre un �metteur SOAP initial et un r�cepteur SOAP final. Typiquement, les scenarii les plus int�ressants impliquent de multiples �changes de messages entre ces deux noeuds. Le plus simple est la s�quence requ�te-r�ponse. Des utilisations premi�res de [SOAP 1.1] mettaient l'accent sur l'utilisation de cette s�quence comme moyen de v�hiculer des appels de proc�dure distante (remote procedure calls, RPC), mais tous les �changes de type requ�te-r�ponse n'ont ou ne n�cessitent pas une mod�lisation en appels de proc�dure distante (RPC). Ces derniers sont utilis�s quand il faut mod�liser un certain comportement programmatique avec des messages �chang�s conformes � une description bien d�finie pour l'appel distant et son retour.

Un panel beaucoup plus large de scenarii d'utilisation que ceux couverts par la s�quence de type requ�te-r�ponse peut �tre mod�lis� simplement comme des �changes de contenu bas� sur XML �chang� dans des messages SOAP pour former une conversation bidirectionnelle, o� la s�mantique se situe au niveau des applications �mettrice et r�ceptrice. La section 2.2.1 couvre le cas d'�change de contenu bas� sur XML �chang� dans des messages SOAP entre l'application de r�servation de voyages et le service des voyages selon un mod�le conversationnel et la section 2.2.2 donne un exemple d'�change mod�lis� en RPC.

2.2.1 Echange de message de type Document

En continuant sur le sc�nario de demande de voyage, l'exemple 2 montre un message SOAP renvoy� par le service de voyages en r�ponse � la requ�te de r�servation de l'exemple 1. Cette r�ponse cherche � affiner des informations de la requ�te : le choix d'a�roport de la ville de d�part.

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 J�gvan �yvind</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itineraryClarification 
    xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>
       <p:airportChoices>
            JFK LGA EWR 
       </p:airportChoices>
     </p:departing>
   </p:departure>
   <p:return>
     <p:arriving>
       <p:airportChoices>
           JFK LGA EWR 
       </p:airportChoices>
     </p:arriving>
   </p:return>  
  </p:itineraryClarification>
 </env:Body>
</env:Envelope>

Message SOAP envoy� en r�ponse au message de l'exemple 1

Comme d�crit pr�c�demment, le env:Body renferme le contenu premier du message, qui dans l'exemple inclut une liste des alternatives pour l'a�roport, conform�ment � une d�finition de sch�ma dans l'espace de nommage XML http://travelcompany.example.org/reservation/travel. Dans cet exemple, les blocs d'en-t�te de l'exemple 1 sont retourn�s (avec des valeurs de sous-�l�ments modifi�es) dans la r�ponse. Ceci permettrait une corr�lation entre messages au niveau de SOAP, mais de tels en-t�tes ont plus s�rement d'autres utilisations propres � l'application.

L'�change de messages des exemples 1 et 2 est un cas o� des contenus bas�s sur XML conformes � un sch�ma d�fini dans l'application sont �chang�s via des messages SOAP. Nous diff�rons de nouveau la discussion � la section 4 au sujet des moyens de transfert employ�s.

Il est assez simple de voir comment de tels �changes peuvent construire une s�quence "conversationnelle" multiple d'�change de messages. L'exemple 3 montre un message SOAP envoy� par l'application de r�servation de voyages en r�ponse � celui de l'exemple 2 pour choisir un des a�roports disponibles dans la liste. Le bloc d'en-t�te reservation avec la m�me valeur du sous-�l�ment reference accompagne chaque message de cette conversation, offrant ainsi un moyen d'�tablir, si n�cessaire, 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 J�gvan �yvind</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary 
   xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>LGA</p:departing>
   </p:departure>
   <p:return>
     <p:arriving>EWR</p:arriving>
   </p:return>
  </p:itinerary>
 </env:Body>
</env:Envelope>

R�ponse au message de l'exemple 2 continuant une s�quence conversationnel d'�change de message

2.2.2 Appels de proc�dure distante (Remote procedure calls)

Un des objectifs du design de SOAP Version 1.2 est d'encapsuler la fonctionnalit� d'appel de proc�dure distante gr�ce � l'extensibilit� et la flexibilit� de XML. la section 4 de SOAP partie 2 a d�fini une repr�sentation uniforme d'invocations et de r�ponses RPC transport�es dans des messages SOAP. Cette section poursuit le sc�nario de r�servation de voyages pour illustrer l'utilisation de messages SOAP dans l'appel de proc�dure distante et dans son retour.

Pour cela, le sc�nario montre le paiement du voyage par carte de cr�dit. (les �changes conversationnels d�crits dans la section 2.2.1 sont suppos�s avoir abouti � un itin�raire confirm�). Ici, il est de plus suppos� se placer dans le contexte d'une transaction globale o� la carte de cr�dit n'est d�bit�e que lorsque le voyage et le s�jour (non explicit� dans les exemples ici, mais r�serv� probablement de la m�me mani�re) sont confirm�s tous les deux. Le passager fournit les informations sur sa carte de cr�dit et les diff�rentes activit�s se terminent, en cas de succ�s, par le d�bit du montant et l'�mission en retour d'un num�ro de r�servation. Cette interaction r�serve-et-d�bite entre le passager et le service de voyages est mod�lis�e par un RPC SOAP.

Elles peuvent �tre exprim�s 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 diff�rent l�g�rement de celles g�n�ralement n�cessaires 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 mani�re appropri�e) le r�le de r�cepteur SOAP final. Comme le requiert l'item 1, le r�cepteur final peut identifier la cible de la proc�dure ou m�thode d�sign�e en regardant son URI. La fa�on de rendre l'URI disponible d�pend de la liaison au protocole sous-jacent. Une possibilit� consiste � v�hiculer l'URI identifiant la cible dans un bloc d'en-t�te SOAP. Certaines liaisons sur des protocoles, telles que la liaison SOAP sur HTTP d�finie dans [SOAP Partie 2], offrent un m�canisme de transport de l'URI en dehors du message SOAP. En g�n�ral, la description du moyen de transporter l'URI cible dans la liaison doit �tre l'une des propri�t�s d'une sp�cification de liaison sur un protocole. Nous remettons � la section 4.1 la discussion et des exemples concr�ts de mani�res de transporter l'URI dans le cas de la liaison standardis�e 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 mani�re 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 li�s aux requ�tes 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 J�gvan �yvind
     </n:name>     
     <o:number>123456789099999</o:number>
     <o:expiration>2005-02</o:expiration>
     </o:creditCard>
  </m:chargeReservation>
 </env:Body>
</env:Envelope>

Requ�te RPC SOAP avec un en-t�te obligatoire et deux param�tres entrants ("in")

L'appel RPC lui-m�me est un fils de l'�l�ment env:Body et est mod�lis� par une struct qui prend le nom de la proc�dure ou m�thode, dans ce cas chargeReservation. (Une struct est un concept du mod�le de donn�es SOAP, d�fini dans [SOAP Part2], qui mod�lise une structure ou un type d'enregistrement qui appara�t dans des langages de programmation courants). La conception de l'appel RPC dans l'exemple (sa description n'a pas encore �t� explicit�e) prend deux param�tres d'entr�e (ou "in"), la reservation du voyageur et l'information creditCard. Ce dernier est aussi une struct, qui poss�de trois �l�ments : le nom du titulaire de la carte (name), le num�ro 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� s�rialis� selon les r�gles d'encodage SOAP, c'est-�-dire plus pr�cis�ment les r�gles d�finies dans la section 3 de SOAP Partie 2. M�me si SOAP sp�cifie ce sch�ma d'encodage particulier, son utilisation est optionnelle et la sp�cification indique clairement que d'autres sch�mas d'encodage peuvent �tre utilis�s pour des donn�es applicatives dans un message SOAP. C'est pour cela qu'existe l'attribut env:encodingStyle pour qualifier les blocs d'en-t�te et les sous-�lements du corps. Le choix de la valeur de cet attribut est une d�cision sp�cifique � l'application et la capacit� d'un appelant et un appel� � interop�rer est suppos�e pr�d�finie "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 n�cessiter de transporter des informations suppl�mentaires, potentiellement importantes pour le traitement de l'appel dans un environnement distribu�, mais qui ne font pas partie de la description formelle de la proc�dure ou m�thode. (Notez que ces informations suppl�mentaires contextuelles ne sont pas sp�cifiques � RPC mais au traitement de n'importe quelle application distribu�e). Dans l'exemple, l'appel RPC est effectu� dans un contexte de transaction globale impliquant plusieurs activit�s qui doivent toutes se terminer avec succ�s pour que le retour du RPC se fasse avec succ�s. L'exemple 4 montre comment un bloc d'en-t�te transaction destin� au r�cepteur final (ce que l'on d�duit 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 compr�hensible par l'application. Nous n'allons pas plus en d�tails dans la s�mantique sp�cifique � l'application de cet en-t�te 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� con�u pour avoir une description de proc�dure indiquant qu'il y a deux param�tres de sortie (ou "out"), l'un fournissant un num�ro de reference pour la r�servation et l'autre une URL o� les d�tails de la r�servation pourront �tre vus. La r�ponse RPC est retourn�e dans l'�l�ment env:Body d'un message SOAP, mod�lis� comme une struct nomm�e d'apr�s la proc�dure chargeReservation et, selon une convention, le mot R�ponse ("Response") ajout�. Les deux param�tres de sortie ("out") accompagnant la r�ponse sont le code alphanum�rique identifiant la r�servation en question et une URI pour l'endroit o� la r�servation peut �tre vue (viewAt).

Ceci est illustr� par l'exemple 5a, o� le bloc d'en-t�te identifie toujours la transaction dans laquelle l'appel RPC est r�alis�.

Les appels RPC ont souvent dans leur description un param�tre en sortie particulier, appel� valeur de "retour" ("return" value). La convention RPC SOAP offre une mani�re de distinguer cette valeur de "retour" des autres param�tres en sortie dans la description de la proc�dure. Pour illustrer ceci, l'exemple de paiement est modifi� pour obtenir une description presque identique � l'exemple 5a, c'est-�-dire avec les m�mes deux param�tres en sortie, mais avec en plus une valeur de "retour" sous la forme d'une �num�ration de valeurs possibles : "confirm�" (confirmed) ou "en attente" (pending). La r�ponse RPC conforme � cette description se trouve dans l'exemple 5b, o� l'en-t�te SOAP, comme pr�c�demment, 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>

R�ponse RPC avec une valeur de "retour" et deux param�tres en sortie ("out") pour l'appel de l'exemple 4

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

Si en principe l'utilisation de SOAP pour RPC est ind�pendante du choix du moyen particulier de transf�rer l'appel et le retour RPC, certaines liaisons sur un protocole supportant la s�quence d'�change de messages de type Requ�te-R�ponse SOAP pourraient �tre plus ad�quates pour cela. Une liaison de protocole supportant cette s�quence d'�change peut fournir une corr�lation entre la requ�te et la r�ponse. Bien s�r, le concepteur d'une application bas�e sur RPC pourrait choisir de placer un identifiant sp�cial pour relier un appel et sa r�ponse dans un en-t�te SOAP, en rendant ainsi le RPC ind�pendant de tout m�canisme de transfert sous-jacent. Dans tous les cas, les concepteurs d'applications doivent �tre conscients de toutes les caract�ristiques 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 requ�te HTTP et la r�ponse RPC � une r�ponse 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 m�me 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 mod�le pour g�rer 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 d�pend du m�canisme de transfert de message utilis� et un des aspects de la sp�cification d'une liaison de SOAP sur un protocole sous-jacent est d'exprimer comment les fautes sont signal�es, le cas �ch�ant. Le reste de cette section suppose qu'un m�canisme de transfert est disponible pour signaler les fautes g�n�r�es lors du traitement des messages re�us et se se concentre sur la structure d'un message de faute SOAP.

L'�l�ment SOAP env:Body joue un autre r�le distinct puisqu'il est l'endroit o� l'on place cette information de faute. Le mod�le de faute SOAP (voir SOAP Partie 1, section 5.4) veut que toutes les fautes sp�cifiques � SOAP et � l'application soient rapport�es en utilisant un seul �l�ment distinct, env:Fault, transport� dans l'�l�ment env:Body. L'�l�ment env:Fault contient deux sous-�lements obligatoires, env:Code et env:Reason, et (optionnellement) des informations sp�cifiques � l'application dans le sous-�l�ment env:Detail de la faute. Un autre sous-�l�ment optionnel, env:Node, identifie via une URI le noeud SOAP qui a g�n�r� la faute, son absence d�signant le r�cepteur final du message. Il existe un autre sous-�l�ment optionnel, env:Role, qui identifie le r�le que le noeud qui a g�n�r� la faute �tait en train de jouer.

Le sous-�l�ment env:Code de env:Fault est lui-m�me constitu� d'un sous-�l�ment env:Value, dont le contenu est sp�cifi� dans la sp�cification SOAP (voir SOAP Part 1 section 5.4.6) ainsi que d'un sous-�l�ment env:Subcode optionnel.

L'exemple 6a montre un message SOAP retourn� en r�ponse � la requ�te 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 zpracov�n�</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'�l�ment 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 inappropri�e dans le message. (Lorsqu'une faute env:Sender est re�ue par l'�metteur, il est suppos� effectuer une action de correction avant d'envoyer � nouveau un message similaire). L'�l�ment env:Subcode est optionnel et, s'il est pr�sent, comme dans cet exemple, qualifie davantage la valeur de son parent. Dans l'exemple 6a, le env:Subcode indique qu'une faute sp�cifique � RPC, rpc:BadArguments, d�finie dans la section 4.4 de SOAP Partie 2, est la cause de l'�chec du traitement de la requ�te.

La structure de l'�l�ment env:Subcode a �t� choisie hi�rarchique - chaque env:Subcode fils a une env:Value obligatoire et un sous-�l�ment env:Subcode optionnel - pour permettre de transporter des codes propres � l'application. La structure hi�rarchique de l'�l�ment env:Code permet un m�canisme uniforme pour faire passer plusieurs niveaux de codes de fautes. La premi�re env:Value est une faute de base sp�cifi�e 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 imbriqu�es sont sp�cifiques � l'application et repr�sentent un d�tail 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 standardis�es, comme les codes RPC standardis�s 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 d�finir des valeurs de sous-codes sp�cifiques � 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 d�finit les classes principales de fautes SOAP. Il n'y a aucune obligation d'un point de vue SOAP que les applications comprennent ou m�me regardent tous les niveaux des valeurs de sous-codes.

Le sous-�l�ment

env:Reason
> href="http://www.w3.org/TR/2003/REC-soap12-part1-20030624/#faultstringelement">

n'a pas pour but un traitement algorithmique, mais plut�t la compr�hension par l'humain, donc m�me si c'est un item obligatoire, la valeur choisie n'a pas besoin d'�tre standardis�e. Par cons�quent tout ce qu'il faut est qu'il d�crive la situation de faute. Il doit avoir un ou plusieurs sous-�l�ments 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 n�gocier la langue du texte de faute en utilisant un m�canisme � base d'en-t�tes SOAP ; cependant ceci sort du champ des sp�cifications SOAP).

L'absence d'un sous-�l�ment env:Node de env:Fault dans l'exemple 6a implique qu'elle est g�n�r�e par le r�cepteur final de l'appel. Le contenu de env:Detail, comme le montre l'exemple, est sp�cifique � l'application.

Lors du traitement d'un message SOAP, une faute peut aussi �tre g�n�r�e si un �l�ment d'en-t�te obligatoire n'est pas compris ou si l'information contenue n'est pas traitable. Les erreurs dans le traitement d'un bloc d'en-t�te sont aussi signal�es par un �l�ment env:Fault dans le env:Body, et un bloc d'en-t�te sp�cial diff�rent, env:NotUnderstood, identifie le bloc d'en-t�te fautif.

L'exemple 6b montre un cas de r�ponse � l'appel RPC de l'exemple 4 indiquant un �chec dans le traitement du bloc d'en-t�te t:transaction. Notez la pr�sence du code de faute env:MustUnderstand dans le env:Body et l'identification de l'en-t�te non compris par l'attribut qname dans le bloc d'en-t�te sp�cial (vide) env:NotUnderstood.

S'il venait � y avoir plusieurs blocs d'en-t�te obligatoires non compris, alors chacun d'eux pourrait �tre identifi� par son attribut qname dans une s�rie de sous-�l�ments env::NotUnderstood.

3. Mod�le de traitement SOAP

Apr�s avoir vu les divers aspects syntaxiques d'un message SOAP ainsi que quelques s�quences basiques d'�change de messages, cette section donne une vue g�n�rale du mod�le de traitement SOAP (sp�cifi� dans la section 2 de SOAP Partie 1). Le mod�le de traitement SOAP d�crit les actions (logiques) effectu�es par un noeud SOAP � la r�ception d'un message.

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

Le mod�le de traitement SOAP d�crit les actions effectu�es par un noeud SOAP recevant un message SOAP. Il est obligatoire pour un noeud d'analyser les parties du message qui sont sp�cifiques � SOAP, soit les �l�ments dans l'espace de nommage "env". Parmi ces �l�ments figurent l'enveloppe elle-m�me, l'en-t�te et le corps. Une premi�re �tape consiste bien �videmment � v�rifier 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 d�finition de type de document (Document Type Definition) - comme d�crit dans la section 5 de SOAP Partie 1.

3.1 L'attribut "role"

Le traitement en profondeur des blocs d'en-t�te et du corps d�pend du(des) r�le(s) assur�s par le noeud SOAP dans le traitement d'un message donn�. SOAP d�finit l'attribut (optionnel) env:role - syntaxiquement, xs:anyURI - pouvant �tre pr�sent dans un bloc d'en-t�te, qui identifie le r�le jou� par la cible attendue de ce bloc d'en-t�te. Un noeud SOAP est oblig� de traiter un bloc d'en-t�te s'il assure le r�le identifi� par la valeur de l'URI. Trois r�les standardis�s ont �t� d�finis (voir SOAP Partie 1, section 2.2), � savoir :

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

Tout noeud SOAP recevant un message avec un bloc d'en-t�te poss�dant un attribut env:role de valeur "next" doit �tre capable de traiter le contenu de l'�l�ment, puisque c'est un r�le standardis� que chaque noeud SOAP doit �tre pr�t � assurer. Les blocs d'en-t�te pourvus de cet attribut sont ceux qui sont cens�s �tre examin�s et (�ventuellement) trait�s par le noeud SOAP suivant sur le chemin du message, en supposant qu'un tel en-t�te n'a pas �t� enlev� par suite de son traitement par un noeud ant�rieur sur le chemin.

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

Le troisi�me bloc d'en-t�te, aThirdBlock, de l'exemple 7a n'a pas d'attribut env:role. Il est destin� � un noeud SOAP assurant le r�le "ultimateReceiver". Le r�le "ultimateReceiver" (qui peut �tre d�clar� explicitement ou est implicite si l'attribut env:role est absent d'un bloc d'en-t�te) est jou� par un noeud SOAP assurant le r�le de r�cepteur final d'un message SOAP particulier. L'absence d'un attribut env:role dans le bloc d'en-t�te aThirdBlock signifie que ce bloc est destin� � un noeud assurant ce r�le "ultimateReceiver".

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

L'autre r�le particulier de l'�l�ment env:Body, comme conteneur o� l'information sur les fautes sp�cifiques � SOAP, c-a-d les �checs de traitement d'�l�ments d'un message SOAP, est plac�e, a �t� d�crit pr�c�demment dans la section 2.3.

Si un �l�ment d'en-t�te poss�de 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 donn�es r�f�renc�es par un autre �l�ment d'en-t�te 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 r�le est r�solue par l'URI de base du message SOAP en question. SOAP Version 1.2 ne d�finit pas d'URI de base pour un message SOAP, mais se repose sur le m�canisme d�fini dans [XMLBase] pour d�river l'URI de base, qui peut �tre utilis�e pour rendre absolue n'importe quelle URI relative. Ce m�canisme sert � la liaison au protocole pour �tablir l'URI de base, par exemple en r�f�rence au protocole d'encapsulation dans lequel le message SOAP est embarqu� pour le transport. (En fait, lorsque des messages SOAP sont transport�s par HTTP, la section 7.1.2 de [SOAP Part2] d�finit l'URI de base comme l'URI de la requ�te HTTP (Request-URI), ou bien la valeur de l'en-t�te HTTP Content-Location).

Le tableau suivant r�sume les r�les standardis�s pouvant �tre jou�s par divers noeuds SOAP. ("Oui" et "Non" signifient que le noeud correspondant joue ou ne joue pas le r�le donn�).

3.2 L'attribut "mustUnderstand"

L'exemple 7b ajoute � l'exemple pr�c�dent en introduisant un autre attribut pour les blocs d'en-t�te, env:mustUnderstand ("doit comprendre").

Apr�s qu'un noeud SOAP a correctement identifi� les blocs d'en-t�te (et �ventuellement le corps) qui lui sont destin�s gr�ce � l'attribut env:role, l'attribut optionnel env:mustUnderstand dans les �l�ments d'en-t�te d�termine les actions de traitement ult�rieures � r�aliser. Afin de s'assurer que les noeuds SOAP n'ignorent pas des blocs d'en-t�te importants pour l'objectif global de l'application, les blocs d'en-t�tes 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 sp�cification de celui-ci. Un tel bloc est couramment d�sign� comme bloc d'en-t�te obligatoire. En fait, le traitement d'un message SOAP ne peut m�me pas commencer tant que le noeud n'a pas identifi� tous les blocs d'en-t�te obligatoires qui lui sont destin�s, et ne les a pas "compris". Comprendre un en-t�te signifie que le noeud doit �tre pr�par� � faire tout ce qui est d�crit dans la sp�cification de ce bloc. (Gardez � l'esprit que les sp�cifications de blocs d'en-t�te ne sont pas partie int�grante de la sp�cification de SOAP).

Dans l'exemple 7b, le bloc d'en-t�te 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 r�le identifi� par "http://example.com/log". Les deux autres blocs d'en-t�te ne sont pas marqu�s ainsi, ce qui signifie que les noeud SOAP auxquels ces blocs sont destin�s n'ont pas besoin de les traiter. (Parce que certainement les sp�cifications de ces blocs autorisent cet �tat de fait).

Une valeur de env:mustUnderstand � "true" signifie que le noeud SOAP doit traiter l'en-t�te avec la s�mantique d�crite dans la sp�cification de celui-ci, ou sinon g�n�rer une faute SOAP. Traiter l'en-t�te de mani�re appropri�s peut inclure de retirer cet en-t�te de tout message SOAP g�n�r�, de r�ins�rer l'en-t�te avec la m�me ou une autre valeur, ou d'ins�rer un nouvel en-t�te. L'incapacit� � traiter un en-t�te obligatoire oblige � stopper tout traitement du message SOAP plus avant et � g�n�rer une faute SOAP. Le message ne sera pas renvoy� plus loin.

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

Le(s) r�le(s) que joue un noeud SOAP lorsqu'il traite un message peut �tre d�termin� par beaucoup de facteurs. Le r�le peut �tre connu a priori, ou d�cid� par quelques proc�d�s hors-ligne, ou bien un noeud peut inspecter toutes les parties d'un message re�u pour d�terminer quels r�les il va assumer avant de traiter le message. Un cas int�ressant se produit lorsqu'un noeud SOAP, pendant l'avancement du traitement d'un message, d�cide qu'il y a des r�les suppl�mentaires qu'il a besoin d'adopter. Peu importe quand cette d�termination a lieu, de l'ext�rieur tout doit sembler respecter le mod�le de traitement. C'est-�-dire appara�tre comme si le r�le avait �t� connu depuis le d�but du traitement du message. En particulier, d'un point de vue externe la v�rification de env:mustUnderstand dans les en-t�tes contenant ce r�le suppl�mentaire doit sembler avoir pr�c�d� le d�but du traitement. De plus, si un noeud SOAP assume de tels r�les suppl�mentaires, il doit s'assurer qu'il est pr�par� pour faire tout ce que les sp�cifications de ces r�les requi�rent.

Le tableau suivant r�sume la mani�re dont les actions de traitement d'un bloc d'en-t�te sont qualifi�es par l'attribut env:mustUnderstand en fonction du noeud cibl� convenablement (par son attribut env:role).

En cons�quence du traitement d'un message SOAP, un noeud SOAP peut g�n�rer une simple faute SOAP s'il �choue, ou, en fonction de l'application, g�n�rer des messages SOAP suppl�mentaires � consommer par d'autres noeuds SOAP. La section 5.4 de SOAP Partie 1 d�crit la structure du message de faute tandis que le mod�le de traitement SOAP d�finit les conditions conduisant � sa g�n�ration. Comme illustr� pr�c�demment dans la section 2.3, une faute SOAP est un message SOAP avec un sous-�l�ment de env:Body standardis� env:Fault.

SOAP fait une distinction entre g�n�rer une faute et s'assurer que la faute est renvoy�e � l'origine du message ou un autre noeud appropri� qui peut se servir de cette information. Cependant, pouvoir propager une faute g�n�r�e convenablement d�pend de la liaison sur protocole sous-jacent choisie pour �changer les messages. La sp�cification ne d�finit pas ce qui se produit si des fautes sont g�n�r�es durant la propagation de messages unidirectionnels. L'autre liaison normative, qui est la liaison sur HTTP, fournit la r�ponse HTTP comme moyen de rapporter une faute dans le message SOAP arrivant (voir section 4 pour plus de d�tails sur les liaisons de SOAP sur protocoles).

3.3 L'attribut "relay"

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

Notez que si ce bloc d'en-t�te est trait�, les r�gles de traitement de SOAP (voir SOAP Partie 1, section 2.7.2) imposent de le retirer du message sortant. (Il pourrait, cependant, �tre r�introduit, intact ou avec un contenu modifi�, si le traitement d'autres blocs d'en-t�te d�terminent que ce bloc d'en-t�te doit �tre conserv� dans le message transmis). Le comportement par d�faut pour un bloc d'en-t�te non trait� adress� � un r�le jou� par un interm�diaire SOAP est de le retirer avant de relayer le message.

Ce choix de d�faut est une pr�caution contre d'�ventuelles suppositions qu'un interm�diaire pourrait faire � propos de la "survie" apr�s lui d'un bloc d'en-t�te adress� � un r�le qu'il assure. Ceci ajoute une fonctionnalit� de valeur suppl�mentaire, surtout s'il choisit de ne pas traiter le bloc d'en-t�te, probablement parce qu'il ne le comprend pas. Certains blocs repr�sentent des fonctionnalit�s de proche en proche et cela n'a pas de sens de les transporter de bout en bout. Comme un interm�diaire peut ne pas �tre en mesure de d�terminer ceci, il est plus s�r de retirer les blocs d'en-t�te non trait�s avant de relayer le message.

Cependant, il existe des cas o� un concepteur d'application voudrait introduire une nouvelle fonctionnalit�, mat�rialis�e par un bloc d'en-t�te SOAP, visant tout interm�diaire capable rencontr� sur le cheminement du message SOAP. Un tel bloc d'en-t�te serait disponible pour les interm�diaires qui le comprendraient (understood) mais ignor� et relay� par ceux qui ne le comprennent pas. En tant que nouvelle caract�ristique, le logiciel pour traiter ce bloc d'en-t�te pourrait n'�tre impl�ment�, au moins initialement, que sur certains noeuds SOAP. Marquer ce bloc en tant que env:mustUnderstand = "false" semble �videmment n�cessaire, pour que les interm�diaires n'impl�mentant pas la caract�ristique ne g�n�rent pas de faute. Pour contourner la r�gle par d�faut du mod�le de traitement, marquer le bloc d'en-t�te avec l'attribut suppl�mentaire env:relay avec la valeur "true" autorise l'interm�diaire � faire suivre le bloc d'en-t�te qui lui est destin� s'il ne le traite pas.

Cibler le bloc d'en-t�te sur le r�le "next" avec l'attribut env:relay fix� � "true" (vrai) peut toujours servir � s'assurer que chaque interm�diaire a une chance d'examiner le bloc, puisque une des utilisations probables de "next" concerne les blocs d'en-t�tes v�hiculant des informations suppos�es persister le long du chemin du message SOAP. Bien entendu, le concepteur d'application peut toujours d�finir un r�le personnalis� permettant de cibler des interm�diaires sp�cifiques jouant ce r�le. Par cons�quent, il n'y a pas de restrictions sur l'utilisation de l'attribut env:relay avec n'importe quel r�le, sauf bien s�r avec "none" et "ultimateReceiver", pour lesquels cela n'a pas de sens.

Le bloc d'en-t�te q:anotherBlock, adress� au noeud suivant ("next") dans le cheminement du message, poss�de l'attribut suppl�mentaire env:relay="true". Un noeud SOAP recevant ce message peut traiter ce bloc s'il le comprend, le cas �ch�ant les r�gles 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-t�te, 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-t�te p:oneBlock est obligatoire et les r�gles de traitement de SOAP imposent de ne pas le relayer, sauf si le traitement d'un autre bloc requiert sa pr�sence dans le message sortant. Le bloc d'en-t�te 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 r�sume les conditions d�terminant si un interm�diaire SOAP assumant un r�le donn� est autoris� � r�acheminer des blocs d'en-t�tes non trait�s.

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

Des messages SOAP peuvent �tre �chang�s gr�ce � une vari�t� de protocoles "sous-jacents", notamment d'autres protocoles de la couche application. La sp�cification de la mani�re de passer des messages d'un noeud SOAP � un autre en utilisant un protocole sous-jacent est appel�e une liaison sur le protocole (protocol binding). [SOAP Partie 1] d�finit un message SOAP sous la forme d'un ensemble d'informations XML [XML Infoset ], c'est-�-dire en termes d'items d'information �l�ments et attributs dans un "document" appel� env:Envelope (enveloppe) (voir SOAP Partie 1, section 5.1). Toute repr�sentation d'infoset env:Envelope SOAP sera concr�tis�e � travers une liaison sur un protocole. L'objectif consiste notamment � fournir une repr�sentation s�rialis�e 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 pr�liminaire, la s�rialisation montr�e 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 limit�e - o� une alternative, la s�rialisation compress�e du m�me infoset, peut �tre pr�f�r�e. Une autre liaison, choisie dans un but diff�rent, pourrait fournir une s�rialisation en une structure chiffr�e repr�sentant le m�me infoset.

En plus d'une r�alisation concr�te d'un infoset SOAP entre noeuds adjacents sur un chemin, une liaison sur un protocole fournit les m�canismes supportant des fonctionnalit�s dont une application SOAP pourrait avoir besoin. Une caract�ristique est une sp�cification d'une certaine fonctionnalit� fournie par une liaison. Une description de caract�ristique est identifi�e par une URI, pour que toutes les applications qui l'utilisent soient assur�es de la m�me s�mantique. Par exemple, un sc�nario d'utilisation typique peut demander beaucoup d'�changes requ�te-r�ponse simultan�s entre noeuds adjacents, auquel cas la fonctionnalit� n�cessaire est la capacit� � corr�ler une requ�te avec sa r�ponse. On peut citer comme autres exemples une caract�ristique de "canal crypt�", une caract�ristique de "canal � livraison fiable" ou une caract�ristique de S�quence d'�change de messages particuli�re.

Une sp�cification de liaison SOAP (voir SOAP Partie 1, section 4) d�crit entre autres quelles caract�ristiques (le cas �ch�ant) elle fournit. Certaines caract�ristiques peuvent �tre fournies nativement par le protocole sous-jacent. Si la caract�ristique n'est pas disponible au travers de la liaison, elle peut �tre impl�ment�e dans l'enveloppe SOAP, gr�ce � des blocs d'en-t�te SOAP. La sp�cification d'une caract�ristique impl�ment�e par des blocs d'en-t�te SOAP est appel�e module SOAP.

Par exemple, si les �changes de messages SOAP �taient transport�s sur un protocole de datagrammes, tel qu'UDP, la corr�lation entre messages devrait bien �videmment �tre fournie ailleurs, peut-�tre directement par l'application ou plus certainement dans une partie des infosets SOAP �chang�s. Dans ce dernier cas, la corr�lation prend une forme sp�cifique � la liaison dans l'enveloppe SOAP, c'est-�-dire celle d'un bloc en-t�te SOAP, d�fini dans un module "Corr�lation Requ�te-R�ponse" identifi� par une URI. Cependant, si les infosets SOAP �taient �chang�s en utilisant un protocole sous-jacent lui-m�me requ�te-r�ponse, l'application pourrait implicitement "h�riter" cette fonctionnalit� fournie par la liaison et il n'y aurait pas besoin de support suppl�mentaire au niveau applicatif SOAP. (En fait, la liaison sur HTTP de SOAP tire parti juste de cette caract�ristique de HTTP).

Pourtant, un message SOAP peut voyager sur plusieurs bonds entre un �metteur et le r�cepteur final, avec une liaison sur un protocole diff�rent pour chaque bond. En d'autres termes, une fonctionnalit� (par ex. corr�lation de message, fiabilit�, etc.) support�e par la liaison sur un protocole pour un bond peut ne pas �tre support�e par une autre dans le chemin suivi. SOAP lui-m�me ne fournit pas de m�canisme pour cacher les diff�rences de fonctionnalit�s des diff�rents protocoles sous-jacents. Cependant, toute fonctionnalit� requise par une application donn�e, mais qui ne serait pas disponible dans l'infrastructure sous-jacente au long du chemin anticip�, peut �tre compens�e en �tant transport�e comme partie de l'infoset du message SOAP, c'est-�-dire un bloc d'en-t�te SOAP sp�cifi� dans un module.

Il appara�t donc qu'un certain nombre de probl�mes doivent �tre r�gl�s par le concepteur d'applications pour la s�mantique d'une application donn�e, notamment comment tirer parti des caract�ristiques natives des protocoles sous-jacents disponibles dans l'environnement choisi. La section 4.2 de SOAP Partie 1 donne une structure g�n�rale pour d�crire comment les applications bas�es sur SOAP peuvent choisir d'utiliser les fonctionnalit�s offertes par une liaison sur un protocole sous-jacent pour assurer une s�mantique particuli�re. Cette section tente aussi de d�gager des grandes lignes pour �crire des sp�cifications de liaison sur un protocole interop�rable pour �changer des messages SOAP.

Entre autres, une sp�cification de liaison doit d�finir une caract�ristique particuli�re : la(les) s�quence(s) d'�change de messages qu'elle supporte. [SOAP Partie 2] d�finit deux de ces s�quences d'�change de messages : une s�quence d'�change de messages de type Requ�te-R�ponse, o� un message SOAP est �chang� dans chaque direction entre deux noeuds SOAP adjacents, et une s�quence d'�change de messages de type R�ponse, qui consiste en un message non-SOAP agissant comme une requ�te suivi d'un message SOAP inclus comme partie de la r�ponse.

[SOAP Partie 2] offre �galement au concepteur d'application une fonctionnalit� g�n�rale appel�e sp�cification de M�thodes Web qui permet aux applications de contr�ler totalement le choix des m�thodes dites Web - GET, POST, PUT, DELETE, dont la s�mantique est d�finie dans les sp�cifications de [HTTP 1.1] - utilisables sur la liaison. Cette fonctionnalit� est d�finie pour s'assurer que les applications utilisant SOAP peuvent le faire de mani�re compatible avec les principes architecturaux du World Wide Web. (Tr�s bri�vement, la simplicit� et le passage � l'�chelle du Web sont largement dus aux quelques m�thodes g�n�riques (GET, POST, PUT, DELETE) utilisables pour interagir avec toute ressource disponible sur le Web via une URI). La caract�ristique de sp�cification de m�thode Web est support�e par la liaison SOAP HTTP, bien que, en principe, elle soit disponible dans toutes les liaisons.

La section 7 de SOAP Partie 2 sp�cifie une liaison standardis�e � 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 � d�finir une liaison sur HTTP permettant d'utiliser la m�thode POST avec la s�quence d'�change de messages de type Requ�te-R�ponse et la m�thode GET avec la s�quence de type R�ponse. D'autres sp�cifications pourraient d�finir dans le futur des liaisons de SOAP � HTTP ou d'autres transports utilisant les autres m�thodes 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 m�canisme de transport est simplement destin� � sugg�rer 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 sp�cifi�e dans [SOAP Partie 1] en d�crivant une liaison exp�rimentale au transport par e-mail, sp�cifiquement bas� sur la RFC 2822.

4.1 Liaison SOAP sur HTTP

HTTP a un mod�le de connexion bien connu et une s�quence d'�change de messages. Le client identifie le serveur gr�ce � une URI, s'y connecte par le r�seau TCP/IP sous-jacent, �met un message de requ�te HTTP et re�oit un message de r�ponse HTTP sur la m�me connexion TCP. HTTP relie implicitement son message de requ�te au message de r�ponse, par cons�quent une application utilisant cette liaison peut d�cider d'en d�duire une corr�lation entre un message SOAP envoy� dans le corps d'une requ�te HTTP et le message SOAP retourn� dans la r�ponse HTTP. De la m�me mani�re, HTTP identifie l'extr�mit� serveur par une URI, Request-URI, qui peut aussi servir d'identifiant du noeud SOAP sur le serveur.

HTTP autorise de multiples interm�diaires entre le client initial et le serveur d'origine (origin server) identifi� par la Request-URI de la requ�te, auquel cas le mod�le requ�te/r�ponse est une s�rie de telles paires. Notez cependant que les interm�diaires HTTP sont diff�rents des interm�diaires SOAP.

La liaison sur HTTP dans [SOAP Partie 2] utilise la caract�ristique de m�thodes Web SOAP pour permettre aux applications de choisir la dite "m�thode Web" - en la restreignant � soit GET soit POST - � employer dans l'�change de message HTTP. De plus, elle utilise deux s�quences d'�change de messages qui offrent aux applications deux mani�res d'�changer les messages SOAP via HTTP : 1) utiliser la m�thode HTTP POST pour transporter des messages SOAP dans les corps de requ�tes et r�ponses HTTP, et 2) utiliser la m�thode HTTP GET dans une requ�te HTTP pour retourner un message SOAP dans le corps de la r�ponse HTTP. La premi�re de ces s�quences est une instanciation sp�cifique � HTTP de la caract�ristique d'une liaison appel�e s�quence d'�change de message SOAP de type requ�te-r�ponse, alors que la seconde utilise la caract�ristique appel�e s�quence d'�change de messages SOAP de type r�ponse.

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 donn�es dans le corps d'un HTTP POST pour cr�er ou modifier l'�tat d'une ressource identifi�e par une URI � laquelle la requ�te HTTP est destin�e. Le second type de structure d'interaction offre la possibilit� d'utiliser une requ�te HTTP GET pour obtenir une repr�sentation d'une ressource sans toucher � son �tat d'aucune mani�re. Dans le premier cas, l'aspect sp�cifique � SOAP qui nous int�resse est de placer dans le corps de la requ�te HTTP POST un message SOAP � traiter (en suivant le mod�le de traitement SOAP) comme partie d'un traitement applicatif n�cessaire pour respecter la s�mantique de POST. Quant au second, il est pr�vu pour le cas o� la repr�sentation de la ressource demand�e n'est pas renvoy�e en HTML, ou en fait un document XML g�n�rique, mais un message SOAP. En pratique, l'en-t�te HTTP Content-Type du message de r�ponse l'identifie comme du type de media "application/soap+xml". Des �diteurs de ressources sur le Web d�termineront probablement si telle ou telle ressource devrait �tre r�cup�r�e et publi�e sous forme de messages SOAP. Notez cependant que des ressources peuvent, en g�n�ral, �tre publi�es sous plusieurs repr�sentations et que la repr�sentation voulue ou pr�f�r�e est indiqu�e par l'application �mettant la requ�te, gr�ce � l'en-t�te HTTP Accept.

Un autre aspect de la liaison SOAP HTTP concerne la mani�re dont une application d�termine laquelle des deux s�quences 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 - m�me s'ils sont tr�s recommand�s - puisque formul�s avec la forme conditionnelle "DEVRAIT (SHOULD)" dans les sp�cifications au lieu d'obligations absolues, identifi�es par le terme "DOIT (MUST)", ces termes �tant � interpr�ter comme d�finis dans la "RFC 2119 de l'IETF). La s�quence d'�change de messages SOAP de type r�ponse avec la m�thode GET est utilis�e lorsqu'une application est s�re que l'�change a pour but la r�cup�ration d'informations, sans toucher � la ressource dans l'interaction. Ce type d'interaction est dit s�r et idempotent dans la sp�cification HTTP. Comme l'utilisation de HTTP GET dans SOAP n'autorise pas de message SOAP dans la requ�te, les applications qui ont besoin de fonctionnalit�s de l'interaction sortante seulement support�e par une expression sp�cifique � la liaison dans l'infoset SOAP (c'est-�-dire des blocs d'en-t�te SOAP) ne peuvent � l'�vidence pas utiliser cette s�quence 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 s�quences d'�change de messages d�finies pour la liaison sur HTTP.

4.1.1. Utilisation de HTTP GET pour SOAP

L'utilisation de la liaison sur HTTP avec la s�quence d'�change de messages SOAP de type R�ponse est restreint � la m�thode HTTP GET. Ce qui signifie que la r�ponse � une requ�te HTTP GET �mise par un noeud SOAP est un message SOAP dans la r�ponse HTTP.

L'exemple 8a montre un HTTP GET dirig� par l'application du voyageur (dans la continuation de l'exemple de sc�nario de r�servation) vers l'URI http://travelcompany.example.org/reservations?code=FT35ZBQ o� l'itin�raire du voyageur peut �tre visualis�. (La mani�re dont l'URL a �t� donn�e est visible dans l'exemple 5a).

L'en-t�te HTTP Accept sert � indiquer la repr�sentation pr�f�r�e de la ressource demand�e, qui dans l'exemple est un type de media "application/soap+xml" � l'usage de la machine client, plut�t que le type de media "text/html" pour l'affichage dans un client navigateur � l'usage de l'humain.

L'exemple 8b montre la r�ponse HTTP au GET de l'exemple 8a. Le corps de la r�ponse HTTP contient un message SOAP avec les d�tails 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 compr�hension 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 J�gvan �yvind</x:passenger>
      <x:outbound>
       <x:TravelRequest>
        <x:to>LAX</x:to>
        <x:from>LGA</x:from>
        <x:date>2001-12-14</x:date>
       </x:TravelRequest>
      </x:outbound>
      <x:return>
       <x:TravelRequest>
        <x:to>JFK</x:to>
        <x:from>LAX</x:from>
        <x:date>2001-12-20</x:date>
       </x:TravelRequest>
      </x:return>
    </x:ReservationRequest>
  </rdf:RDF>
 </env:Body>
</env:Envelope>

Message SOAP retourn� en r�ponse au HTTP GET de l'exemple 8a

Notez que les d�tails de r�servation auraient pu aussi �tre renvoy�s sous forme d'un document (X)HTML, mais le but �tait de montrer un cas o� l'application de r�servation retourne l'�tat de la ressource (la r�servation) sous une forme de media centr�e sur les donn�es (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 pr�vues 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 r�ponse HTTP offre la possibilit� d'exprimer des caract�ristiques sp�cifiques � l'application au travers d'en-t�tes SOAP. Gr�ce � SOAP, l'application b�n�ficie d'une structure coh�rente et d'un mod�le de traitement pour exprimer de telles caract�ristiques.

4.1.2 Utilisation de HTTP POST pour SOAP

L'utilisation de la liaison sur HTTP avec la s�quence d'�change de messages SOAP de type Requ�te-R�ponse est restreinte � la m�thode HTTP POST. Notez que l'utilisation de cette s�quence d'�change de messages dans la liaison SOAP sur HTTP est disponible � toutes applications, qu'elles soient �changes ax�s donn�es g�n�rales XML ou ax�s RPCs (comme dans les exemples) encapsul�s dans des messages SOAP.

Les exemples 9 et 10 sont des utilisations de liaison sur HTTP avec la s�quence d'�change de messages de type Requ�te-R�ponse, sur le m�me sc�nario que pour les exemples 4 et 5a respectivement, c'est-�-dire transport d'un appel RPC et sa r�ponse dans le corps d'un message SOAP. Les exemples et la discussion dans cette section se concentre seulement sur les en-t�tes HTTP et leur r�le.

L'exemple 9 montre une requ�te RPC destin�e � l'application de service de voyages. Le message SOAP est envoy� dans le corps d'une m�thode HTTP POST destin�e � l'URI identifiant la ressource "r�servations" sur le serveur travelcompany.example.org. Lorsque l'on utilise HTTP, l'URI de la requ�te (Request-URI) indique la ressource � laquelle l'invocation est "post�e". 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 identifi�es par des URIs. Ceci implique que la plupart des services SOAP bien construits seront incarn�s par un grand nombre de ressources, chacune ayant sa propre URI. En effet, beaucoup de ces ressources seront probablement cr��es dynamiquement durant l'ex�cution du service, comme la r�servation de voyage sp�cifique de l'exemple. Donc une application de r�servation de voyages bien construite aura une URI diff�rente pour chaque r�servation et les requ�tes SOAP pourront les r�cup�rer 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 mani�re privil�gi�e d'adresser des ressources telles qu'une r�servation de voyage particuli�re. Par cons�quent, nous laissons pour la section 4.1.3 la discussion d�taill�e 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-t�te "Content-type") doit �tre "application/soap+xml". (Le param�tre optionnel "charset", qui peut prendre la valeur "utf-8" ou "utf-16", appara�t dans cet exemple, mais lorsqu'il est absent, les r�gles de jeu de caract�res pour [XML 1.0] seul s'appliquent au corps de la requ�te 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 J�gvan �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 requ�te HTTP POST

L'exemple 10 donne la r�ponse RPC (les d�tails sont omis) envoy�e par le service de voyages dans la r�ponse HTTP correspondant � la requ�te de l'exemple 5a. SOAP utilisant le transport HTTP suit la s�mantique des codes d'�tat HTTP pour communiquer les informations d'�tat dans HTTP. Par exemple, la s�rie de codes d'�tat HTTP 2xx indique que la requ�te du client (incluant la composante SOAP) a �t� correctement re�ue, comprise, accept�e, etc.

Si une erreur se produit au cours du traitement de la requ�te, la sp�cification 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 c�t� serveur.

L'exemple 11 est le m�me message de faute SOAP que dans l'exemple 6a, mais avec des en-t�tes 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 zpracov�n�</env:Text>
      </env:Reason>
      <env:Detail>
        <e:myFaultDetails 
          xmlns:e="http://travelcompany.example.org/faults" >
          <e:message>Name does not match card number</e:message>
          <e:errorcode>999</e:errorcode>
        </e:myFaultDetails>
      </env:Detail>
    </env:Fault>
 </env:Body>
</env:Envelope>

Exemple de message SOAP dans une r�ponse 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 d�taill� de gestion des diff�rents codes de r�ponse HTTP, c'est-�-dire les 2xx (succ�s), 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 interop�rer 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 tr�s importante - en fait pr�dominante - du World Wide Web est la r�cup�ration d'informations pure, o� la repr�sentation d'une ressource disponible, identifi�e par une URI, est ramen�e par une requ�te HTTP GET sans toucher � la ressource d'aucune fa�on. (C'est ce que l'on appelle une m�thode s�re 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 con�us seulement pour r�cup�rer des informations, comme une requ�te sur l'�tat d'une ressource (ou d'un objet, en termes de programmation), au contraire d'utilisations qui ex�cutent des manipulations de la ressource. Dans ce type de cas, l'utilisation d'un corps SOAP pour transporter la requ�te sur l'�tat, avec un corps SOAP repr�sentant l'objet en question, est per�ue comme contraire � l'esprit du Web car la ressource n'est pas identifi�e par la Request-URI de la requ�te HTTP GET. (Dans certaines impl�mentations de SOAP/RPC, la Request-URI HTTP est souvent une entit� interm�diaire qui doit �valuer le message SOAP pour identifier la ressource, et non lidentifiant de la ressource elle-m�me).

Pour souligner les changements n�cessaires, l'exemple 12a montre la mani�re d�conseill�e pour r�cup�rer de l'information de mani�re s�re sur le Web. C'est un exemple d'appel RPC transport� dans un message SOAP, toujours sur le th�me de la r�servation de voyages, o� la requ�te vise � r�cup�rer l'itin�raire d'une r�servation donn�e, identifi�e par un des param�tres de l'appel RPC : reservationCode. (Pour les besoins de la discussion, il est suppos� que l'application utilisant cette requ�te RPC ne n�cessite pas de fonctionnalit�s qui oblige � utiliser des en-t�tes SOAP).

Notez que la ressource � r�cup�rer n'est pas identifi�e par l'URI cible de la requ�te 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 d�finir des appels RPCs constituant des r�cup�rations s�res et idempotentes d'informations de mani�re respectueuse du Web. Ceci en distinguant les aspects de la m�thode et les param�tres sp�cifiques dans la d�finition RPC qui servent � identifier les ressources de ceux qui servent d'autres buts. Dans l'exemple 12a, la ressource � r�cup�rer est identifi�e par deux choses : la premi�re est qu'il s'agit d'un itin�raire (partie du nom de la m�thode), la seconde est la r�f�rence � une instance particuli�re (un param�tre de la m�thode). Dans un tel cas, il est recommand� de placer ces parties identifiant la ressource quelque part dans la Request-URI de la requ�te HTTP, comme ceci : http://travelcompany.example.org/reservations/itinerary?reservationCode=FT35ZBQ.

En outre, lorsque la d�finition d'un RPC est telle que toutes les parties de sa description de m�thode peuvent �tre d�crites comme identifiant la ressource, ainsi la ressource en entier peut �tre identifi�e par une URI et son fournisseur peut �tre assur� de la s�ret� de la r�cup�ration, SOAP 1.2 recommande le choix de la propri�t� de M�thode Web GET et l'utilisation de la s�quence d'�change de messages SOAP de type R�ponse comme d�crit dans la section 4.1.1, qui assurent que le RPC SOAP est ex�cut� de mani�re respectueuse du Web. L'exemple 12b montre la mani�re pr�f�rable pour un noeud SOAP de demander la r�cup�ration s�re de la ressource.

Il est � noter que SOAP Version 1.2 ne sp�cifie aucun algorithme pour d�duire une URI de la d�finition d'un RPC repr�sentant une r�cup�ration pure d'information.

Notez cependant que si l'application requiert l'utilisation de fonctionnalit�s exprimables seulement par rapport � une liaison donn�e dans l'infoset SOAP, c'est-�-dire gr�ce � des blocs d'en-t�te SOAP, alors l'application doit choisir la m�thode HTTP POST avec un message SOAP dans le corps de la requ�te.

Elle n�cessiterait aussi l'utilisation de la s�quence d'�change de messages SOAP de type Requ�te-R�ponse impl�ment�e par un HTTP POST si la description RPC incluait des donn�es (param�tres) qui n'identifiaient pas la ressource. M�me dans ce cas, HTTP POST avec un message SOAP peut �tre repr�sent� de mani�re respectueuse du Web. Comme pour GET, [SOAP Partie 2] recommande dans le cas g�n�ral que toute partie du message qui identifie la ressource recevant la requ�te POST figure dans la Request-URI de la requ�te HTTP. Les m�mes param�tres peuvent �videmment �tre repris dans l'�l�ment SOAP env:Body. (Les param�tres doivent �tre repris dans le Body dans le cas d'un RPC bas� sur SOAP puisqu'ils sont li�s � la description de proc�dure/m�thode attendue par l'application r�ceptrice).

L'exemple 13 est similaire � l'Exemple 9, except�e la modification de la Request-URI HTTP pour inclure le code de la r�servation, qui sert � identifier la ressource (la r�servation en question, confirm�e et pay�e).

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 J�gvan �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 requ�te HTTP POST de mani�re respectueuse du Web

Dans l'exemple 13, la ressource � manipuler est identifi�e par deux choses : la premi�re est que c'est une r�servation (partie du nom de la m�thode), et la seconde est que c'est une instance donn�e de r�servation (qui est la valeur du param�tre code de la m�thode). Le reste des param�tres de l'appel RPC n'identifient pas la ressource mais sont des donn�es 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 d�velopp�s dans le futur. Notez aussi que tous les �l�ments identifiants de la ressource ont �t� repris comme dans l'Exemple 9 sous leur forme encod�e dans l'�l�ment SOAP env:Body.

En d'autres termes, comme vu dans les exemples ci-dessus, la recommandation dans les sp�cifications 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 d�veloppeurs d'applications peuvent utiliser l'infrastructure de l'e-mail Internet pour d�placer 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 consid�r�s comme la mani�re standard de proc�der. Les sp�cifications de SOAP 1.2 ne sp�cifient pas de telle liaison. Cependant, il existe une note du W3C non normative [SOAP Email Binding] d�crivant une liaison email pour SOAP, son but principal �tant de d�montrer l'application de la structure g�n�rale pour les liaisons SOAP sur protocole d�crite dans [SOAP Part 1].

L'exemple 14 montre un message de requ�te de r�servation de voyage de l'exemple 1 transport� comme message �lectronique entre agents utilisateurs de courrier, un �metteur et un r�cepteur. Le noeud r�cepteur poss�de implicitement des fonctions SOAP, auxquelles le corps du courrier �lectronique est d�livr� pour �tre trait�. (Il est �galement suppos� que l'�metteur poss�de des fonctions SOAP pour traiter les �ventuelles fautes SOAP re�ues en r�ponse ou pour corr�ler tout message SOAP re�u en r�ponse � celui-ci).

Exemple 14

From: a.oyvind@mycompany.example.com
To: reservations@travelcompany.example.org
Subject: Travel to LA
Date: Thu, 29 Nov 2001 13:20:00 EST
Message-Id: <EE492E16A090090276D208424960C0C@mycompany.example.com> 
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 J�gvan �yvind</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary 
     xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>New York</p:departing>
     <p:arriving>Los Angeles</p:arriving>
     <p:departureDate>2001-12-14</p:departureDate>
     <p:departureTime>late afternoon</p:departureTime>
     <p:seatPreference>aisle</p:seatPreference>
   </p:departure>
   <p:return>
     <p:departing>Los Angeles</p:departing>
     <p:arriving>New York</p:arriving>
     <p:departureDate>2001-12-20</p:departureDate>
     <p:departureTime>mid morning</p:departureTime>
     <p:seatPreference/>
   </p:return>
  </p:itinerary>
  <q:lodging 
     xmlns:q="http://travelcompany.example.org/reservation/hotels">
   <q:preference>none</q:preference>
  </q:lodging>
 </env:Body>
</env:Envelope>

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

L'en-t�te 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 sp�cification de SMTP (Simple Mail Transport Protocol) [SMTP] offrent un m�canisme 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 envoy�s � l'adresse donn�e dans l'en-t�te du courrier. Les applications ainsi que les utilisateurs finaux de l'e-mail peuvent utiliser ces m�canismes pour donner l'�tat d'une transmission de message mais ceux-ci, s'ils sont d�livr�s, sont des notifications au niveau SMTP. Le d�veloppeur d'applications peut parfaitement comprendre les fonctions et les limitations de ces notifications de livraison ou risquer de supposer une donn�e d�livr�e avec succ�s alors qu'elle ne l'a pas �t�.

Les messages d'�tat de livraison SMTP sont �cart�s du traitement de messages par la couche SOAP. Les r�ponses SOAP aux donn�es SOAP contenues seront retourn�es au travers d'un nouveau message �lectronique qui peut ou non avoir un lien avec la requ�te de d�part au niveau SMTP. L'utilisation de l'en-t�te In-reply-to: de la [RFC 2822] permet de faire la relation au niveau SMTP mais n'offre pas n�cessairement de lien au niveau SOAP.

L'exemple 15 est exactement le m�me sc�nario que d�crit pour l'exemple 2, qui montre le message SOAP (les d�tails du corps sont omis pour abr�ger) envoy� par l'application de service de voyages � l'application de r�servation du passager demandant des pr�cisions sur la r�servation, mais transmis cette fois comme un message �lectronique. Dans cet exemple, le Message-Id du message �lectronique d'origine figure dans un en-t�te suppl�mentaire In-reply-to: du message �lectronique, ce qui relie les messages au niveau SMTP mais ne fournit pas de corr�lation sp�cifique � SOAP. Dans cet exemple, l'application s'appuie sur le bloc d'en-t�te reservation pour corr�ler les messages SOAP. L� encore, les fonctions qui r�alisent cette corr�lation d�pendent de la conception des applications et ne sont pas du ressort de SOAP.

Exemple 15

From: reservations@travelcompany.example.org
To: a.oyvind@mycompany.example.com
Subject: Which NY airport?
Date: Thu, 29 Nov 2001 13:35:11 EST
Message-Id: <200109251753.NAA10655@travelcompany.example.org>
In-reply-to:<EE492E16A090090276D208424960C0C@mycompany.example.com>
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 J�gvan �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-t�te le reliant � un pr�c�dent message

5. Sc�narii d'utilisation avanc�s

5.1 Utilisation d'interm�diaires SOAP

Le sc�nario d'application de r�servation de voyages donne l'opportunit� d'exposer quelques utilisations d'interm�diaires SOAP. Rappelez-vous que l'�change de base �tait une r�servation de voyage entre une application de r�servation de voyages et service de voyages. SOAP ne sp�cifie pas comment un tel cheminement de message est d�termin� et suivi. Cela sort du cadre de la sp�cification SOAP. Elle d�crit cependant comment un noeud SOAP devrait se comporter � la r�ception d'un message dont il n'est pas le destinataire final. SOAP Version 1.2 d�crit deux types d'interm�diaires : les interm�diaires de r�acheminement et les interm�diaires actifs.

Un interm�diaire de r�acheminement est un noeud SOAP qui, en fonction de la s�mantique d'un bloc d'en-t�te dans un message SOAP re�u ou en fonction de la s�quence d'�change de messages utilis�e, r�achemine le message SOAP vers un autre noeud SOAP. Par exemple, le traitement d'un bloc d'en-t�te "routage" d�crivant une caract�ristique de cheminement dans un message SOAP arrivant peut dicter le r�acheminement du message SOAP vers un autre noeud SOAP, identifi� par des donn�es dans ce bloc d'en-t�te. Le format de l'en-t�te SOAP du message SOAP sortant, c-a-d le placement de blocs d'en-t�tes ins�r�s ou r�ins�r�s, serait d�termin� par le traitement global � cet interm�diaire de r�acheminement (forawrding intermediary) bas� sur la s�mantique des blocs d'en-t�te trait�s.

Un interm�diaire actif effectue quant � lui un traitement suppl�mentaire sur un message SOAP arrivant avant de faire suivre le message, selon des crit�res non d�crits dans des blocs d'en-t�te SOAP arrivant ou par la s�quence d'�change de messages utilis�e. 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-t�te, ou inclure des informations suppl�mentaires dans un nouveau bloc d'en-t�te pour horodater ou annoter le message sortant, par exemple, � l'intention de noeuds suivants correctement cibl�s.

Un m�canisme via lequel un interm�diaire actif peut d�crire les modifications effectu�es sur un message consiste � ins�rer des blocs d'en-t�te dans le message SOAP sortant. Ces blocs d'en-t�te peuvent informer les noeuds SOAP suivants jouant un role n�cessitant de recevoir cette information. Dans ce cas, la s�mantique des blocs d'en-t�te ins�r�s devrait �galement appeler la (r�)insertion de blocs d'en-t�te identiques ou autres au niveau des interm�diaires suivants, puisque c'est n�cessaire pour assurer que le message puisse �tre trait� sans probl�me par des noeuds encore plus loin. Par exemple, si un message avec des blocs d'en-t�te supprim�s pour �tre chiffr�s passe au travers d'un second interm�diaire (sans que le bloc d'origine soit d�crypt� et reconstruit), alors l'indication du chiffrement doit �tre conserv�e dans le second relais de message.

Dans l'exemple suivant, un noeud SOAP est introduit dans le cheminement de la requ�te entre les applications de r�servation 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 soci�t�. Notez que les blocs d'en-t�te reservation et passenger dans cet exemple sont destin�s au(x) noeud(s) jouant le r�le "next", c'est-�-dire tout noeud SOAP suivant dans le cheminement qui re�oit le message. Les blocs d'en-t�tes sont obligatoires (l'attribut mustUnderstand a pour valeur "true"), ce qui signifie que le noeud doit savoir qu'en faire (au travers d'une sp�cification externe de la s�mantique de ces blocs d'en-t�te). Une sp�cification d'enregistrement pour de tels blocs d'en-t�te peut simplement obliger � enregistrer divers d�tails du message � chaque noeud le recevant et � relayer le message inchang� sur le chemin. (Notez que les sp�cifications des blocs d'en-t�te doivent obliger � r�ins�rer les m�mes blocs d'en-t�te dans le message sortant, car sinon le mod�le de traitement SOAP imposerait de les retirer). Dans ce cas, le noeud SOAP agit comme un interm�diaire de r�acheminement.

Un sc�nario plus complexe consiste � modifier le message SOAP re�u d'une certaine mani�re non pr�vue par l'�metteur initial. Dans l'exemple qui suit, il est suppos� que l'application de voyages de la soci�t� sur l'interm�diaire SOAP attache un bloc d'en-t�te 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-t�te contient les contraintes impos�es par une politique de d�placements pour le voyage demand�. La sp�cification d'un tel bloc d'en-t�te peut n�cessiter 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 interm�diaire actif ins�rant un bloc d'en-t�te suppl�mentaire, travelPolicy, destin� au r�cepteur 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 J�gvan �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 r�servation de voyage, apr�s qu'un interm�diaire actif a ins�r� un bloc obligatoire destin� au r�cepteur final du message

5.2 Utilisation d'autres sch�mas d'encodage

Si SOAP sp�cifie un sch�ma d'encodage particulier (voir la section 3 de SOAP Partie 2), son utilisation est optionnelle et la sp�cification dit clairement que d'autres sch�mas d'encodage peuvent �tre utilis�s pour des donn�es sp�cifiques � une application dans un message SOAP. Pour cela, elle fournit l'attribut env:encodingStyle, de type xs:anyURI, pour qualifier les blocs d'en-t�te, tout �l�ment fils de l'�l�ment SOAP env:Body et tout �l�ment fils de env:Detail et sa descendance. Il signale un sch�ma de s�rialisation pour le contenu englob� ou au moins jusqu'� ce qu'un autre �l�ment indique un autre style d'encodage pour ses contenus englob�s. Le choix de la valeur de l'attribut env:encodingStyle est sp�cifique � l'application et la capacit� � interop�rer est suppos�e d�finie "hors-ligne". Si cet attribut n'est pas pr�sent, alors rien ne permet de dire quel encodage est utilis�.

Nous pr�sentons une utilisation de sch�ma d'encodage alternatif dans l'exemple 17. A la suite du th�me de r�servation de voyage, cet exemple montre un message SOAP qui pourrait �tre envoy� au passager par le service de voyages apr�s confirmation de la r�servation, avec les d�tails du voyage. (Le m�me 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 J�gvan �yvind</x:passenger>
      <x:outbound>
       <x:TravelRequest>
        <x:to>LAX</x:to>
        <x:from>LGA</x:from>
        <x:date>2001-12-14</x:date>
       </x:TravelRequest>
      </x:outbound>
      <x:return>
       <x:TravelRequest>
        <x:to>JFK</x:to>
        <x:from>LAX</x:from>
        <x:date>2001-12-20</x:date>
       </x:TravelRequest>
      </x:return>
    </x:ReservationRequest>
  </rdf:RDF>
 </env:Body>
</env:Envelope>

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

Dans l'exemple 17, le corps du message SOAP contient une description de l'itin�raire utilisant l'encodage d'un graphe de ressources et leurs propri�t�s dans le langage RDF (Resource Description Framework) [RDF]. (Tr�s bri�vement, puisque la syntaxe de RDF n'est pas le sujet de ce pr�liminaire, un graphe RDF relie des ressources - telles que la ressource de r�servation de voyage disponible � http://travelcompany.example.org/reservations?code=FT35ZBQ - � d'autres ressources (ou valeurs) via des propri�t�s, telles que passenger, et les dates de voyages outbound et return. L'encodage RDF pour l'itin�raire peut avoir �t� choisi par exemple pour permettre au passager de le stocker dans une application de calendrier supportant RDF, qui pourrait alors �tre interrog�e de mani�re complexe).

6. Changements entre SOAP 1.1 et SOAP 1.2

La version 1.2 de SOAP pr�sente un certain nombre de modifications dans la syntaxe et fournit de la s�mantique suppl�mentaire (ou clarifi�e) � ce que d�crit SOAP 1.1 [SOAP 1.1]. Voici une liste de caract�ristiques o� les deux sp�cifications diff�rent. Le but de cette liste est de donner au lecteur un r�sum� concis et facilement accessible des diff�rences entre les deux sp�cifications. Les changements suivants ont �t� pr�sent�s en cat�gories simplement pour faciliter les r�f�rences et, dans certains cas, un item pourrait aussi bien se placer dans une autre cat�gorie.

L'annexe A de SOAP Partie 1 fournit des r�gles 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 d�finit un bloc d'en-t�te env:Upgrade qui peut �tre utilis� par un noeud SOAP 1.2 � la r�ception d'un message [SOAP 1.1] pour envoyer un message de faute SOAP � l'�metteur pour signaler quelle version de SOAP il supporte.

7. R�f�rences

[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 sc�nario d'utilisation, qui a depuis �t� d�plac� dans le brouillon Sc�narii 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 d�taill�s sur des versions pr�c�dentes 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 r�daction de ce document et par ordre alphab�tique) : 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 xml-dist-app@w3.org.