SOAP 规范（3）

5.4.1 复合值，结构和值引用
复合值的成员编码为accessor元素。当accessor由名区分时（如结构），accessor名即作为元素名。名局部于类型的accessor有不受限的名，其他的accessor则有受限的名。

下面的例子是类型为"book"的结构：

<e:book>
   <author>henry ford</author>
   <preface>prefatory text</preface>
   <intro>this is a book.</intro>
</e:book>

以下是描述上面结构的schema片断：

<element name="book">
<complextype>
  <element name="author" type="xsd:string"/>
  <element name="preface" type="xsd:string"/>
   <element name="intro" type="xsd:string"/>
</complextype>
</e:book>
<e:book>
   <title>my life and work</title>
   <author href="#person-1"/>
</e:book>
<e:person id="person-1">
   <name>henry ford</name>
   <address href="#address-2"/>
</e:person>
<e:address id="address-2">
   <email>mailto:[e-mail]</email>
   <web>http://www.henryford.com</web>
</e:address>

当"person"的值和"address"的值是multi-reference时，上面的形式是正确的。如果他们是single-reference，就必须用嵌入的形式，如下所示：

<e:book>
   <title>my life and work</title>
   <author>
       <name>henry ford</name>
       <address>
      <email>mailto:[e-mail]</email>
      <web>http://www.henryford.com</web>
       </address>
   </author>
</e:book>
如果添加一个限制，任意两个人都不会有相同的地址，并且地址能是街道或email地址，一本书能有两个作者，编码如下：

<e:book>
   <title>my life and work</title>
   <firstauthor href="#person-1"/>
   <secondauthor href="#person-2"/>
</e:book>
<e:person id="person-1">
   <name>henry ford</name>
   <address xsi:type="m:electronic-address">
       <email>mailto:[e-mail]</email>
       <web>http://www.henryford.com</web>
   </address>
</e:person>
<e:person id="person-2">
   <name>samuel crowther</name>
   <address xsi:type="n:street-address">
       <street>martin luther king rd</street>
       <city>raleigh</city>
       <state>north carolina</state>
   </address>
</e:person>

序列化能包含对不在同一个资源的值的引用：

<e:book>
   <title>paradise lost</title>
   <firstauthor href="http://www.dartmouth.edu/~milton/"/>
</e:book>

以下是描述上面结构的schema片断：

<element name="book" type="tns:book"/>
<complextype name="book">
   <!-- either the following group must occur or else the
        href attribute must appear, but not both. -->
   <sequence minoccurs="0" maxoccurs="1">
       <element name="title" type="xsd:string"/>
       <element name="firstauthor" type="tns:person"/>
       <element name="secondauthor" type="tns:person"/>
   </sequence>
   <attribute name="href" type="urireference"/>
   <attribute name="id" type="id"/>
   <anyattribute namespace="##other"/>
</complextype>

<element name="person" base="tns:person"/>
<complextype name="person">
   <!-- either the following group must occur or else the
        href attribute must appear, but not both. -->
   <sequence minoccurs="0" maxoccurs="1">
       <element name="name" type="xsd:string"/>
       <element name="address" type="tns:address"/>
   </sequence>
   <attribute name="href" type="urireference"/>
   <attribute name="id" type="id"/>
   <anyattribute namespace="##other"/>
</complextype>

<element name="address" base="tns:address"/>
<complextype name="address">
   <!-- either the following group must occur or else the
        href attribute must appear, but not both. -->
   <sequence minoccurs="0" maxoccurs="1">
       <element name="street" type="xsd:string"/>
       <element name="city" type="xsd:string"/>
       <element name="state" type="xsd:string"/>
   </sequence>
   <attribute name="href" type="urireference"/>
   <attribute name="id" type="id"/>
   <anyattribute namespace="##other"/>
</complextype>
5.4.2 数组
soap数组定义为具有"soap-enc:array"类型或一个从"soap-enc:array"衍生的类型（参见规则8）。数组表示为元素值，对元素的名没有特别的约束（正如元素值并不约束他们所属的元素）。

数组能包含任意类型的元素，包括嵌套数组。能创建新的类型（受soap-enc:array类型限制）来表示数组，如整数数组或某些用户定义的枚举。

