Home > Articles > Programming > Java

Building Web Services with Java: SOAP

Learn how to use SOAP straight out of the box, and how to extend SOAP in multiple ways to support your diverse and changing needs. Steve Graham et al apply design best practices to build several meaningful e-commerce Web services, and prepare you to climb still higher toward the top of the Web services interoperability stack.
This sample chapter is excerpted from Building Web Services with Java: Making Sense of XML, SOAP, WSDL, and UDDI, by Steve Graham, Toufic Boubez, Glen Daniels, Doug Davis, Yuichi Nakamura, Ryo Neyama, and Simeon Simeonov.
This chapter is from the book

There is a lot more to Web services than Simple Object Access Protocol (SOAP). Chapter 1, "Web Services Overview," introduced the Web services interoperability stack that went several levels higher than SOAP. SOAP is synonymous with Web services, however, because since its introduction in late 1999, it has become the de facto standard for Web services messaging and invocation. With competitive and market pressures driving the Web services industry in a hard race to provide meaningful solutions to cross-enterprise integration problems, SOAP is the go-to-market technology of choice.

What is SOAP all about, you ask? Will it save you from failure (and keep you clean) while you toil 80-hour work weeks on a business-to-business (B2B) integration project from hell? Will it support your extensibility needs as requirements change, and provide you with interoperability across multi-vendor offerings? Will it be the keyword on your resume that will guarantee you a big raise as you switch jobs? In short, is it the new new thing? Well, maybe.

SOAP is so simple and so flexible that it can be used in many different ways to fit the needs of different Web service scenarios. This is both a blessing and a curse. It is a blessing because chances are that SOAP can fit your needs. It is a curse because you probably won't know how to make it do that. This is where this chapter comes in. When you are through with it, you will know not only how to use SOAP straight out of the box, but also how to extend SOAP in multiple ways to support your diverse and changing needs. You will also have applied design best practices to build several meaningful e-commerce Web services for our favorite company, SkatesTown. Last but not least, you will be ready to handle the rest of the book and climb still higher toward the top of the Web services interoperability stack. To this end, the chapter will discuss the following topics:

  • The evolution of XML protocols and the history and motivation behind SOAP's creation

  • The SOAP envelope framework, complete with discussions of versioning, header-based vertical extensibility, intermediary-based horizontal extensibility, error handling, and bindings to multiple transport protocols

  • The various mechanisms for packaging information in SOAP messages, including SOAP's own data-encoding rules and a number of heuristics for putting just about any kind of data in SOAP messages

  • The use of SOAP within multiple distributed system architectures such as RPC- and messaging-based systems in all their flavors

  • Building and consuming Web services using the Java-based Apache Axis Web services engine

One final note before we begin. The SOAP 1.1 specification is slightly over 40 pages long. This chapter is noticeably longer, because the purpose of this book is to be something more than an annotated spec or a tutorial for building Web services. We've tried hard to create a thorough treatment of Web services for people who want answers to questions that begin not only with "what" and "how" but also with "why." To become an expert at Web services, you need to be comfortable dealing with the latter type of questions. We are here to help.

So, why SOAP? As this chapter will show, SOAP is simple, flexible, and highly extensible. Because it is XML based, SOAP is programming language, platform, and hardware neutral. What better choice for the XML protocol that is the foundation of Web services? To prove this point, let's start the chapter by looking at some of the earlier work that inspired SOAP.

Evolution of XML Protocols

The enabling technology behind Web services is built around XML protocols. XML protocols govern how communication happens and how data is represented in XML format on the wire. XML protocols can be broadly classified into two generations. First-generation protocols are based purely on XML 1.0. Second-generation protocols take advantage of both XML Namespaces and XML Schema. SOAP is a second-generation XML protocol.

First-Generation XML Protocols

There were many interesting first-generation XML protocol efforts. They informed the community of important protocol requirements and particular approaches to satisfying these requirements. Unfortunately, very few of the first-generation XML protocols achieved multi-vendor support and broad adoption. Two are worth mentioning: Web Distributed Data Exchange (WDDX) and XML-RPC.

