W3C

SOAP Version 1.2

W3C Working Draft 9 July 2001

英文版:
http://www.w3.org/TR/2001/WD-soap12-20010709/
英文版的最后版:
http://www.w3.org/TR/soap12/
英文版编辑:
Martin Gudgin (DevelopMentor)
Marc Hadley (Sun Microsystems)
Jean-Jacques Moreau (Canon)
Henrik Frystyk Nielsen (Microsoft Corp.)
 
中文版:
http://www.uddi-china.org/pubs/misc/soap12.htm
中文版编辑:
柴晓路, Fennivel Chai (DealEasy)
中文版贡献者:
许佑骏, Arthor Xu (DealEasy)
 

Abstract

SOAP 1.2为在一个松散的、分布的环境中使用XML对等地交换结构化的和类型化的信息提供了一个简单且轻量级的机制。这是一个基于XML的协议,同时它由四部分组成: 一个作为描述在消息中的内容以及如何处理消息的信息框架的信封(envelope),一组用于表示应用定义的数据类型的编码规则(encoding rules),一个用于表示远程过程调用和返回的约定以及一个使用底层协议进行消息交换的绑定(binding)约定。潜在地,SOAP可以与很多其他的协议绑定使用;不过,在本文档中,只定义了SOAP与HTTP已经SOAP与HTTP Extension Framework的绑定。

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This is the first W3C Working Draft of the SOAP version 1.2 specification for review by W3C members and other interested parties. It has been produced by the XML Protocol Working Group (WG), which is part of the XML Protocol Activity.

The XML Protocol Protocol Working Group has, in keeping with its charter, produced a set of requirements and usage scenarios that have been published as a Working Draft. To better evaluate SOAP/1.1 against these requirements and usage scenarios, the Working Group has produced an abstract model and a glossary of terms and concepts used by the Working Group. In addition, the Working Group has produced an issues list that describes issues and concerns raised by mapping its requirements and the XMLP abstract model against the SOAP/1.1 specification as well as issues raised on the <xml-dist-app@w3.org> mailing list against SOAP/1.1.

The current name for this specification is SOAP version 1.2, this first Working Draft being based on SOAP/1.1 as per the Working Group's charter (see change log in appendix D)

Comments on this document should be sent to xmlp-comments@w3.org (public archives). It is inappropriate to send discussion emails to this address.

Discussion of this document takes place on the public <xml-dist-app@w3.org> mailing list (Archives) per the email communication rules in the XML Protocol Working Group Charter.

This is a public W3C Working Draft. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of all W3C technical reports can be found at http://www.w3.org/TR/.

Table of Contents

1. 引言
1.1 设计目标
1.2 符号约定
1.3 SOAP消息示例
1.4 SOAP术语
1.4.1 协议概念
1.4.2 数据封装概念
1.4.3 消息发送者和接收者概念
1.4.4 数据编码概念
2. SOAP消息交换模型
2.1 SOAP结点
2.2 SOAP角色与SOAP结点
2.3 定位SOAP Header条目
2.4 理解SOAP Header
2.5 处理消息
3. 与XML的关系
4. SOAP信封
4.1.1 SOAP encodingStyle属性
4.1.2 Envelope版本模型
4.2 SOAP Header
4.2.1 使用Header属性
4.2.2 SOAP actor属性
4.2.3 SOAP mustUnderstand属性
4.3 SOAP Body
4.3.1 SOAP Header和Body的关系
4.4 SOAP错误
4.4.1 SOAP错误代码
4.4.2 MustUnderstand错误
5. SOAP编码
5.1 使用XML进行类型编码的规则
5.2 简单类型
5.2.1 字符串
5.2.2 枚举
5.2.3 字节数组
5.3 多态存取标识
5.4 复合类型
5.4.1 复合值及对值的引用
5.4.2 数组
5.4.2.1 部分传输数组
5.4.2.2 稀疏数组
5.4.3 通用复合类型
5.5 默认值
5.6 SOAP root属性
6. 在HTTP中使用SOAP
6.1 SOAP HTTP请求
6.1.1 HTTP Header中的SOAPAction字段
6.2 SOAP HTTP响应
6.3 HTTP扩展框架
6.4 SOAP HTTP示例
7. 在RPC中使用SOAP
7.1 RPC和SOAP Body
7.2 RPC和SOAP Header
8. 安全机制的考虑
9. 参考文献
9.1. Normative references
9.2. Informative references
A. SOAP Envelope Examples
A.1 Sample Encoding of Call Requests
A.2 Sample Encoding of Response
B. Acknowledgements
C. Version Transition From SOAP/1.1 to SOAP/1.2
D. Change Log
D.1 SOAP Specification Changes
D.2 XML Schema Changes

1. 引言

SOAP v1.2为在一个松散的、分布的环境中使用XML对等地交换结构化的和类型化的信息提供了一个简单且轻量级的机制。SOAP本身并不定义任何应用语义,如编程模型或特定语义实现,它只是定义了一种简单的机制,通过一个模块化的包装模型和对模块中特定格式编码的数据的重编码机制来表示应用语义。SOAP的这项能力使得它可被很多类型的系统用于从消息系统到RPC(Remote Procedure Call)的延伸。

SOAP由四部分组成:

  1. SOAP envelop (SOAP信封,参阅 section 4),它构造定义了一个整体的表示框架,可用于表示在消息(message)中的是什么应当处理它,以及这是可选的 还是强制的。

  2. SOAP encoding rules (SOAP编码规则,参阅 section 5),定义了一个编序机制用于交换应用程序定义的数据类型的实例。

  3. SOAP RPC representation (SOAP RPC表示,参阅 section 7),定义了一个用于表示远端过程调用和响应的约定。

  4. SOAP binding (SOAP绑定,参阅 section 6) 定义了一个使用底层传输协议来完成在结点间交换SOAP信封的约定。

为了简化本规范,这四部分在功能上是正交的。特别的,信封和编码规则是被定义在不同的命名空间(namespace)中,这样有利于通过模块化获得简明性。

本规范还定义了两种SOAP绑定(binding),用于描述SOAP消息(message)如何通过带或不带HTTP扩展框架[6](HTTP Extension Framework)的HTTP[5]消息(message)进行传输。

1.1 设计目标

SOAP的主要设计目标是简明性和可扩展性。这就意味着有一些传统消息系统或分布式对象系统中的特性将不包含在SOAP的核心规范中。这些特性包括:

1.2 符号约定

本文中的关键词“MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, “OPTIONAL”的语义应当参阅RFC-2119[2]。在本中文版规范中被翻译成:“必须”、“必须不”,“需要的”,“将”,“将不”,“应该”,“应该不”,“被推荐的”,“可以”,“可选的”。

本文中使用的命名空间前缀“env”和“enc”等关联的SOAP命名空间分别位于以下位置:"http://www.w3.org/2001/06/soap-envelope" 和"http://www.w3.org/2001/06/soap-encoding"。

在本文的全部内容中,命名空间前缀"xs"和"xsi"总假定是与"http://www.w3.org/2001/XMLSchema" 和"http://www.w3.org/2001/XMLSchema-instance"相关联的,这是由XML Schemas规范[10,11]所定义的。

值得注意的是其他的对命名空间前缀的使用都是比较随意的而并没有显著语义的约束的。

若命名空间的URI使用"http://example.org/..."或"http://example.com/..."的形式,表明这是一些应用依赖或上下文依赖的URI[4]

本规范使用扩充BNF(Backus-Naur Form)作为构造语言,可参阅RFC-2612 [5]

编辑的注解将使用黄色背景标识(也许无法在所有的媒介上显示),并使用前缀"Ednote"。

1.3 SOAP消息示例

第一个例子展示了一个使用SOAP表示的简单的通知消息。该消息包含了一个消息头"alertcontrol"和消息体"alert",这两部分都是由应用程序定义的,而而并不是由SOAP定义的。消息头包含了两个参数"priority"和"expires",用于消息传输中介和消息接受者对消息的处理。而消息体中则包含是实际传送的消息。

Example 0
<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope"> 
 <env:Header>
  <n:alertcontrol xmlns:n="http://example.org/alertcontrol">
   <n:priority>1</n:priority>
   <n:expires>2001-06-22T14:00:00-05:00</n:expires>
  </n:alertcontrol>
 </env:Header>
 <env:Body>
  <m:alert xmlns:m="http://example.org/alert">
   <m:msg>Pick up Mary at school at 2pm</m:msg>
  </m:alert>
 </env:Body>
</env:Envelope>
Sample SOAP Message containing a header block and a body block

SOAP消息能够与不同的底层协议进行绑定,同时可以在很多种消息传输模式中使用。下面的例子则展示了SOAP是如何在HTTP的连接中使用的,其中充分使用了HTTP提供的请求/相应机制(参阅 section 6)。

Example 1和Example 2展示了一个SOAP/HTTP请求的例子和一个SOAP/HTTP响应的例子。SOAP/HTTP请求包含了一个获取最后交易价格(GetLastTradePrice)的信息块,其中包含了一个简单的参数,指明需要报价的股票代号。同样,与先前的例子相似,GetLastTradePrice这个XML元素也并不是由SOAP自身定义的。该请求的服务响应也包含了一个简单的参数,股票的价格。SOAP信封元素是表示SOAP消息的XML文档的顶级元素。XML命名空间则用来消除SOAP标识符与应用定义的标识符之间可能存在的歧义。

Example 1
POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://example.org/2001/06/quotes"

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 <env:Body>
  <m:GetLastTradePrice 
        env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
        xmlns:m="http://example.org/2001/06/quotes">
    <symbol>DIS</symbol>
  </m:GetLastTradePrice>
 </env:Body>
</env:Envelope>
Sample SOAP Message embedded in an HTTP Request

Example 2展示了StockQuote服务响应由Example 1描述的请求消息而返回的SOAP消息。

Example 2
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 <env:Body>
  <m:GetLastTradePriceResponse 
        env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
        xmlns:m="http://example.org/2001/06/quotes">
   <Price>34.5</Price>
  </m:GetLastTradePriceResponse>
 </env:Body>
</env:Envelope>
Sample SOAP Message embedded in an HTTP Response

Appendix A中提供了更多的例子。

1.4 SOAP术语

1.4.1 协议概念

SOAP

关于SOAP消息的格式和处理规则、为沿着SOAP消息路径交换信息而需要的不同应用程序之间生成接收SOAP消息的交互过程的简单控制机制等的一整套规范和约定。

SOAP绑定

为传输的需要而将SOAP消息在另一个底层协议之上或之内传输的一整套规范和规则。典型的SOAP绑定包括在HTTP消息中传送SOAP消息或在TCP之上传送SOAP消息等。

SOAP结点

SOAP结点根据SOAP定义的整套规范来处理SOAP消息。SOAP结点有责任遵守SOAP消息交换的规则以及提供通过依赖底层协议的SOAP绑定来访问的服务。任何不符合SOAP约定的情况都将导致SOAP结点产生一个SOAP错误(可参阅SOAP接受者SOAP发送者)。

1.4.2 数据封装概念

SOAP消息

SOAP消息(message)是在对等SOAP结点(SOAP nodes)间通讯的基本单位。

SOAP信封

SOAP信封(envelope)是SOAP规范中定义的SOAP消息(SOAP message)在句法上的最外层结构。在句法上,它包含了所有其他的元素。

SOAP条目

SOAP条目是一个句法上的结构,它用于包含一个逻辑上的单一元素,这一元素是需要被SOAP结点处理的。一个SOAP条目是由该条目最外层元素的完整修饰名所标识的,这个完整修饰名是由一个局部名和一个命名空间URI组成的。封装在SOAP header中的SOAP条目成为Header条目,而封装在SOAP body中的SOAP条目为Body条目。

SOAP header

能够被SOAP消息路径中任意的SOAP接受者处理的一组SOAP条目(0个或多个)。 

SOAP body

能够被SOAP消息路径中的最终SOAP接受者处理的一组SOAP条目(0个或多个)。

SOAP fault

SOAP结点产生的用于包含错误信息的特殊的SOAP条目

以下的图表演示了一个SOAP消息是如何组成的。

Figure 1: Encapsulation model illustrating the parts of a SOAP message

SOAP message model

1.4.3 消息发送者和接收者概念

SOAP发送者

SOAP发送者是发出SOAP消息的SOAP结点

SOAP接收者

SOAP接收者是接受SOAP消息的SOAP结点

SOAP消息路径

为传送一个简单的SOAP消息而要经过的一组SOAP发送者SOAP接受者。其中包含了初始SOAP发送者、零个或多个SOAP中介以及最终SOAP接受者

初始SOAP发送者

SOAP消息的最初产生者,同时也是SOAP消息路径的第一个结点。

SOAP中介

SOAP中介即是SOAP接收者也是SOAP发送者,是SOAP消息可到达的某一个应用程序。当SOAP消息沿着SOAP消息路径传输时,SOAP中介将处理一组确定的SOAP条目,然后它将消息转发给消息路径的下一个SOAP结点,直至传送到最终SOAP接收者

最终SOAP接收者

初始SOAP发送者指定的通过SOAP消息路径传送SOAP消息的最终SOAP接收者。如果在SOAP消息路径中有SOAP结点产生了SOAP错误,那么SOAP消息将不会到达最终接收者。

1.4.4 数据编码概念

SOAP数据模型

一组抽象的构造约定,用于描述通用的数据类型和数据中的链接关系。

SOAP数据编码

