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)

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.