Web Services and the Sun ONE Developer Platform

One of the things that makes the Web services model so attractive is that it's built on standard technologies, especially Extensible Markup Language (XML) technologies, that have wide industry acceptance. These technologies make for an "open" environment, ensuring that a Web service can be located and used, no matter where it is, what platform it runs on, or who developed it.

This section describes XML and the following XML technologies that are pertinent to Web services:

• Universal Description, Discovery, and Integration (UDDI)
• Simple Object Access Protocol (SOAP)
• Web Service Description Language (WSDL)
• Electronic Business XML (ebXML)

XML is emerging as the standard for exchanging data on the Internet. There are a number of reasons for this, some of which are:

XML is relatively easy to learn, especially for people who know HTML

In fact, XML and Hypertext Markup Language (HTML) have the same ancestry: Standard Generalized Markup Language (SGML). SGML is an international standard for defining the structure of electronic documents. These include Web-based and non-Web-based documents. SGML is functionally rich but complex. HTML is a small, simple application of SGML that defines the structure of the type of document you typically see on the Web -- that is, one with paragraphs, lists, tables, graphics and so on. XML is a more ambitious application of SGML. It allows you to define your own type of documents (to learn more about that, see XML is extensible).

For people who know HTML, a language whose use is pervasive across the Web, learning XML tends not to be a major obstacle. Like HTML, XML involves the use of tags that "mark up" the contents of a text file, (notice that the "M" in HTML, XML, and SGML stands for Markup) however the objective of the markup differs. HTML tags are designed for presentation. They instruct an application that can interpret the tags, such as a Web browser, how to display information. For example, the following HTML markup instructs the interpreting application to:

• Display the first line as a heading.
• Put the next few lines in a paragraph.
• Put the last three lines in a numbered list.

<h4>This is a heading</h4>
<p>This is a paragraph.
Here's the second line of the paragraph.
Here's the end of the paragraph.

</p>
<ol>
<li>The first item</li>
<li>The last item</li>
</ol>

And here's the displayed result. (Note that the box around the output is simply to set it off from the text in this article. The previous HTML tags do not create the box, although you can display a box like this using HTML tags.)

XML describes the content of a document

An XML tag identifies information in a document, and also identifies the structure of the information. Applications capable of interpreting these tags can then process the information according to the meaning of the information and its organization.

For example, the following XML markup identifies some information. The information is identified as bookshelf. The XML markup also describes the structure of bookshelf. The bookshelf structure includes two subordinate items identified as book. Each book has three subordinate items identified as title, author, and price.

<bookshelf>
   <book>
      <title>My Life and Times</title>
      <author>Felix Harrison</author>
      <price>39.95</price>

   </book>
   <book>
      <title>Travel Tips for the Frugal</title>
      <author>Juan Arellaga</author>
      <price>25.00</price>
   </book>

</bookshelf>

Although tags such as <book> and <title> might appear to inherently give meaning to the information they identify, they really don't. Information tagged with XML tags has meaning only if people associate a particular meaning with a particular tag. If people (1) agree on a meaning, say that the <book> tag is used to identify a book, and that <title>,<author>, and <price> tags identify the title, author, and price of the book, respectively, and (2) use those tags consistently, it gives people a way to exchange data. Their applications can send XML documents to each other, and process the information in those documents, relying on the commonly understood meanings associated with the XML tags.

XML documents have a well-formed structure

Notice that in the previous example, each XML tag has an ending tag. For example, <bookshelf>...</bookshelf>. This is a requirement in XML. Another requirement is that a tag that begins within another tag must end before the end of the other tag, and must be completely nested within that other tag. So that </title>, </author>, and </price> all come before </book>, and in that relative order. XML does allow for empty tags, that is, tags that have nothing between the opening and closing of the tag. For these tags, you can use a shorthand notation. For example, instead of coding an empty tag like this:

<emptytag></emptytag>

You can code it like this:

<emptytag/>

These requirements are part of set of requirements that must be met to make an XML document "well-formed". To be valid, an XML document must be well-formed. Because valid XML documents must be well-formed, it makes it easier to create programs that process XML documents.

The structure within an XML tag is consistent

An important requirement for effective data interchange, that is, in addition to having a consistently understood meaning associated with an XML tag, is the consistent structure of an XML document. Structural consistency can mean that an XML document is well-formed. However, it can also mean that the structure inside of an XML tag is consistent. For example, it might mean that an application can rely on the fact that any time a <book> tag is specified, <title>, <author>, and <price> tags are specified within the <book> tag. XML provides for this latter type of structural consistency through schema specifications.