SOAP消息中使用一个或多个SOAP条目,按照SOAP数据模型完成句法上的数据表示。

2. SOAP消息交换模型

从根本上来看,SOAP消息是从发送方到接受方的一种传输方法,但就象前面例子中阐述的那样,SOAP消息一般会和实现模式结合,例如请求/响应。

SOAP的实现可以为特殊网络系统的特有特征来优化。例如,在section 6中描述的HTTP binding将SOAP响应消息通过HTTP响应来传输,使用与相对应请求的同一HTTP连接。

2.1 SOAP结点

SOAP结点可以是初始SOAP发送者,可以是最终SOAP接收者,也可以是同时作为SOAP发送者和接收者的SOAP中介。SOAP并不提供一个路由机制,曾因此SOAP需要识别SOAP发送者产生的SOAP消息应当通过哪些零个或多个SOAP中介被发送到一个最终SOAP接收者。

接收到SOAP消息的SOAP结点必须能够实施处理、产生必要的SOAP错误和SOAP响应,如果合适的话还应当根据本规范的后续描述生成额外的SOAP消息。

2.2 SOAP角色与SOAP结点

当处理一个SOAP消息的时候,SOAP结点将被告知应当以一个或多个SOAP处理角色来处理,这些SOAP角色由SOAP actor名来标识,SOAP actor的名字是一个URI。每个SOAP结点都必须以一个指定的角色来处理,这个角色使用命名为"http://www.w3.org/2001/06/soap-envelope/actor/next"的SOAP actor来表示,同时可以按照需要应用零个或多个其他SOAP actor表示的额外角色。SOAP结点可以通过以匿名SOAP actor的角色来实施处理以使得自己成为最终SOAP接收者。当SOAP结点在处理一个SOAP消息的时候,其表现出的SOAP角色在整个处理过程中不得更改。这是因为本规范只涉及如何处理单个SOAP消息而无需考虑状态,因此是否允许在处理单个SOAP消息的时候转换角色是没有意义的。

