7.2. 在 SOAP 1.2 消息中添加标头

概述

SOAP 邮件标题通过在 SOAP 1.2 信息中添加 soap12:header 元素来定义。soap12:header 元素是绑定的、outputfault 元素的可选子项。SOAP 标头成为父消息的一部分。SOAP 标头通过指定消息和消息部分来定义。每个 SOAP 标头只能有一个消息部分,但您可以根据需要插入多个标头。

语法

定义 SOAP 标头的语法显示在 例 7.3 “SOAP 标头语法” 中。

例 7.3. SOAP 标头语法

<binding name="headwig">
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="weave">
      <soap12:operation soapAction="" style="documment"/>
      <input name="grain">
        <soap12:body ... />
        <soap12:header message="QName" part="partName"
                       use="literal|encoded"
                        encodingStyle="encodingURI"
                        namespace="namespaceURI" />
      </input>
...
</binding>

表 7.1 “soap12:header Attributes” 描述了 soap12:header 元素的属性。

表 7.1. soap12:header Attributes

属性描述

message

指定将要插入到标头中的消息的合格属性。

part

指定插入到 SOAP 标头中的消息部分的名称所需的属性。

使用

指定消息部分是否使用编码规则进行编码。如果设置为 编码 消息部分,则使用由 encodingStyle 属性的值指定的编码规则进行编码。如果设置为 字面,则消息部分由所引用的 schema 类型定义。

encodingStyle

指定用于构建消息的编码规则。

namespace

使用 use="encoded" 定义分配给标头元素序列化的命名空间。

在正文和标头间分割消息

插入到 SOAP 标头的消息部分可以是合同中任何有效的消息部分。它也可以是父消息的一部分,这些消息用作 SOAP 正文。由于您不太可能在同一消息中发送信息两次,因此 SOAP 1.2 绑定提供了指定插入到 SOAP 正文中的消息部分的方法。

soap12:body 元素具有一个可选的属性(part),它取一个以空格分隔的部分名称列表。当定义各个部分时,只有列出的消息部分插入到 SOAP 1.2 消息的正文中。然后您可以将剩余的部分插入消息的标头中。

注意

当您使用父消息的部分定义 SOAP 标头时,Apache CXF 会自动填写您的 SOAP 标头。

示例

例 7.4 “使用 SOAP Header 的 SOAP 1.2 绑定” 显示 例 7.1 “排序系统接口” 中显示的 orderWidgets 服务的修改版本。此版本会被修改,以便每个顺序都放置在请求的标头中的 xsd:base64binary 值。标头定义为来自 widgetKey 消息的 keyVal 部分。在这种情况下,您需要添加应用程序逻辑来创建标头,因为它不是输入或输出消息的一部分。

例 7.4. 使用 SOAP Header 的 SOAP 1.2 绑定

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<types>
  <schema targetNamespace="http://widgetVendor.com/types/widgetTypes"
           xmlns="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <element name="keyElem" type="xsd:base64Binary"/>
  </schema>
</types>

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>
<message name="widgetKey">
  <part name="keyVal" element="xsd1:keyElem"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap12:operation soapAction="" style="document"/>
      <input name="order">
        <soap12:body use="literal"/>
        <soap12:header message="tns:widgetKey" part="keyVal"/>
      </input>
      <output name="bill">
        <soap12:body use="literal"/>
        <soap12:header message="tns:widgetKey" part="keyVal"/>
      </output>
      <fault name="sizeFault">
        <soap12:body use="literal"/>
      </fault>
  </operation>
</binding>
...
</definitions>

您可以修改 例 7.4 “使用 SOAP Header 的 SOAP 1.2 绑定” 以便标头值是输入和输出信息的一部分,如 例 7.5 “带有 SOAP 标头的 orderWidgets 的 SOAP 1.2 绑定” 所示。在这种情况下 keyVal 是输入和输出消息的一部分。在 soap12:body 元素中,part 属性指定该 keyVal 不应插入到正文中。但是,它将插入到标头中。

例 7.5. 带有 SOAP 标头的 orderWidgets 的 SOAP 1.2 绑定

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<types>
  <schema targetNamespace="http://widgetVendor.com/types/widgetTypes"
           xmlns="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <element name="keyElem" type="xsd:base64Binary"/>
  </schema>
</types>

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
  <part name="keyVal" element="xsd1:keyElem"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
  <part name="keyVal" element="xsd1:keyElem"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap12:operation soapAction="" style="document"/>
      <input name="order">
        <soap12:body use="literal" parts="numOrdered"/>
        <soap12:header message="tns:widgetOrder" part="keyVal"/>
      </input>
      <output name="bill">
        <soap12:body use="literal" parts="bill"/>
        <soap12:header message="tns:widgetOrderBill" part="keyVal"/>
      </output>
      <fault name="sizeFault">
        <soap12:body use="literal"/>
      </fault>
  </operation>
</binding>
...
</definitions>