DOM for Web Services, Part 1
October 14, 2003
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
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
are children of the
definitions element and are siblings of each other. Notice
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.
DOM 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
The tree structure of DOM is object oriented, which means that the different nodes
Figure 1 are not just data structures. Each node is an object, which contains both
methods to manipulate the object. For example, you can take the
node and call its methods to get a list of its child element nodes. You can then take
particular child element and call its methods to move further down the DOM tree. This
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.
MSXML, by Microsoft, implements DOM Level 2 interfaces. In addition MSXML also adds some extended features not included in DOM Level 2.
Some of the MSXML's DOM level 2 interfaces include:
IXMLDOMNode interface is the generic DOM node from which all the different types of nodes extend. You will never use this interface directly. Rather you will use the different types of nodes (e.g. element node, attribute node etc.) that extend from the IXMLDOMNode interface.
IXMLDOMDocument interface exposes the functionality of a document node, which holds the entire DOM document as its direct or indirect children. You will normally start DOM authoring and processing with this interface.
IXMLDOMElement interface defines the functionality of a DOM element node. For example, it has methods to get the list of attributes associated with an element or fetch a particular attribute value, etc.
IXMLDOMNodeList interface helps in manipulating a list of DOM nodes (such as all child element nodes of an XML element). It contains methods to iterate through the child element list and find a particular node in the list.
IXMLDOMText interface exposes methods to manipulate the textual content of an XML element.
IXMLDOMComment interface is used to play with comments in an XML file.
IXMLDOMAttribute interface represents the functionality of an attribute node (for example to edit an attribute value).
In addition, MSXML also implements the HTML-specific DOM interfaces for HTML authoring
processing. The HTML-specific interfaces provide simple set and get methods to populate
HTML body with
<input> and other HTML elements.
Or otherwise you can directly generate HTML on the client side using the same DOM features of MSXML.
Have a look at Listing 4, which is meant to introduce XML processing with MSXML. Listing 4 is
FindServiceDocumentation, which reads the contents of the
documentation element within the
service element of Listing 1 and
prompts the comments to the user as a browser alert.
Following is a brief explanation of how the
FindServiceDocumentation method in
Listing 4 works
The first line in the
FindServiceDocumentationmethod instantiates an MSXML object.
The second, third, and fourth lines of code method are variable declarations, which we will use to hold different DOM element nodes.
The fifth line (
xmlDoc.load) loads a WSDL file into DOM.
The next line is an
ifstatement, which checks whether there were any errors while loading the XML document. The most probable error is perhaps that the XML that you want to load into DOM is not well formed.
If there were no problems while loading XML into DOM, we will read the root element and check if it is
definitions. If it is not definitions, we are not interested in further processing.
If the root element is definitions, we will try to find its
serviceelement. Note that the line
serviceElement = definitionsElement.getElementsByTagName("service").item(0)actually works in two steps. First the
getElementsByTagNamereturns a list of all
serviceelements and then the method
item(0)returns the first element from the list.
Similarly, we read the
documentationelement in the
Next look at the
alertline, which contains
documentationElement.firstChild.nodeValuemethod call. This method works in two steps. The
documentationElement.firstChildmethod call fetches the first child node of the
documentationelement. The first child of the
documentationelement is the required text node that we were looking for. The
nodeValueproperty returns the value of the text node as a textual string. The alert statement displays the textual string as an alert.
We have kept Listing 4 and its explanation very simple and brief, as this is only an introduction. Real world XML authoring and processing is never so simple. We will take this example further in the second article of this series and demonstrate the use of MSXML for both XML and HTML processing as well as authoring in detail.
Xerces is a Java-based DOM Level 2 implementation by Apache. In addition Xerces partially supports DOM Level 3. You can create Java-based SOAP client side applications using Xerces, however it is mostly used on the server side.
Xerces interfaces are similar to the interfaces that you have seen while discussing MSXML, which is natural to expect, as both are DOM implementations.
The third article of this series will demonstrate the use of Xerces in detail. For the moment, just notice the following points Xerces interfaces:
Almost all interfaces extend from the Node interface.
The Document interface allows you to manipulate the complete XML document. Normally you will use the
Documentinterface to get the root element of the XML document. You can also use this interface to import a node from some other DOM document into this document.
The Element interface allows you to process or author elements (e.g. adding attributes to or removing attributes from an element).
NodeListinterface is used to manipulate a list of nodes.
We have provided a brief introduction of MSXML and Xerces. The second article will demonstrate the use of MSXML, while the third article will demonstrate the use of Xerces. Both the second and third articles will use the web services usage models and XML authoring and processing requirements as an example application scenario to demonstrate the use of DOM features.