SOAP actor名字是用来识别SOAP结点的,并没有与路由或者消息交换的语义相联系。举例来说,一个SOAP actor可以被命名为一个用来发送SOAP消息给适当SOAP结点的URI。相反,也有这样一些SOAP处理角色的名字,这些名字或者直接和消息路由相联系(例如,http://example.org/banking/anyAccountMgr),或者和路由没有联系(例如,当一个消息头被用来携带一个指示,该指示用来告知任何有关的软件该SOAP消息是长期不变的,是能够被安全的缓存和重用的,在这种SOAP消息头中,一个URI可以用于标识“所有缓存管理软件”),通过名字使用这些SOAP处理角色也是合适的。

2.3 定位SOAP Header条目

SOAP header条目包含可选的env:actor属性(参阅section 4.2.2)用来把他们定位到合适的SOAP结点。没有该属性的SOAP Header隐含地定位到一个匿名的SOAP actor,这意味着他们被处理为最终的SOAP接收者。我们把SOAP actor属性的值(隐含的或者直接指明的)作为相应SOAP条目(SOAP Header条目或者SOAP Body条目)的SOAP actor。

如果SOAP条目中SOAP actor(如果出现的话)匹配了一个SOAP结点的角色,或者是SOAP条目没有actor属性(包括SOAP Body条目)而该SOAP结点已经假设为匿名SOAP处理角色,这时我们就说SOAP条目被指向一个SOAP结点。

2.4 理解SOAP Header

我们认为随着时间的过去,会有大量的SOAP Header函数规范出现,而且每个SOAP结点都可以包含一个或多个处理这些扩展所必须的软件。如果SOAP结点的软件是完全兼容的而且实现了那些由条目中完整修饰的最外层元素名所传递的语义,我们说这个SOAP Header被一个SOAP结点理解。

当定位到一个SOAP结点的SOAP Header块的mustUnderstand属性为“1”,被指向的SOAP结点必须:或者依照由条目中完整修饰的最外层元素名传递的语义来处理SOAP块,或者更本不处理SOAP消息而失败(参见section 4.4).。

2.5 处理消息

本节陈述了SOAP消息处理规则。除非另外规定,处理必须在语义上等同于分别执行下述的步骤,同时还必须按照给定的顺序。注意到,无论如何在这个规范中都没有阻止使用如并行、回滚或者其他可以在处理中提高灵活性的技术,只要所有的SOAP消息、SOAP fault和应用程序级的结果和那些直接执行下列规则得到的结果是相同的。

  1. 如果一个或多个定位到SOAP结点的SOAP条目有env:mustUnderstand="1"并且没有被结点理解,则产生一个SOAP mustUnderstand错误。如果这样一个错误产生了,那么必须停止进一步的处理。

  2. 处理定位到SOAP结点的SOAP条目,如果需要,产生SOAP错误。当定义env:mustUnderstand="1"时,一个SOAP结点必须处理SOAP块。如果没有定义,那么SOAP结点可以处理或忽略该SOAP条目。如果一个SOAP条目被处理,无论如何,这个SOAP结点必须理解该SOAP条目而且必须以和那个SOAP条目说明完全一致的样式进行处理。而对于错误,无论是那种,也必须和SOAP条目的说明一致。有可能处理特殊SOAP条目会控制或者决定其他SOAP条目的处理顺序。例如,一个SOAP条目可能建立一个SOAP Header条目用来强制按词汇的顺序执行其他的SOAP Header条目。如果没有这样一个SOAP条目,处理的顺序是由SOAP结点来判断的。当处理一个SOAP条目的时候,SOAP结点可以引用SOAP envelope中的任何信息。例如如果需要,一个缓存函数可以缓存整个SOAP消息。

如果SOAP结点是一个SOAP中介,SOAP消息的式样和处理的结果(如果没有产生错误)可以要求进一步沿着SOAP消息路径送递SOAP消息。这种接力转递必须以同样顺序包括从SOAP消息源来的所有的SOAP Header条目和SOAP Body条目,除了那些指向SOAP中介的SOAP Header条目,这些条目必须被移去(无论他们是否被处理,这些SOAP条目都将被移去)。附加的SOAP Header条目可以被插入在SOAP消息的任何一点,这样被插入的SOAP Herder条目可能没法和刚刚被移走的一个或多个条目区分开来(实际上是会将他们保留,但强调需要沿着SOAP消息路径重新解释每个SOAP结点)

3. 与XML的关系

所有的SOAP消息都是使用XML格式来编码的(可参阅[7]以获得更多的XML的信息)。

SOAP应用程序在生成由SOAP定义的所有元素和属性的时候,应该包含恰当的SOAP命名空间。SOAP应用程序必须能处理其收到的消息中的SOAP命名空间。它必须丢弃那些包含不正确命名空间(参阅 section 4.4)的消息,并且可以处理那些不包含SOAP命名空间的SOAP消息,就好象他们包含了正确的命名空间一样。

SOAP定义了以下的命名空间 (可参阅[8]以获得更多的XML命名空间的信息):

而这些命名空间的模式文档可以通过解析这些命名空间标识符来获得。

SOAP消息必须不包含DTD,同时SOAP消息也必须不包含PI(Processing Instructions)。 [7]

SOAP使用局部的非限制的ID类型的id属性来指定编码元素(encoded element)的唯一标识,使用局部的非限制的uri-reference类型的href属性来指定编码元素的值的应用,以获得与XML规范[7]、XML Schema规范[11]和XML Linking Language规范[9]的一致。

除SOAP mustUnderstand属性(参阅 section 4.2.3)和SOAP actor属性(参阅 section 4.2.2)外,一般允许属性及属性值自由地选择是在XML实例中描述还是在XML Schema中描述,当然前提是他们具有相同的效果。也就是说,在DTD或模式(schema)中使用默认值或固定值定义在语义上等价于在实例中的定义。

4. SOAP信封

SOAP消息是由一个强制的SOAP Envelope、一个可选的SOAP Header和一个强制的SOAP Body组成的XML文档。作为SOAP消息的该XML文档将在本规范的其余部分被引用。而本节的元素和属性的命名空间标识是"http://www.w3.org/2001/06/soap-envelope"。SOAP消息应当包含如下部分:

语法规则如下:

  1. SOAP Envelope

  2. SOAP Header (参阅 section 4.2)

  3. SOAP Body (参阅 section 4.3)

4.1.1 SOAP encodingStyle属性

SOAP的全局encodingStyle属性被用于指明在SOAP消息中使用哪种编序规则。该属性可以在任意元素中出现,并且其作用范围包括该元素的内容和所有其子元素中未使用该属性的所有子元素,这就象XML命名空间定义的作用范围。对于一个SOAP消息来说,没有默认的编码定义。

该属性的值是一个或多个用于标识编序规则和用于标识解序SOAP消息的规则的有序列表,其排序是按照详尽程度从大到小排列。Example 3展示了encodingStyle属性的三个例子:

Example 3
encodingStyle="http://www.w3.org/2001/06/soap-encoding"
encodingStyle="http://example.org/encoding/restricted http://example.org/encoding/"
encodingStyle=""
Example values for the encodingStyle attribute

section 5中定义的编序规则的标识为"http://www.w3.org/2001/06/soap-encoding"。消息若要使用特别的编序应该使用SOAP encodingStyle属性来指明。另外,所有在句法上由"http://www.w3.org/2001/06/soap-encoding"开始的URI序列表明这其中包含的所有URI都与section 5中定义的SOAP编码规则相一致。(虽然可能会添加潜在的更为严格的规则)

一个空值的URI(“”)明确地指明并未为其所包含的元素声明任何编码风格。这可以为包含的元素关闭任何声明。

4.1.2 Envelope版本模型

 SOAP并未定义一个传统的基于主辅版本号的版本模型。SOAP消息必须包含一个与命名空间"http://www.w3.org/2001/06/soap-envelope"相关联的Envelope元素。如果SOAP应用程序收到一个SOAP消息,这个消息中的Envelope元素与一个与"http://www.w3.org/2001/06/soap-envelope"不同的命名空间相关联,则该应用程序必须视其为一个版本错误并生成一个VersionMismatch SOAP错误。SOAP VersionMismatch错误消息必须使用SOAP 1.1的信封命名空间"http://schemas.xmlsoap.org/soap/envelope/"(参阅 Appendix C)修饰。

4.2 SOAP Header

SOAP提供了一个可伸缩的机制用于在分散的模块化的环境下扩展SOAP消息,而通讯双方并不需要有预先的约定知识。典型的扩展例子可以是实现一些诸如认证、事务管理以及支付的Header条目。

SOAP Header元素应当被编码为SOAP Envelope XML文档的第一直接子元素。Header的所有直接子元素都被称为Header条目。

Header条目的编码规则包括:

  1. 一个SOAP Header条目由一个完整修饰的元素名来标识,所谓完整修饰的元素名是由一个命名空间URI和局部名来组成。SOAP Header元素的所有直接子元素都必须是完整修饰的。

  2. SOAP encodingStyle属性可以用于指明Header条目的编码风格(参阅 section 4.1.1)。

  3. SOAP actor属性(参阅 section 4.2.2)和SOAP mustUnderstand属性(参阅 section 4.2.3)可以用于指明由哪个SOAP结点来处理条目以及如何处理条目。

4.2.1 使用Header属性

本节中定义的SOAP Header属性决定了SOAP消息的接收者应该如何处理消息(参阅 section 2)。一个生成SOAP消息的SOAP应用程序应该仅使用SOAP Header元素的直接子元素的SOAP Header属性。而对于那些并非作为SOAP Header元素的直接子元素出现的SOAP Header属性,SOAP消息的接受者必须忽略。

以下是一个SOAP Header的例子(Example 4),其中包含了一个元素标识Transaction和一个mustUnderstand属性及其值1,以及Transactin的值5:

Example 4
<env:Header xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
  <t:Transaction xmlns:t="http://example.org/2001/06/tx" env:mustUnderstand="1" >
    5
  </t:Transaction>
</env:Header>
Example header with a single header block

4.2.2 SOAP actor属性

EdNote: This section partially overlaps with section 2. We expect this to be reconciled in a future revision of the specification.

SOAP消息从生成者到达最终接受者,将潜在地沿着消息路径(message path)经过一系列的SOAP中间介。SOAP中间介是一个能够接受和转发SOAP消息的应用程序。所有的中间介都如同最终接受者一样由一个URI来标识。

并非一个SOAP消息的所有部分都是最终接收者想要的,其中部分是路径中的一个或多个中间介所需要的。Header元素中接收者角色类似和约的接受者,他并不能将其交给其它方。也就是说,一个接收者接到其想要的一个Header元素必须不转发该Header给SOAP消息路径中的下一个应用程序,因为合约关系是存在于前二者之间的。该接收者可以插入一个类似的Header元素,但在这个情况下,和约关系存在于该应用程序及下一个Header元素的接收者之间了。

SOAP actor全局属性可以被用于指明Header元素的接收者。而SOAP actor属性的值是一个URI。这个特别的URI"http://www.w3.org/2001/06/soap-envelope/actor/next"指明该Header元素是直接的下一个进行消息处理的SOAP应用程序想要的。这与HTTP的连接头字段的hop-by-hop scope model的表示。

若省略SOAP actor属性,则表明接收者是SOAP消息的最终接收者。

这个属性必须出现在SOAP消息的实例中,而不能定义在相关的XML Schema中以期获得同样效果(参阅 section 3section 4.2.1)。

4.2.3 SOAP mustUnderstand属性

EdNote: This section partially overlaps with section 2. We expect this to be reconciled in a future revision of the specification.

SOAP mustUnderstand全局属性用于指明一个Header条目是强制的还是可选的要求接收者处理。Header条目的接收结点由SOAP actor属性来定义(参阅 section 4.2.2)。mustUnderstand属性的值可为“0”或“1”。若没有使用SOAP mustUnderstand属性,则在语义上等价于mustUderstand属性出现同时取值为“0”,也就是说这个条目是可选的。

若Header条目带有值为“1”的SOAP mustUnderstand属性,则该Header条目的接收结点要么必须遵循语义(由具备完整修饰的元素名来传达)并正确地处理这些语义,要么必须宣称处理消息失败(参阅 section 4.4)。

SOAP mustUnderstand属性是为了考虑健壮地升级而设置的。所有用值为“1”的SOAP mustUnderstand属性来标记的元素必须被认为是可以影响该元素的上级元素或同级元素的语义。而这种风格标记的元素应保证对语义的修改并不能被那些不能完全理解该修改后的语义的那些元素静默地或假设地、不正确地忽略。

该属性若要生效必须在实例中出现,而不能定义在相关的XML Schema中以期获得同样效果(参阅 section 3section 4.2.1)。

4.3 SOAP Body

SOAP Body元素提供一个简单的用于与消息的最终接收者交换强制信息的机制。而Body元素的典型应用包含序列的RPC调用和错误报告。

Body元素在编码上应当作为SOAP Envelope元素的一个直接子元素。如果包含Header元素,则Body元素必须直接跟随Header元素,为Header元素的直接下一个兄弟元素,否则Body元素必须是Envelope元素的第一直接子元素。

所有Body元素的直接子元素被成为SOAP Body条目,同时每一个Body条目都应当编码为SOAP Body元素里的一个独立元素。

Body条目的编码规则包括:

  1. 一个Body条目由一个完整修饰的元素名来标识,所谓完整修饰的元素名是由一个命名空间URI和局部名来组成。SOAP Body元素的直接子元素可以是命名空间修饰的。

  2. SOAP encodingStyle属性可以被用来表明Body条目中使用的编码规则(参阅 section 4.1.1)。

SOAP定义了一个Body条目,用于报告错误的Fault条目(参阅 section 4.4)。

4.3.1 SOAP Header和Body的关系

Header和Body在定义上是独立的,但在事实上是相联系的。一个Body条目和一个Header条目的关系是:一个Body条目在语义上与这样一个Header条目等价,该Header条目将由默认参与者(最终接受者)解释同时由值为“1”的SOAP mustUnderstand属性标记。默认参与者可以使用actor属性缺失的方式来指明(参阅 section 4.2.2)。

4.4 SOAP错误

SOAP Fault元素是用于在SOAP消息中传输错误或状态信息。如果SOAP消息需要包含SOAP Fault元素的话,它必须作为一个Body条目出现,同时在Body元素内它必须不出现多于一次(至多出现一次)。

SOAP Fault元素定义了如下子元素:

faultcode

faultcode元素是应那些要提供一个算法上的机制来标识错误的软件的需要。faultcode必须在SOAP Fault元素中出现,同时faultcode的值必须是如[8]中的第3节中定义的一个修饰(限制)名。SOAP定义了一个很小的SOAP错误代码的集合用于覆盖基本的SOAP错误(参阅 section 4.4.1)。

faultstring

faultstring元素是为那些错误代码提供一个人可以读懂的错误解释,它不是为程序处理而设。Faultstring元素有点类似于HTTP中定义的’Reason-Phrase’(参阅 [5], section 6.1)。faultstring必须在SOAP Fault元素中出现,同时它至少应该提供一些解释该错误种类的信息。

faultactor

faultactor元素是为在SOAP消息路径(参阅 section 2)中是谁引起了该错误的发生这一情况描述信息。它类似于SOAP actor属性(参阅 section 4.2.2),不过它不是用于指示Header条目的接收者,而是用于指示错误源。faultactor属性的值是一个标识该源的一个URI。所谓并非作为SOAP消息最终接收者的应用程序必须在SOAP Fault元素中包含faultactor元素。而消息的最终接收者可以使用faultactor元素来明确地指明是它生成了该错误(参阅下面的detail元素]。

detail

detail元素是用于传输与SOAP Body元素相关的应用程序特别的错误信息。如果Body元素中的内容不能被成功地处理的时候,它必须出现。它必须不能被用于传输属于Header条目的错误信息。详细的属于Header条目的错误信息必须在Header条目中表示传输,如果需要例子的话,请参阅section 4.4.2

若SOAP Fault元素中不出现detail元素则表明其中的错误与Body元素的处理无关。这可以用于区分在错误情况下Body元素是否被SOAP的最终接受者处理过。

detail元素的所有直接子元素都被称为detail条目,同时每个detail条目都作为detail元素中的一个独立的元素进行编码。

Detail条目的编码规则如下(也可以参阅 example 10):

  1. 一个detail条目由一个完整修饰的元素名来标识,所谓完整修饰的元素名是由一个命名空间URI和局部名来组成。Detail元素的直接子元素可以是命名空间修饰的。

  2. SOAP encodingStyle属性可以被用来表明detail条目中使用的编码规则(参阅 section 4.1.1)。

4.4.1 SOAP错误代码

当描述由本规范定义的错误的时候,faultcode元素必须使用在本节中定义的faultode的值。这些faultcode值的命名空间标识为"http://www.w3.org/2001/06/soap-envelope"。在现有规范之外定义的方法的规范推荐使用该命名空间(但不是必须的)。

默认的SOAP faultcode值是按照一种可扩展的风格来定义的,它允许在维持已有的faultcode值的向后兼容的基础定义新的SOAP faultcode值。这一机制在使用上非常类似与HTTP中基本状态类的定义1xx, 2xx, 3xx等(参阅[5]中的section 10)。不过,他们是用XML修饰名来定义(参阅[8]中的section 3),而不是用整数。“.”符号是faultcode值的分隔符,用于指明“.”左边的是一个比右边更泛化的错误代码。Example 5显示了这一特性:

Example 5
Client.Authentication
Example of an authentication fault code

在SOAP中定义的faultcode值集合被罗列在下表。

Name Meaning
VersionMismatch 处理程序发现在SOAP Envelope元素中有一个非法的命名空间。(参阅 section 4.1.2)
MustUnderstand SOAP Header元素的一个直接子元素无法被理解或者他并不遵守由处理对象要求的SOAP mustUnderstand属性必须取值为“1”的要求。(参阅 section 4.2.3)
Client

Client错误类用于指示以下错误:消息的格式有误或消息中缺乏能成功处理所必须的一些适当信息。例如,消息中可能缺乏适当的认证和支付信息。一般情况下应指明消息不应该在没有修改过的情况下重发。可参阅section 4.4来参阅Fault detail子元素的描述。

Server

Server错误类用于表明消息无法被处理的原因,但那些属于内容上的错误并不属于该范畴,它主要被用于指示那些属于处理上的错误。例如,处理操作需要包含与一个上游处理程序进行通讯,但该程序没有响应。但该消息可能在下一个时间点上被成功处理。可参阅section 4.4来参阅Fault detail子元素的描述。

4.4.2 MustUnderstand错误

当SOAP结点产生一个MustUnderstand错误时,它应该在产生出的出错消息中按照下面描述的的方式提供相应的Header条目。在产生的错误消息中,它应该提供Header条目来描述不能被理解的带修辞的名的细节(Qnames,由XML Schema数据类型说明)。

每个这样的Header条目有个本地的名字为Misunderstood以及一个叫"http://www.w3.org/2001/06/soap-faults"的命名空间。每个块都有一个名为qname的不带修饰的属性,它的值为出错结点所不能理解的Header条目的Qname。

举例来说,如果最初消息的容器不能理解Example 6中的两个Header元素abc:Extension1和def:Extension2,则会产生出错消息,该消息显示在Example 7中。

Example 6
<env:Envelope xmlns:env='http://www.w3.org/2001/06/soap-envelope'>
  <env:Header>
    <abc:Extension1 xmlns:abc='http://example.org/2001/06/ext' 
                       env:mustUnderstand='1' />
    <def:Extension2 xmlns:def='http://example.com/stuff' 
                       env:mustUnderstand='1' />
  </env:Header>
  <env:Body>
  . . .
  </env:Body>
</env:Envelope>
SOAP envelope that will cause a SOAP MustUnderstand fault if Extension1 or Extension2 are not understood

 

Example 7
<env:Envelope xmlns:env='http://www.w3.org/2001/06/soap-envelope'
                      xmlns:f='http://www.w3.org/2001/06/soap-faults' >
  <env:Header>
    <f:Misunderstood qname='abc:Extension1'
                                xmlns:abc='http://example.org/2001/06/ext' />
    <f:Misunderstood qname='def:Extension2' 
                                xmlns:def='http://example.com/stuff' />
  </env:Header>
  <env:Body>
    <env:Fault>
      <faultcode>MustUnderstand</faultcode>
      <faultstring>One or more mandatory headers not understood</faultstring>
    </env:Fault>
  </env:Body>
</env:Envelope>
SOAP fault generated as a result of not understanding Extension1 and Extension2 in Example 6

注意到这里不需要命名空间前缀返回与源Header元素命名空间相匹配的qname,倘若前缀映射到一个相同的命名空间名,则错误结点可使用任意前缀。

还注意到这里没有保证每个Mustunderstand错误都包含所有的Misunderstood Header 的Qname,SOAP结点可以在第一个Header块产生一个只包含单个Header块错误细节信息之后再产生一个错误。SOAP结点也可以产生一个一次包含所有MustUnderstand问题细节的混合错误。

5. SOAP编码

SOAP编码风格是基于一个简单类型系统,而这个系统是程序语言、数据库和半结构数据中类型系统的公共特性的泛化。一个类型要么是一个简单(可量化的)类型或是一个复合类型,这个复合类型由多个部分组成,每个部分是一个类型。下面会有类型的更为详细的描述。本节定义了一个编序规则,用于可类型化对象图的编序。它在两个级别上操作。首先,给出一个符号上一致化的由该类型系统描述的模式,构造一个XML语法层的模式。其次,提供一个类型系统的模式以及一个与该模式相一致的值的表示方法,构造一个XML实例层的模式。反之,先提供一个符合这些规则XML实例,然后再给出原始的模式、一个原始值表示,也是可以构造的。

在本节中定义的元素和属性所用到的命名空间标识是"http://www.w3.org/2001/06/soap-encoding"。而这些编码的例子中假定所有命名空间声明都是在更高的元素层次上。

在本节中描述的数据模型和编码风格的使用方式是被鼓励的而不是必备的,其他的数据模型和编码也是可以与SOAP联合使用的(参阅 section 4.1.1)。

5.1 使用XML进行类型编码的规则

XML允许非常柔性地编码数据。SOAP只定义了非常有限的编码规则。本节在一个高层次上定义编码规则,而下一节则描述明确类型的编码规则,当有更细节的需求的时候。本节中描述的编码可以与Section 7中描述的RPC调用和响应的映射联合使用。

为了描述编码,以下术语将被使用:

  1. “value”值是一个字符串(string)、一个可量度对象(数字、日期、玫举)的名字、或是数个简单值的组合。所有的值都有明确的类型。

  2. “simple value”简单值是是一个不可分的值,它不包含任意可以命名的部分。简单值的离子可以是特定的字符串、证书或玫举值等。

  3. “compound value”复合值是一个值的关系的聚集。复合值的例子可以是特定的采购定单、存货报表、街道地址等。

  4. 在一个复合值中,每一个相关的值都可以用一个角色名来区分,也可以用一个序数来区分,当然也可以同时使用两者。这被称为“accessor”存取标识。复合值的离子包括特定的采购定单、存货报表等。数组也是复合值。它可以被看成是具有多个相同名字的存取标识(accessor)的复合值,例如RDF。

  5. “array”数组是一个复合值,在其成员值之间仅有顺序位置不同。

  6. “struct”结构是一个复合值,在其成员值之间的区分是依靠存取标识(accessor)。同时所有存取标识的名应不同。

  7. “simple type”简单类型是简单值的类。简单类型的例子包括那些类“string”, “integer”,玫举类等。

  8. “compound type”复合类型是复合值的类。复合类型的例子包括采购定单的抽象类型,这些由该类型派生的采购定单具备相同的存取标识(shipTo, totalCost等),当然他们有不同的值(也许对某些值还有约束)。

  9. 在一个复合类型中,一个存取标识在本符合类型中是唯一的,如果它和其他复合类型中的某个存取标识无法相区别,则该存取标识名加上复合类型的名字才能成为唯一标识,这个名称为"局部名"。无论该名是直接或间接基于一个URI,如果该存取标识不用加类型名约束就已经是唯一的,那该名就成为"全局名"。

  10. 值表的编序的模式中所给出的信息,是有可能能决定一些值只能关联一个存取标识的简单实例。对于其他可能的情况,则无法下这个断言。一个值被称为”single-reference”单引用,如果只有一个存取标识能够引用它。如果能被多个引用,无论是事实上还是潜在可能,那就是”multi-reference”多引用。注意有可能在一模式中有一个确定的值是单引用而其他则是多引用。

  11. 在句法上,一个元素可以是"独立的"或"嵌入的"。一个独立的元素是作为编序中一个顶级元素出现。而其他则是嵌入元素。

尽管使用xsi:type属性可以令值的表示为自描述的,也就是说即包含值的结构也包含值的类型,但编序规则允许值的类型可以仅仅引用模式(Schema)中的类型定义。而这些模式可以使用“XML Schema Part 1: Structures”[10]和“XML Schema Part 2: Datatypes”[11]中定义的规范来描述,当然也可以使用其他的模式定义来定义。注意尽管这样,但许多模式定义只支持结构(struct)和数组(array)类型,而编序规则则有可能要尝试使用结构(struct)和数组(array)类型之外的复合类型。

编序规则如下:

  1. 所有的值都应当表现为元素的内容(content)。一个多引用的值必须被表示为一个独立元素的内容。而一个单引用的值应该不如此(不过也可以如此)。

  2. 对每个包含一个值的元素,值的类型表示必须满足以下至少一个条件:(a) 包含该值的元素实例包含一个xsi:type属性,(b) 包含该值的元素实例包含在一个具备enc: arrayType属性的元素中(可能是被设置成default的),(c) 该元素的名带有一个类型的明确关联,而该类型由一个模式来决定。

  3. 一个简单值应被表示为字符数据(character data),也就是说,没有任何子元素。每一个简单值必须有一个类型,该类型要么是在XML Schema规范的DataTypes部分[11]中被罗列,要么它的源类型应当在该部分中被罗列(可参阅 section 5.2)。

  4. 一个复合值应当被编码为一个元素序列,其中每一个存取标识由一个嵌入元素来表示,他们的名是一一对应的。若存取标识的名在包含它的型中是局部的,则它有一个未修饰的元素名,而其他则应有完全修饰的名(可参阅 section 5.4)。

  5. 一个多引用的简单或复合值应当被编码为一个独立元素,该独立元素应包含一个局部的带有非限制名的“id”属性,该属性的类型为XML规范[7]中定义的ID类型。对该值的每一个存取标识是一个空元素,该空元素有一个局部的未修饰的属性“href”,该属性类型是XML Schema规范[11]中定义的“uri-reference”类型,“href”属性的值是一个引用该对应独立元素的URI片段标识。

  6. 字串和字节数组被表示为多引用简单类型,不过特别的规则也允许它们在通常情况下更有效地表示(可参阅 section 5.2.1以及section 5.2.3)。一个字串或字节数组的存取标识可以有一个在XML规范[7]中定义的名为”id”的ID类型的属性。如果这样的话,所有其他对该同一值的存取标识可以被编码为一个空元素,该空元素应包含一个局部的带有非限制名的“href”属性,该属性的类型为XML Schema规范[11]中定义的“uri-reference”类型,“href”属性的值是一个引用该对应独立元素的URI片段标识。

  7. 对一个值编码多个引用是允许的,看上去这些引用好象是引用了多个不同的值,但仅当从上下文中可得到该XML 实例的含义是未改变的的结论。

  8. 数组是复合值(可参阅 section 5.4.2)。SOAP数组被定义为类型是“enc:Array”或类型是源于“enc:Array”。

    SOAP数组有一或多维,而它的成员由顺序位置区分。一个数组的值被表示为一序列反映该数组的元素,这些成员按序数从小到大顺序出现。对于多维数组,则元素维按从右到左顺序变化。没一个成员元素都被命名为一个独立元素(参阅 rule 2)。

    SOAP数组可以是单引用值,也可以是多引用值,从而可以被表示为一个嵌入元素或一个独立元素。

    SOAP数组必须包含一个“enc:arrayType”属性,其中定义的包含元素的值的类型与维数一起描述了该数组。”enc:arrayType”属性的值定义如下:

    arrayTypeValue  =  atype asize
    atype  =  QName *( rank )
    rank  =  "[" *( "," ) "]"
    asize  =  "[" #length "]"
    length  =  1*DIGIT

    “atype”结构是数组所包含的元素的类型的名,首先它包含一个QName表示,QName应在XML Schema元素声明中的“type”属性中出现,QName是一个型约束(意味着所有其包含的元素都应宣称与该指明的类型相一致,也就是说,在enc:arrayType中引用的类型必须是所有数组元素的类型或超类型)。对于那些数组的数组或是“jagged arrays”,使用rank结构来表示数组的元素是一个数组,同时该数组的具体类型将在下层具体成员数组的定义时数值实例化,rank中出现零个、一个到多个逗号,表明该成员变量是一维、二维或多维数组。对于多维数组,维数定义为一个由“,”分隔的维数序列,每个维数的记数基数为1。

    “asize”结构包含一个由逗号分隔的由零个、一个或多个整数组成的序列指明的数组的每个维的长度。一个由零个整数组成的序列表明对数组打下并没有特别限制,不过具体的大小将由下层具体的成员来决定。

    例如,一个有5个成员的数组,成员类型为integer数组,它的arrayTypeValue的值就应当是 “int[][5]”。其中,atype的值是“int[]”,asize的值是“[5]”。类似地,一个有3个成员的数组,成员类型为integer二维数组,它的arrayTypeValue的值就应当是 “int[,][3]”。其中,atype的值是“int[,]”,asize的值是“[3]”。

    SOAP数组成员可以包含一个“enc:offset”属性来指明该成员在其装载的数组中的偏移量。这也可以用于指明在一个部分描述的数组中成员的偏移(参阅 section 5.4.2.1)。类似的,SOAP数组成员可以包含一个“enc:position”属性来指明该成员在其装载的数组中的位置。这也可以用于指明在一个稀疏描述的数组中成员的位置(参阅 section 5.4.2.2)。“enc:offset”和“enc:position”属性的值定义为:

    arrayPoint  =  "[" #length "]"

    他们的基数都是0。

  9. NULL值和默认值可以在存取标识元素中省略。NULL值可以在一个存取标识元素中使用一个值为1的属性xsi:null来指明,或者可以是其他依赖于应用程序的属性和值。

注意rule 2允许独立元素和数组中成员元素对于包含的类型可以有不同的名。

5.2 简单类型

对于简单类型,SOAP采用了在“XML Schema Part 2: Datatypes”[11]的“Build-in datatypes”节中定义的所有类型,包括值和词汇空间(lexical spaces)。例子包括:

Type Example
int 58502
float 314159265358979E+1
negativeInteger -32768
string Louis "Satchmo" Armstrong

在XML Schema规范中声明的数据类型可以直接在元素模式中使用。而源于这些类型的类型也可以被使用。下面是一个模式片段和相应类型元素数据的例子:

Example 7
<!-- schema document -->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" >

  <xs:element name="age" type="xs:int" />
  <xs:element name="height" type="xs:float" />
  <xs:element name="displacement" type="xs:negativeInteger" />
  <xs:element name="color" >
    <xs:simpleType base="xsd:string">
      <xs:restriction base="xs:string" >
        <xs:enumeration value="Green"/>
        <xs:enumeration value="Blue"/>
          </xs:restriction>
    </xs:simpleType>
  </xs:element>

</xs:schema>
Schema with simple types

以下是一些合法的元素实例:

Example 8
<!-- Example instance elements -->
<age>45</age>
<height>5.9</height>
<displacement>-450</displacement>
<color>Blue</color>
Message fragment corresponding to the schema in Example 7

无论简单值类型是在“XML Schema Part 2: Datatypes”规范[11]中定义,还是基于XML Schema规范所提供的类型定义机制,都必须被编码为元素的内容。

如果一个简单值被编码为一个独立元素或一个异构数组的元素,这就很方便有一个对应于数据类型的元素声明。因为“XML Schema Part 2: Datatypes”规范[11]中包含了类型定义,但没有包含对应元素的声明,而enc模式和命名空间为每个简单数据类型声明了一个元素。这些是可以被使用的。

Example 9
<enc:int xmlns:enc="http://www.w3.org/2001/06/soap-encoding" id="int1">45</enc:int>

5.2.1 字符串

“string”数据类型在“XML Schema Part 2: Datatypes”[11]中被定义。值得注意的是在许多数据库或编程语言中,“string”类型并不是一致的,在某些特别的语言中,可能只允许一些字符能出现在“string”中。(这些值可能需要表示为xsd:string之外的一些数据类型)

一个字串可以被编码为一个单引用或多引用值。

包含string值的元素可以有一个“id”属性。额外的存取标识元素可以有匹配它的“href”属性。

例如,如果有两个对同一string的存取标识出现,则可以表现为:

Example 10
<greeting id="String-0">Hello</greeting>
<salutation href="#String-0"/>
Two accessors for the same string

无论如何,事实上对一个string(或者是string的子类型)的实例加以两个引用与将他们编码成两个单引用值并没有本质的区别:

Example 11
<greeting>Hello</greeting>
<salutation>Hello</salutation>
Two accessors for the same string

对于这些例子的模式描述可能是:

Example 12
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:enc="http://www.w3.org/2001/06/soap-encoding" >

  <xs:import namespace="http://www.w3.org/2001/06/soap-encoding" />

  <xs:element name="greeting" type="enc:string" />
  <xs:element name="salutation" type="enc:string" />

</xs:schema>
Schema for Example 11

(在这个例子中,用于描述元素类型的enc:string类型是一个方便的方法,来描述一个元素的类型是“xsd:string”,并且它可以附带“id” 和“href”属性。可以参阅SOAP Encoding模式来得到确切的定义。模式也可以使用这些SOAP Encoding模式中的声明,但不是必须的。)

5.2.2 枚举

“XML Schema Part 2: Datatypes”规范[11]定义了一种称为“玫举(enumeration)”的机制。SOAP数据模型直接采用了这个机制。可是,由于编程语言及其他语言在定义玫举上存在着一些细微的差别,因此我们在这里描述了更详细的概念,并描述了如何将一个成为玫举列表成员的值进行编码。具体的,它编码为该值的名。

在概念上,“玫举”表示了一组不同的名。一个具体的玫举是一个符合基本类型的不同值的具体列表。例如,颜色名(“Green”, “Blue”, “Brown”)的集合可以被定义为一个基于内置string类型的玫举, 值(“1”, “3”, “5”)则可能是一个基于integer的玫举,等等。“XML Schema Part 2: Datatypes”规范[11]支持除boolean外所有简单类型的玫举。“XML Schema Part 2: Structures”规范[10]语言可以用于定义玫举类型。如果一个模式是从另一种符号体系生成过来而没有具体的基本类型可应用,那么就使用“string”。在下面的模式例子“EyeColor”被定义为一个string的玫举,其可能的值包括“Green”、“Blue”、“Brown”,同时实例数据也对应地给出了。

Example 13
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                   xmlns:tns="http://example.org/2001/06/samples"
                   targetNamespace="http://example.org/2001/06/samples" >

  <xs:element name="EyeColor" type="tns:EyeColor" />
  <xs:simpleType name="EyeColor" >
    <xs:restriction base="xs:string" >
      <xs:enumeration value="Green" />
      <xs:enumeration value="Blue" />
      <xs:enumeration value="Brown" />
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
Schema with enumeration

 

Example 14
<p:EyeColor xmlns:p="http://example.org/2001/06/samples" >Brown</p:EyeColor>
Message fragment corresponding to the schema in Example 13

5.2.3 字节数组

一个Byte数组可以编码为单引用或多引用值。Byte数组的编码规则与string是类似的。

特别的,包含Byte数组值的元素可以有一个“id”属性。额外的存取标识元素可以有一个用于匹配的“href”属性。

对一个不透明的Byte数组的推荐表示是使用在XML Schema规范[10][11]中定义的“base64”编码方式,具体编码算法是在RFC 2045[13]中定义。不过,MIME中base64编码数据的数据行长度限制在SOAP中将不存在。SOAP中应使用“enc:base64”子类型来定义base64编码。

Example 15
<picture xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
         xsi:type="enc:base64" >
   aG93IG5vDyBicm73biBjb3cNCg==
</picture>
Image with base64 encoding

5.3 多态存取标识

许多语言允许存取标识可以多态地访问数个类型的值,在运行时刻每个类型都是可使用的。一个多态存取标识实例必须包含一个“xsi:type”属性以描述类型的实际值。

例如,一个名为“cost”带有类型为“xsd:float”的值的多态存取标识可以编码为:

Example 16
<cost xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
          xsi:type="xs:float">29.95</cost>
Polymorphic accessor

与之相对的是一个值类型不变的cost存取标识。

Example 17
<cost>29.95</cost>
Accessor whose value type is invariant

5.4 复合类型

SOAP依照在程序语言中常常看见的以下结构模式来定义复合类型:

Struct

“struct”是一个复合类型值,其成员的存取标识名是相互区别的唯一标志,应彼此各不相同。

Array

“array”是一个复合类型值,其成员的顺序位置是相互区别的唯一标志。

SOAP也允许数据的编序即不是Struct也不是Array,例如在Directed-Labeled-Graph数据模型中单个数据结点有很多不同的存取标识,其中有些会出现多次。SOAP遍序并不需要下层的数据模型要区别存取标识的次序区别,但如果有这种次序存在的话,那么存取标识必须按照该次序编码。

5.4.1 复合值及对值的引用

复合值的成员被编码为存取标识元素。存取标识由他们的名字来相区别(例如在struct里面),而元素名就是存取标识名。存取标识名是局部的,作用域是包含他们的类型中,具备一个未修饰的元素名,而其他则有完全修饰名。

下面是一个“Book”结构的例子:

Example 18
<e:Book xmlns:e="http://example.org/2001/06/books" >
   <author>Henry Ford</author>
   <preface>Prefactory text</preface>
   <intro>This is a book.</intro>
</e:Book>
Book structure

下面则是一个描述该结构的模式片段:

Example 19
<xs:element name="Book"
            xmlns:xs='http://www.w3.org/2001/XMLSchema' >
  <xs:complexType>
    <xs:sequence>
      <xs:element name="author" type="xs:string" />
      <xs:element name="preface" type="xs:string" />
      <xs:element name="intro" type="xs:string" />
    </xs:sequence>
  </xs:complexType>
</xs:element>
Schema for Example 18

下面是一个即包含简单类型成员也包含复合类型成员的类型的例子。它显示了两层的引用。注意“Author”存取标识元素的“href”属性一个对匹配“id”值对应的值的引用。“Address”中的情况也是类似的。

Example 20
<e:Book xmlns:e="http://example.org/2001/06/books" >
  <title>My Life and Work</title>
  <author href="#Person-1"/>
</e:Book>
<e:Person xmlns:e="http://example.org/2001/06/books" 
          id="Person-1" >
  <name>Henry Ford</name>
  <address href="#Address-2"/>
</e:Person>
<e:Address xmlns:e="http://example.org/2001/06/books" 
           id="Address-2" >
  <email>mailto:henryford@hotmail.com</email>
  <web>http://www.henryford.com</web>
</e:Address>
Book with muli-reference addresses

当“Person”和“Address”的值是需要多引用的时候,上述描述是合适的。如果使用单引用来描述,则应该是嵌入的,如下:

Example 21
<e:Book xmlns:e="http://example.org/2001/06/books" >
   <title>My Life and Work</title>
   <author>
       <name>Henry Ford</name>
       <address>
          <email>mailto:henryford@hotmail.com</email>
          <web>http://www.henryford.com</web>
       </address>
   </author>
</e:Book>
Book with single-reference addresses

如果这里存在着一个限制:在一个给出的实例中不允许有两个人有同样的地址,地址可以是一个街道地址(Street-address),也可以是一个电子地址(Electronic-address)。一本有两个作者的书可以编码为:

Example 22
<e:Book xmlns:e="http://example.org/2001/06/books" >
   <title>My Life and Work</title>
   <firstauthor href="#Person-1"/>
   <secondauthor href="#Person-2"/>
</e:Book>
<e:Person xmlns:e="http://example.org/2001/06/books" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          id="Person-1" >
   <name>Henry Ford</name>
   <address xsi:type="e:ElectronicAddressType">
       <email>mailto:henryford@hotmail.com</email>
       <web>http://www.henryford.com</web>
   </address>
</e:Person>
<e:Person xmlns:e="http://example.org/2001/06/books"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          id="Person-2">
   <name>Samuel Crowther</name>
   <address xsi:type="e:StreetAddressType">
       <street>Martin Luther King Rd</street>
       <city>Raleigh</city>
       <state>North Carolina</state>
   </address>
</e:Person>
Book with two authors having different addresses

编序也可以包含一些不在同一资源中的值的引用:

Example 23
<e:Book xmlns:e="http://example.org/2001/06/books" >
   <title>Paradise Lost</title>
   <firstAuthor href="http://www.dartmouth.edu/~milton/" />
</e:Book>
Book with external references

同时下面是一个对上面结构的模式描述片段:

Example 24
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:tns="http://example.org/2001/06/books"
                   targetNamespace="http://example.org/2001/06/books" >

  <xs:element name="Book" type="tns:BookType" />
  <xs:complexType name="BookType" >
    <xs:annotation>
          <xs:documentation>
            <info>
        Either the following group must occur or else the
        href attribute must appear, but not both.
                </info>
          </xs:documentation>
    </xs:annotation>
    <xs:sequence minOccurs="0" maxOccurs="1" >
      <xs:element name="title" type="xs:string" />
      <xs:element name="firstAuthor" type="tns:PersonType" />
      <xs:element name="secondAuthor" type="tns:PersonType" />
    </xs:sequence>
    <xs:attribute name="href" type="xs:anyURI" />
    <xs:attribute name="id" type="xs:ID" />
    <xs:anyAttribute namespace="##other" />
  </xs:complexType>

  <xs:element name="Person" type="tns:PersonType" />
  <xs:complexType name="PersonType" >
    <xs:annotation>
          <xs:documentation>
            <info>
        Either the following group must occur or else the
        href attribute must appear, but not both.
                </info>
          </xs:documentation>
        </xs:annotation>
    <xs:sequence minOccurs="0" maxOccurs="1" >
      <xs:element name="name" type="xs:string" />
      <xs:element name="address" type="tns:AddressType" />
    </xs:sequence>
    <xs:attribute name="href" type="xs:anyURI" />
    <xs:attribute name="id" type="xs:ID" />
    <xs:anyAttribute namespace="##other" />
  </xs:complexType>

  <xs:element name="Address" base="tns:AddressType" />
  <xs:complexType name="AddressType" abstract="true" >
    <xs:annotation>
          <xs:documentation>
            <info>
        Either one of the following sequences must occur or 
                else the href attribute must appear, but not both.
                </info>
          </xs:documentation>
        </xs:annotation>
    <xs:choice>
          <xs:sequence minOccurs="0" maxOccurs="1" >
            <xs:element name="email" type="xs:string" />
                <xs:element name="web" type="xs:anyURI" />
          </xs:sequence>
          <xs:sequence minOccurs='0' maxOccurs='1' >
        <xs:element name="street" type="xs:string" />
        <xs:element name="city" type="xs:string" />
        <xs:element name="state" type="xs:string"/>
          </xs:sequence>
        </xs:choice>
    <xs:attribute name="href" type="xs:anyURI"/>
    <xs:attribute name="id" type="xs:ID"/>
    <xs:anyAttribute namespace="##other"/>        
  </xs:complexType>

  <xs:complexType name="StreetAddressType">
    <xs:annotation>
          <xs:documentation>
            <info>
        Either the second sequence in the following group 
                must occur or else the href attribute must appear, 
                but not both.
                </info>
          </xs:documentation>
        </xs:annotation>
        <xs:complexContent>
          <xs:restriction base="tns:AddressType" >
            <xs:sequence>
              <xs:sequence minOccurs="0" maxOccurs="0" >
                <xs:element name="email" type="xs:string" />
                    <xs:element name="web" type="xs:anyURI" />
              </xs:sequence>
          <xs:sequence minOccurs="0" maxOccurs="1">
            <xs:element name="street" type="xs:string" />
            <xs:element name="city" type="xs:string" />
            <xs:element name="state" type="xs:string"/>
          </xs:sequence>
                </xs:sequence>
        <xs:attribute name="href" type="xs:anyURI"/>
        <xs:attribute name="id" type="xs:ID"/>
        <xs:anyAttribute namespace="##other"/>
          </xs:restriction>
        </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="ElectronicAddressType">
    <xs:annotation>
          <xs:documentation>
            <info>
        Either the first sequence in the following group 
                must occur or else the href attribute must appear, 
                but not both.
                </info>
          </xs:documentation>
        </xs:annotation>
        <xs:complexContent>
          <xs:restriction base="tns:AddressType" >
            <xs:sequence>
          <xs:sequence minOccurs="0" maxOccurs="1">
            <xs:element name="email" type="xs:string" />
            <xs:element name="web" type="xs:anyURI" />
          </xs:sequence>
                  <xs:sequence minOccurs="0" maxOccurs="0">
            <xs:element name="street" type="xs:string" />
            <xs:element name="city" type="xs:string" />
            <xs:element name="state" type="xs:string"/>
          </xs:sequence>
                </xs:sequence>
            <xs:attribute name="href" type="xs:anyURI"/>
        <xs:attribute name="id" type="xs:ID"/>
        <xs:anyAttribute namespace="##other"/>
          </xs:restriction>
        </xs:complexContent>
  </xs:complexType>

</xs:schema>
Schema for example 22

5.4.2 数组

SOAP数组被定义为类型为“enc:Array”或类型源于“enc:Array”(可参阅 rule 8)。这种类型源于"enc:Array"的类型必须遵从"enc:Array"的限制,同时它可用于表示以下情况的类型定义,譬如整型数的数组或是一些用户自定义的枚举类型的数组等。数组被表示为对包含其的元素的名无特殊约束的元素值(就象值一般不会约束包含元素的名)。组成数组的元素可以是任意类型,包括嵌套的数组。

数组值的表示是一个该数组组成元素的一个有序序列。作为一个数组的值,元素名对于区分存取标识并非重要。元素可以有任意的名。实际上,这些元素的命名将按照模式中声明的建议,或由他们的类型所决定。就象在复合类型中通常情况下,如果数组中条目的值是单引用值,则该条目将包含它的值。否则,条目通过“href”属性引用它的值。

下面是一个模式的片段以及一个包含integer成员的数组:

Example 25
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           xmlns:enc="http://www.w3.org/2001/06/soap-encoding" >
  <xs:import namespace="http://www.w3.org/2001/06/soap-encoding" />
  <xs:element name="myFavoriteNumbers" type="enc:Array" />
</xs:schema>
Schema declaring an array of integers

 

Example 26
<myFavoriteNumbers xmlns:xs="http://www.w3.org/2001/XMLSchema"
                   xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
                   enc:arrayType="xs:int[2]" >
  <number>3</number>
  <number>4</number>
</myFavoriteNumbers>
Array conforming to the schema in Example 25

在这个例子中,“myFavoriteNumber”数组包含了几个成员,每个成员的值的类型都是xs:int。而类型是由enc:arrayType属性决定的。注意enc:Array的类型允许不严格的未修饰的元素名。这些名只传输了非类型的信息,因此在具体使用的时候,要么有一个xsi:type属性,要么包含它的元素要包含一个enc:arrayType属性。自然地,源于enc:Array的类型可以声明带类型信息的局部元素。

就象先前指出的,enc模式包含了一些元素名的声明,而这些名是对应于“XML Schema Part 2: Datatypes”规范[11]中的每个简单类型的。这也包含一个“Array”的声明。使用这些定义,我们也许可以将显现先前的描述改写为:

Example 27
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           enc:ArrayType="xs:int[2]" >
  <enc:int>3</enc:int>
  <enc:int>4</enc:int>
</enc:Array>
Using the enc:Array element

数组可以包含任意指定arrayType的子类型的实例。也就是说,成员的类型可以是任何描述在arrayType属性中类型的可替代类型,这将依照于在模式中表示的可替代规则。因此,例如,一个整数数组可以包含任何源于integer的类型的值(例如 “int”或任何用户定义的源于integer的类型)。类似的,一个“address”数组可以包含一个严格的或扩展的类型,比如“internationalAddress”。因为提供的enc:Array类型允许包含任何类型或类型混合的成员,除非有对arrayType属性使用的特别限制。

成员元素类型在实例中可以使用xsi:type来描述,或则是在成员元素模式中声明,就象在下面两个数组中分别演示的那样:

Example 28
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           enc:arrayType="xs:anyType[4]">
   <thing xsi:type="xs:int">12345</thing>
   <thing xsi:type="xs:decimal">6.789</thing>
   <thing xsi:type="xs:string">
      Of Mans First Disobedience, and the Fruit
      Of that Forbidden Tree, whose mortal tast
      Brought Death into the World, and all our woe,
   </thing>
   <thing xsi:type="xs:anyURI">
      http://www.dartmouth.edu/~milton/reading_room/
   </thing>
</enc:Array>
Array with elements of varying types

 

Example 29
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           xmlns:enc="http://www.w3.org/2001/06/soap-encoding"
           enc:arrayType="xs:anyType[4]" >
   <enc:int>12345</enc:int>
   <enc:decimal>6.789</enc:decimal>
   <enc:string>
      Of Mans First Disobedience, and the Fruit
      Of that Forbidden Tree, whose mortal tast
      Brought Death into the World, and all our woe,
   </enc:string>
   <enc:anyURI>
      http://www.dartmouth.edu/~milton/reading_room/
   </enc:anyURI >
</enc:Array>
Array with elements of varying types

数组值可以是结构或其他复合值。例如一个“xyz:Order”结构的数组:

Example 30
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding"
           xmlns:xyz="http://example.org/2001/06/Orders" 
           enc:arrayType="xyz:Order[2]">
   <Order>
       <Product>Apple</Product>
       <Price>1.56</Price>
   </Order>
   <Order>
       <Product>Peach</Product>
       <Price>1.48</Price>
   </Order>
</enc:Array>
Arrays containing structs and other compound values

数组也可以有一些成员值是数组。下面是一个有两个数组的数组的例子,而那两个数组都是string数组:

Example 31
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
           enc:arrayType="xs:string[][2]" >
   <item href="#array-1"/>
   <item href="#array-2"/>
</enc:Array>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
           id="array-1" 
           enc:arrayType="xs:string[2]">
   <item>r1c1</item>
   <item>r1c2</item>
   <item>r1c3</item>
</enc:Array>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
           id="array-2" 
           enc:arrayType="xs:string[2]">
   <item>r2c1</item>
   <item>r2c2</item>
</enc:Array>
Array containing other arrays

包含一个数组值的元素并不需要一定被命名为“enc:Array”。它可以有任意的名,而提供的类型则要么是enc:Array,要么是受源于enc:Array的限制。例如,下面是一个模式片段以及与之一致的一个实例数组:

Example 32
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
           xmlns:tns="http://example.org/2001/06/numbers" 
           targetNamespace="http://example.org/2001/06/numbers" >

  <xs:simpleType name="phoneNumberType" >
    <xs:restriction base="xs:string" />
  </xs:simpleType>

  <xs:element name="ArrayOfPhoneNumbers" type="tns:ArrayOfPhoneNumbersType" />

  <xs:complexType name="ArrayOfPhoneNumbersType" >
    <xs:complexContent>
      <xs:restriction base="enc:Array" >
            <xs:sequence>
          <xs:element name="phoneNumber" type="tns:phoneNumberType" maxOccurs="unbounded" />
            </xs:sequence>
        <xs:attributeGroup ref="enc:arrayAttributes" />
        <xs:attributeGroup ref="enc:commonAttributes" />
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

</xs:schema>
Schema for an array

 

Example 33
<abc:ArrayOfPhoneNumbers xmlns:abc="http://example.org/2001/06/numbers"
                         xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
                         enc:arrayType="abc:phoneNumberType[2]" >
   <phoneNumber>206-555-1212</phoneNumber>
   <phoneNumber>1-888-123-4567</phoneNumber>
</abc:ArrayOfPhoneNumbers>
Array conforming to the schema in Example 32

数组可以是多维的。在这种情况下,就会有多个描述维数大小的值出现在arrayType属性的asize部分:

Example 34
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:enc="http://www.w3.org/2001/06/soap-encoding"  
           enc:arrayType="xs:string[2,3]" >
   <item>r1c1</item>
   <item>r1c2</item>
   <item>r1c3</item>
   <item>r2c1</item>
   <item>r2c2</item>
   <item>r2c3</item>
</enc:Array>
Multi-dimensonal array

上述例子中显示了一个数组如何被编码为独立元素,数组值可以以嵌套方式出现并且如果他们是单引用的话,应该使用这种方式。

下面是一个模式片段的例子以及符合该模式的一个嵌套在“Person”结构中的电话号码数组,该数组可以从存取标识“phone-numbers”访问:

Example 34
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:enc="http://www.w3.org/2001/06/soap-encoding"
           xmlns:tns="http://example.org/2001/06/numbers"
                   targetNamespace="http://example.org/2001/06/numbers" >

  <xs:import namespace="http://www.w3.org/2001/06/soap-encoding" />

  <xs:simpleType name="phoneNumberType" >
    <xs:restriction base="xs:string" />
  </xs:simpleType>


  <xs:element name="ArrayOfPhoneNumbers" type="tns:ArrayOfPhoneNumbersType" />

  <xs:complexType name="ArrayOfPhoneNumbersType" >
    <xs:complexContent>
      <xs:restriction base="enc:Array" >
            <xs:sequence>
          <xs:element name="phoneNumber" type="tns:phoneNumberType" maxOccurs="unbounded" />
            </xs:sequence>
        <xs:attributeGroup ref="enc:arrayAttributes" />
        <xs:attributeGroup ref="enc:commonAttributes" />
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <xs:element name="Person">
    <xs:complexType>
          <xs:sequence>
        <xs:element name="name" type="xs:string" />
        <xs:element name="phoneNumbers" type="tns:ArrayOfPhoneNumbersType" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>
Schema fragment for array of phone numbers embedded in a struct

 

Example 35
<def:Person xmlns:def="http://example.org/2001/06/numbers" 
            xmlns:enc="http://www.w3.org/2001/06/soap-encoding" >
   <name>John Hancock</name>
   <phoneNumbers enc:arrayType="def:phoneNumber[2]">
       <phoneNumber>206-555-1212</phoneNumber>
       <phoneNumber>1-888-123-4567</phoneNumber>
   </phoneNumbers>
</def:Person>
Array of phone numbers embedded in a struct conforming to the schema in Example 34

下面是单引用数组值的另一个例子,数组值被编码为嵌入元素,这些元素都包含作为存取标识的元素名:

Example 36
<xyz:PurchaseOrder xmlns:xyz="http://example.org/2001/06/Orders" >
   <CustomerName>Henry Ford</CustomerName>
   <ShipTo>
       <Street>5th Ave</Street>
       <City>New York</City>
       <State>NY</State>
       <Zip>10010</Zip>
   </ShipTo>
   <PurchaseLineItems xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
                      enc:arrayType="xyz:Order[2]">
       <Order>
           <Product>Apple</Product>
           <Price>1.56</Price>
       </Order>
       <Order>
           <Product>Peach</Product>
           <Price>1.48</Price>
       </Order>
   </PurchaseLineItems>
</xyz:PurchaseOrder>
Single-reference array encoded as en embedded element
5.4.2.1 部分传输数组

SOAP提供对部分传递数组的支持,这就象在一些上下文[12]中的“可变长”数组。一个部分传递数组应使用“enc:offset”属性标识,该属性的记数是以第一元素的位移为0开始的。如果省略该属性,则位移默认是0。

下面是一个大小为5的数组,同时在传递的时候仅传递第三和第四个元素:

Example 37
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           enc:arrayType="xs:string[6]"
           enc:offset="[3]" >
  <item>The fourth element</item>
  <item>The fifth element</item>
</enc:Array>
Array of size five that transmits only the third and fourth element
5.4.2.2 稀疏数组

SOAP提供对稀疏数组的支持。每一个表示成员值的元素包含一个“enc:position”属性来表明它处于数组的位置。下面是一个二维字串数组的稀疏数组的例子。他的大小是4,但仅有位置2被使用:

Example 38
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding" 
           xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           enc:arrayType="xs:string[,][4]" >
   <enc:Array href="#array-1" enc:position="[2]" />
</enc:Array>
<enc:Array id="array-1" 
           enc:arrayType="xs:string[10,10]" >
   <item enc:position="[2,2]">Third row, third col</item>
   <item enc:position="[7,2]">Eighth row, third col</item>
</enc:Array>
Sparse array

如果在上述数组中对array-1仅有一个引用,那上述例子可以被编码为:

Example 39
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           enc:arrayType="xs:string[,][4]" >
  <enc:Array enc:position="[2]" enc:arrayType="xs:string[10,10]" >
    <item enc:position="[2,2]">Third row, third col</item>
    <item enc:position="[7,2]">Eighth row, third col</item>
  </enc:Array>
</enc:Array>
Another sparse array

5.4.3 通用复合类型

上面引用到的编码规则并不限于那些预先知道存取标识的情形。如果存取标识名仅当在编码过程中由值的出现才能决定的时候,同样的规则也可以应用,也就是一个存取标识被编码为同名的元素,并且该存取标识要么包含要么引用它的值。包含那些类型不能预先决定的值的存取标识必须包含一个合适的xsi:type属性来给出值的类型。

类似的,引用的规则对于包含一些混合的存取标识的复合类型的编序而言已经足够了,这些存取标识有的是以名来区分,有的是以名和位置来区分 (也就是说,有些存取标识会重复出现) 。这并不一定需要有包含这一类型的模式存在,但是如果一个类型模型模式没有该类型时,那么一个对应的XML句法模式和实例就应该被生成。

Example 40
<xyz:PurchaseOrder xmlns:xyz="http://example.org/2001/06/Orders" >
  <CustomerName>Henry Ford</CustomerName>
  <ShipTo>
    <Street>5th Ave</Street>
    <City>New York</City>
    <State>NY</State>
    <Zip>10010</Zip>
  </ShipTo>
  <PurchaseLineItems>
    <Order>
      <Product>Apple</Product>
      <Price>1.56</Price>
    </Order>
    <Order>
      <Product>Peach</Product>
      <Price>1.48</Price>
    </Order>
  </PurchaseLineItems>
</xyz:PurchaseOrder>
Generic compound types

类似的,将一个复合类型值编序为类似数组结构的是合法的,但这不是enc:Array类型或其子类型。例如:

Example 41
<PurchaseLineItems>
    <Order>
        <Product>Apple</Product>
        <Price>1.56</Price>
    </Order>
    <Order>
        <Product>Peach</Product>
        <Price>1.48</Price>
    </Order>
</PurchaseLineItems>
Compound value

5.5 默认值

一个省略格式的存取标识元素以为着有一个默认值或是尚不知道它的值。而该细节是基于存取标识、方法和上下文的。例如一个省略格式的存取标识典型地是表示一个多态存取标识的Null值(Null依赖存取标识的确切含义)。同样地,一个省略格式的Boolean存取标识典型地就意味着是一个False值或值未知,同时一个省略格式的数值存取标识典型地意味着它的值是0或值未知。

5.6 SOAP root属性

SOAP root属性可以被用来标注编序的根,当然他并不是对象图真正的根,所以对象图是可以解序的。该属性可以赋予“0”和“1”这两个值的任意一个。一个对象图的真正的根一般就有值“1”。那些非真正根的编序根也可以被标注为赋予值为“1”的编序根。一个元素也可以被明确地标注为赋予值为“0”的非编序根。

SOAP根属性可以出现在SOAP Header和SOAP Body元素中的任何子元素里,该属性并没有一个默认值。

6. 在HTTP中使用SOAP

本节描述了如何在使用或不使用HTTP Extension Framework的前提下将SOAP与HTTP的协同工作机制。将SOAP绑定在HTTP上可以利用HTTP丰富的特性集,提供使用SOAP形式方法和分布适应性的优点。将SOAP在HTTP上传输并不以为着SOAP可以完全超越HTTP的语义,更恰当的描述应当是SOAP的语义通过HTTP的映射而很自然地成为HTTP的语义。

SOAP很自然地利用HTTP的请求/响应消息模型,将SOAP请求的参数放在HTTP请求里,而将SOAP响应的参数放在HTTP响应里面。注意,无论如何,SOAP的中间介与HTTP中间介是不同的。也就是说,根据HTTP Connection头字段来寻址的HTTP中间介一般并不能来处理HTTP请求中的SOAP实体体。

当需要将SOAP消息体包含在HTTP消息中时,HTTP应用程序必须依照RFC2376[3]使用媒体类型“text/xml”。

6.1 SOAP HTTP请求

虽然SOAP可以和多种HTTP请求方法联合使用,但这里的绑定只定义了SOAP是如何在HTTP Post请求中传输的。(可参阅section 7了解如何在RPC中使用SOAP,以及section 6.3如何使用HTTP Extension Framework)

6.1.1 HTTP Header中的SOAPAction字段

SOAPAction HTTP请求头字段(header field)可以用于指示SOAP HTTP请求的目的。它的值是一个标识该目的的URI。SOAP对于格式上并没有严格的限制,同时对URI的描述以及是否要是可解析的都没有严格的限制。当发出SOAP HTTP请求时,HTTP客户必须使用该头字段。

soapaction  =  "SOAPAction" ":" [ <"> URI-reference <"> ]
URI-reference  =  <as defined in RFC 2396 [4]>

SOAPAction头字段的存在及其内容可以被服务器例如防火墙用于在HTTP中过滤SOAP请求消息。当该字段的值为空字符串( “”)时,则意味着SOAP消息的目的由HTTP Request-URI来提供。而如果没有值则表示对消息的目的没有指示。

例如:

Example 42
SOAPAction: "http://electrocommerce.org/abc#MyMessage"
SOAPAction: "myapp.sdl"
SOAPAction: ""
SOAPAction:
Examples of values for SOAPAction

6.2 SOAP HTTP响应

在HTTP之上的SOAP遵从用于在HTTP中表示通讯状态的HTTP状态代码的语义。例如,2xx状态代码表明这是客户端包含SOAP构件的请求被成功的接收、理解和接受等等。

当处理请求的时候发生SOAP错误的时候,SOAP HTTP服务器必须发出一个HTTP 500 “Internal Server Error”响应同时在包含于该响应的SOAP消息中应包含一个SOAP Fault元素(参阅 section 4.4)来指明SOAP处理的错误。

6.3 HTTP扩展框架

SOAP消息可以与HTTP Extension Framework[6]一起使用来标识SOAP HTTP请求的出现和意图。

是使用Extension Framework还是使用简单HTTP对于通讯各方而言是一个策略及能力的问题。客户端可以通过一个强制扩展声明以及一个“M-”HTTP方法名前缀来强制使用HTTP Extension Framwork。服务器端可以通过使用 510 “Not Extended” HTTP状态代码来强制使用HTTP Extension Framework。也就是说,通过一次额外的环游,每个通讯方都可以检测到其他通讯方和因此的动作。

用于使用Extension Framework标识SOAP的扩展标识是:

http://www.w3.org/2001/06/soap-envelope

6.4 SOAP HTTP示例

Example 43
POST /StockQuote HTTP/1.1
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://electrocommerce.org/abc#MyMessage"

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>
SOAP HTTP Request Using POST

 

Example 44
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>
SOAP HTTP Response to Example 43

 

Example 45
M-POST /StockQuote HTTP/1.1
Man: "http://www.w3.org/2001/06/soap-envelope"; ns=NNNN
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
NNNN-SOAPAction: "http://electrocommerce.org/abc#MyMessage"

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>
SOAP HTTP Request using the experimental HTTP Extension Framework

 

Example 46
HTTP/1.1 200 OK
Ext:
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>
SOAP HTTP Response to Example 45

7. 在RPC中使用SOAP

SOAP的一个设计目标就是要利用XML的可扩展性和可伸缩性来包装和交换RPC调用。本节定义了一个统一的远程过程调用和响应的表示。

其实我们也可以预想到在RPC环境下的表示很可能是与在其他表示中定义的编码风格结合。SOAP encodingStyle属性(参阅 section 4.3.2)可以被用于指明在本节表示中使用的方法调用/响应的编码风格。

在RPC中使用SOAP与SOAP协议绑定(参阅 section 6)基本是正交的。在使用HTTP作为SOAP协议绑定媒介的情况下,一个RPC调用可以很自然地映射到一个HTTP请求,而RPC响应则可以映射到HTTP响应。无论如何,使用SOAP方式的RPC并不限于HTTP协议绑定。

为实施一个方法调用,需要以下信息:

 SOAP依赖协议绑定来提供传送URI的机制。例如,对HTTP而言,请求URI指明了与该调用相对应的资源。除要求该URI是合法的以外,SOAP对于该地址没有任何限制(参阅[4]以获得URI的更多信息)。

7.1 RPC和SOAP Body

RPC调用和响应都是在SOAP Body元素(参阅 section 4.3)中传送,使用如下表示方式:

就象先前表述的那样,方法和响应的结构可以使用在section 5中定义的规则来编码,也可以使用在encodingStyle属性中描述的其他编码(参阅 section 4.1.1)。

应用程序可以处理漏写参数的请求不过也可以返回一个错误。

因为在响应中若包含“result”则表明成功,若包含“fault”则表明失败,所以如果方法响应中同时包含了“result”和“fault”则是错误的。

7.2 RPC和SOAP Header

对于那些并非是方法的正式调用数据部分,而是方法请求编码相关的一些额外信息,也可以在RPC编码中表示。如果这样,它必须作为SOAP Header元素的一个子元素来描述。

对于使用header元素的一个例子是在消息中传送一个事务ID。事务ID并不是调用参数表中的一员,它一般是要被下层构件所处理而不仅仅是一个应用程序ID,而这里并没有一个直接的方法在调用中传送这一需要的信息。通过在头上加一个条目并赋予它一个固定的名字,接收方的事务管理器就可以将该事务ID抽取出来,同时就可以在不影响远程过程调用的代码的前提下使用它。

8. 安全机制的考虑

在本文档中并不包含完整性和私密性保护的方法的描述。这些问题将在本文档的以后版本中详细说明。

9. 参考文献

9.1. Normative references

[2] IETF "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt

[3] IETF "RFC 2376: XML Media Types", E. Whitehead, M. Murata, July 1998. Available at http://www.ietf.org/rfc/rfc2376.txt

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

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

[6] IETF "RFC 2774: An HTTP Extension Framework", H. Nielsen, P. Leach, S. Lawrence, February 2000. Available at http://www.ietf.org/rfc/rfc2774.txt

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

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

[9] W3C Proposed Recommendation "XML Linking Language (XLink) Version 1.0", Steve DeRose, Eve Maler, David Orchard, 20 December 2000. Available at http://www.w3.org/TR/2000/PR-xlink-20001220/

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

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

9.2. Informative references

[12] Transfer Syntax NDR, in Open Group Technical Standard "DCE 1.1: Remote Procedure Call", August 1997. Available at http://www.opengroup.org/public/pubs/catalog/c706.htm

[13] IETF "RFC2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", N. Freed, N. Borenstein, November 1996. Available at http://www.ietf.org/rfc/rfc2045.txt

A. SOAP Envelope Examples

A.1 Sample Encoding of Call Requests

Example 47
POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://example.org/2001/06/quotes"

<env:Envelope
  xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
   <env:Header>
       <t:Transaction
           xmlns:t="http://example.org/2001/06/tx"
           env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
           env:mustUnderstand="1" >
               5
       </t:Transaction>
   </env:Header>
   <env:Body >
       <m:GetLastTradePrice 
             env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
             xmlns:m="http://example.org/2001/06/quotes" >
           <m:symbol>DEF</m:symbol>
       </m:GetLastTradePrice>
   </env:Body>
</env:Envelope>
Similar to Example 1 but with a Mandatory Header

 

Example 48
POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://example.org/2001/06/quotes"

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
   <env:Body>
       <m:GetLastTradePriceDetailed 
             env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
             xmlns:m="http://example.org/2001/06/quotes" >
           <Symbol>DEF</Symbol>
           <Company>DEF Corp</Company>
           <Price>34.1</Price>
       </m:GetLastTradePriceDetailed>
   </env:Body>
</env:Envelope>
Similar to Example 1 but with multiple request parameters

A.2 Sample Encoding of Response

Example 49
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
   <env:Header>
       <t:Transaction xmlns:t="http://example.org/2001/06/tx"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xmlns:xs="http://www.w3.org/2001/XMLSchema"
                      xsi:type="xs:int" 
                      env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
                      env:mustUnderstand="1" >
           5
       </t:Transaction>
   </env:Header>
   <env:Body>
       <m:GetLastTradePriceResponse 
             env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
             xmlns:m="http://example.org/2001/06/quotes" >
           <Price>34.5</Price>
       </m:GetLastTradePriceResponse>
   </env:Body>
</env:Envelope>
Similar to Example 2 but with a Mandatory Header

 

Example 50
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
   <env:Body>
       <m:GetLastTradePriceResponse 
             env:encodingStyle="http://www.w3.org/2001/06/soap-encoding"
             xmlns:m="http://example.org/2001/06/quotes" >
           <PriceAndVolume>
               <LastTradePrice>34.5</LastTradePrice>
               <DayVolume>10000</DayVolume>
           </PriceAndVolume>
       </m:GetLastTradePriceResponse>
   </env:Body>
</env:Envelope>
Similar to Example 2 but with a Struct

 

Example 51
HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope">
   <env:Body>
       <env:Fault>
           <faultcode>env:MustUnderstand</faultcode>
           <faultstring>SOAP Must Understand Error</faultstring>
       </env:Fault>
   </env:Body>
</env:Envelope>
Similar to Example 2 but Failing to honor Mandatory Header

 

Example 52
HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
  <env:Body>
    <env:Fault>
      <faultcode>env:Server</faultcode>
      <faultstring>Server Error</faultstring>
      <detail>
        <e:myfaultdetails xmlns:e="http://example.org/2001/06/faults" >
          <message>My application didn't work</message>
          <errorcode>1001</errorcode>
        </e:myfaultdetails>
      </detail>
    </env:Fault>
 </env:Body>
</env:Envelope>
Similar to Example 2 but Failing to handle Body

B. Acknowledgements

This document is the work of the W3C XML Protocol Working Group.

Members of the Working Group are (at the time of writing, and by alphabetical order): Yasser al Safadi (Philips Research), Vidur Apparao (Netscape), Don Box (DevelopMentor), David Burdett (Commerce One), Charles Campbell (Informix Software), Alex Ceponkus (Bowstreet), Michael Champion (Software AG), David Clay (Oracle), Ugo Corda (Xerox), Paul Cotton (Microsoft Corporation), Ron Daniel (Interwoven), Glen Daniels (Allaire), Doug Davis (IBM), Ray Denenberg (Library of Congress), Paul Denning (MITRE Corporation), Frank DeRose (TIBCO Software, Inc.), Brian Eisenberg (Data Channel), David Ezell (Hewlett-Packard), James Falek (TIBCO Software, Inc.), David Fallside (IBM), Chris Ferris (Sun Microsystems), Daniela Florescu (Propel), Dan Frantz (BEA Systems), Dietmar Gaertner (Software AG), Scott Golubock (Epicentric), Rich Greenfield (Library of Congress), Martin Gudgin (Develop Mentor), Hugo Haas (W3C), Marc Hadley (Sun Microsystems), Mark Hale (Interwoven), Randy Hall (Intel), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), Yin-Leng Husband (Compaq), John Ibbotson (IBM), Ryuji Inoue (Matsushita Electric Industrial Co., Ltd.), Scott Isaacson (Novell, Inc.), Kazunori Iwasa (Fujitsu Software Corporation), Murali Janakiraman (Rogue Wave), Mario Jeckle (Daimler-Chrysler Research and Technology), Eric Jenkins (Engenia Software), Mark Jones (AT&T), Jay Kasi (Commerce One), Jeffrey Kay (Engenia Software), Richard Koo (Vitria Technology Inc.), Jacek Kopecky (IDOOX s.r.o.), Alan Kropp (Epicentric), Yves Lafon (W3C), Tony Lee (Vitria Technology Inc.), Michah Lerner (AT&T), Richard Martin (Active Data Exchange), Noah Mendelsohn (Lotus Development), Nilo Mitra (Ericsson Research Canada), Jean-Jacques Moreau (Canon), Masahiko Narita (Fujitsu Software Corporation), Mark Needleman (Data Research Associates), Eric Newcomer (IONA Technologies), Henrik Frystyk Nielsen (Microsoft Corporation), Mark Nottingham (Akamai Technologies), David Orchard (JamCracker), Kevin Perkins (Compaq), Jags Ramnaryan (BEA Systems), Andreas Riegg (Daimler-Chrysler Research and Technology), Hervé Ruellan (Canon), Marwan Sabbouh (MITRE Corporation), Shane Sesta (Active Data Exchange), Miroslav Simek (IDOOX s.r.o.), Simeon Simeonov (Allaire), Nick Smilonich (Unisys), Soumitro Tagore (Informix Software), James Tauber (Bowstreet), Lynne Thompson (Unisys), Patrick Thompson (Rogue Wave), Randy Waldrop (WebMethods), Ray Whitmer (Netscape), Volker Wiechers (SAP AG), Stuart Williams (Hewlett-Packard), Amr Yassin (Philips Research) and Dick Brooks (Group 8760). Previous members were: Eric Fedok (Active Data Exchange) Susan Yee (Active Data Exchange) Alex Milowski (Lexica), Bill Anderson (Xerox), Ed Mooney (Sun Microsystems), Mary Holstege (Calico Commerce), Rekha Nagarajan (Calico Commerce), John Evdemon (XML Solutions), Kevin Mitchell (XML Solutions), Yan Xu (DataChannel) Mike Dierken (DataChannel) Julian Kumar (Epicentric) Miles Chaston (Epicentric) Bjoern Heckel (Epicentric) Dean Moses (Epicentric) Michael Freeman (Engenia Software) Jim Hughes (Fujitsu Software Corporation) Francisco Cubera (IBM), Murray Maloney (Commerce One), Krishna Sankar (Cisco), Steve Hole (MessagingDirect Ltd.) John-Paul Sicotte (MessagingDirect Ltd.) Vilhelm Rosenqvist (NCR) Lew Shannon (NCR) Henry Lowe (OMG) Jim Trezzo (Oracle) Peter Lecuyer (Progress Software) Andrew Eisenberg (Progress Software) David Cleary (Progress Software) George Scott (Tradia Inc.) Erin Hoffman (Tradia Inc.) Conleth O'Connell (Vignette) Waqar Sadiq (Vitria Technology Inc.) Tom Breuel (Xerox) David Webber (XMLGlobal Technologies) Matthew MacKenzie (XMLGlobal Technologies) and Mark Baker (Sun Microsystems).

