Understanding Web Services

This chapter is from the book

JSP and XML: Integrating XML and Web Services in Your JSP Application

Learn More Buy

This chapter is from the book

This chapter is from the book 

JSP and XML: Integrating XML and Web Services in Your JSP Application

Learn More Buy

The ABCs of Web Services

While building a Web service might be simple, getting started is very confusing. There exists an entire universe of initiatives, products, and APIs to sort through. If as a new user you are confused by this alphabet soup muddle, don't despair; things are getting better and more concise in the Web services development arena. The best news is that as a developer, you will only have to know a few critical pieces to make things work.

As stated earlier, much of what it takes to build a Web service will be automated in the future. In addition, higher-level APIs that hide the complexity of Web service infrastructure are being developed. Your programming style will determine when you should consider building Web services. For programmers who want full control and need to know the entire picture, now is the time to dive in. If you are more of a business-level programmer (concentrating mainly on your business requirements), you can wait a few months for the tools to catch up so that you can concentrate mainly on the business logic rather than the lower-level details of Web services.

First, let's look at how things work when everything is in action. Figure 3.1 gives an overview.

Figure 3.1 Overview of a Web service.

Let's review the steps involved in using a Web service, as shown in Figure 3.1.

1. A Web service provider registers a Web service. This can be done either manually or automatically through code.

2. A user requests a Web page.

3. The Web application accesses a Web service. If the service client already knows about the Web service, it directly accesses the Web service (step 3a). However, if the Web service cannot be found, the service client can query to discover/rediscover an appropriate Web service to use (step 3b). Once done, the client can re-query a Web service with the revised information.

4. The Web service processes the request.

5. The results of the execution of the Web service are sent back to the requesting client.

6. The Web service results are incorporated into the final page.

7. The client receives a Web page, not realizing that the application ever used a Web service.

The Basic Building Blocks

A Web service consists of several components. This section will review the components that make up an average Web service.

XML

Without XML, Web services would not have been possible. Virtually every aspect of a Web service uses XML in some manner. As an example, sending a message to invoke a Web service uses SOAP (Simple Object Access Protocol), which is entirely built on top of XML.

SOAP (Simple Object Access Protocol)

After XML, the second most important piece in the Web service puzzle is SOAP. This is a protocol for transferring queries and responses used by a Web service. Like the XML and HTML specifications, SOAP is maintained by the World Wide Web Consortium (W3C). The W3C's goal is to develop interoperable specifications and guidelines. The W3C defines SOAP as an XML-based protocol to exchange information in a decentralized and distributed environment.

SOAP has three parts:

1. The first part is an envelope in which a message is contained. This envelope is important as it does more than just hold a message.

The envelope also

