SOAP

printer-friendly version of this section  Print  e-mail this section  E-Mail  add a public, group or private note  Add Note  add a bookmark about this section  Add Bookmark    

Java APIs for XML Kick Start
By Aoyon Chowdhury, Parag Choudhary

Table of Contents
Chapter 2.  Components of Web Services


Simple Object Access Protocol (SOAP) is an XML-based protocol that allows programs running on heterogeneous hardware and software in a distributed environment to exchange data with each other, and to do remote procedure calls (RPC). All communication in the Web services architecture is done via SOAP.

NOTE

At the time of this writing, both SOAP 1.1 and SOAP with Attachments specifications have been submitted to the W3C as Notes. You can access the SOAP 1.1 specification at http://www.w3.org/TR/SOAP/.

The SOAP with Attachments Note can be accessed at http://www.w3.org/TR/SOAP-attachments.

Although the SOAP 1.1 and SOAP with Attachments specifications are submitted with the W3C as Notes, a Working Draft on SOAP 1.2 has also been submitted. An excellent place to find out about the SOAP 1.2 specification is at http://www.w3.org/TR/soap12-part0/.


For those who are familiar with CORBA, SOAP can be considered similar to the IIOP protocol.

The protocol consists of three parts:

  • An envelope, which is an XML document that defines a framework for describing the message, such as what is in the message, who it is meant for, and whether any processing is necessary or not.

  • A set of data encoding rules that describe a way to encode a collection of either simple or compound values. Simple values include simple data types such as int, float, and so on, and built-in data types such as arrays of bytes and enumerations. Compound values include structures such as arrays, and other complex types as defined in the XML Schema specifications. The encoding rules also specify the rules for object serialization. The rules for object serialization provide the support for doing RPCs.

  • A convention for representing remote procedure calls and responses.

Although SOAP can be used in combination with a variety of protocols, the primary transport mechanisms used by SOAP are the common Internet protocols, such as HTTP and SMTP. There are two reasons for choosing the common Internet protocols as the transport mechanism:

  • The common Internet protocols are installed on every major operating system.

  • Because HTTP requests pass through firewalls, programs that use SOAP to communicate can communicate with programs residing in different platforms.

Having gotten an idea of what SOAP is about, let's now look at what it means to say that the components of a Web service talk to each other using SOAP.

A Web application generates the information it wants to exchange in an XML file encoded as a SOAP message, and transmits it using some Internet protocol, such as HTTP. The responding application processes the SOAP message and sends the necessary response back to the requesting application in a SOAP message. As it's possible that the applications are behind firewalls, the SOAP specification ensures that the HTTP header is specially encoded to allow a SOAP message to pass through firewalls.

Let's now look at the SOAP message exchange model.

SOAP Message Exchange Model

SOAP messages can traverse various nodes before reaching the intended final destination. Each intermediate node has to process the SOAP message. The order in which the SOAP message is processed by a node is as follows:

  1. The node identifies all the parts of the SOAP message that it is expected to process.

  2. The application at the processing node verifies that all mandatory parts that were identified are supported. If they are supported, then the SOAP message is processed. This decision is reached depending on the value of a mustUnderstand attribute of the Header element. If the server fails to process the SOAP message, then it must throw a fault. The processor might also choose to ignore optional parts identified in step 1. This does not affect the outcome of the processing of the SOAP message.

  3. If the node that is currently processing the SOAP message is not the ultimate destination, then it removes the parts it has processed and forwards the message.

Although SOAP messages are essentially one-way transmissions, SOAP implementations can use the unique characteristics of the network in which they are traveling. For example, in SOAP messages with HTTP bindings, the SOAP response message can be delivered as an HTTP response message using the same connection through which the request was received. The request-response mechanisms and the encoding capability provided by the SOAP specification enable it to do RPCs.

The following is an example of a SOAP request-response message embedded in an HTML request. We will use this example to explain how SOAP works with HTTP and the semantics of a SOAP message itself.

SOAP Message Example

Examples of a SOAP request and response embedded in HTTP are displayed in Listing 2.1 and Listing 2.2, respectively.

Listing 2.1 SOAP Request
POST /BookPrice HTTP/1.1 Host: xxx.xxx.xxx.xxx Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://xxxx.xxxx/xxxx" <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> <SOAP-ENV:Header> <t:CompanyID xmlns:t="http://xxxx.xxxx/xxxx" SOAP-ENV:mustUnderstand="1"> 1234 </t:CompanyID > </SOAP-ENV:Header> <SOAP-ENV:Body> <m:GetBookPrice xmlns:m="http://xxxx.xxxx/yyyy"> <ISBN>0789725673</ISBN> </m:GetBookPrice> </SOAP-ENV:Body> </SOAP-ENV:Envelope> 
Listing 2.2 SOAP Response
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> <SOAP-ENV:Header> <t:CompanyID xmlns:t= "http://xxxx.xxxx/xxxx" SOAP-ENV:mustUnderstand="1"> 5 </t:CompanyID> </SOAP-ENV:Header> <SOAP-ENV:Body> <m:GetBookPriceResponse xmlns:m="http://xxxx.xxxx/yyyy"> <Price>40</Price> </m:GetBookPriceResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

We will use the SOAP request and response listings to explain how SOAP is used over HTTP in detail.

SOAP and HTTP

From Listing 2.1, you can see that the SOAP HTTP request was as follows:

POST /BookPrice HTTP/1.1 Host: xxx.xxx.xxx.xxx Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://xxxx.xxxx/xxxx" <SOAP-ENV:Envelope .... ..... </SOAP-ENV:Envelope> 

SOAP can be (and mostly is) bound with HTTP with or without using the HTTP Extension Framework.

The SOAP request response in Listing 2.2 shows how the SOAP messages travel over the HTTP request-response mechanism. SOAP requests are sent in the POST (or M-POST if the extension framework is used), and the SOAP response is returned in the HTTP response.

It is important to remember that the Content-Type header must indicate that the body is text/xml when SOAP messages are included in the HTTP messages.

Additionally, when issuing a SOAP HTTP request, a client must use the SOAPAction HTTP header. The value of the SOAPAction HTTP header is a URI. The header is required by servers such as firewalls to identify incoming SOAP requests. SOAP places no restriction on the format, specificity, or resolvability of the URI.

From Listing 2.2, we see that the SOAP HTTP response is as follows:

HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <SOAP-ENV:Envelope .... ..... </SOAP-ENV:Envelope> 

To report the status of a SOAP request message to a client, the SOAP HTTP response follows the semantics of the HTTP status codes. For example, a 200 status code indicates that the client's request, which included the SOAP component, was successful.

If an error is reported while processing the SOAP request, the SOAP HTTP server issues an HTTP 500 "Internal Server Error" response. It also includes a SOAP message in the response containing a SOAP Fault element indicating the SOAP processing error.

Let's now look at the constituents of the SOAP message.

Understanding the SOAP Envelope

The SOAP Envelope appears as follows:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 

The Envelope element is the first element in a SOAP message. This element identifies the XML document as a SOAP message. All other elements are wrapped within the Envelope element. The Envelope contains the version information of the message, and the encoding rules used by the application to serialize data.

The definitions of the elements and attributes of a SOAP message and the encoding rules are represented as namespace URIs in the Envelope. The first namespace URI references the SOAP schema, and the second namespace URI references the SOAP encodings.

It is important to remember that the namespace that references the SOAP schema also defines the version information. This is different from the standard and more traditional major-number minor-number versioning method. If an application receives a SOAP message in which the SOAP Envelope element is associated with a namespace different from http://schemas.xmlsoap.org/soap/envelope/, then the application must raise a version error and discard the message.

After the Envelope element, a SOAP message can contain a Header element. The Header element is optional. After the Header element, a SOAP message must contain a Body element. This element is compulsory. The information contained within the Body part is always intended for the final recipient of the message.

Understanding the SOAP Header

If it's used, the Header element has to be the first element after the Envelope element. As per the SOAP specifications, the Header element is processed separately from the main content of the SOAP message. This provides an ideal mechanism to pass information to the intermediate processing nodes.

Whether a node needs to process a Header or not depends on the value of the mustUnderstand attribute of the Header element. If the value of the attribute is 1, then the node has to process the Header element. In case the node fails to process the message, then a fault element is thrown. A fault element is the mechanism by which error information is sent back to the client.

For example, consider the following code sample:

<SOAP-ENV:Header> <t:CompanyID xmlns:t="http://xxxx.xxxx/xxxx" SOAP-ENV:mustUnderstand="1"> 1234 </t:CompanyID > </SOAP-ENV:Header> 

It has a CompanyID element with a namespace attribute and a mustUnderstand attribute. The value of the mustUnderstand attribute determines whether a node needs to process the Header. Because the value of the mustUnderstand attribute is 1, the node accepting this message must process this message. This implies that there is a prior semantic agreement between the application that created the SOAP message and the application at the node that is processing this Header element. Therefore, the application at the node knows what to do with the contents of the element, which is 1234 in this case.

Similarly, a SOAP message can contain Header entries for nodes that perform authentication, data encryption, and a myriad of other tasks.

Understanding the SOAP Body

The SOAP Body contains the actual content that is meant for the final recipient. The SOAP Body is primarily used for doing RPCs and reporting errors. For example, in the following code sample, the request is actually invoking the GetBookPrice method on the Web service:

<SOAP-ENV:Body> <m:GetBookPrice xmlns:m="http://xxxx.xxxx/yyyy"> <ISBN>0789725673</ISBN> </m:GetBookPrice> </SOAP-ENV:Body> 

The SOAP response contains the GetBookPriceResponse element with a structure named Price, which returns the results of the method invocation:

<SOAP-ENV:Body> <m:GetBookPriceResponse xmlns:m="http://xxxx.xxxx/yyyy"> <Price>40</Price> </m:GetBookPriceResponse> </SOAP-ENV:Body> 

Note that the convention used for doing RPCs over SOAP is that the method name is used in the SOAP request, and methodname + Response is used for the corresponding SOAP response. In the case of the SOAP response, the return value must appear as the first child element.

This completes a brief description of SOAP. Normally, you will not need to bother about the semantics, because the JAX APIs will create the necessary SOAP messages.


printer-friendly version of this section  Print  e-mail this section  E-Mail  add a public, group or private note  Add Note  add a bookmark about this section  Add Bookmark    
Top

[0672324342/ch02lev1sec2]

 
 


JavaT APIs for XML Kick Start
JAX: Java APIs for XML Kick Start
ISBN: 0672324342
EAN: 2147483647
Year: 2002
Pages: 133

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net