This document is based on the SOAP/1.1 specification whose authors were: Don Box (Develop Mentor), David Ehnebuske (IBM), Gopal Kakivaya (Microsoft Corp.), Andrew Layman (Microsoft Corp.) Noah Mendelsohn (Lotus Development Corp.), Henrik Frystyk Nielsen (Microsoft Corp.), Satish Thatte (Microsoft Corp.) and Dave Winer (UserLand Software, Inc.).

We also wish to thank all the people who have contributed to discussions on xml-dist-app@w3.org.

C. Version Transition From SOAP/1.1 to SOAP Version 1.2

EdNote: The scope of the mechanism provided in this section is for transition between SOAP/1.1 and SOAP version 1.2. The Working Group is considering providing a more general transition mechanism that can apply to any version.  Such a general mechanism may or may not be the mechanism provided here depending on whether it is deemed applicable.

The SOAP/1.1 specification says the following on versioning in section 4.1.2:

"SOAP does not define a traditional versioning model based on major and minor version numbers. A SOAP message MUST have an Envelope element associated with the "http://schemas.xmlsoap.org/soap/envelope/" namespace. If a message is received by a SOAP application in which the SOAP Envelope element is associated with a different namespace, the application MUST treat this as a version error and discard the message. If the message is received through a request/response protocol such as HTTP, the application MUST respond with a SOAP VersionMismatch faultcode message (see section 4.4) using the SOAP "http://schemas.xmlsoap.org/soap/envelope/" namespace."