XML is extensible

A schema specifies the "grammar" for an XML document. In other words, it specifies what tags are allowed in the document, the structure of those tags, and other rules about the tags, such as what type of data is expected in a tag (or no data if it's an empty tag). A schema is typically specified in a Document Type Definition (DTD). A DTD however is optional. There are other mechanisms to specify a schema. Additionally, you don't have to specify any grammar at all. In that case, the XML document is relatively unconstrained. It can include any tags -- you can even define your own tags. In this way, XML (unlike HTML) allows you to define your own type of document. However, whatever type of document you define, it still needs to be well-formed. This ability to define your own tags means that XML is extensible (remember that the X in XML stands for extensible).

A DTD specification for the bookshelf tag would look something like this:

<!ELEMENT bookshelf(book)+>
<!ELEMENT book(title, author, price)>
<!ELEMENT title(#PCDATA)+>
<!ELEMENT author(#PCDATA)+>
<!ELEMENT price(#PCDATA)+>

The specification says that there is an "element" named bookshelf. (Formally, each unit in an XML document is an element.) The bookshelf element contain at least one book element (the + means that there can be more than one). Each book element contains a title, author, and price element. The #PCDATA specification means that the data supplied with the title, author, and price elements is character data that must be parsed.

If people agree to use the same schemas in addition to agreeing on consistent meanings for XML tags, it makes the use of XML an effective way to exchange data. And, in fact, many areas of business are agreeing to agree. For example, there already are DTDs available for many business areas, and businesses within these areas are starting to converge on the use of those DTDs for data interchange.

XML is an effective way to exchange data, but how is it used specifically in Web services? One way is to identify a Web service in a registry so that a program looking for a Web service can easily find it and understand what it does. A large consortium representing a wide variety of industries has developed specifications for Web service registration. This cross-industry effort is called the Universal Description, Discovery, and Integration (UDDI) project. The UDDI specifications are becoming one of the generally adopted standards for Web services. The consortium has also implemented the UDDI specifications in a UDDI Business Registry, and it makes the Business registry available to the public for businesses to register their Web services. (UDDI is not the only standard that is commonly used for Web services registration. Another approach that is generally adopted for Web services is ebXML.)

Think of a UDDI registry as a "Yellow Pages" for Web services. Like the Yellow Pages directory for phone numbers, a UDDI registry provides simple information about:

• Who it is. A registration includes the name of the Web service provider, and can include additional identifiers such as a North American Industry Classification System (NAICS) code or a Dun & Bradstreet D-U-N-S number.
• What it is. A registration includes the name of a Web service and, typically, a brief description.
• Where it is. A registration contains "binding templates" that point to an address where the service can be accessed.
• How to request it. A registration contains "tModels" that describe the interface for the Web service.

Each registry that conforms to UDDI is operated at its own site (the UDDI specifications refer to this as the "operator" site). The operator site contains the master copy of its registry. However, the collection of UDDI registries is replicated. If a business searches for a Web service in a registry at one operator site, the search is done across the information in the master copy, including the information replicated from the other UDDI registries.

The UDDI specifications define how to publish and discover information about Web services in a UDDI-conforming registry. More specifically, the specifications define a UDDI schema and a UDDI API. The schema identifies the types of XML data structures that comprise an entry in the registry for a Web service. The API describes the SOAP messages that are used to publish an entry in a registry, or discover an entry in a registry. Note that the current version of the UDDI specifications, Version 3, covers additional features, such as a subscription API that can be used to notify "subscribers" when registry entries of interest change. The UDDI schema and API described below is based on Version 2 -- this is the version that is supported by the Sun ONE Developer Platform tools and servers.

UDDI Schema

The UDDI schema identifies the types of XML data structures that comprise an entry in the registry for a Web service. The following figure illustrates the schema. It shows the five types of XML data structures that comprise a registration.

Click image to enlarge

businessEntity. This structure represents all known information about a business or entity and the services that it offers. (The reference to "entity" means that an entry in a UDDI registry does not necessarily have to be for a business. It could be for other types of enterprises such as schools or research institutions.) From an XML standpoint, a businessEntity is the top-level data structure that holds descriptive information about a business or entity. A businessEntity element contains attributes that:

• Uniquely identify the businessEntity (businessKey). The key is a Universal Unique Identifier (UUID) that is generated by the registry. The mechanism that produces UUIDs guarantees uniqueness through a combination of hardware addresses, timestamps and random numbers.
• Name the individual who published the businessEntity data (authorizedName)
• Specify the UDDI registry site that manages the master copy of the businessEntity data (operator)

Other elements within the structure identify the name recorded for the business or entity (name), and optionally specify additional information about the business or entity, such as its:

• Description (description)
• List of contacts (contacts)
• List of services offered (businessServices)
• List of identifiers that can be used in a search (identifierBag)
• One or more category designations, such as an industry designation or a geographic designation (categoryBag).

Here is an example that shows part of a complete BusinessEntity structure for a hypothetical company named BooksToGo. The company provides various Web services, including an online book ordering service.

<businessEntity businessKey="35AF7F00-1419-11D6-A0DC-000C0E00ACDD"
authorizedName="0100002CAL" 
  operator="www-3.ibm.com/services/uddi">
<name>BooksToGo</name>
<description xml:lang="en">
   The source for all professional books
</description>
<contacts>
<contact>

<personName>Ramesh Mandava</personName>
<phone>
  (877)1111111
</phone>
</contact>
</contacts>

businessService. This structure identifies a service provided by the business or entity that is represented by the parent businessEntity. A business or entity can provide multiple services, so there can be multiple businessService elements within a businessEntity. The set (or "family") of businessService elements are specified in a businessServices structure.

Here is an example that shows part of a complete businessService structure for an online book ordering service offered by BooksToGo. Notice especially the categoryBag element, which is used to specify a classification scheme (formally this is known as a "taxonomy"). In this example, the taxonomy is NAICS.

<businessServices>
<businessService serviceKey="
  2AB346C0-2282-43B0-756B-0003CC35CC1D">
<name>Online Book Ordering</name>
<description xml:lang="en">
  Ordering books online
</description>
<categoryBag>
  ntis-gov:naic

<catgeoryBag>  

bindingTemplate and tModel. A bindingTemplate in tandem with a tModel provides two important pieces of information about a Web service: its technical specification and its accessPoint. A technical specification (also called a "technical fingerprint") typically provides details about things such as protocols and interchange formats used in communicating with the service. The accessPoint is an address, such as a URL or email address, at which the service can be called. Contained within a bindingTemplate structure is a tModelInstanceInfo element that references a tModel by its key. The referenced tModel provides the technical specification.

There can be multiple bindingTemplate elements for the family of services identified in a businessServices structure. As you might guess, the multiple bindingTemplate elements are specified in a bindingTemplates structure.

Here is an example that shows part of a complete bindingTemplate structure for the online book ordering service offered by BooksToGo. Notice the reference to the tModelKey in the tModelInstanceInfo element.

<bindingTemplates>
<bindingTemplate bindingKey="
  4BC7C340-2398-12E6-887C-0005AC33CC2D"
<description>
  JAXRPC (SOAP/HTTP ) based binding
</description>  

<accessPoint>
  http://www.BooksToGo.com:8080/books/
</accessPoint>

<tModelInstanceDetails>
<tModelInstanceInfo tModelKey="UUID:
  36E13526-4553-3265-B5F7-C4B522E75A05" />
</tModelInstanceDetails>

publisherAssertion. This structure is used as a way of asserting a relationship between one businessEntity and another. For example, the structure can be used to show that two business are subsidiaries of the same company. To assert the relationship, each of the two businessEntity structures specifies its own publishAssertion structure. However the information in each structure needs to be exactly the same.

Continuing with the BooksToGo example, let's assume that it has no relationship that it needs to assert.

UDDI API

The UDDI API describes the Simple Object Access Protocol (SOAP) messages that are used to publish an entry in a registry (the "Publish" API), and those that are used to discover an entry in a registry (the "Inquiry" API).

Publish API. There are a variety of messages defined in the Publish API. What they have in common is that they perform some action related to one of the types of structures that comprise the UDDI schema. For example, the Publish API message save_business is used to save or update one or more complete businessEntity structures in a registry. Similar messages are available to save or update one or more complete businessService structures (the message is save_service), bindingTemplate structures (save_binding), and tModel structures (save_tModel). A slight variation is the set_publisherAssertions message, which is used to manage all of the assertions associated with an individual publisher.

Here, for example, is a message that saves the businessService structure (named Online Book Ordering) that you saw previously in the description of the UDDI schema. Notice the authinfo element. It is used to specify an authentication token. This is a value that is a standard part of UDDI's authentication mechanism and needs to be specified in all Publisher API calls. You obtain the authentication token by issuing a call to get_authToken.

<save_service generic="2.0" xmlns=um:uddi-org:api-v2">
<authinfo>authentication token goes here ...</authinfo>
<businessServices>

<businessService serviceKey="
  2AB346C0-2282-43B0-756B-0003CC35CC1D">
<name>Online Book Ordering</name>
<description xml:lang="en">
  Use this service to purchase books over the Web
</description>

In addition to messages that save or update UDDI structures in a registry, the Publish API also defines messages that delete these structures. For example, the delete_service message deletes a businessService structure.

Inquiry API. The Inquiry API contains two types of messages: "find" messages that search UDDI registries for entries that meet specified search criteria, and "get" messages that retrieve detailed information about a specified registration. For example, you use the Inquiry API message find_business to search for all registered business entities that meet search criteria specified in the call. Here, for example, is a find_business message that searches for all business entities whose registered name begins with the characters "Books":

<find_business generic="2.0" xmlns=um:uddi-org:api-v2">
<name>Books%</name>
</find_business>

The call returns a businessList structure that contains information about each matching business, and summaries of the businessService elements exposed by those businesses. Similar messages exist to search for services within a registered businessEntity (find_service), bindings within a registered businessService (find_binding), and tModels (find_tModel). You can also search for businessEntity registrations that are related to a specific business entity (find_relatedBusinesses).

The "get" messages include those that return detailed information about one or more business entities (get_businessDetail and get_businessDetailExt), business services (get_serviceDetail), bindingTemplates get_bindingDetail), and tModels get_tModelDetail.

Here, for example, is a get_serviceDetail message that returns detailed information about the Online Book Ordering service. Notice how the serviceKey value is used to identify the service.

<get_serviceDetail generic="2.0" xmlns=um:uddi-org:api-v2">
<serviceKey>"2AB346C0-2282-43B0-756B-0003CC35CC1D"</name>
</get_serviceDetail>

Though agreeing on the meaning and structure of XML tags makes the use of XML an effective way to exchange data, it's not sufficient for data interchange over the Web. For instance, you still need some agreed-upon protocol for sending XML documents across the Web so that the receiver understands what it's getting, and what to do in response. That's where Simple Object Access Protocol (SOAP) comes in. SOAP is a XML-based protocol for exchanging information in a distributed environment. It's a major underpinning of the communication mechanism for Web services. For example, you register a Web service in a UDDI registry using the SOAP protocol. You also use the SOAP protocol to look for a Web service in a UDDI registry, and once you find the service, you use the SOAP protocol to request it.

The SOAP protocol is defined in the SOAP specification. The Sun ONE Developer Platform tools and servers support the current level of the specification, SOAP 1.1. An update to the specification, SOAP 1.2, is close to being finalized.

Like UDDI, SOAP is XML based. Also, like UDDI, SOAP is a generally accepted standard for Web services. The reason for SOAP's widespread adoption is its simplicity. SOAP is "lightweight," that is, it involves a relatively small amount of code, and it's fairly easy to understand. The basic item of transmission in SOAP is the SOAP message, which consists of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body.

What those items mean is that if a Web services client exchanges some information with a Web service, what gets exchanged is a SOAP message that conceptually looks like this:

Click image to enlarge

Envelope. The envelope is the top element of the XML document, and is represented by an Envelope element. The envelope can contain namespace declarations as well as additional attributes such an encoding style. An XML namespace defines a collection of names that can be used in XML elements and attributes. The namespace identifies the scope for a name, so that "name clashes" can be avoided. In particular, namespace declarations are designed to distinguish the names used in the XML document from the names used in an application that might process the XML document. They also distinguish names within the XML document, so that two elements with the same name, but associated with different namespaces, can be correctly understood as being different. An encoding style identifies the data types recognized by SOAP messages, and specifies rules for how these data types are serialized, that is, transformed for transport across the Web.

Header. The header is represented by a Header element. As mentioned previously, the header is optional. However, if it's included in a SOAP message, it must be the first child o the Envelope element. The header, through attributes, extends the SOAP message. In other words, it adds information beyond what is in the body of the SOAP message. It's important to understand that as a SOAP message travels from an originator (a client application) to a final destination (for example, an application providing a requested service), it potentially passes through a set of intermediate nodes along the path. Each node is an application that can receive and forward SOAP messages. The SOAP header can be used to indicate some additional processing at a node, that is, processing independent of the processing done at the final destination. For example, the header could be used to request that each message be logged at a particular node.

Body. The body, represented by a Body element, contains the "payload", that is, the information intended for the final destination. The Body element can optionally contain a Fault element that is used to hold error and status information returned by a processing node. The Body element must be an immediate child element of a SOAP Envelope element. If the envelope contains a header, the Body element must immediately follow the Header element.

Here's an example of a SOAP message:

<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:Transaction xmlns:t="some-URI">
              SOAP-ENV:mustUnderstand="1"> 
                  5
           </t:Transaction>
        </SOAP-ENV:Header>
        <SOAP-ENV:Body>

           <m:GetLastTradePrice xmlns:m="some-URI">
              <symbol>DEF</Symbol>
           </m: GetLastTradePrice>
        </SOAP-ENV:Body>
</SOAP-Envelope>

The Envelope element specifies:

• A namespace. The URI http://schemas.xmlsoap.org/soap/envelope/ identifies the namespace used for this SOAP message. This is the standard namespace for all SOAP messages. Notice the prefix SOAP-ENV. This prefix maps to the namespace, so that any additional references to the prefix in the SOAP message, are references to that namespace.
   
  
• An encoding style. The URI http://schemas.xmlsoap.org/soap/encoding/ identifies the encoding style for "Section 5" encodings, that is, the SOAP encoding described in Section 5 of the SOAP specification. Section 5 define rules for encoding data types in XML, and rules for serialization.

The Header element specifies:

• A Transaction element. The URI represented by "some-URI" identifies the namespace for the element.
   
  
• A demand to process the header. The attribute value mustUnderstand=1 means that the receiver of the header must process it. SOAP provides an attribute, called the "SOAP actor", whose value is a URI. The URI identifies the node that receives the SOAP header (remember that a SOAP message can potentially travel through multiple nodes before arriving at a final destination). Because the SOAP actor attribute is not specified in this example, it means that header should be received at the final destination. And because mustUnderstand=1 is specified, that node must process the header.
   
  
• A value of 5. Presumably, the receiver knows how to process this value.

The Body element specifies a GetLastTradePrice element (and its namespace), and a subordinate element DEF.

If you've guessed that this example has something to do with stock quotes, you're right. The SOAP message is designed to retrieve the current price of a stock. Specifically, the SOAP message includes a request for the current stock price (GetLastTradePrice), and passes a symbol (DEF) that identifies the stock. This is an example of using SOAP for a Remote Procedure Call (RPC), where GetLastTradePrice represents a remote method, and DEF represents a parameter passed in the RPC call. Using SOAP for RPC is one of two approaches to using SOAP. The other is using SOAP for messaging.

SOAP for RPC

In a remote procedure call (or RPC), a program (the "client") in one location in a network requests a procedure (in Java technology terms, a method) from a program (in Java technology, an object) that is located in another part of the network. The client can pass parameters as part of the RPC call. In the stock quote example, the RPC call is to the remote method GetLastTradePrice and the parameter passed is the symbol DEF. This indicates something important about using SOAP for RPC (as opposed to using SOAP for messaging). When using SOAP for RPC, the client knows which procedure it wants to call, and knows what parameters that procedure requires. (By comparison, when using SOAP for messaging, the client doesn't necessarily know what application will process the request.)

The remote procedure can return a response to the client (but it doesn't have to). The interaction between the client and the remote procedure is governed by specific rules. In other words, there's a defined protocol that governs how the components interact in an RPC call.

Support for RPC is a key objective of SOAP. In fact, the SOAP specification states:

To meet that goal, the SOAP specification includes a section that describes how to represent RPC calls and responses. For example, an RPC call needs to include:

• The URI of the target object
• A method name
• An optional method signature
• The parameters to the method
• Optional header data

RPC method calls and responses are carried in the SOAP Body element. In the stock quote example, the Body element contains the following:

        <SOAP-ENV:Body>
           <m:GetLastTradePrice xmlns:m="some-URI">
              <symbol>DEF</Symbol>
           </m: GetLastTradePrice>
        </SOAP-ENV:Body>

The response to the method call might look like this:

        <SOAP-ENV:Body>
           <m:GetLastTradePriceResponse xmlns:m="some-URI">
              <price>42.40</price>

           </m: GetLastTradePriceResponse>
        </SOAP-ENV:Body>

The response to the request for a stock price is in the element GetLastTradePriceResponse. Although SOAP does not require it, the convention is to give the response element the same name as the remote method name, with the string "Response" appended to it. In this example, the returned price is 42.40.

SOAP for Messaging

Although support for RPC is a key objective of SOAP, the SOAP protocol can also be used for messaging. In messaging, the client sends a document (rather than an RPC call) for the server to process. The document contains information in a format that both the client and server can understand. For example, the document could be something that both the client and server recognize as a purchase order. The server then processes the purchase order, and could return a response (perhaps confirming that the purchase order was received).

It's important to understand that the messaging client does not call a specific method -- in the purchase order example, the messaging client does not call a purchase order method. In fact, the client might not know what program on the server actually processes the request. Instead, the client relies on the server to invoke the appropriate application to process the request because the server understands the format of the message it receives. Similarly, what the server returns is not a method response, but rather a response generated by the processing application.

This example indicates that the server could return a response, but it doesn't have to. As is the case when using SOAP for RPC, SOAP for messaging does not require that the receiver of a request return a response. In fact, one-way (asynchronous) requests are probably more typical in messaging than two-way (synchronous) requests.

The architecture of a SOAP message is the same for messaging as it is for RPC. In both cases, the message contains an envelope, an optional header, and a body. For messaging, the payload in the body is the document passed by the client for processing by the server. Here's an example of a SOAP message used for messaging:

<SOAP-ENV: Envelope
  xmlns:SOAP-ENV=
    "http://schemas.xmlsoap.org/soap/envelope/"
        </SOAP-ENV:Header>
        <SOAP-ENV:Body>
           <bp:GetBookDetails xmlns:bp="http://bookprovider.com">

              <searchCriteria>ISBN</searchCriteria>
              <searchValue>0123454321</searchCriteria>
           </m: GetBookDetails>
        </SOAP-ENV:Body>
</SOAP-Envelope>

Notice that the body contains an element GetBookDetails that contains two subelements searchCriteria and searchValue. Assume that GetBookDetails is recognized as a structure that contains information about books, in particular, the International Standard Book Number (ISBN). Assume too that the server processes the message by searching a database of book information, using the ISBN value as search criteria. Finally, assume that the server returns detailed information about the book that has the specified ISBN value.

In other respects, SOAP for messaging is similar to SOAP for RPC.

SOAP Messages With Attachments

The SOAP 1.1 specification does not cover attachments to SOAP messages. For example, if you send a SOAP message that conforms to the SOAP 1.1 specification, you send a payload that either represents an RPC call or that contains a document for messaging. But what if you want to attach something to the SOAP message, say an image? A standard way of doing this is described in the SOAP Messages With Attachments specification. This specification describes how to attach one or more items to a SOAP message, no matter what content these items hold. For example, an attachment can be an image, audio, text, even an XML document.

A SOAP message with attachments, which the specification calls a "SOAP message package", conceptually looks like this.

Click image to enlarge

The SOAP Messages With Attachments specification takes a MIME approach in describing how to build a SOAP message package. MIME, which stands for Multipurpose Internet Mail Extensions, is a standard that extends the format of Internet mail to allow for things like multipart message bodies.

A message that conforms to the MIME standard consists of a header and a body. The header contains various fields that contain information about the message. For example, the MIME-Version header field specifies which version of the MIME standard applies to the message. Another header field, named CONTENT-TYPE specifies the type of data in the body of the message. For example, the CONTENT-TYPE field value Text specifies that the body contains text, and a value of Audio specifies audio data. One CONTENT-TYPE field value has particular relevance for SOAP message packages. It's the CONTENT-TYPE field value Multipart/Related. This value specifies that the body contains a compound object consisting of several interrelated body parts. This is the MIME data type that is used to construct a SOAP message package.

A Multipart/Related type of compound object has a root body part (by default, this is the first body part in the compound object) and one or more related body parts. Complicating matters is that fact that each body part has its own header and body. The MIME standard further specifies that each body part in a MIME message is separated from another body part at a boundary, and that a boundary is identified in a parameter of the CONTENT-TYPE field. So putting all this together, a SOAP message package consists of a SOAP message that is contained in the root body part, and one or more attachments that are other body parts separated from each other at a boundary.

Here's an example of a SOAP message package. The SOAP message is in the root body part. The value of the start parameter in the CONTENT-TYPE field of the header points to content of the SOAP message (claim061400a.xml@claiming-it.com). The package contains an attachment that's an image (claim061400a.tiff@claiming-it.com).

MIME-Version: 1.0
Content-Type: Multipart/Related; 
 boundary=MIME_boundary; type=text/xml; 
 start="<claim061400a.xml@claiming-it.com>"

Content-Description: 
 This is the optional message description.

--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <claim061400a.xml@claiming-it.com>

<?xml version='1.0' ?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
..
<theSignedForm href="cid:claim061400a.tiff@claiming-it.com"/>
..
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

--MIME_boundary
Content-Type: image/tiff
Content-Transfer-Encoding: binary
Content-ID: <claim061400a.tiff@claiming-it.com>

...binary TIFF image...
--MIME_boundary--

Notice that the SOAP message refers to the attached image. SOAP 1.1 allows for an accessor to point to a URI. The URI can provide any type of resource, including a non-XML resource such as an image.

How does a Web services client know what format to use in making a request to a server? For that matter, how do the client and the server know what the request means? In SOAP for messaging, the answer is that there's a previous agreement about the format and meaning of SOAP messages exchanged between the client and the server. The client and server know what a document representing a purchase order looks like because there's previous agreement about its format. But what about SOAP for RPC? How does a Web services client know what method to call, what arguments to pass, and what to expect in response? In fact, how does the client know to expect a response? The answers to all these questions are provided by information in an XML document, called the WSDL document, that contains a description of the Web service's interface and semantics.

A WSDL document contains information specified in Web Service Description Language (WSDL), as defined in the WSDL specification. WSDL defines an XML schema for describing a Web service. To uncover the description for a Web service, a Web services client needs to find the service's WSDL document. One way, perhaps the most typical way, to do this is for the client to find a pointer to the WSDL document in the Web service's UDDI registration. (However the UDDI specification doesn't mandate such a link.) A typical scenario is that a business registers its service in a UDDI registry. The registry entry includes a pointer to a WSDL file that contains the WSDL document for the service. Another business searches the registry and finds the service. A programmer uses the interface and semantic information in the WSDL document to construct the appropriate calls to the service.

WSDL Document

A WSDL document describes a Web service as a collection of abstract items called "ports" or "endpoints". A WSDL document also defines the actions performed by a Web service and the data transmitted to these actions in an abstract way. Actions are represented by "operations", and data is represented by "messages". A collection of related operations is known as a "port type". A port type constitutes the collection of actions offered by a Web service. What turns a WSDL description from abstract to concrete is a "binding". A binding specifies the network protocol and message format specifications for a particular port type. A port is defined by associating a network address with a binding. If a requester locates a WSDL document, and finds the binding and network address for each port, it can call the service's operations according to the specified protocol and message format.

Here is an example of a WSDL document. The example illustrates a WSDL document for a service that provides stock quotes. This is the service that was called in the example illustrated in the section on SOAP. Recall that the application that requests this service supplies a symbol for a specific stock. The service responds with the current price of the stock. Notice that the document contains the following elements:

definitions. In WSDL terms, the description of a Web service's interface is its "definition", marked by the definitions element. This is the root element in a WSDL document. A definitions element specifies a name for the definition (in this example, StockQuote) and points (using URIs) to pertinent namespaces. All WSDL files need to point to a WSDL namespace, a SOAP namespace, and an XML Schema Definition (XSD) namespace. A WSDL file can also point to a target namespace for the associated Web service. In this example, a target namespace for the Web service is located at the URI http://example.com/stockquote.wsdl.

types. This structure, marked by the types element, contains data type definitions using some type system (such as XSD). WSDL uses a small set of primitive data types that are defined in XSD. Using the types structure in a WSDL document, you can define complex types that build on these basic types. These types can then be used in the operations defined for the Web service. Notice that the example defines two complex types, one that contains an element named tickerSymbol that is based on the primitive data type string, and another complex type that contains the element price that is based on the primitive data type float.

message. The message element describes data that is passed to and from the operations defined for the Web service. An operation identifies an action or set of actions offered by the Web service. In essence, a message describes the parameters that are passed to and from an operation. Messages are made up of parts (marked by the part element). This allows for multi-part data to be passed to an operation, for example, a purchase order with an accompanying invoice can be passed to an auditing service. In the StockQuote example, two messages are defined: GetLastTradePriceInput and GetLastTradePriceOutput. Each is a one-part message. Notice that TradePriceRequest is the part defined in GetLastTradePriceInput. Recall that it was defined in the type structure as containing the type tickerSymbol. TradePrice, the part defined in GetLastTradePriceOutput, was defined in the type structure as containing the type price.

port type. The portType structure defines the operations and messages for the Web service. In other words, it identifies the distinct actions provided by the Web service, and the data passed to each one. Each operation in the portType structure is marked with the operation element. The port type structure has a grammar that identifies the message-passing protocol for the operation, for example, one-way or request-response. Notice the one operation defined in the StockQuote example. The port type in the example has a grammar for a request-response protocol. The operation named GetLastTradePrice specifies an input message (GetLastTradePriceInput) and a output (response) message (GetLastTradePriceOutput). Remember that GetLastTradePriceInput has the type tickerSymbol, and TradePrice has the type price. This means that the GetLastTradePrice operation takes a tickerSymbol as input, and returns a price.

binding. The binding structure defines the message format and protocol details for operations and messages associated with a particular portType. Typically the binding structure identifies SOAP as the protocol for the binding. This is the case in the StockQuote example. Notice that the binding structure in the example specifies additional SOAP-specific information. The soap:operation element specifies a SOAPAction header URI of http://example.com/GetLastTradePrice. The URI indicates the intent of the message (in this case, a SOAP message). This allows it to perform conditional processing based on the presence of the SOAPAction header. The input and output elements in the binding indicates that the input and output messages to and from GetLastTradePrice reference a concrete schema definition using type attribute.

service. The service structure defines a collection of related ports that comprise a Web service. Each port identifies a binding and an address for the binding. In the StockQuote example, a service named StockQuoteService is defined to have one port StockQuotePort. The binding for the port is StockQuoteBinding and the address for the binding is http://example.com/stockquote.

While SOAP provides a means to send Web service-related messages, such as those that register a Web service in a UDDI registry or request a Web service operation, it's fairly limited. For example, there's no way in SOAP to describe the larger context of the service, that is, the business process in which the service fits. In the real world, being able to successfully use a Web service might depend on how well the pertinent processes of a requesting business mesh with the processes of a business offering the service. ebXML is designed to provide a comprehensive B2B framework for describing these processes as well as other information so that businesses can successfully collaborate in a global electronic marketplace.

The ebXML framework is being developed by the ebXML initiative. This initiative is a joint project of the United Nations Centre for Trade Facilitation and Electronic Business (UN/CEFACT) and the Organization for the Advancement of Structured Information Standards (OASIS), and includes representation from an extremely wide set of businesses and other entities around the world (including standards bodies). The framework consists of a set of ebXML specifications, all of them XML based. A fundamental concept in ebXML is expressed in the following extract taken from one of the ebXML specifications (the Collaboration-Protocol Profile and Agreement Specification):

The CPP and CPA are typically stored in an ebXML registry. Let's examine each of these ebXML components:

Collaboration-Protocol Profile (CPP). The CPP is an XML document that contains information about a business (in ebXML terms, a business is referred to as a "Party") and the way it exchanges information with another Party. This can include information about who the Party is (for example, its name and contact information), the services it offers (ebXML calls these "business transactions"), its role in a business collaboration (for example, a "buyer" or "seller"), and details about the message transport it uses, and its security constraints. This information about a business's ebXML capabilities and constraints is also known as a "business profile". The CPP also points to a document called a "Business-Process Specification" that defines the interactions supported by the Party, in other words, the specifics of a collaboration that a Party is capable of implementing.

Collaboration-Protocol Agreement (CPA). The CPA is an XML document that describes the specific capabilities that two Parties have agreed to use in a business collaboration. One way to look at a CPA is as an intersection of the CPPs for the two Parties that collaborate. A CPA contains the same type of information as a CPP, but for the two parties involved. This also includes the appropriate reference to a Business-Process Specification. Essentially, a CPA is a contract between the two Parties in a collaboration. It describes the valid, enforceable interactions that can take place between the two parties as part of the collaboration.

ebXML Registry. An ebXML registry stores CPPs, CPA, and other information relevant to business collaboration. As is the case for UDDI, ebXML offers services to register and discover information about a business. However unlike a UDDI registry (which points to a WSDL document for a description of a Web service), an ebXML Registry actually contains the description of a business's service within its CPP and associated Business-Process Specification.

A high-level view of how these components are used for Web services is as follows:

1. Parties register their CPPs in an ebXML registry.
2. A Party (let's call it Party 1) searches the ebXML registry for a needed Web service. It finds that the needed service is provided by Party 2. The information is in Party 2's CPP in the ebXML registry.
3. Party 2 creates a CPA for a business collaboration with Party 1 and sends the CPA to Party 1.
4. Party 1 and Party 2 negotiate an agreement. Each stores a copy of the CPA in its server.
5. Party 1 finds and uses the Web service provided by Party 2 as part of the collaboration defined by the CPA.

One other thing to note about ebXML is that two Parties exchange information using the ebXML messaging standard. This standard is based on the SOAP standard. However it extends SOAP in important areas such as security (for example, it adds support for creating and verifying a digital signature) and reliable message handling. The ebXML messaging standard also conforms with the SOAP Messages with Attachments specification, itself an extension of SOAP that enables a user to send attachments with a SOAP message.