• Describes what is in the message (sounds like XML, doesn't it? Self-describing envelopes...)

• Contains rules on how to process the message

• Includes information on which Web service should respond to the message

• Contains information that indicates whether responding to the message is optional or mandatory

The SOAP envelope gives quite a bit of information to the receiving Web service. With the data received, a Web service is able to determine whether it should process a SOAP service request or not.

2. SOAP also has a set of encoding rules to define special Web service–defined data types. This feature is helpful, as it allows the definition of unique data types for a service. Any data that can be described as an XML structure can be embedded and used within a SOAP message.

3. SOAP includes rules for describing the exposed methods of a Web service. This includes a structure for the description of the calls and responses of a Web service.

SOAP allows a program to invoke a service through the interchange of messages. It permits entities to invoke each other's exposed methods regardless of the programming language or network used to build and host the entities. An entity is anything that invokes a SOAP call, such as an application, a Web service, or any program.

SOAP can use any combination of other protocols for transporting messages between Web services. However, HTTP (Hypertext Transfer Protocol) is the protocol of choice for delivering messages. HTTP is the underlying protocol used by the World Wide Web. It defines how messages are transmitted and formatted and what actions Web servers should take in response. HTTP is favored due to its widespread availability and its ability to navigate through obstacles such as firewalls.

A simple SOAP message might appear as in Listing 3.1.

Listing 3.1 A Simple SOAP Message

<SOAP:Envelope
 xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
 SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP:Body>
    <EXAMPLE:getBookPublisher xmlns:EXAMPLE="Example-URI">
      <title>JSP and XML</title>
    </EXAMPLE: getBookPublisher >
  </SOAP:Body>
</SOAP:Envelope>

In this example, the element <SOAP:Envelope> encloses the entire message, which is contained within the <SOAP:Body> element. Also note that in the envelope tag, the SOAP:encodingStyle attribute indicates the encoding specification of the message. That is, when a SOAP server validates this message, it can refer to the schema found at http://schemas.xmlsoap.org/soap/encoding/ to find the rules with which this message was encoded. For this example, we are accessing a fictitious Web service method called getBookPublisher. For this method, the example passes the value JSP and XML into the <title> element, which acts as a return parameter called title.

To complete this example, let's imagine that a Web service responded to the example message. A response might look like the one in Listing 3.2.

Listing 3.2 A SOAP Response Message

<SOAP:Envelope
 xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
 SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP:Body>
    <EXAMPLE:getBookPublisherResponse xmlns:EXAMPLE="Example-URI">
      <name>SAMS Publishing INC.</name>
    </EXAMPLE:getBookPublisherResponse >
  </SOAP:Body>
</SOAP:Envelope>

The routing of the SOAP message is handled by another protocol. This example doesn't demonstrate the protocol with which the message is transported. As stated earlier, HTTP is the preferred protocol for transferring SOAP messages.

SOAP has clients and servers. A SOAP server is an application waiting to process requests from a SOAP client. The SOAP server will interpret incoming SOAP requests and convert them into a format that the receiving process can use. Any request that the server cannot process will be rejected. A SOAP client is any application or piece of code sending a SOAP message to be processed by the server.

Another important term within SOAP is RPC (Remote Procedure Calls). RPC is a method of writing the procedure calls and responses that are found in SOAP messages. RPC enables a client to invoke a procedure call on a server. The client program sends a message to the server with the appropriate arguments for the method being called. Then the server returns a message containing the results of the program executed. In essence, RPC is a format through which these procedure calls and responses must be made. While we could just use SOAP to send messages between applications and act on the messages, using SOAP RPC gives a well defined method of declaring parameters and methods to be accessed over a SOAP message.

To use SOAP, we will need a server or API that implements the SOAP protocol. The Java API section of this chapter will go into more detail on two common SOAP tool implementations.

Before concluding our discussion of SOAP, we need to discuss security. SOAP frequently uses text-based XML and HTTP. This effectively means that any message transported with SOAP is exposed for the world to view. Currently, two simple solutions exist to protect sensitive data placed within a SOAP envelope.

1. Use SSL (Secure Sockets Layer) to transmit the messages back and forth. SSL is a protocol designed to transfer private documents over the Internet. The disadvantage of SSL relates to performance considerations. Simply put, security comes at the price of speed. Also, sometimes system architecture can have security ramifications for an SSL solution.

2. Encrypt the data that is wrapped within the SOAP message. The disadvantage of this method is that a Web service must be expecting the encrypted data and therefore can only be used with specific Web services designed to use encryption.

An in-depth security discussion is beyond the scope of this chapter. However, you should consider the following piece of advice: If you need high security in your Web service transactions, the security needs to be addressed at the start of your project.

For more information on SOAP refer to the SOAP Web site at http://www.w3.org/TR/SOAP.

WSDL (Web Service Description Language)

WSDL is an XML-formatted language for describing Web services. WSDL is a standard maintained by the W3C, and was originally proposed by Ariba, IBM, and Microsoft. The strength of WSDL lies in its ability to describe a Web service in a standard way. While we can use SOAP to access and query a Web service, we still need a way to determine the capabilities of the Web service. WSDL performs this task. By querying a Web service registry, we can obtain the WSDL document stored there. Through this document, we can retrieve information regarding the Web service in question. It is this information that will allow the client to determine what methods to call, how to use them, and where to direct those requests.

The real meat of WSDL is the document definition of the standard XML document used to describe the Web service. So let's look at an example WSDL file and review the high points of the document. The example WSDL file used here will be from a Web service that we will access later in the chapter. The WSDL definition can be found at the XMethods Web site (http://www.xmethods.net/). This site has a simple registry that publishes a list of Web services. From this list, the service selected is called "TemperatureService" and is geared at getting the current temperature at a zip code. The WSDL document for this service appears in Listing 3.3.

Listing 3.3 XMethods TemperatureService WSDL File

<?xml version="1.0" ?>
<definitions name="TemperatureService"
      targetNamespace="http://www.xmethods.net/sd/TemperatureService.wsdl"
      xmlns:tns="http://www.xmethods.net/sd/TemperatureService.wsdl"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
      xmlns="http://schemas.xmlsoap.org/wsdl/">

<message name="getTempRequest">
    <part name="zipcode" type="xsd:string" />
</message>

<message name="getTempResponse">
   <part name="return" type="xsd:float" />
</message>

<portType name="TemperaturePortType">
   <operation name="getTemp">
       <input message="tns:getTempRequest" />
       <output message="tns:getTempResponse" />
   </operation>
</portType>

<binding name="TemperatureBinding" type="tns:TemperaturePortType">
 <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" />
 <operation name="getTemp">
   <soap:operation soapAction="" />
   <input>
    <soap:body use="encoded" namespace="urn:xmethods-Temperature"
         encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
   </input>
   <output>
    <soap:body use="encoded" namespace="urn:xmethods-Temperature"
         encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
   </output>
 </operation>
</binding>

<service name="TemperatureService">
   <documentation>Returns current temperature in a given U.S. zip code
   </documentation>
   <port name="TemperaturePort" binding="tns:TemperatureBinding">
    <soap:address
     location="http://services.xmethods.net:80/soap/servlet/rpcrouter" />
   </port>
</service>
</definitions>

Now let's walk through this XML document to highlight the various sections of a WSDL service document. This discussion is just a brief introduction to a few critical elements needed to translate the information from a WSDL document for use in a Web service invocation.

The initial high-level definition of the Web service is placed within the service element:

<service name="TemperatureService">

The document subelement gives us a description of the service:

     <documentation>Returns current temperature in a given U.S. zipcode
     </documentation>

The port subelement defines where the service resides. Each port will have a unique name and binding attribute. The binding attribute must match to a previous binding element:

     <port name="TemperaturePort" binding="tns:TemperatureBinding">

The location attribute gives us the URL to access this service:

     <soap:address
     location="http://services.xmethods.net:80/soap/servlet/rpcrouter" />
   </port>
</service>

Next, we need a way to specify the messages being sent around. The binding element defines the SOAP message format, protocols (SMTP, HTTP, and so on), messages the service will use (typically a request and response). The soap:binding subelement binds a SOAP envelope format to match to the Web service. Since we are using SOAP, the soap:binding element is a required element. To summarize, the binding takes the abstract information required for the calls to and from the Web service and produces a real physical model of the messages to be sent to and from the service.

Here's how the binding element works:

<binding name="TemperatureBinding" type="tns:TemperaturePortType">

The transport attribute indicates the protocol to use, in this case HTTP:

 <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" />

An operation matches to each method the Web service exposes for use:

   <operation name="getTemp">

The soapAction is an HTTP header the client sends when invoking the service:

     <soap:operation soapAction="" />

The message the Web service expects to receive to initiate this method is defined within the input element:

     <input>

The namespace is a unique URI used to reference the service method:

    <soap:body use="encoded" namespace="urn:xmethods-Temperature"
         encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
   </input>

The message the Web service sends back out from this method is defined within the output element:

   <output>
    <soap:body use="encoded" namespace="urn:xmethods-Temperature"
         encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
   </output>
   </operation>
 </binding>

Now let's look at how WSDL defines what methods are available from a Web service. The portType element defines a collection of all methods that the Web service exposes to the world. (Each operation matches a method.) In relation to SOAP, all operations have an input and output message that needs to be defined for use. Finally, the binding element shown previously will further define the operations first referenced in portType:

 <portType name="TemperaturePortType">
     <operation name="getTemp">
         <input message="tns:getTempRequest" />
         <output message="tns:getTempResponse" />
     </operation>
 </portType>

The final piece to examine is how to define the parameters being sent back and forth within the messages. The message element, shown in the following code, defines the parameters that must be embedded within a message. For us, this translates to the method arguments and return values.

The first thing to notice is that the name matches a message attribute defined with the portType:

 <message name="getTempRequest">

This message has a parameter called zipcode of type string:

      <part name="zipcode" type="xsd:string" />
 </message>

This message also returns a value of type float:

 <message name="getTempResponse">
     <part name="return" type="xsd:float" />
 </message>

The key to learning and understanding WSDL is just working through the WSDL document specification. For more information, you can refer to the WSDL Web site at http://www.w3.org/TR/wsdl.

Service Management Initiatives

Once you've built a Web service, oftentimes you also want a way to let others know about it. This section will review the current options for listing a Web service for public access.

UDDI

Universal Description, Discovery, and Integration (UDDI) is a distributed directory that allows businesses to list themselves on the Internet. This directory is found on the Web, and, like the white and yellow pages of a phone book, enables businesses to find each other.

UDDI was started by Ariba, IBM, and Microsoft. The UDDI framework defines what Web-based services a business offers and creates a global registry specifically geared towards business-to-business electronic commerce. The core of the UDDI business registration is an XML file describing a business and any Web service it might provide. UDDI acts as an electronic phone book that provides information in three sections:

• Green pages—The green pages provide technical data about a business's services. The information found in the green pages includes pointers to technical information and URLs with more information about each service. It is interesting to point out here that while UDDI is advertised as primarily registering Web services, the actual index will permit any type of service to be indexed in the registry.

• White pages —The white pages consist of addresses and other contact data for business registrations. This is the basic identification information for a business registering to provide services.

• Yellow pages— The yellow pages are sorted by industrial categorizations to make searching for a business easier. The categories are based on several standard business coding systems such as SIC (Standard Industrial Classification) and the NAICS (North American Industry Classification System).

The overall UDDI registry is hosted across many sites. Currently both IBM and Microsoft are hosting UDDI registries. Information from each of these registries is duplicated so when you register at one site your business information is replicated across the entire UDDI registry.

Businesses can access UDDI either through a Web interface or through automated programming methods. Any company using the registry can have automated methods to query and find an appropriate service for their customers. In addition, your own services can automatically update themselves within the registry, so the UDDI registry always reflects current information.

It should be noted that UDDI by itself only provides basic searching features. More advanced features such as searching by price of service or geographic region are not part of the UDDI framework. Instead, UDDI permits others to add a new layer on top of the current framework to provide such features. In the future, various third parties will create search engines for querying the UDDI registry for the general business community. This evolution will end up having similarities to the current search engine marketplace for indexing Web sites.

From a technical point of view, the UDDI APIs are built on top of SOAP. A programmer can use the information supplied by the UDDI registry to directly query a Web service. The UDDI APIs are broken into two major sections. The first set is the Inquiry APIs. These are used to query the UDDI registry. The second set is the Publish APIs for creating and updating a UDDI registry entry.

The UDDI is not currently a standard. However, there are plans to submit UDDI to become a standard sometime in 2002. Currently UDDI is managed by dozens of companies.

For more information, you can refer to the UDDI Web site at http://www.uddi.org.

ebXML

ebXML (e-business XML) is a specification for standardizing XML globally to aid in trade between organizations of any size. It provides a standard method to exchange business messages written in XML.

This is a huge project that has many subgoals and groups working towards promoting electronic business. ebXML will become a formal standard using XML to provide a framework for messages and services for businesses and consumers.

The ebXML project is noteworthy because it is backed by the United Nations (UN). This project seeks to encourage enterprises around the world to conduct business with each other. More importantly, the goal is to create a single global electronic marketplace where anyone can engage in business. The other organization behind ebXML is OASIS. This organization consists of over 170 members, including many of the large technology companies. The primary goal of OASIS is to promote standards in XML to improve electronic business. Between the UN and OASIS, ebXML has the backing to become a rock solid specification. ebXML will bring with it a set of tools, APIs, and registries to empower businesses to exchange information with each other.

At the time of this writing, ebXML is new enough that it doesn't impact the way we currently build Web services. It isn't practical to cover an example of ebXML yet; it is just too new. The question then becomes When will ebXML become mature enough that ebXML standards will be used by our Web services? The answer to this is unclear; however, you needn't reexamine ebXML until late 2002 at the earliest.

For more information you can refer to the ebXML Web site at http://www.ebxml.org/geninfo.htm.

The Difference Between UDDI and ebXML

At first glance, UDDI and ebXML appear to be doing the same thing. However, while there is an overlap between the two initiatives, there is a difference between market focus and scope. ebXML is a much larger system aimed at general business-to- business communication. ebXML is designed to be a complete business-to-business solution while UDDI focuses on serving as a simple index and a place for companies to integrate Web services relative to each other.

Why do we need different service registries? The simple fact is that the marketplace will perceive a need for many different types of registries. From a technical point of view, ebXML is flexible enough with its structure to support most businesses, and this will reduce the need for more registries to appear in the marketplace. However, due to human nature and the mechanics of business, we can expect more registries to appear and disappear over time. Organizations will want their own system or someone will see a way to profit in making a new system. UDDI and ebXML are here to stay. Only time will tell what other registries will appear.

Finally, it should be noted that both ebXML and UDDI are supported by many of the same industries. This means that, over time, these two initiatives will end up complementing each other rather than competing with each other.

Java APIs

To make our lives easier, several Java applications and quite a few Java APIs exist to help us implement Web services. This section will discuss several of these projects.

Apache SOAP

http://xml.apache.org/soap

The Apache SOAP API is probably the most widely used Java SOAP implementation. Apache SOAP was built on top of the IBM SOAP4J API library. IBM donated the library to get a solid open source–based SOAP implementation out for the development community. The code examples in this book use Apache SOAP.

AXIS

http://xml.apache.org/axis

AXIS is the next generation of a Java-based SOAP implementation (at the time of this writing, it is in the alpha stage). AXIS replaces the Apache SOAP API. AXIS is much faster than Apache SOAP due to design considerations such as using XML tools like SAX over DOM (we will cover SAX and DOM in future chapters). The drawback of AXIS is that the API is still in alpha release and as such is still too young to use in production environments.

JAXM (Java API for XML Messaging)

http://java.sun.com/xml/jaxm/index.html

JAXM implements SOAP 1.1. A programmer can use JAXM to enable a JSP page or Java object to send SOAP messaging. JAXM hides much of the lower level programming so a programmer can concentrate on sending a message. Eventually, JAXM will expand the messaging capabilities so that it offers functionality that SOAP cannot provide.

JAXM is listed as JSR-67 at the Java Community Process Web site. The Java Community Process is a community-based approach Sun takes to expand and improve upon Java. Whenever a new tool or feature for Java is required, a small team of programmers and companies is formed to oversee and develop the specifications and code.

JAXR (Java API for XML Registries)

http://java.sun.com/xml/jaxr/index.html

This API will be a valuable one for many programmers. The JAXR API will define a standard Java interface to access any Web service registry whether it is based on ebXML, UDDI, or another standard. It is important to understand that this API doesn't define a registry, but rather is purely a one-stop shopping interface to access any registry. While at the time of writing it was too early to use it, sometime in 2002 this API will be ready for prime time. The API currently uses ebXML to establish a baseline of required functionality; however, it is being expanded as needed for additional functionality. Currently, it supports only ebXML and UDDI specifications (version 0.6 at the time of writing). JAXR will use JAXM to communicate between the registry and a client.

JAXR is listed as JSR-093 at the Java Community Process Web site.

JWSDL (Java API for WSDL)

This API is designed to simplify using WSDL. JWSDL can represent and manipulate a service described by a WSDL document. Currently, JAXP is the best way to access and use a WSDL document. However, later in 2002, when JWSDL has become an established Java API, it will be the quickest and easiest API to use for WSDL documents. This API is really meant more for the tool builders—programmers building the tools to access and use Web services. The average Web developer building a Web service will never need to access this API.

JWSDL is listed as JSR-110 at the Java Community Process Web site. At the time of this writing, no reference implementation of JWSDL has been released to the public.