That is, rather than a versioning model based on shortnames (typically version numbers), SOAP uses a declarative extension model which allows a sender to include the desired features within the SOAP envelope construct. SOAP says nothing about the granularity of extensions nor how extensions may or may not affect the basic SOAP processing model. It is entirely up to extension designers be it either in a central or a decentralized manner to determine which features become SOAP extensions.

The SOAP extensibility model is based on the following four basic assumptions:

  1. SOAP versioning is directed only at the SOAP envelope. It explicitly does not address versioning of blocks, encodings, protocol bindings, or otherwise.
  2. A SOAP node must determine whether it supports the version of a SOAP message on a per message basis. In the following, "support" means understanding the semantics of the envelope version identified by the QName of the Envelope element:
  3. It is essential that the envelope remains stable over time and that new features are added using the SOAP extensibility mechanism. Changing the envelope inherently affects interoperability, adds complexity, and requires central control of extensions -- all of which directly conflicts with the SOAP requirements.
  4. No versioning model or extensibility model can prevent buggy implementations. Even though significant work has been going into clarifying the SOAP processing model, there is no guarantee that a SOAP 1.2 implementation will behave correctly. Only extensive testing within the SOAP community and design simplicity at the core can help prevent/catch bugs.

The rules for dealing with the possible SOAP/1.1 and SOAP Version 1.2 interactions are as follows:

  1. Because of the SOAP/1.1 rules, a compliant SOAP/1.1 node receiving a SOAP Version 1.2 message will generate a VersionMismatch SOAP fault using an envelope qualified by the "http://schemas.xmlsoap.org/soap/envelope/" namespace identifier.
  2. A SOAP Version 1.2 node receiving a SOAP/1.1 message may either process the message as SOAP/1.1 or generate a SOAP VersionMismatch fault using the "http://schemas.xmlsoap.org/soap/envelope/" namespace identifier. As part of the SOAP VersionMismatch fault, a SOAP Version 1.2 node should include the list of envelope versions that it supports using the SOAP upgrade extension identified by the "http://www.w3.org/2001/06/soap-upgrade" identifier.

