soap协议规范.htm

internet协议集

      mustUnderstand 属性考虑了消息演变的准确性（robust evolution）。必须假定包含SOAP 
      mustUnderstand属性且值为"1"的元素以某种方式修改了它们的父元素或同层元素的语义。以这种方式连接元素确保了语义上的变化不会被那些不能完全理解它的接收者忽略。如果这个属性要生效，它必须出现在SOAP消息实例中。（见第3节和4.2.1节）</P>
      <H4>4.3 SOAP体</H4>
      <P>SOAP体元素提供了一个简单的机制，使消息的最终接收者能交换必要的信息。使用体元素的典型情况包括配置RPC请求和错误报告。体元素编码为SOAP封装元素的直接子元素。如果已经有一个头元素，那么体元素必须紧跟在头元素之后，否则它必须是SOAP封装元素的第一个直接子元素。体元素的所有直接子元素称作体条目，每个体条目在SOAP体元素中编码为一个独立的元素。条目的编码规则如下：
      <UL>
        <LI>一个条目由它的元素全名（包括名域URI和局部名）确定。SOAP体元素的直接子元素可能是名域限制的。 
        <LI>SOAP encodingStyle属性可能用来指示条目（见4.1.1节）的编码方式。 
        <LI>SOAP定义了一个Fault条目用来报告错误信息。（见4.4节） </LI></UL>
      <H4>4.3.1 SOAP头和体的关系</H4>
      <P>虽然头和体定义为独立的元素，它们实际上是有关系的。体条目和头条目的关系如下：体条目在语义上等同于actor属性为缺省值且mustUnderstand属性值为"1"的头条目。不使用actor属性则表示缺省的actor。（见4.2.2节）</P>
      <H4>4.4 SOAP错误</H4>
      <P>SOAP错误元素用于在SOAP消息中携带错误和（或）状态信息。如果有SOAP错误元素，它必须以以体条目的方式出现，并且在一个体元素中最多出现一次。SOAP错误元素定义了以下四个子元素：
      <UL>
        <LI>faultcode<BR>faultcode元素给软件提供了一个识别此错误的算法机制。SOAP错误元素必须有faultcode子元素，并且它的值必须是一个合法的名（在[8]节定义）。SOAP定义一些SOAP 
        faultcode描述基本的SOAP错误（见4.4.1节）。 
        <LI>faultstring<BR>faultstring元素提供了一个错误解释，而不是为了软件处理。faultstring元素类似于HTTP中定义(见[5]，第6.1节）的'Reason-Phrase'。SOAP错误元素必须有faultstring子元素，并且它应该提供一些错误本质的解释信息。 

        <LI>faultactor<BR>faultactor元素提供了在消息路径上是谁导致了错误发生的信息（见第2节）。它类似于SOAP 
        actor属性（见4.2.2节），只是SOAP 
        actor指的是头条目的目的地，faultactor指的是错误的来源。faultactor属性的值是用来区分错误来源的URI。不是SOAP消息的最终目的地的应用程序必须在SOAP 
        Fault元素中包含faultactor元素。消息的最终目的地可以使用faultactor元素明确的指示是它产生了这个错误（参见下面的detail元素） 

        <LI>detail<BR>detail元素用来携带与Body元素有关的应用程序所要的错误信息。如果Body元素的内容不能被成功的处理，则必须包含detail子元素。它不能用来携带属于头条目的错误信息。头条目的详细出错信息必须由头条目携带。Fault元素中没有detail元素表示这个错误与Body元素的处理无关。在有错误的时候，这可以用来区分Body元素有没有被正确的处理。detail元素的所有直接子元素称作detail条目，并且每个detail条目在detail元素中编码为独立的元素。detail条目的编码规则如下（参见例10）： 
        一个detail条目由它的元素全名（包括名域URI和局部名）确定。SOAP体元素的直接子元素可能是名域限制的。SOAP 
        encodingStyle属性可能用来指示detail条目（见4.1.1节）的编码方式。也可以有其它的Fault子元素，只要它们是名域限制的。 
        </LI></UL>
      <H4>4.4.1 SOAP 错误代码</H4>
      <P>在描述这个规范中定义的错误时，这一节中定义的Faultcode值必须用在faultcode元素中。这些faultcode值得名域标志符为"http://schemas.xmlsoap.org/soap/envelope/"。定义这个规范之外的方法时推荐（不要求）使用这个名域。缺省的SOAP 
      faultcode值以可扩展的方式定义，允许定义新的SOAP 
      faultcode值，并与现有的faultcode值向后兼容。使用的机制类似于HTTP中定义的1xx, 
      2xx,3xx等基本的状态类（见[5]第10节），不过，它们定义为XML合法名（见 [8] 第3节 ），而不是整数。 
      字符"."（点）作为faultcode的分隔符，点左边的错误代码比右边的错误代码更为普通。如：</P>
      <P>Client.Authentication</P>
      <P>这篇文档中定义的faultcode值是：</P>
      <TABLE cellSpacing=0 cellPadding=0 width="100%" border=1>
        <TBODY>
        <TR>
          <TD width="23%">名称</TD>
          <TD width="77%">含义</TD></TR>
        <TR>
          <TD width="23%">VersionMismatch</TD>
          <TD width="77%">处理方发现SOAP封装元素有不合法的名域（见4.1.2节）</TD></TR>
        <TR>
          <TD width="23%">MustUnderstand</TD>
          <TD width="77%">处理方不理解或者不服从一个包含值为"1"的</TD></TR>
        <TR>
          <TD width="23%">mustUnderstand</TD>
          <TD width="77%">属性的 SOAP头元素的直接子元素。（见4.2.3节）</TD></TR></TBODY></TABLE>
      <P>Client</P>
      <P>Client错误类表示消息的格式错误或者不包含适当的正确信息。例如，消息可能缺少正确的认证和支付信息。一般地，它表示消息不能不作修改就重发。参见4.4节</P>
      <P>SOAP Fault detail子元素的描述。</P>
      <P>Server</P>
      <P>Server错误类表示由于消息的处理过程而不是消息的内容本身使得消息消息不能正确的处理。例如，处理消息时可能要与其它处理器通信，但它没有响应。这个消息可能在迟一点的时间处理成功。 
      SOAP Fault子元素的详细信息参见4.4节</P>
      <H4>5. SOAP编码</H4>
      <P>SOAP编码格式基于一个简单的类型系统，概括了程序语言，数据库和半结构化数据等类型系统的共同特性。一个类型或者是一个简单的（标量的）类型，或者是由几个部分组合而成的复合类型，其中每个部分都有自己的类型。以下将详细描述这些类型。这一节定义了类型化对象的序列化规则。它分两个层次。首先，给定一个与类型系统的符号系统一致的Schema（译者注：这里的schema不是符合XML语法的schema，而仅仅表示广义的用于表示消息结构的定义方式），就构造了XML语法的Schema。然后，给定一个类型系统的Schema和与这个Schema一致的特定的值，就构造了一个XML文档实例。反之，给定一个依照这些规则产生的XML文档实例和初始的Schema，就可以构造初始值的一个副本。这一节中定义的元素和属性的名域标志符为"http://schemas.xmlsoap.org/soap/encoding/"。下面的例子都假定在上一层的元素中声明了名域。 
      <BR>鼓励使用这一节中描述的数据模型和编码方式，但也可以在SOAP中使用其他的数据模型和编码方式。（见4.1.1节）</P>
      <H4>5.1 XML中的编码类型规则</H4>
      <P>XML允许非常灵活的数据编码方式。SOAP定义了一个较小的规则集合。这一节在总的层次上定义了这些编码规则，下一节将描述特定类型的编码规则的细节。这一节定义的编码规则可以与第7节中所述的RPC调用和应答映射结合使用。下面的术语用来描述编码规则: 

      <UL>
        <LI>一个"value"是一个字符串，类型（数字，日期，枚举等等）的名或是几个简单值的组合。所有的值都有特定的类型。 
        <LI>一个"simple value"没有名部分， 如特定的字符串，整数，枚举值等等。 
        <LI>一个"compound value"是相关的值的结合，如定单，股票报表，街道地址等等。在"compound 
        value"中，每个相关的值都潜在的以名，序数或这两者来区分。这叫作"a 
        ccessor"。复合值的例子有定单和股票报表等等。数组也是复合值。在复合值中，多个accessor有相同的名是允许的，例如RDF就是这样做的。 

        <LI>一个"array"是一个复合值，成员值按照在数组中的位置相互区分。 
        <LI>一个"struct"也是一个复合值，成员值之间的唯一区别是accessor名，accessor名互不相同。 
        <LI>一个"simple type"是简单值的类，如叫做"string" "integer"的类，还有枚举类等等。 
        <LI>一个"compound type"是复合值的类。复合类型的例子有定单类，它们有相同的accessor名（shipTo, 
        totalCost等），但可能会有不同的值（可能以后被设置为确定的值）。 </LI></UL>
      <P>在复合类型中，如果类型内的accessor名互不相同，但是可能与其他类型中的accessor名相同，即，accessor名加上类型名形成一个唯一的标志符，这个名叫作"局部范围名"。如果名是直接或间接的基于URI的一部分，那么不管它出现在什么类型中，这个名本身就可以唯一标志这个accessor，这样的名叫作"全局范围名"。给定了schema中相关的值的序列化信息，就可能确定某些值只与某个accessor的一个实例有关。其它情况下则无法确定。当且仅当一个accessor引用一个值，这个值才能被视为"single-reference"，如果有不止一个accessor引用它，那么就将它视为"multi-reference"。注意，可能一个确定的值在一个schema中是"single-reference"，而在另一个schema中是"multi-reference"。在语句构成上，一个元素可能是"independent" 
      或 
      "embedded"。一个独立的元素指出现在序列化最顶层的任何元素。所有其它元素都是嵌入元素。虽然用xsi:type属性可以使值的结构和类型变为自描述的，但是序列化规则允许值的类型仅仅参照schema而定。这样的schema可能使用"XML 
      Schema Part 1: Structures" [10]和"XML Schema Part 2: Datatypes" 
      [11]中描述的符号系统，也可能使用其它符号系统。注意，虽然序列化规则可以用于除了数组和结构之外的复合类型，但是许多schema仅仅包含数组和结构类型。序列化规则如下: 
      </P>
      <P>所有的值以元素内容的形式表示。一个multi-reference值必须表示为一个独立元素的内容，而一个single-reference值最好不要这样表示（也可以这样表示）。对于每个具有值的元素，值的类型时必须用下述三种方式之一描述：
      <UL>
        <LI>所属元素实例有xsi:type属性 
        <LI>所属元素是一个有SOAP-ENC:arrayType 属性（该属性可能是缺省的）的元素的子元素，或者 
        <LI>所属元素的名具有特定的类型，类型可以由schema确定。 </LI></UL>
      <P>一个简单值表示为字符数据，即没有任何子元素。每个简单值必须具有一个类型，这个类型或者是XML Schemas Specification, 
      part 2 
      [11]有的类型，或者具有源类型（参见5.2节）。一个复合值编码成一个元素的序列，每个accessor用一个嵌入元素表示，该元素的元素名和accessor的名一致。如果accessor的名是局部于其所属的类型的，则该元素的元素名不是合格的，否则对应的元素名是合格的。(参见5.4节) 
      <BR>一个multi-reference的简单值或复合值编码成一个独立的元素，这个元素包含一个局部的无需校验的属性，属性名为"id"，类型为"ID"（依照XML 
      Specification [7]）。值的每个accessor对应一个空元素，该元素有一个局部的，无需校验的属性，属性名为"href"，类型为" 
      uri-reference "（依照XML Schema Specification 
      [11]），"href"属性的值引用了相对应的独立元素的URI标志符。字符串和字符数组表示为multi-reference的简单类型，但是特殊的规则使它们在普通的情况下能被更有效的表示（参见5.2.1节和5.2.3节）。字符串和字符数组值的accessor可能有一个名字为"id"，类型为"ID"（依照XML 
      Specification 
      [7]）的属性。如果这样，所有这个值的所有其它accessor编码成一个空元素，这个元素有一个局部的，无需校验的属性，属性名为"href"，类型为" 
      uri-reference "（依照XML Schema Specification 
      [11]），"href"属性的值引用了包含这个值的元素的URI标志符。编码时允许一个值有多个引用，就像多个不同的值有多个引用一样，但这仅在从上下文可以知道这个XML文档实例的含义没有改变时才可使用。数组是复合值（参见5.4.2节）。SOAP数组定义为具有类型"SOAP-ENC:Array"或从它衍生的类型.</P>
      <P>SOAP数组可以时一维或多维，它们的成员以序数位置相互区分。一个数组值表示为反映这个数组的一系列元素，数组成员按升序出现。对多维数组来说，右边的这一维变化最快。每个成员元素命名为一个独立元素。（见规则2）SOAP数组可以是single-reference 
      或multi-reference值，因此可以表示为嵌入元素或独立元素的内容。SOAP数组必须包含一个"SOAP-ENC:arrayType"属性，它的值指定了包含元素的类型和数组的维数。"SOAP-ENC:arrayType"属性的值定义如下：</P>
      <P>arrayTypeValue = atype asize <BR>atype = QName *( rank ) <BR>rank = "[" 
      *( "," ) "]" <BR>asize = "[" #length "]" <BR>length = 1*DIGIT
      <UL>
        <LI>"atype"结构是被包含元素的类型名，它表示为QName并且作为类型限制在XML元素声明的 
        <LI>"type"属性中出现（这意味着被包含元素的所有值都要与该类型一致，即在SOAP-ENC:a 
        rrayType中引用的类型必须是每个数组成员的类型或超类型）。在arrays of arrays or "jagged 
        arrays"的情况下，类型组件编码为"innermost"类型且在从第一层开始的嵌套数组的每一层中，类型名后都跟随一个rank结构。多维数组编码时从第一维起，每一维之间用逗号隔开。 

        <LI>"asize"结构包含一个以逗号分隔的列表，数值0，1或其它整数表示数组每一维的长度。整数0表示没有指定详细的大小，但是可能在检查数组实际成员的大小后确定。例如，一个5个成员的整型数组的arrayTypeValue值为"int[][5]"，它的atype值是int[]"，asize值是"[5]"。同样，一个3个成员的两维整型数组的arrayTypeValue值为"int[,][3]"，它的atype值是int[,]"，asize值是"[3]"。 
        </LI></UL>
      <P>一个SOAP数组成员可能包含一个"SOAP-ENC:offset"属性表示这一项在整个数组中的位置偏移值。这被用来指示一个部分储值数组（见5.4.2.1节）的位置偏移值。同样，一个数组成员可能包含一个"SOAP-ENC:position"属性表示这一项在整个数组中的位置，这被用来描述稀疏数组（见5.4.2.2节）的成员。"SOAP-ENC:offset" 
      和"SOAP-ENC:position"属性值的定义如下：</P>
      <P>arrayPoint = "[" #length "]"<BR>偏移值和位置从0开始 
      <BR>NULL值或缺省值可能通过省略accssor元素来表示。NULL值也可能通过一个包含值为'1'的xsi:null属性的accssor元素来表示，其它的依赖于应用程序的属性和值也可能用来表示NULL值。注意，规则2允许独立的元素和数组成员名不同于值类型的元素。 
      </P>
      <H4>5.2 简单类型</H4>
      <P>SOAP采用了"XML Schema Part 2: Datatypes"规范[11]"Built-in 
      datatypes"节中的所有类型作为简单类型，包括值和取值范围。例如：</P>
      <DIV align=center>
      <CENTER>
      <TABLE cellSpacing=0 cellPadding=0 width="42%" border=1>
        <TBODY>
        <TR>
          <TD width="23%">类型</TD>
          <TD width="77%">举例</TD></TR>
        <TR>
          <TD width="23%">int</TD>
          <TD width="77%">58502</TD></TR>
        <TR>
          <TD width="23%">float</TD>
          <TD width="77%">314159265358979E+1</TD></TR>