数组值表示为组成这个数组的项的元素的规则序列。在数组值中，元素名对于区分accesor并不重要。元素能有任意的名。实际上，元素常常用他们在schema中暗示或确定的数组类型来命名元素。并且一般情况下对于复合值来说，如果数组中数组项的值是single-reference值，则这个数组项包含他的值，否则，该数组项通过"href"属性引用这个值。

下面的例子是个整型数组的schema片断：

<element name="myfavoritenumbers"
        type="soap-enc:array"/>

<myfavoritenumbers
  soap-enc:arraytype="xsd:int[2]">
   <number>3</number>
   <number>4</number>
</myfavoritenumbers>

在这个例子中，数组"myfavoritenumbers"包括几个成员，每个成员是个类型为soap-enc:int的值。注意soap-enc:array允许不受限制的元素名，他们不传达所有类型信息，所以在使用时，或他们有xsi:type属性，或他们所属的元素有soap-enc:arraytype属性。自然，由soap-enc:array衍生的类型能声明局部元素，但这种情况下要包括类型信息。

上面已提到，soap-enc schema包含了元素的声明，元素名和"xml schema part 2: datatypes"规范[11]中的简单类型一致。其中包括了对"array"的声明。于是，我们能这样写：

<soap-enc:array soap-enc:arraytype="xsd:int[2]">
   <soap-enc:int>3</soap-enc:int>
   <soap-enc:int>4</soap-enc:int>
</soap-enc:array>

数组能包含特定arraytype的任意子类型的实例。即，数组成员能是arrytype属性值指定的类型的任意子类型，这个类型对于arraytype属性中指定的类型来说是可替换的（根据schema中的替换规则）。例如，一个整型数组能包含从整型衍生的任意类型（如"int"或任意用户定义的从整型衍生的类型）。同样，一个"address"数组可能包含一个address的受限类型或扩展类型如"internationaladdress"。因为提供的soap-enc:array类型允许任意类型的成员，所以能包含任意类型的混合除非使用arraytype属性加以特别的限制。

在实例中，能使用xsi:type指定成员元素的类型，或通过schema中成员元素的声明来指定。下面是两个例子。

<soap-enc:array soap-enc:arraytype="soap-enc:ur-type[4]">
   <thing xsi:type="xsd:int">12345</thing>
   <thing xsi:type="xsd:decimal">6.789</thing>
   <thing xsi:type="xsd: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="xsd:urireference">
      http://www.dartmouth.edu/~milton/reading_room/
   </thing>
</soap-enc:array>

<soap-enc:array soap-enc:arraytype="soap-enc:ur-type[4]">
   <soap-enc:int>12345</soap-enc:int>
   <soap-enc:decimal>6.789</soap-enc:decimal>
   <xsd:string>
      of mans first disobedience, and the fruit
      of that forbidden tree, whose mortal tast
      brought death into the world, and all our woe,
   </xsd:string>
   <soap-enc:urireference>
      http://www.dartmouth.edu/~milton/reading_room/
   </soap-enc:urireference >
</soap-enc:array>

数组值能是结构或其他复合值。例如"xyz:order"结构数组：

<soap-enc:array soap-enc:arraytype="xyz:order[2]">
   <order>
       <product>apple</product>
       <price>1.56</price>
   </order>
   <order>
       <product>peach</product>
       <price>1.48</price>
   </order>
</soap-enc:array>

数组成员值也能是数组。下例是两个字符串数组组成的数组：

<soap-enc:array soap-enc:arraytype="xsd:string[][2]">
   <item href="#array-1"/>
   <item href="#array-2"/>
</soap-enc:array>
<soap-enc:array id="array-1" soap-enc:arraytype="xsd:string[2]">
   <item>r1c1</item>
   <item>r1c2</item>
   <item>r1c3</item>
</soap-enc:array>
<soap-enc:array id="array-2" soap-enc:arraytype="xsd:string[2]">
   <item>r2c1</item>
   <item>r2c2</item>
</soap-enc:array>

包含数组的元素无需命名为"soap-enc:array"。他能有任意的名，只要元素的类型是soap-enc:array或由之衍生的类型。例如，下面是个schema片断和和之一致的数组实例。

<simpletype name="phonenumber" base="string"/>