The upgrade extension contains an ordered list of namespace identifiers of SOAP envelopes that the SOAP node supports in the order most to least preferred. Following is an example of a VersionMismatch fault generated by a SOAP Version 1.2 node including the SOAP upgrade extension:

Example 53
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Header>
    <V:Upgrade xmlns:V="http://www.w3.org/2001/06/soap-upgrade">
      <envelope qname="ns1:Envelope" xmlns:ns1="http://www.w3.org/2001/06/soap-envelope"/>
    </V:Upgrade>
  </env:Header>
  <env:Body>
    <env:Fault>
      <faultcode>env:VersionMismatch</faultcode>
      <faultstring>Version Mismatch</faultstring>
    </env:Fault>
  </env:Body>
</env:Envelope> 
VersionMismatch fault generated by a SOAP Version 1.2 node, and including a SOAP upgrade extension

Note that existing SOAP/1.1 nodes are not likely to indicate which envelope versions they support. If nothing is indicated then this means that SOAP/1.1 is the only supported envelope.

D. Change Log

D.1 SOAP Specification Changes

Date Author Description
20010629 MJG Amended description of routing and intermediaries in Section 2.1
20010629 JJM Changed "latest version" URI to end with soap12 
20010629 JJM Remove "previous version" URI
20010629 JJM Removed "Editor copy" in <title>
20010629 JJM Removed "Editor copy" in the title.
20010629 JJM Added "Previous version" to either point to SOAP/1.1, or explicitly mention there was no prior draft.
20010629 JJM Pre-filed publication URIs.
20010629 JJM Incorporated David's suggested changes for the examples in section 4.1.1 to 4.4.2
20010629 JJM Fixed some remaining typos.
20010629 MJH Fixed a couple of typos.
20010628 MJG Made various formatting, spelling and grammatical fixes.
20010628 MJG Moved soap:encodingStyle from soap:Envelope to children of soap:Header/soap:Body in examples 1, 2, 47, 48, 49 and 50
20010628 MJG Changed text in Section 2.1 from 'it is both a SOAP sender or a SOAP receiver' to 'it is both a SOAP sender and a SOAP receiver'
20010628 MJG Fixed caption on Example 24
20010628 MJH Fixed a couple of capitalisation errors where the letter A appeared as a capital in the middle of a sentence.
20010628 MJH Updated figure 1, removed ednote to do so.
20010622 HFN Removed the introductory text in terminology section 1.4.3 as it talks about model stuff that is covered in section 2. It was left over from original glossary which also explained the SOAP model.
20010622 HFN Moved the definition of block to encapsulation section in terminology
20010622 HFN Removed introductory section in 1.4.1 as this overlaps with the model description in section 2 and doesn't belong in a terminology section
20010622 HFN Removed reference to "Web Characterization Terminology & Definitions Sheet" in terminology section as this is not an active WD
20010622 HFN Added revised glossary
20010622 HFN Added example 0 to section 1.3 and slightly modified text for example 1 and 2 to make it clear that HTTP is used as a protocol binding
20010622 MJG Added http://example.com/... to list of application/context specific URIs in section 1.2
20010622 MJG Updated examples in section 4.1.1 to be encodingStyle attributes rather than just the values of attributes
20010622 MJG Added table.norm, td.normitem and td.normtext styles to stylesheet. Used said styles for table of fault code values in section 4.4.1
20010622 MJG In Appendix C, changed upgrade element to Upgrade and env to envelope. Made envelope unqualified. Updated schema document to match.
20010622 MJG Moved MisunderstoodHeader from envelope schema into seperate faults schema. Removed entry in envelope schema change table in Appendix D.2 that refered to additon of said element. Modified example in section 4.4.2 to match. Added reference to schema document to section 4.4.2
20010622 MJH Added binding as a component of SOAP in introduction. Fixed a couple of typos and updated a couple of example captions.
20010622 MJG Made BNF in section 6.1.1 into a table.
20010622 MJG Made BNFs in section 5.1 clause 8 into tables. Added associated 'bnf' style for table and td elements to stylesheet
20010622 MJG Amended text regarding namespace prefix mappings in section 1.2
20010622 MJG Added link to schema for the http://www.w3.org/2001/06/soap-upgrade namespace to Appendix C. Updated associated ednote.
20010622 MJG Added reference numbers for XML Schema Recommendation to text prior to schema change tables in Appendix D.2 and linked said numbers to local references in this document
20010622 MJG Reordered entries in schema change classification table in Appendix D.2
20010622 MJG Changed type of mustUnderstand and root attributes to standard boolean and updated schema change tables in Appendix D.2 accordingly
20010622 JJM Manually numbered all the examples (53 in total!)
20010622 JJM Added caption text to all the examples
20010622 JJM Replaced remaining occurrences of SOAP/1.2 with SOAP Version 1.2 (including <title>)
20010621 HFN Added ednote to section 4.2.2 and 4.2.3 that we know they have to be incorporated with section 2
20010621 HFN Added version transition appendix C
20010621 HFN Applied new styles to examples
20010621 HFN Changed term "transport" to "underlying protocol
20010621 HFN Changed example URNs to URLs of the style http://example.org/...
20010621 MJH Updated the Acknowledgements section.
20010621 JJM Added new style sheet definitions (from XML Schema) for examples, and used them for example 1 and 2.
20010621 JJM Incorporated David Fallside's comments on section Status and Intro sections.
20010620 HFN Changed the status section
20010620 HFN Changed title to SOAP Version 1.2 and used that first time in abstract and in body
20010620 HFN Removed question from section 2.4 as this is an issue and is to be listed in the issues list
20010620 HFN Moved change log to appendix
20010615 JJM Renamed default actor to anonymous actor for now (to be consistent)
20010615 JJM Fixed typos in section 2
20010614 JJM Updated section 2 to adopt the terminology used elsewhere in the spec.
20010613 MJH Updated mustUnderstand fault text with additions from Martin Gudgin.
20010613 MJH Added schema changes appendix from Martin Gudgin.
20010613 MJH Added mustUnderstand fault text from Glen Daniels.
20010612 MJH Fixed document <title>.
20010612 MJH Moved terminology subsection from message exchange model section to introduction section.
20010612 MJH Fixed capitalisation errors by replacing "... A SOAP ..." with "... a SOAP ..." where appropriate.
20010612 MJH Removed trailing "/" from encoding namespace URI.
20010612 MJH Fixed links under namespace URIs to point to W3C space instead of schemas.xmlsoap.org.
20010612 MJH Removed some odd additional links with text of "/" pointing to the encoding schema following the text of the encoding namespace URI in several places.
20010611 MJH Incorporated new text for section 2.
20010611 JJM Changed remaining namespaces, in particular next.
20010609 JJM Changed the spec name from XMLP/SOAP to SOAP.
20010609 JJM Changed the version number from 1.1 to 1.2.
20010609 JJM Changed the namespaces from http://schemas.xmlsoap.org/soap/ to http://www.w3.org/2001/06/soap-.
20010609 JJM Replaced the remaining XS and XE prefixes to env and enc, respectively.
20010601 MJH Updated the examples in section 1, 6 and appendix A with text suggested by Martin Gudgin to comply with XML Schema Recommendation.
20010601 JJM Updated the examples in section 4 and 5 with text suggested by Martin Gudgin, to comply with XML Schema Recommendation.
20010531 HFN Removed appendices C and D and added links to live issues list and separate schema files.
20010531 MJH Added this change log and updated schemas in appendix C to comply with XML Schema Recommendation.