WDDX

WDDX provides a language- and platform-neutral mechanism for data exchange between applications. WDDX is perfect for data syndication and remote B2B integration APIs because it is all about representing data as XML. For example, Moreover Technologies, the Web feed company, exposes all its content through a WDDX-based remote API. Access http://moreover.com/cgi-local/page?index+wddx with an XML-aware browser such as Internet Explorer and you will get a WDDX packet with current headline news. A simplified version of the packet is shown in the following example. You can see from it that the data format is a recordset (tabular data) with three fields containing the URL to the full article, its headline text, and the publishing source:

<wddxPacket version="1.0">
   <header/>
   <data>
      <recordset rowCount="2" fieldNames="url,headline_text,source">
         <field name="url">
            <string>http://c.moreover.com/click/here.pl?x22535276</string>
            <string>http://c.moreover.com/click/here.pl?x22532205</string>
         </field>
         <field name="headline_text">
            <string>Firefighters hold line in Wyoming</string>
            <string>US upbeat as China tensions ease</string>
         </field>
         <field name="source">
            <string>CNN</string>
            <string>BBC</string>
         </field>
      </recordset>
   </data>
</wddxPacket>

Allaire Corporation (now Macromedia, Inc.) created WDDX in 1998. WDDX is currently supported in many environments and is flexible enough to handle most useful datatypes (strings, numbers, booleans, date/time, binary, arrays, structures, and recordsets), but it cannot represent arbitrary data in XML. It is an epitome of the 80/20 rule: flexible enough to be useful yet simple enough to be broadly supported. Because WDDX is not bound to any particular transport, applications can exchange WDDX packets via HTTP, over e-mail, or by any other means. Many applications persist data as XML in a relational database using WDDX.

XML-RPC

XML-RPC is an RPC protocol introduced in the market in 1998 by Userland. XML-RPC supports a set of datatypes similar to that supported by WDDX and uses HTTP as the underlying transport protocol. Because of its simplicity, XML-RPC enjoyed good multi-vendor support. Here's an example XML-RPC method call and response:

<methodCall>
   <methodName>NumberToText</methodName>
   <params>
      <param>
         <value><i4>28</i4></value>
      </param>
   </params>
</methodCall>
...
<methodResponse>
   <params>
      <param>
         <value><string>twenty-eight</string></value>
      </param>
   </params>
</methodResponse>

First-Generation Problems

Although first-generation XML protocols have been and still are very useful, their simplicity and reliance on XML 1.0 alone causes some problems.

First-generation protocols are not very extensible. The protocol architects had to reach agreement before any changes were implemented, and the protocol version had to be revved up in order to let tools distinguish new protocol versions from old ones and handle the XML appropriately. For example, when XML-RPC and WDDX added support for binary data, both protocols had to update their specifications, and the protocol implementations on all different languages and platforms supporting the protocols had to be updated. The overhead of constantly revising specifications and deploying updated tools for handling the latest versions of the protocols imposed limits on the speed and scope of adoption of first-generation protocols. Second-generation protocols address the issue of extensibility with XML namespaces.

The second problem with first-generation protocols had to do with datatyping. First-generation XML protocols stuck to a single Document Type Definition (DTD) to describe the representation of serialized data in XML. In general, they used just a few XML elements. This approach made building tools supporting these protocols relatively easy. The trouble with such an approach is that the XML describing the data in protocol messages expressed datatype information and not semantic information. In other words, to gain the ability to represent data in XML, first-generation XML protocols went without the ability to preserve information about the meaning of the data. Second-generation XML protocols use XML schema as a mechanism to combine descriptive syntax with datatype information.

To sum things up, the need to provide broad extensibility without centralized standardization and the need to combine datatype information with semantic information were the driving forces behind the effort to improve upon first-generation efforts and to create SOAP, the de facto standard XML protocol for modern Web services and B2B applications.

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