SOAP, WSDL, and UDDI
2.2 SOAP Message Structure
2.2.3 SOAP Message Envelope
The SOAP envelope contains a message from one application to be sent to another application.
The envelope part of the SOAP message acts as a container for the message. The Envelope element:
is the root element of the message and is mandatory
acts as a processing node to the receiving application. For example, the <Envelope>
tag indicates the start of a SOAP message and the </Envelope> tag indicates the end.
Once the receiving application encounters the </Envelope> tag, it starts processing the message
contains two child elements, an optional <Header> element and a mandatory <Body>
element
SOAP 1.1 allows additional elements to be added after the SOAP Body element, SOAP 1.2 does not allow these
Code Snippet 2 demonstrates the Envelope tag in a SOAP message.
Code Snippet 2:
A SOAP Envelope contains several XML elements and it is possible to use the same name for one or more elements. SOAP prevents name collisions using XML namespaces.
SOAP uses the namespace http://www.w3.org/2003/05/soap- envelope/ to qualify the XML elements and attributes in a SOAP message. Code Snippet 3 demonstrates a SOAP message with its elements qualified with respective namespaces.
SOAP, WSDL, and UDDI
<!--SOAP Message goes here -->
<po:orderDate> 2014/07/06 </po:orderDate>
...
</SOAP-ENV:Envelope>
In the given Code Snippet, the Envelope element is qualified by http://www.
w3.org/2003/05/soap-envelope/ namespace. The prefix of this namespace is SOAP-ENV.
The namespace http://www.flamingo.com/books/PO is used to qualify the data elements of the SOAP message. The prefix for this namespace is po. The orderDate element is qualified with this namespace.
The namespace http://www.w3.org/2003/05/soap-envelope/ indicates that the message adheres to SOAP 1.2. This ensures that both the sender and the receiver adhere to same version of SOAP.
SOAP Message Header
Header is the child element of Envelope element. It is an optional element. However, if present it should be the immediate child of Envelope element. The immediate child elements of the Header element are referred as header entries. Each header entry and its child elements must be qualified with a namespace. The header entries can have the attributes role and mustUnderstand. These attributes identify the consumer of the header entry and how to process the header entry.
Headers can be used to extend SOAP messages to include additional information and functionality to process a message. For example, a typical transfer payment service requires a from account number, to account number, and the amount to be transferred. However, to process such services, you need additional information, such as identity of the person requesting the service, account information, and so on. Such information is included in the header part of the SOAP message.
Headers can also include information such as digital signatures for password-protected service, authentication, authorization, transaction management, and routing path.
SOAP, WSDL, and UDDI
Session 02
• role Attribute
A SOAP message travels from the original source to the ultimate destination. In the process, it passes through several intermediate entities referred as nodes or SOAP intermediaries. These intermediaries are applications capable of receiving SOAP message and forwarding them. The role attribute is used to specify the URI or role of such intermediaries and the ultimate destination of a message.
SOAP 1.2 defines the following three roles that have significant importance in a SOAP message:
next: This role specifies that each SOAP nodes involved in transporting the message and the final SOAP receiver must process the message.
none: This role specifies that each SOAP node involved in transporting the message must not process the message.
utimateReceiver: This role specifies that the final SOAP receiver must process the message.
Code Snippet 4 demonstrates a SOAP message with various header entries.
Code Snippet 4:
<SOAP-ENV: Header>
<mid:message-id
SOAP, WSDL, and UDDI
Session 02
<identity>austria</identity>
</node>
</SOAP-ENV: Header>
</SOAP-ENV: Envelope>
In the given Code Snippet, the header element message-id has the role attribute set to http://www.flamingo.com/logger. Therefore, all the nodes identifying themselves by this URI are the recipients of this header entry.
The header element monitored-by uses the role attribute to refer to the role http://www.w3.org/2003/05/soap-envelope/next. This special URI indicates that this header entry should be processed by the very first node that receives the message.
The header element monitoring-date uses the role attribute none to refer to the role http://www.w3.org/2003/05/soap-envelope/role/none. This new SOAP 1.2 URI indicates that this header entry should not be directly processed by any of the SOAP nodes.
The header element mark uses the role attribute to refer to the ultimateReceiver http://www.w3.org/2003/05/soap-envelope/role/none. This new SOAP 1.2URI indicates that this header entry should be processed only by the final receiver of the message.
• mustUnderstand Attribute
A header attribute may contain another attribute, mustUnderstand. This attribute is used to indicate to the recipient whether it is mandatory to process the header entry. This attribute allows two values false and true. The true value indicates that the recipient should process the header entry. A false value is equivalent to omitting the mustUnderstand attribute.
SOAP, WSDL, and UDDI
Session 02
Code Snippet 5 demonstrates an example of a header entry with the mustUnderstand attribute.
Code Snippet 5:
<!-- SOAP Message Structure -->
<?xml version =”1.0” encoding=”UTF-8” ?><SOAP-ENV:Envelope xmlns:SOAP-ENV=
“http://www.w3.org/2003/05/soap-envelope”>
</SOAP-ENV:Header>
...
</SOAP-ENV:Envelope>
In the given Code Snippet, the mustUnderstand attribute is set to true indicating that the receiver of the message should process the header entry.
Body Element
The Body element contains application-specific data to be exchanged between applications. The data in the Body element is an XML fragment containing information, such as billing address or parameters to a method call.
The Body element is the mandatory element of Envelope element. The immediate child elements of Body element must be namespace-qualified.
The Body element must be placed as follows:
• If the Header element is not present, the Body element should be the immediate child of Envelope element.
• If the Header element is present, the Body element should immediately follow the Header element.
Need of Attachment
SOAP messages contain XML fragment. However, at times you may want to send data that is not XML. For example, consider a scenario wherein you want to allow customers to book a room in a hotel.
SOAP, WSDL, and UDDI
Session 02
This can easily be achieved through SOAP-based Web Service wherein a user sends the number of rooms to book and the service responds by sending the availability of the rooms. All this can be achieved through SOAP as the data exchanged is text.
Consider another scenario wherein the hotel management decides to upgrade the service. They would like the customers to have a glance of the interiors of the rooms before finalizing a booking. For this, the Web Service should be able to send images back to the customer. However, SOAP does not allow binary data such as images in the message.
Messages that require binary data are converted to a Multipurpose Internet Mail Extensions (MIME) message format and then sent. A MIME message can contain multiple parts and supports binary data as well.