D.2 XML Schema Changes

The envelope and encoding schemas have been updated to be compliant with the XML Schema Recomendation[10,11]. The table below shows the categories of change.

Class Meaning
Addition New constructs have been added to the schema
Clarification The meaning of the schema has been changed to more accurately match the specification
Deletion Constructs have been removed from the schema
Name The schema has been changed due to a datatype name change in the XML Schema specification
Namespace A namespace name has been changed
Semantic The meaning of the schema has been changed
Style Style changes have been made to the schema
Syntax The syntax of the schema has been updated due to changes in the XML Schema specification

The table below lists the changes to the envelope schema.

Class Description
Namespace Updated to use the http://www.w3.org/2001/XMLSchema namespace
Namespace Value of targetNamespace attribute changed to http://www.w3.org/2001/06/soap-envelope
Clarification Changed element and attribute wildcards in Envelope complex type to namespace="##other"
Clarification Changed element and attribute wildcards in Header complex type to namespace="##other"
Clarification Added explicit namespace="##any" to element and attribute wildcards in Body complex type
Clarification Added explicit namespace="##any" to element and attribute wildcards in detail complex type
Clarification Added an element wildcard with namespace="##other" to the Fault complex type
Name Changed item type of encodingStyle from uri-reference to anyURI
Name Changed type of actor attribute from uri-reference to anyURI
Name Changed type of faultactor attribute from uri-reference to anyURI
Semantic Added processContents="lax" to all element and attribute wildcards
Semantic Changed type of the mustUnderstand attribute from restriction of boolean that only allowed 0 or 1 as lexical values to the standard boolean in the http://www.w3.org/2001/XMLSchema namespace. The lexical forms 0, 1, false, true are now allowed.
Style Where possible comments have been changed into annotations
Syntax Changed all occurences of maxOccurs="*" to maxOccurs="unbounded"
Syntax Added <xs:sequence> to all complex type definitions derived implicitly from the ur-type
Syntax Added <xs:sequence> to all named model group definitions

