DOM for Web Services, Part 1
In this first article of a three-part series, I offer a tutorial of the W3C Document Object Model (DOM) with particular application to web services. Here we will discuss, explain, and demonstrate what DOM can do for the XML authoring and processing required by web service applications. We will consider each of the three DOM levels and apply the DOM functionality to explain why, when, and how to use the various features that W3C DOM offers. Each level provides a certain collection of XML authoring and processing features. Levels 1 and 2 have become W3C recommendations, while the third level is currently a working draft at W3C.
The first article is divided into two sections. The first section discusses the XML authoring and processing requirements in web services, and the second introduces DOM and two of its implementations, namely, Microsoft XML (MSXML) and Xerces.
Note that we acknowledge that DOM is not always the only or best way to process either XML or web services, but it has advantages in ubiquity and deployment.
XML Authoring and Processing Requirements in Web Services
Listing 1 is a simple WSDL file. The purpose of WSDL is to define the syntax for describing web service interfaces. The syntax includes three major components: the name of the request method, the parameters that go along with the request, and the details of the message that the web service will send in response. Further explanation of WSDL can be found in various articles on WebServices.XML.com.
A WSDL description can be processed to produce an HTML-based presentation format for human interaction with web services and to produce SOAP messages that will interact with a SOAP server.
Listing 2 is a simple HTML file that we have derived from the WSDL file of Listing 1. At the moment we are only concerned with explaining the XML processing and authoring requirements of transforming a WSDL file into an HTML file for presentation to web service users. We will later demonstrate how this is accomplished using DOM APIs.
Notice the following points about the WSDL to HTML transformation:
The HTML file contains a paragraph (a
pelement) and a table.
The paragraph contains a heading (an
h3element) and a sentence.
Notice that the string wrapped inside the
"WeatherService", which has been taken from the
nameattribute of the
serviceelement in Listing 1. Recall from earlier discussion that the
nameattribute value of the
serviceelement is the name of the service. That's why we have used this name as the heading for our web service invocation page.
Similarly, we have copied the description of our web service from the WSDL file and included it immediately after the heading in the HTML file.
The table in the HTML file of Listing 2 contains a form. The form in turn contains a number of rows.
The first and second rows contain the name and description of the
GetCityWeatherReportrequest method. These two bits of information are also copied from the corresponding elements of the WSDL file of Listing 1.
The table also contains an
inputelement, which represents the parameter that this request method takes to invoke the
GetCityWeatherReportweb service method. The user will need to enter the name of the city for which he wants to get the whether report.
The HTML file of Listing 2 is derived from the WSDL file of Listing 1 to enable human interaction with our web service. Similarly, we can also author a SOAP request by reading bits of information from a WSDL file.
Look at Listing
3, which is a SOAP message that carries the
GetCityWeatherReport method invocation request to our web
service. Of particular interest,
The name of the method (
GetCityWeatherReport) defined in the WSDL file becomes the name of the immediate child element of the SOAP Body element.
The user who wants to invoke our web service will need to provide the
CityNameparameter value (the
partelement inside the first
messageelement in Listing 1). This value is wrapped inside the
CityNameelement in Listing 3. Notice that the
nameattribute value (
CityName) of the
partelement in Listing 1 becomes an element name in the SOAP request of Listing 3.
This description of the WSDL-to-HTML transformation and SOAP authoring is meant to give you an idea about the XML processing requirements in web services. This type of transformation can be accomplished in several ways, one of which is by using DOM.
On the other hand, if you decide to use server side DOM, your web server will use its DOM implementation to author HTML and SOAP.
This series of article will demonstrate the use of both client and server side DOM implementations. It is time when we start looking at the DOM APIs. The following section introduces DOM and two of the most important DOM implementations, MSXML and Xerces.
Document Object Model
DOM represents an XML document as a tree of nodes. DOM defines various types of nodes corresponding to the different XML constructs. For example an XML element is an element node, an XML attribute-value pair is an attribute node, the content of an element is a text node and so on.
You can load an XML document into a DOM tree of nodes. For example a partial DOM representation of Listing 1 is shown in Figure 1. We have shown all element nodes as green, and all attribute nodes as blue in Figure 1.
|Figure 1: Partial DOM representation of Listing 1|
Nodes in a DOM model are related to each other in a parent-child or
sibling relationship. For example, note from Figure 1 that
portType elements are children of
definitions element and are siblings of each other.
Notice that the
document node in Figure 1 is the parent of
the root (
definitions) node, which means all nodes in a DOM
model are direct or indirect children of the document node.
interfaces use the concept of inheritance from Object Oriented
Programming. The different types of nodes (such as element node, attribute
node, text node etc.) inherit from a generic
The tree structure of DOM is object oriented, which means that the
different nodes shown in Figure 1 are not just data structures. Each node
is an object, which contains both data and methods to manipulate the
object. For example, you can take the
definitions node and
call its methods to get a list of its child element nodes. You can then
take a particular child element and call its methods to move further down
the DOM tree. This way you can traverse the entire DOM document.
In order for all this to work, the DOM specification defines the programmatic interfaces for different types of nodes to expose their functionality. Using these programmatic interfaces of DOM, you can fulfill all the XML authoring and processing requirements of web services discussed earlier in this article. You will take your WSDL file, load it into a DOM document, and then use the various DOM interfaces for XML authoring and processing.
Recall from the discussion in the last section that we may need to generate HTML pages from our WSDL files. For such applications, DOM provides an HTML-specific interface, which is especially designed to author or process HTML documents. Therefore, we can load our WSDL file into a DOM document, read the various bits of information from the WSDL file, and author HTML using the HTML-specific DOM interfaces.
From Level 1 to 3
W3C has developed DOM in levels. Level 1 included the basic features for XML processing such as traversing through the structure of an XML file, getting all children of a particular node, checking the type of a node (whether it is an element node or an attribute node or some other type of node), setting and reading the attributes of a particular element node, jumping to the next or previous sibling of a particular node, adding or removing attributes of a particular element node, appending a new child to a node, getting a list of all elements with a particular name, working with XML processing instructions, etc.
In addition to these XML features, DOM Level 1 also contains an HTML-specific set of interfaces, which can handle individual HTML elements. For example, in DOM Level 1, you can work with HTML tables, forms, and selection lists etc.
Level 2 has added several features to those of DOM Level 1. For example, there was no support of namespaces in DOM Level 1. While working with several namespaces in the same DOM Level 1 document, you have to write your own programmatic logic to manage namespace URIs, prefixes, and element names. DOM Level 2 interfaces contain methods to manage namespace related authoring and processing requirements.
DOM Level 3 is currently a working draft at W3C and adds further to DOM Level 2 functionality. One of the important features that is being added to DOM in its Level 3 is the ability to work with multiple schema-specific DOM extensions.
For example, you may want to define schema-specific programmatic interfaces for your own XML vocabularies, just like the HTML-specific interfaces in DOM Level 1. If you do so, you have developed a high level programmatic interface to manipulate XML according to your own schema. Similarly many companies will come up with their own schema-specific XML authoring and processing interfaces, which can all be implemented using DOM interfaces at a lower level.
Sometimes you will need that such schema-specific interfaces be used in one application together with standard DOM interfaces. DOM level 3 provides a mechanism for developing schema-specific interfaces as DOM extensions and using different DOM extensions together in one application.
In web service applications it is very common that different namespaces be used together in the same WSDL-based web service interface. Therefore, schema-specific DOM interfaces may be developed and used together in a single web service application. The second and third articles of this series will discuss this concept further.
Pages: 1, 2