<element name="arrayofphonenumbers">
  <complextype base="soap-enc:array">
    <element name="phonenumber" type="tns:phonenumber" maxoccurs="unbounded"/>
  </complextype>
  <anyattribute/>
</element>

<xyz:arrayofphonenumbers soap-enc:arraytype="xyz:phonenumber[2]">
   <phonenumber>206-555-1212</phonenumber>
   <phonenumber>1-888-123-4567</phonenumber>
</xyz:arrayofphonenumbers>

数组可能是多维的。在这种情况下，在arraytype属性的asize部分将不止有一个值：

<soap-enc:array soap-enc:arraytype="xsd:string[2,3]">
   <item>r1c1</item>
   <item>r1c2</item>
   <item>r1c3</item>
   <item>r2c1</item>
   <item>r2c2</item>
   <item>r2c3</item>
</soap-enc:array>

虽然上面的例子把数组编码为独立的元素，但元素值也能是嵌入形式，而且若元素值是single reference时，必须编码为嵌入形式。
下例是个schema片断，电话号码数组嵌入到一个类型为"person"的结构中，并且通过accessor "phone-numbers"访问他：

<simpletype name="phonenumber" base="string"/>

<element name="arrayofphonenumbers">
  <complextype base="soap-enc:array">
    <element name="phonenumber" type="tns:phonenumber" maxoccurs="unbounded"/>
  </complextype>
  <anyattribute/>
</element>

<element name="person">
  <complextype>
    <element name="name" type="string"/>
    <element name="phonenumbers" type="tns:arrayofphonenumbers"/>
  </complextype>
</element>

<xyz:person>
   <name>john hancock</name>
   <phonenumbers soap-enc:arraytype="xyz:phonenumber[2]">
       <phonenumber>206-555-1212</phonenumber>
       <phonenumber>1-888-123-4567</phonenumber>
   </phonenumbers>
</xyz:person>

下面的例子中，数组值为single-reference，被编码为嵌入元素，包含他的元素名即为入口名：

<xyz:purchaseorder>
   <customername>henry ford</customername>
   <shipto>
       <street>5th ave</street>
       <city>new york</city>
       <state>ny</state>
       <zip>10010</zip>
   </shipto>
   <purchaselineitems soap-enc:arraytype="order[2]">
       <order>
           <product>apple</product>
           <price>1.56</price>
       </order>
       <order>
           <product>peach</product>
           <price>1.48</price>
       </order>
   </purchaselineitems>
</xyz:purchaseorder>

5.4.2.1 部分储值（partially transmitted）数组
soap提供了对部分储值（partially transmitted）数组的支持，如某些上下文中的可变数组。一个partially transmitted 数组由一个"soap-enc:offset"属性（从第一个transmitted的元素开始的偏移量，基于0）指示。如果省略，偏移量取0。

下面的例子中数组的大小为5，但只有从0起，第三和第四个元素被储值。

<soap-enc:array ;soap-enc:arraytype="xsd:string[5]" ;soap-enc:offset="[2]">
  <item>the third element</item>   
  <item>the fourth element</item>
</soap-enc:array>

5.4.2.2 稀疏数组sparse arrays
soap提供了对稀疏数组的支持。每个表示成员值的元素包含一个"soap-enc:position"属性，用来指示他在数组中的位置。下例是两维字符串稀疏数组的例子，数组大小是4，但只用到第2个。

<soap-enc:array soap-enc:arraytype="xsd:string[,][4]">
   <soap-enc:array href="#array-1" soap-enc:position="[2]"/>
</soap-enc:array>
<soap-enc:array id="array-1" soap-enc:arraytype="xsd:string[10,10]">
   <item soap-enc:position="[2,2]">third row, third col</item>
   <item soap-enc:position="[7,2]">eighth row, third col</item>
</soap-enc:array>

如果对array-1的引用仅发生在数组内部，上例也能编码如下：

<soap-enc:array soap-enc:arraytype="xsd:string[,][4]">
  <soap-enc:array soap-enc:position="[2]" soap-enc:arraytype="xsd:string[10,10]>
    <item soap-enc:position="[2,2]">third row, third col</item>
    <item soap-enc:position="[7,2]">eighth row, third col</item>
  </soap-enc:array>
</soap-enc:array>