The table below lists the changes to the encoding schema.

Class Description
Namespace Updated to use the http://www.w3.org/2001/XMLSchema namespace
Namespace Value of targetNamespace attribute changed to http://www.w3.org/2001/06/soap-encoding
Semantic Changed type of the root attribute from restriction of boolean that only allowed 0 or 1 as lexical values to the standard boolean in the http://www.w3.org/2001/XMLSchema namespace. The lexical forms 0, 1, false, true are now allowed.
Addition Added processContents="lax" to all element and attribute wildcards
Syntax Changed base64 simple type to be a vacuous restriction of the base64Binary type in the http://www.w3.org/2001/XMLSchema namespace
Syntax Updated all complex type definitions with simple base types to new syntax
Syntax Added <xs:sequence> to all complex type definitions derived implicitly from the ur-type
Syntax Added <xs:sequence> to all named model group definitions
Deletion Removed the timeDuration datatype
Addition Added duration datatype derived by extension from the duration datatype in the http://www.w3.org/2001/XMLSchema namespace.
Deletion Removed the timeInstant datatype
Addition Added dateTime datatype derived by extension from the dateTime datatype in the http://www.w3.org/2001/XMLSchema namespace.
Addition Added gYearMonth datatype derived by extension from the gYearMonth datatype in the http://www.w3.org/2001/XMLSchema namespace.
Addition Added gYear datatype derived by extension from the gYear datatype in the http://www.w3.org/2001/XMLSchema namespace.
Addition Added gMonthDay datatype derived by extension from the gMonthDay datatype in the http://www.w3.org/2001/XMLSchema namespace.
Addition Added gDay datatype derived by extension from the gDay datatype in the http://www.w3.org/2001/XMLSchema namespace.
Addition Added gDay datatype derived by extension from the gDay datatype in the http://www.w3.org/2001/XMLSchema namespace.
Deletion Removed the binary datatype
Addition Added hexBinary datatype derived by extension from the hexBinary datatype in the http://www.w3.org/2001/XMLSchema namespace.
Addition Added base64Binary datatype derived by extension from the base64Binary datatype in the http://www.w3.org/2001/XMLSchema namespace.
Deletion Removed the uriReference datatype
Addition Added anyURI datatype derived by extension from the anyURI datatype in the http://www.w3.org/2001/XMLSchema namespace.
Addition Added normalizedString datatype derived by extension from the normalizedString datatype in the http://www.w3.org/2001/XMLSchema namespace.
Addition Added token datatype derived by extension from the token datatype in the http://www.w3.org/2001/XMLSchema namespace.
Clarification Added explicit namespace="##any" to all element and attribute wildcards which did not previously have an explicit namespace attribute
Style Where possible comments have been changed into annotations

In addition several changes occured in the names of datatypes in the XML Schema specification and some datatypes were removed. The following table lists those changes.

Datatype Class Description
timeDuration Renamed New name is duration
timeInstant Renamed New name is dateTime
recurringDuration Removed The recurringDuration datatype no longer exists.
recurringInstant Removed The recurringInstant datatype no longer exists.
binary Removed The binary datatype has been replaced by the hexBinary and base64Binary datatypes.
month Renamed New name is gYearMonth
timePeriod Removed The timePeriod datatype no longer exists
year Renamed New name is gYear
century Removed The century datatype no longer exists
recurringDate Renamed New name is gMonthDay
recurringDay Renamed New name is gDay


Last Modified: $Date: 2001/07/09 13:39:15 $ UTC