Newsletter sign-up
View all newsletters

Enterprise Java Newsletter
Stay up to date on the latest tutorials and Java community news posted on JavaWorld

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

JavaWorld.com > Java Enterprise Edition >

Clean up your wire protocol with SOAP, Part 1

An introduction to SOAP basics

By Tarak Modi, JavaWorld.com, 03/30/01

  • Print
  • Feedback
.

Page 6 of 6

Once the server has processed the request, it will return a response to the client that looks like Listing 11 (assuming that there are no errors):

Listing 11

HTTP/1.0 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: 615
<SOAP-ENV:Envelope 
                       xmlns:SOAP-ENV="
http://schemas.xmlsoap.org/soap/envelope/"               
                       xmlns:xsi="
http://www.w3.org/1999/XMLSchema-instance" 
                       xmlns:xsd="http://www.w3.org/1999/XMLSchema">
     <SOAP-ENV:Body>
           <ns1:sayHelloToResponse 
                      xmlns:ns1="Hello" 
                      SOAP-ENV:encodingStyle="
http://schemas.xmlsoap.org/soap/encoding/">
                <return xsi:type="xsd:string">Hello John, How are 
you doing?</return>
          </ns1:sayHelloToResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


That is the same SOAP response as shown in Listing 5 with some HTTP-specific code at the beginning. Since there was no error, the first line produces the code 200, which in HTTP speak means "everything's OK." If there were any errors/faults while processing the SOAP message (in the header or body), the returned code would generate 500, which means "internal server error" in HTTP speak. Thus, the first line would look like this: 

HTTP 500 Internal Server Error


The HTTP extension framework

Many applications require services beyond those provided by traditional HTTP. As a result, such applications extend the traditional HTTP protocol. However, these extensions are proprietary to the application itself. The HTTP extension framework attempts to solve that problem by describing a generic extension mechanism for HTTP. Among other things, the HTTP extension framework adds the M-POST method, where M stands for mandatory. An HTTP request is called a mandatory request if it includes at least one mandatory extension declaration. Include a mandatory extension declaration by using the Man or the C-Man header fields. The method name of a mandatory request must be prefixed by M-, hence the mandatory POST method is called M-POST.

SOAP 1.0 required that a client start off with an HTTP POST request and send an M-POST request only if the server returned an HTTP error 510. SOAP 1.1 places no such restriction on a client, thus allowing it to start off with either request type. Below is the same request that we've considered so far presented in M-POST form:

Listing 12

M-POST http://www.SmartHello.com/HelloApplication HTTP/1.1
Content-Type: text/xml; charset="utf-8"
Content-Length: 587
Man: "http://schemas.xmlsoap.org/soap/envelope/"; ns=01
01-SOAPAction: "http://www.SmartHello.com/HelloApplication#sayHelloTo"
<SOAP-ENV:Envelope 
                       xmlns:SOAP-ENV="
http://schemas.xmlsoap.org/soap/envelope/" 
                       xmlns:xsi="
http://www.w3.org/1999/XMLSchema-instance" 
                       xmlns:xsd="http://www.w3.org/1999/XMLSchema">
     <SOAP-ENV:Header>
     </SOAP-ENV:Header>
    <SOAP-ENV:Body>
         <ns1:sayHelloTo 
                      xmlns:ns1="Hello" 
                     SOAP-ENV:encodingStyle="
http://schemas.xmlsoap.org/soap/encoding/">
             <name xsi:type="xsd:string">Tarak</name>
         </ns1:sayHelloTo>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


As far as the actual SOAP message goes, Listing 12 doesn't differ from Listing 10. The header does feature a few dissimilarities. For example, instead of a POST request, we have an M-POST request. As described above, every mandatory HTTP request such as M-POST requires at least one mandatory extension declaration. Here we have one: the Man field describes a mandatory end-to-end extension declaration and maps the header-prefix 01 to the namespace http://schemas.xmlsoap.org/soap/envelope/. Note how this prefix is attached to the SOAPAction field.

Once the server processes the request, it will return a response to the client that looks like the code below (assuming that there are no errors):

Listing 13

HTTP/1.0 200 OK
Ext:
Content-Type: text/xml; charset="utf-8"
Content-Length: 615
<SOAP-ENV:Envelope 
                       xmlns:SOAP-ENV="
http://schemas.xmlsoap.org/soap/envelope/"               
                       xmlns:xsi="
http://www.w3.org/1999/XMLSchema-instance" 
                       xmlns:xsd="http://www.w3.org/1999/XMLSchema">
     <SOAP-ENV:Body>
           <ns1:sayHelloToResponse 
                      xmlns:ns1="Hello" 
                      SOAP-ENV:encodingStyle="
http://schemas.xmlsoap.org/soap/encoding/">
                <return xsi:type="xsd:string">Hello John, How are
you doing?</return>
          </ns1:sayHelloToResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


Again, the response in Listing 13 resembles the one returned for a POST request -- shown in Listing 11 -- except for the Ext field.

In using SOAP via HTTP, it is interesting to see that the actual SOAP message (the SOAP envelope and everything within it) always remains the same as the message with no protocol. That fact can be extrapolated to conclude that HTTP is not the only protocol that SOAP works with. For example, SOAP can easily work with the SMTP or any custom homegrown protocol. The only requirement is that both sides -- the client and the server -- understand the protocol.

SOAP does not define everything

So far I've discussed different aspects that SOAP defines, but there are a number of areas that SOAP does not define. The authors of the SOAP specification explicitly exclude the more involved aspects of building an object model, as well as anything that's already been built. The reason for that can be found upon examining the goals of SOAP. Besides extensibility, a major design goal of SOAP is simplicity. To keep SOAP simple, the authors decided to define only those aspects that were absolutely critical for creating a lightweight protocol. For example, SOAP does not define/specify anything about distributed garbage collection, type safety or versioning, bidirectional HTTP communications, message-box carrying or pipeline processing, object-by-reference, or no-object activation. SOAP is meant to be simple -- a protocol a developer could implement in a couple of days using any programming language on any operating system. When you think about it, this is actually a blessing since SOAP can easily be adapted to existing technologies for building distributed systems, even technologies as different as CORBA and DCOM.

Until next time ...

In this article I introduced you to the basics of SOAP and discussed some of the reasons behind its design. But this is only the tip of the SOAP iceberg. To find out more about SOAP, refer to the Resources section for a link to the SOAP specification. As far as this series goes, what I've included here is all you need to know about the specification.

In Part 2, I will introduce you to Apache's SOAP implementation. With that implementation, you will create a simple distributed application that uses SOAP as the wire protocol.

About the author

A certified Java programmer, Tarak Modi is an architect at North Highland, which specializes in management and technology consulting. He has a master's degree in computer engineering and an MBA concentrating in information systems. He has several years of experience working with C++ and Java and technologies such as DCOM, CORBA, RMI, and EJB. He has written articles for leading software magazines including JavaWorld and is currently working on a book on Java Message Service with Manning Publications. To find out more about Tarak, his articles, and upcoming book, please visit his Website at http://tmodi.home.att.net/

Read more about Enterprise Java in JavaWorld's Enterprise Java section.

  • Print
  • Feedback

Resources