第 3 章 定义服务使用的逻辑消息

摘要

服务由消息在调用操作时进行交换。在 WSDL 合同中,这些消息通过 消息 元素进行定义。消息由一个或多个利用 部分 元素定义的部分组成。

概述

服务的操作通过指定调用操作时交换的逻辑信息来定义。这些逻辑消息定义通过网络传输的数据作为 XML 文档。它们包含作为方法调用的一部分的所有参数。 使用您的合同中的 message 元素定义逻辑消息。每个逻辑消息由 部分 元素中定义的一个或多个部分组成。

虽然您的消息可以将每个参数列为单独的部分,但建议的做法是只使用一个部分来封装操作所需的数据。

消息和参数列表

服务公开的每个操作只能有一个输入消息和一个输出消息。输入消息定义在调用操作时服务接收的所有信息。输出消息定义在操作完成后服务返回的所有数据。故障消息定义服务在发生错误时返回的数据。

另外,每个操作都可以具有任意数量的故障消息。故障消息定义服务遇到错误时返回的数据。这些消息通常只有一个部分,以供消费者了解错误。

用于与旧系统集成的消息设计

如果要将现有应用程序定义为服务,您必须确保实施操作方法使用的每个参数都在消息中表示。您还必须确保操作输出消息中包含返回值。

定义您的消息的一种方法是 RPC 样式。在使用 RPC 样式时,您可以在方法的参数列表中为每个参数定义一个消息。每种消息部分均基于合同 类型 元素中定义的类型。您的输入消息包含方法中每个输入参数的部分。您的输出消息会包括每个输出参数的一个部分,以及代表返回值的部分(如果需要)。如果参数既是输入参数和输出参数,它将被列为输入消息和输出消息的一部分。

当启用使用 Tibco 或 CORBA 等传输的旧系统时,RPC 样式消息定义很有用。这些系统围绕了程序和方法设计。因此,使用类似参数列表的消息可方便建模,用于调用的操作。RPC 样式也使得服务与它所公开的应用之间形成一个干净的映射。

SOAP 服务的消息设计

而 RPC 样式对现有系统建模非常有用,而该服务的社区很广泛地使用嵌套文档风格。在嵌套文档风格中,每个消息都有一个部分。该消息的部分引用合同 类型 元素中定义的打包程序元素。wrapper 元素具有以下特征:

  • 它是包含一系列元素的复杂类型。更多信息请参阅 第 2.5 节 “定义复杂数据类型”
  • 如果它是一个用于输入信息的打包程序:

    • 它为每个方法的输入参数都有一个元素。
    • 其名称与与其关联的操作的名称相同。
  • 如果它是一个输出信息的打包程序:

    • 它为每个方法的输出参数和一个元素,每个方法的 inout 参数中有一个元素。
    • 第一个元素表示方法的返回参数。
    • 其名称将通过将响应 附加到 与打包程序关联的操作的名称。

消息命名

合同中的每个消息都必须在其命名空间中具有唯一的名称。建议您使用以下命名规则:

  • 消息只应用于一个操作。
  • 输入消息名是通过在操作名称中添加 Request 来形成的。
  • 输出消息的名称是通过在操作名称中添加 Response 来形成的。
  • 错误消息名称应该代表故障的原因。

消息部分

消息部分是逻辑消息的正式数据单元。每一部分使用 part 元素来定义,由 name 属性标识,另一个是 type 属性或指定其数据类型的 element 属性。数据类型属性列在 表 3.1 “部分数据类型属性” 中。

表 3.1. 部分数据类型属性

属性描述

element="elem_name"

部分的数据类型由名为 elem_name 的元素定义。

type="type_name"

部分的数据类型由名为 type_name 的类型定义。

允许消息重复使用部分名称。例如,如果方法有参数 foo,它通过引用或是一个 in/out 传递,它可以是请求消息和响应信息的一部分,如 例 3.1 “重复使用的部分” 所示。

例 3.1. 重复使用的部分

<message name="fooRequest">
  <part name="foo" type="xsd:int"/>
<message>
<message name="fooReply">
  <part name="foo" type="xsd:int"/>
<message>

示例

例如,假设您有一个存储个人信息的服务器,并提供了一个基于员工的 ID 编号返回员工数据的方法。查找数据的签名方法与 例 3.2 “personalInfo 查找方法” 类似。

例 3.2. personalInfo 查找方法

personalInfo lookup(long empId)

这个方法签名可以映射到 例 3.3 “RPC WSDL 消息定义” 中显示的 RPC 风格的 WSDL 片段。

例 3.3. RPC WSDL 消息定义

<message name="personalLookupRequest">
  <part name="empId" type="xsd:int"/>
<message/>
<message name="personalLookupResponse>
  <part name="return" element="xsd1:personalInfo"/>
<message/>

它还可以映射到 例 3.4 “嵌套文档 WSDL 消息定义” 中显示的嵌套文档风格的 WSDL 片段。

例 3.4. 嵌套文档 WSDL 消息定义

<wsdl:types>
  <xsd:schema ... >
  ...
  <element name="personalLookup">
    <complexType>
      <sequence>
        <element name="empID" type="xsd:int" />
      </sequence>
    </complexType>
  </element>
  <element name="personalLookupResponse">
    <complexType>
      <sequence>
        <element name="return" type="personalInfo" />
      </sequence>
    </complexType>
  </element>
  </schema>
</types>
<wsdl:message name="personalLookupRequest">
  <wsdl:part name="empId" element="xsd1:personalLookup"/>
<message/>
<wsdl:message name="personalLookupResponse">
  <wsdl:part name="return" element="xsd1:personalLookupResponse"/>
<message/>