5.4.3 一般复合类型
在这里提到的编码规则不仅仅限于accessor名已知的情况，如果accessor名是运行环境下实时获得的，编码规则同样适用，也就是说accessor编码成一个元素名和accessor名匹配的元素，同时accessor可能包含或引用该元素的值。如果accessor包含类型不能事先确定的值，他必须包含一个合适的属性xsi:type 。
类似地，上述引用的规则已足够用于复合类型的序列化，这些复合类型可能包含用名区分的accessors（结构）和用名及序数位置区分的accessors。（可能包含重复的accessor）实际上这并不需求所有schema模式包含这些类型，但更为准确的说法是：一个类型模型（type-model）schema如果有这些类型，就能构造一个符合xml句法规则的schema和xml文件实例。

　

<xyz:purchaseorder>
   <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>

类似地，将一个结构上类似数组但实际上不是个 soap-enc:array类型或 soap-enc:array子类型的复合值序列化同样是允许的，例如：

<purchaselineitems>
    <order>
        <product>apple</product>
        <price>1.56</price>
    </order>
    <order>
        <product>peach</product>
        <price>1.48</price>
    </order>
</purchaselineitems>

5.5 缺省值
省略accessor元素意味着或有一个缺省值或值不知道。具体细节依靠这个accessor，方法和上下文。例如，对于多态accessor，省略accessor一般意味着一个null值。同样，省略布尔accessor一般意味着false值或值不知道，省略数字accessor一般意味着值为零或值不知道。

5.6 soap root属性
soap root 属性可用于标记一个序列化root，从而一个对象能反序列化（deserialized），而实际上该root并不是真正的对象root。这个属性有两个可选值"1" or "0"。对象真正的roots属性值为“1” ，序列化root但不是真正的root属性值也为“1”，元素如果要显式地指定不能为序列化root，只需将该属性设置为“0” soap root属性能出目前soap头和soap体元素的任意子元素中。（译者注：soap root属性为0的元素不是个独立的实体，外部的应用不能访问到该元素，但该元素能被soap文件本身的其他元素访问到）

soap root属性能出目前soap头和soap体元素的任意子元素中。这个属性没有缺省值。

6. 在http中使用soap
这一节讲述了怎么在http中使用soap。把soap绑定到http，无论使用或不用http扩展框架，都有非常大的好处：在利用soap的形式化和灵活性的同时，使用http种种丰富的特性。在http中携带soap消息，并不意味着soap改写了http已有的语义，而是将构建在http之上soap语义自然地对应到http语义。

soap自然地遵循http的请求/应答消息模型使得soap的请求和应答参数能包含在http请求和应答中。注意，soap的中间节点和http的中间节点并不等同，即，不要期望一个根据http连接头中的域寻址到的http中间节点能够检查或处理http请求中的soap消息。

在http消息中包含soap实体时，按照rfc2376[3] http应用程式必须使用媒体类型 "text/xml"。

6.1 soap http请求
虽然soap可能和各种http请求方式相结合，不过绑定仅定义了在http post请求中包含soap消息。（第7节中描述了怎么在rpc中使用soap，第6.3节描述了怎么使用http扩展框架）

6.1.1 http头中soapaction域
一个http请求头中的soapaction域用来指出这是个soap http请求，他的值是所要的uri。在格式、uri的特性和可解析性上没有所有限制。当http客户发出soap http请求时必须使用在http头中使用这个域。

soapaction    = "soapaction" ":" [ <"> uri-reference <"> ]
uri-reference = <as defined in rfc 2396 [4]>

http头中soapaction域使服务器（如防火墙）能正确的过滤http中soap请求消息。如果这个域的值是空字符串（""），表示soap消息的目标就是http请求的uri。这个域没有值表示没有soap消息的目标的信息。

例子:

soapaction: "http://electrocommerce.org/abc#mymessage"
soapaction: "myapp.sdl"
soapaction: ""
soapaction:

6.2 soap http应答
soap http遵循http 中表示通信状态信息的http状态码的语义。例如，2xx状态码表示这个包含了soap组件的客户请求已被成功的收到，理解和接受。

在处理请求时如果发生错误，soap http服务器必须发出应答http 500 "internal server error"，并在这个应答中包含一个soap fault元素（见4.4节）表示这个soap处理错误。

