SOAP

SOAP used to stand for Simple Object access protocol. Now it's simply called as SOAP. SOAP is the message format that travels between applications. It was initially developed by Developer Mentor as a platform independent way of communicating. The big success of SOAP is attributed to it's ability to travel on HTTP. (Though that ability has nothing to do with SOAP specification as such). The success of SOAP can also be attributed to it being XML based and as their is wide support for tooling for XML, it helps in dealing with SOAP.

SOAP though is more popular over HTTP however SOAP can be sent over any protocol like ftp, smtp etc. SOAP at this point exists in both 1.1 and 1.2 version. We will outline the differences between the two versions at appropriate location. In Java, JAX-RPC supports version 1.1 and JAX-WS supports both version 1.1 and 1.2.

SOAP message is an ordinary XML document which has following elements

• Envelope (required) – Identifies XML document as SOAP message.
• Header (optional) – Contains header information
• Body (required) – Contains call and response information
• Fault (optional) – Provides error occurred while processing the message

A typical SOAP message looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelop/">
  <soap:Header>
    …
  </soap:Header>

  <soap:body>
   …
  </soap:body>
</soap:Envelope>

Bring soapUI tool up and let's hit a webservice hosted by JavaSE Service endpoint. The SOAP request in this case looks like

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.crayom.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:celsiusToFarenheitOp>
         <arg0>?</arg0>
      </ws:celsiusToFarenheitOp>
   </soapenv:Body>
</soapenv:Envelope>

In place of ?, the value is send to the server. This the whole SOAP message which travels on the wire. If we put a value of 50 and call the webservice, the response we get is:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:celsiusToFarenheitOpResponse xmlns:ns2="http://ws.crayom.com/">
         <return>122.0</return>
      </ns2:celsiusToFarenheitOpResponse>
   </S:Body>
</S:Envelope>

In essence SOAP represent the message that travels as part of request and response. The popularity of SOAP comes from it being in XML format which makes it language and platform independent. Travelling over HTTP helps it to cross firewalls also. Being a XML, SOAP is amenable to XML processsing tools. SOAP messages are for application to generate and consume. A video explaining the SOAP:




Let's look into the different elements of a SOAP message.

SOAP Envelope

---

SOAP envelope element is the root element of a SOAP message. It has encoding Style attribute which tells about the encoding being used in the message.

---

SOAP Header

---

SOAP header usually contains application specific inforamtion. For example authentication information. Many Webservices specifications like addressing are using header to define the message exchange formats. The attributes of SOAP header in different version are as follows:

• SOAP 1.1 attributes
  • mustUderstand : If the value of this attribute is 1 than reciever should be able to process this element otherwise it should raise a fault.
  • actor : A SOAP message may travel along multiple endpoints. The actor attribute tells which endpoint will be responsible for processing this header.
• SOAP 1.2 attributes
  • mustUderstand : As in version 1.1
  • role : actor in SOAP 1.1 is replaced with role with similar semantics.
  • ultimateReceiver : Introduced in SOAP version 1.2. It marks a header to be processed by the end reciever only.
  • relay : Tells if header blocks need to be forwarded

---

SOAP Body

---

SOAP body element contains the actual payload/message. It is again an XML fragment but understood by applications talking to each other.

---

SOAP fault

---

SOAP fault element indicate the error conditions. It is an optional element. The different subelement of SOAP fault are:

• faultcode - Code to identify the fault
• faultstring - Information about fault
• faultactor - The actor/endpoint responsible for generating the fault.
• detail - Detailed inforamtion about the fault.

There are standard fault codes (in SOAP 1.1) which are as follows:

• VersionMismatch - The SOAP message is of different version than the server can understand.
• MustUnderstand - The header element with mustUnderstand attribute is not understood.
• Client - Problem because of message not well formed or understood as sent by client.
• Server - Server is unable to process the message.

In SOAP 1.2 SOAP "client" and "server" fault codes are replaced with "Sender" and "Receiver" respectively. SOAP1.2 has hierarchical namespace qualified fault structure

<s:Fault>
  <s:Code>
    <s:Value>...</s:Value>
    <s:Subcode>
      <s:Value>...</s:Value>
    </s:Subcode>
  </s:Code>
  <s:Reason>Out of memory</s:Reason>
</s:Fault>

---

SOAP versions

---

There are two dominant version of SOAP messages which coexist. The versions are 1.1 and 1.2. You have to careful that the tools you are using to deal with webservices support the right version of service. The other major differences between SOAP versions are:

• Change in namespace:
  • SOAP 1.2 namespace is http://www.w3.org/2003/05/soap-envelope
  • SOAP 1.1 namespace is http://schemas.xmlsoap.org/soap/envelope/
• SOAP 1.2 has uses XML infosets and not serializations of the form <?xml....?> as in SOAP 1.1.
• SOAPAction in HTTP header as in SOAP 1.1 has been removed. This has been replaced with the qualification in content type in the Header. The Content-type is "application/soap+xml" in SOAP 1.2 instead of "text/xml".
• SOAP 1.2 does not allows additional elements after SOAP Body element whereas SOAP 1.1 allows these

If a SOAP 1.1 node recieves SOAP 1.2 message, it generates version mismatch SOAP fault. If SOAP 1.2 recieves SOAP 1.1 message, it might handle the message if SOAP 1.1 is supported. If not, it will generate the version mismatch fault. Also the SOAP fault should include an upgrade header block.

Books

---

• Programming Web Services with SOAP James Snell
• Soap Programming With Java William B. Brogden

References

---

• W3C Soap site

---

Back To Java Home
Back To Home

---