The "wrapped" document/literal convention

In my First Stop: WS-I posting, I recommended that web service developers always use document/literal, even though the WS-I Basic Profile allows rpc/literal. Some people might resist this notion, thinking the document style is harder to work with than rpc style, but that just isn't true. For developers that want an RPC-like programming experience using document/literal, all you have to do is use the "wrapped" convention.

Most SOAP implementations now support the "wrapped" convention. .NET uses it by default (and it doesn't support rpc/literal). All JAX-RPC compliant implementations also must support "wrapped". The "wrapped" convention yields the best results for interoperability.

The "wrapped" convention produces document/literal services, and yet it supports an RPC-style programming interface (i.e., it performs automatic marshalling of input parameters and return values).

The rules for the "wrapped" convention are fairly simple:

1. "Wrapped" is a form of document/literal, therefore it must follow all the rules defined for document/literal. When defining a document/literal service, there can be at most one body part in your input message and at most one body part in your output message. You do *not* define each method parameter as a separate part in the message definition. (The parameters are defined in the types section, instead.)
   
2. Each part definition must reference an element (not a type) defined, imported, or included in the types section of the WSDL document. These element definitions are "wrapper" elements (hence the name of this convention). You define your input and output parameters as element structures within these wrapper elements.
   
3. A wrapper element must be defined as a complex type that is a sequence of elements. Each child element in that sequence will be generated as a parameter in the service interface.
4. The name of the input wrapper element must be the same as the operation name.
5. The name of the output wrapper element should be (but doesn't have to be) the operation name appended with "Response" (e.g., if the operation name is "add", the output wrapper element should be called "addResponse").
   
6. In the binding definition, the soap:binding should specify style="document" (although this is the default value, so the attribute may be omitted), and the soap:body definitions must specify use="literal" and nothing else. You must not specify the namespace or encodingStyle attributes in the soap:body definition.

The following WSDL shows an example of the "wrapped" convention. It defines a simple add operation that takes two ints in and returns an int . This WSDL permits you to invoke the service like this:

int sum = addProxy.add(arg1, arg2);

Notice that the portType defines an operation called "add". It takes the "addRequest" message in and returns the "addResponse" message out. The "addRequest" message has one body part called "parameters" (.NET always uses this name for "wrapped" style). It references an element called "add". (The name of this input element must be the same as the operation name.) The "add" element is defined as a complex type that is a sequence of two elements (the input parameters), "arg1" and "arg2", which are both defined as ints. The "addResponse" message has one body part, also called "parameters", and it references an element called "addResponse". The "addResponse" element is defined as a complex type that is a sequence of one element (the return value), "sum", which is defined as an int.

<wsdl:definitions name=’addWrappedLiteral’

    targetNamespace='urn:example/wrapped/add'

    xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'

    xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'

    xmlns:types='urn:add/types'

    xmlns:intf='urn:example/wrapped/add'>

  <wsdl:types>

    <xsd:schema elementFormDefault="qualified"

        targetNamespace='urn:add/types'

        xmlns:xsd='http://www.w3.org/2001/XMLSchema'>

      <xsd:element name="add" type="types:add_t"/>

      <xsd:element name="addResponse" type="types:addResponse_t"/>

      <xsd:complexType name="add_t">

        <xsd:sequence>

          <xsd:element name="arg1" type="xsd:int"/>

          <xsd:element name="arg2" type="xsd:int"/>

        </xsd:sequence>

      </xsd:complexType>

      <xsd:complexType name="addResponse_t">

        <xsd:sequence>

          <xsd:element name="sum" type="xsd:int"/>

        </xsd:sequence>

      </xsd:complexType>

    </xsd:schema>

  </wsdl:types>

  <wsdl:message name='addRequest'>

    <wsdl:part name='parameters' element='types:add'/>

  </wsdl:message>

  <wsdl:message name='addResponse'>

    <wsdl:part name='parameters' element='types:addResponse'/>

  </wsdl:message>

  <wsdl:portType name='addPT'>

    <wsdl:operation name='add'>

      <wsdl:input message='intf:addRequest'/>

      <wsdl:output message='intf:addResponse'/>

    </wsdl:operation>

  </wsdl:portType>

  <wsdl:binding name='addSoapBinding' type='intf:addPT'>

    <soap:binding

       transport='http://schemas.xmlsoap.org/soap/http'

       style='document'/>

    <wsdl:operation name='add'>

      <soap:operation soapAction='urn:example/wrapped/add'/>

      <wsdl:input>

        <soap:body use='literal'/>

      </wsdl:input>

      <wsdl:output>

        <soap:body use='literal'/>

      </wsdl:output>

    </wsdl:operation>

  </wsdl:binding>

  <wsdl:service name='addService'>

    <wsdl:port name='addSoapPort' binding='intf:addSoapBinding'>

      <soap:address location='...'/>

    </wsdl:port>

  </wsdl:service>

</wsdl:definitions>