6.3 http扩展框架
一个soap消息能和http扩展框架 [6]一起使用以区分是否有soap http请求和他的目标。

是使用扩展框架或是普通的http关系到通信各方的策略和能力。通过使用一个必需的扩展声明和"m-"http方法名前缀，客户能强制使用http扩展框架。服务器能使用http状态码510 "not extended"强制使用http扩展框架。也就是说，使用一个额外的来回，所有一方都能发现另一方的策略并依照执行。

用来表示soap使用了扩展框架的扩展标志符是：

http://schemas.xmlsoap.org/soap/envelope/
6.4 soap http举例
例3 使用post的soap http

post /stockquote http/1.1
content-type: text/xml; charset="utf-8"
content-length: nnnn
soapaction: "http://electrocommerce.org/abc#mymessage"

<soap-env:envelope...

http/1.1 200 ok
content-type: text/xml; charset="utf-8"
content-length: nnnn

<soap-env:envelope...

例4 使用扩展框架的soap http

m-post /stockquote http/1.1
man: "http://schemas.xmlsoap.org/soap/envelope/"; ns=nnnn
content-type: text/xml; charset="utf-8"
content-length: nnnn
nnnn-soapaction: "http://electrocommerce.org/abc#mymessage"

<soap-env:envelope...

http/1.1 200 ok
ext:
content-type: text/xml; charset="utf-8"
content-length: nnnn

<soap-env:envelope...

7. 在rpc中使用soap
设计soap的目的之一就是利用xml的扩展性和灵活性来封装和交换rpc调用。这一节定义了远程过程调用和应答的统一表示形式。

虽然能预计到这种表示形式最可能被用于和第5节中定义的编码方式相结合，但也可能有其他的表示形式。soap的encodingstyle属性（见4.3.2节）能用来表明方法调用和应答都使用这一节所指定的表示方式。

在rpc中使用soap和soap协议绑定（见第6节）是紧密相关的。在使用http作为绑定协议时，一个rpc调用自然地映射到一个http请求，rpc应答同样映射到http应答。不过，在rpc中使用soap并不限于绑定http协议。

要进行方法调用，以下的信息是必需的：

目标对象的uri
方法名
方法signature（可选）
方法的参数
头数据（可选）
soap依靠协议绑定提供传送uri的机制。例如，对http来说，请求的uri指出了调用的来源。除了必须是个合法的uri之外，soap对一个地址的格式没有所有限制。（更多uri的信息参见 [4]）

7.1 rpc和soap体
rpc方法调用和应答都包含在soap body元素中（见4.3节），他们使用如下的表示形式：

一个方法调用用一个结构表示
一个方法调用被看作一个单个的结构，每个[in]和[in/out]参数有一个accessor。结构的名和类型和方法相同。
每个[in]和[in/out]参数都被看作一个accessor，这个accessor的名和类型和参数的名和类型相对应。他们的出现顺序和方法中定义的参数顺序相同。
一个方法应答用一个结构表示。
一个方法应答被看作一个单个的结构，返回值和每个[in]和[in/out]参数有一个accessor。第一个accessor是返回值，之后是参数accessor，参数accessor的出现顺序和方法中定义的参数顺序相同。
每个参数accessor的名称和类型和参数的名称和类型相对应。返回值accessor的名称并不重要。同样，结构的名称也不重要，不过，通常在方法名称的后面加上字符串"response"作为结构的名称。
方法错误使用soap fault元素（见4.4节）表示。如果绑定的协议有额外的规则表示错误，则这些规则也必须要遵从。
正如上面所述，方法调用和应答结构能按照第5节中规则编码，或用encodingstyle属性（见4.1.1节）指定编码方式。

应用程式能处理缺少参数的请求，不过可能返回一个错误。

因为返回结果表示调用成功，错误表示调用失败，所以，在方法应答中同时包含返回结果和错误是错误的。

7.2 rpc和soap头
在rpc编码中，可能会有和方法请求有关但不是正规的方法signature的附加信息。如果这样，他必须作为soap头元素的子元素。

使用这种头元素的一个例子是在消息中传递事务id。由于事务id不是方法signature的一部分，通常由底层的组件而不是应用程式代码控制，所以没有一种直接的方法在调用中传递这个必要的信息。通过在头中添加一个给定名字的条目，接收方的事务管理器就能析取这