Home > Articles > Programming > Java

XML and Web Services: Understanding SOAP

There have been several proposals to use XML in the field of Web services, but one of the most promising standards is SOAP: the Simple Object Access Protocol. This article introduces you to the SOAP protocol.
This article is excerpted from Java Web Services Unleashed (Sams, 2002: 067232363X), by Benoit Marchal, Robert J. Brunner, Frank Cohen, Francisco Curbera, Darren Govoni, Steven Haines, Matthias Kloppmann, K. Scott Morrison, Arthur Ryman, Mark Wutka, and Joseph Weber.
This chapter is from the book

This chapter is from the book

Some technologies, such as MP3, serve a very specific and well-defined purpose. MP3 is an audio file format specific for audio information, whereas XML, on the other hand, is a versatile technology that is used in a variety of solutions, including audio, voice, and data.

One of those solutions is the specific file format for application integration that is associated with Web services. As you will see, there have been several proposals to use XML in the field of Web services, but one of the most promising standards is SOAP, the Simple Object Access Protocol. This article introduces you to the SOAP protocol.

History of SOAP

SOAP connects two fields that were previously largely unrelated: application middleware and Web publishing.

Consequently, depending on whether your background is in middleware or Web publishing, you might understand SOAP slightly differently. Yet it's important to realize that it is neither pure middleware nor is it pure Web publishing; it really is the convergence of the two.

The best approach to understanding the dual nature of SOAP is a historical one. If you review the concepts and trends that led to the development of SOAP, you will be better prepared to study it.

RPCs and Middleware

