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:
The Bridge supports SOAP RPC encoding as default. This default is used when no stereotype is set at the port type operation. |
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.
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.
Document Style / Literal Encoding Request | RPC Style / SOAP Encoding Request | ||
---|---|---|---|
|
|
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:
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
Flag wsdlPerService in the E2E composite controls the generation of WSDLs at compile time.
RPC Style Encoding | Document-style Encoding | |
---|---|---|
Definitions of Types |
|
|
Definitions of Services |
|
|
Best Practice | Use this configuration for:
|
|
RPC Style Encoding / Document-style Encoding | |
---|---|
Definitions of Types |
|
Definitions of Services |
|
Best Practice |
|
The Compiler uses namespaces in the following order:
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. |