Encoding of SOAP Operations

SOAP uses an XML format to marshal data that is transported between software applications. SOAP was planned to be used for legacy systems and modern object-oriented systems as well. Consequently, SOAP offers more than one encoding method to convert data from a software object into XML and vice versa (see the page of W3C).

There are two ways, in which it maps high level data types like arrays, integers, floats and so on to a serialized XML format: SOAP encoding (also called Section 5 encoding) and Literal encoding.
Literal encoding means that the body contents conform to a specific XML Schema. SOAP encoding uses a set of rules based on the XML Schema data types to encode the data, but the message does not conform to a particular schema.
In addition to the SOAP encoding styles, messages can be of two styles: RPC (Remote Procedure Call) style or Document style. See SOAP Encoding Styles for a tabular overview and more details about all encoding styles.
The following encodings are commonly used and supported by the Bridge:

• SOAP Remote Procedure Call (RPC) encoding
  • SOAP encoding
  • RPC style messages
• SOAP document-style encoding, which is also known as message-style or document-literal encoding.
  • literal encoding
  • document style messages

The Bridge supports SOAP RPC encoding as default. This default is used when no stereotype is set at the port type operation.

Implementing Document-style Encoding with the E2E Bridge

Example File (Builder project Basic Modeling/Frontend):

<your example path>\Basic Modeling\Frontend\uml\documentStyleEncoding.xml

The DocumentStyleEncodingPort contains two SOAP operations.

Figure: Hello World Example SOAP Service

From the modeling point of view, the whole difference between RPC and document style operations is given by choosing the stereotype <<SOAPDocumentOperation>> on a port type operation:

Figure: Defining Stereotype for Document-style Encoding

This stereotype can also be set on backend port type operations when accessing an external Web Service.

The stereotype <<SOAPDocumentOperation>> needs to be set on a port type operation, if it is required by the connecting SOAP client. In a SOAP document-style call, the SOAP stack sends an entire XML document to the Bridge. The message can contain any sort of XML data that is appropriate to the deployed web service.
The parameter names of the <<SOAPDocumentOperation>> port type operation will correspond to XSD element names. The parameters require the accordant object flow states in the implementing activity diagram (mostly, the required classes are generated by importing the XSD file with the E2E Builder). Document-style encoded operations mostly have zero or one input and output parameters. The parameter names correspond to the root element of the input respectively output message that is transferred in the SOAP body.

Differences between Document-style and RPC Style on the E2E Bridge

The request/response stream of RPC and document style operation calls differs considerably. The following table shows examples of two such requests, both requests transporting the same information.

  <env:Body> 
      <in1 myKey="Hello World!"></in1> 
   </env:Body> 
</env:Envelope>

<env:Body> 
 <ns3:createSimpleObjectInOut> 
    <in1 xsi:type="ns2:Input"> 
        <myKey xsi:type="xsd:string">Hello World!</myKey></in1> 
 </ns3:createSimpleObjectInOut> 
 </env:Body></env:Envelope>

In the left-hand-side example, the SOAP envelope body contains plain (= literal) XML. Each child element of the SOAP body corresponds to an operation parameter serialized to plain XML. On the right hand side, the first and only child of the SOAP body element is the SOAP operation containing the input parameters serialized according to the SOAP encoding rules. The main differences between the two formats are as follows:

• Literal XML messages do not contain explicit type information making it more compact than SOAP encoded requests.
• The operation is explicitly given for RPC style calls. For document style requests, the SOAP operation must be derived by the SOAP action.

By default, the SOAP action is given by the operation name (prefixed with urn: to make it to an URI), but it can be overridden using the tagged value soapAction. This SOAP action is used as UML message name instead of the operation name when displaying sequence diagrams for document style requests in the E2E Model Debugger (see sequence diagram depicted beneath). Additionally, if sequence diagrams depict document style/literal encoding requests, the input and output messages are not rendered as UML objects but are shown in a separate text window (see the following picture below).

Figure: SOAP Action in E2E Model Debugger

Clicking on input parameter in1 of operation urn:createSimpleObjectInOut will display the message in a separate pane.

Figure: Document Style Encoded Message

Effect of Flag wsdlPerService on the Encoding Styles

Flag wsdlPerService in the E2E composite controls the generation of WSDLs at compile time.

If true (default=false), each xUML service gets its own WSDL file. Additionally, all XML Schema elements and types having the same namespace are put into one schema file. These schema files are imported into the WSDLs to be shared among them. In this case it is also possible to mix RPC/soap-encoded services with Document/literal services.

wsdlPerService = true

wsdlPerService = false

Defining the XML Namespace

The Compiler uses namespaces in the following order:

1. Namespace defined on the class.
2. Namespace defined on the owning package (going up until the top of the hierarchy).
3. No namespace.

It is recommended to define the XML Namespace on the package, sub namespaces are then generated automatically. But it is also possible to set the namespace in each sub package or even on classes.

	To define a namespace on packages with stereotype <<XMLPackage>>, use tagged value xmlNamespace.
	Tagged value xmlNamespace can also be used on classes with stereotype XML.