One of the goals of SOAP is to use XML to enable remote procedure calls (RPCs) over HTTP. Originally, RPC was developed by the Open Group (http://www.opengroup.org) as part of its Distributed Computing Environment (DCE).

When writing distributed applications, programmers spend a disproportionate amount of time implementing network protocols: opening and closing sockets, listening on ports, formatting requests, decoding responses, and more. RPC offers an easier alternative. Programmers simply write regular procedure calls and a pre-compiler generates all the protocol-level code to call those procedures over a network.

Even if you have never used RPC, you might be familiar with its modern descendants: CORBA (Common Object Request Broker Architecture), DCOM (Distributed Component Object Model), and RMI (Remote Method Invocation). Although the implementations differ (and they are mostly incompatible), CORBA, DCOM, and RMI offer what is best described as an enhanced, object-oriented mechanism of implementing RPC functionality.

Listing 1 is the interface to a remote server object that uses RMI. As you can see, it's not very different from a regular interface. The only remarkable aspect is that it extends the java.rmi.Remote interface and every method can throw java.rmi.RemoteException exceptions.

Listing 1—RemoteBooking.java

package com.psol.resourceful;

import java.util.Date;
import java.rmi.Remote;
import java.rmi.RemoteException;

public interface RemoteBooking
  extends Remote {
  public Resource[] getAllResources()
    throws RemoteException;
  public Resource[] getFreeResourcesOn(Date start,
                     Date end)
    throws RemoteException;
  public void bookResource(int resource,
               Date start,
               Date end,
               String email)
    throws RemoteException;
}

Where's the network code? There is none beyond what's necessary to extend the Remote interface. That's precisely the beauty of middleware: All you have to do is designate certain objects as remote and the middleware takes care of all the networking and protocol aspects for you. The way you designate remote objects varies depending on the actual technology (CORBA, RMI, or DCOM) you're using.

The Downside of Middleware

It's not all rosy with middleware, though. It has been successfully implemented on private networks (LANs, intranets, and the like) but has not been so successful on the Internet at large.

One of the issues is that middleware uses its own protocols and most firewalls are configured to block non-HTTP traffic. You have to reconfigure your firewall to authorize those communications. Oftentimes those changes prove incompatible with the corporate security policy.

Another issue is that middleware successfully addresses only one half of the equation: programming. It's not as good with the other half: deployment. Middleware significantly reduces the burden on the programmer writing distributed applications, but it does little to ease the deployment. In practice, it is significantly easier to deploy a Web site than to deploy a middleware-based application.

Most organizations have invested in Web site deployment. They have hired and trained system administrators that deal with the numerous availability and security issues. They are therefore reluctant to invest again in deploying another set of servers.

As you will see in a moment, SOAP directly addresses both issues. It borrows many concepts from middleware and enables RPC, but it does so with a regular Web server, which lessens the burden on system administrators.

RSS, RDF, and Web Sites

In parallel, the World Wide Web has evolved from a simple mechanism to share files over the Internet into a sophisticated infrastructure. The Web is universally available, and it is well understood and deployed in almost every company—small and large. The Web's success traces back to the ease with which you can join. You don't have to be a genius to build a Web site, and Web hosts offer a simple solution to deployment.

Obviously, the Web addresses a different audience than middleware, because it is primarily a publishing solution that targets human readers. RPC calls are designed for software consumption.

Gradually the Web has evolved from a pure human publishing solution into a mixed mode where some Web pages are geared toward software consumption. Most of those pages are built with XML.

RSS Documents

RSS is a good example of the using XML to build Web sites for software rather than for humans. RSS, which stands for RDF Site Summary format, was originally developed by Netscape for its portal Web site. An RSS document highlights the main URLs in a Web vocabulary. Listing 2 is a sample RSS document.

Listing 2—index.rss

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns="http://purl.org/rss/1.0/">
  <channel rdf:about="http://www.marchal.com/index.rss">
    <title>marchal.com</title>
    <link>http://www.marchal.com</link>
    <description>
      Your source for XML, Java and e-commerce.
    </description>
    <image rdf:resource="http://www.marchal.com/images/buttons/
       marchal.jpg"/>
    <items>
      <rdf:Seq>
        <rdf:li resource="http://www.marchal.com/go/xbe"/>
        <rdf:li resource="http://www.pineapplesoft.com/newsletter"/>
      </rdf:Seq>
    </items>
  </channel>
  <image rdf:about="http://www.marchal.com/images/buttons/marchal.jpg">
    <title>marchal.com</title>
    <link>http://www.marchal.com</link>
    <url>http://www.marchal.com/images/buttons/marchal.jpg</url>
  </image>
  <item rdf:about="http://www.marchal.com/go/xbe">
    <title>XML by Example</title>
    <link>http://www.marchal.com/go/xbe</link>
    <description>
      Introduction to XML. Discover the practical applications
      of XML, and see examples that include e-Commerce and SOAP.
    </description>
  </item>
  <item rdf:about="http://www.pineapplesoft.com/newsletter">
    <title>Pineapplesoft Link</title>
    <link>http://www.pineapplesoft.com/newsletter</link>
    <description>
      A free email magazine. Each month it discusses technologies,
      trends, and facts of interest to web developers.
    </description>
  </item>

</rdf:RDF>

As you can see, Listing 2 defines a channel with two items and one image. The two items are further defined with a link and a short description. The portal picks this document up and integrates it into its content.

Other applications of RSS include distributing newsfeeds. The items summarize the news and link to articles that have more details. See http://www.moreover.com for an example.

Although they are hosted on Web sites, RSS documents differ from plain Web pages. RSS goes beyond downloading information for browser rendering. A server downloads the RSS file and most likely integrates it in a database.

Making Requests: XML-RPC

The next logical step is to merge middleware with XML and the Web. How to best characterize the result depends on your point of view. To the Web programmer, adding XML to Web sites is like enhancing Web publishing with a query/response mechanism. But to the middleware programmer, it appears as if middleware had been enhanced to be more compatible with the Web and XML.

This is another illustration of XML being used to connect two fields (Web publishing and middleware) that were previously unrelated.

One of the earliest such implementations is probably XML-RPC. From a bird's-eye view, XML-RPC is similar to regular RPC, but the binary protocol used to carry the request on the network has been replaced with XML and HTTP.

Listing 3 illustrates an XML-RPC request. The client is remotely calling the getFreeResourcesOn(). The equivalent call in Java would have been written as:

BookingService.getFreeResourcesOn(startDate,endDate);

As you can see in Listing 3, XML-RPC packages the call in an XML document that is sent to the server through an HTTP POST request.

Listing 3—An XML-RPC Request

POST /xmlrpc HTTP/1.0
User-Agent: Handson (Win98)
Host: joker.psol.com
Content-Type: text/xml
Content-length: 468

<?xml version="1.0"?>
<methodCall>
  <methodName>com.psol.resourceful.BookingService.
    getFreeResourcesOn</methodName>
  <params>
    <param>
      <value>
        <dateTime.iso8601>2001-01-15T00:00:00</dateTime.iso8601>
      </value>
    </param>
    <param>
      <value>
        <dateTime.iso8601>2001-01-17T00:00:00</dateTime.iso8601>
      </value>
    </param>
  </params>
</methodCall>

Without going into all the details, the elements in Listing 3 are

  • methodCall, which is the root of the RPC call;

  • methodName, which states which method is to be called remotely;

  • params, which contains one param element for every parameter in the procedure call;

  • param, to encode the parameters;

  • value, an element that appears within param and holds its value;

  • dateTime.iso8601, which specifies the type of the parameter value.

XML-RPC defines a handful of other types, including:

  • i4 or int for a four-byte signed integer;

  • boolean, with the value of 0 (false) or 1 (true);

  • string, a string;

  • double, for double-precision signed floating point numbers;

  • base64, for binary streams (encoded in base64).

XML-RPC also supports arrays and structures (also known as records) through the array and struct elements.

Note one major difference between Listing 3 and Listing 2: the former is a request made to a server. XML-RPC goes beyond downloading files; it provides a mechanism for the client to send an XML request to the server.

Obviously, the server reply is also encoded in XML. It might look like Listing 4.

Listing 4—An XML-RPC Encoded Response

HTTP/1.0 200 OK
Content-Length: 485
Content-Type: text/xml
Server: Jetty/3.1.4 (Windows 98 4.10 x86)

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
        <array>
          <data>
            <value><string>Meeting room 1</string></value>
            <value><string>Meeting room 2</string></value>
            <value><string>Board room</string></value>
          </data>
        </array>
      </value>
    </param>
  </params>
</methodResponse>

From XML-RPC to SOAP

XML-RPC is simple and effective, but early on its developers (Microsoft, Userland, and Developmentor) realized that they could do better.

Indeed XML-RPC suffers from four serious flaws:

  • There's no clean mechanism to pass XML documents themselves in an XML-RPC request or response. Of course the request (or response) is an XML document, but what if you issue a call to, say, a formatter? How do you pass the XML document to the formatter? As you have seen, "XML document" is not a type for XML-RPC. In fact, to send XML documents, you would have to use strings or base64 parameters, which requires special encoding and is therefore suboptimal.

  • There's no solution that enables programmers to extend the request or response format. For example, if you want to pass security credentials with the XML-RPC call, the only solution is to modify your procedure and add one parameter.

  • XML-RPC is not fully aligned with the latest XML standardization. For example, it does not use XML namespaces, which goes against all the recent XML developments. It also defines its own data types, which is redundant with Part 2 of the XML schema recommendation;

  • XML-RPC is bound to HTTP. For some applications, another protocol, such as Simple Mail Transfer Protocol (SMTP, the email protocol), is more sensible.

With the help of IBM, the XML-RPC designers upgraded their protocol. The resulting protocol, SOAP, is not as simple as XML-RPC, but it is dramatically more powerful. SOAP also broadens the field to cover applications that are not adequately described as remote procedure calls.

NOTE

Does SOAP make XML-RPC irrelevant? Yes and no. Most recent developments take advantage of SOAP's increased flexibility and power, but some developers still prefer the simpler XML-RPC protocol.

Listing 5 is the SOAP equivalent to Listing 3. Decoding the SOAP request is more involved than decoding an XML-RPC request, so don't worry if you can't read this document just yet. You learn how to construct SOAP requests in the next section.

Listing 5—A SOAP Request

POST /soap/servlet/rpcrouter HTTP/1.0
Host: joker.psol.com
Content-Type: text/xml; charset=utf-8
Content-Length: 569
SOAPAction: "http://www.psol.com/2001/soapaction"

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/1999/XMLSchema"
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<SOAP-ENV:Body>
<ns1:getFreeResourcesOn xmlns:ns1="http://www.psol.com/2001/resourceful"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<start xsi:type="xsd:timeInstant">2001-01-15T00:00:00Z</start>
<end xsi:type="xsd:timeInstant">2001-01-17T00:00:00Z</end>
</ns1:getFreeResourcesOn>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Listing 6 is the reply, so it's the SOAP equivalent to Listing 4. Again, don't worry if you don't understand this listing; you will learn how to decode SOAP requests and responses in a moment.

Listing 6—A SOAP Response

HTTP/1.0 200 OK
Server: Jetty/3.1.4 (Windows 98 4.10 x86)
Servlet-Engine: Jetty/3.1 (JSP 1.1; Servlet 2.2; java 1.3.0)
Content-Type: text/xml; charset=utf-8
Content-Length: 704

<?xml version='1.0' encoding='UTF-8'?>
<env:Envelope xmlns:xsd="http://www.w3.org/1999/XMLSchema"
   xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<env:Body>
<ns1:getFreeResourcesOnResponse
   xmlns:ns1="http://www.psol.com/2001/resourceful"
   env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<return xmlns:ns2="http://schemas.xmlsoap.org/soap/encoding/"
     xsi:type="ns2:Array" ns2:arrayType="ns1:String[3]">
<item xsi:type="xsd:string">Meeting room 1</item>
<item xsi:type="xsd:string">Meeting room 2</item>
<item xsi:type="xsd:string">Board room</item>
</return>
</ns1:getFreeResourcesOnResponse>
</env:Body>
</env:Envelope>

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.

Overview


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information


To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.

Surveys

Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.

Newsletters

If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information


Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.

Security


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.

Children


This site is not directed to children under the age of 13.

Marketing


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information


If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.

Choice/Opt-out


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information


Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents


California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure


Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.

Links


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact


Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice


We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020