DOM for Web Services, Part 3
January 6, 2004
In the first article of this series I discussed the XML authoring and processing requirements in web services, explained the DOM architecture along with the features in the three DOM levels, and introduced MSXML and Xerces, two popular DOM implementations.
In this third and final article of this series I demonstrate the use of Xerces, which is the most popular Java-based implementation of DOM. In this article's first section I develop a couple of Java classes that can create and process SOAP messages. This will demonstrate the basic DOM features of Xerces. In the second section I demonstrate the use of some other important features, including:
- Working with multiple XML documents in which you need to import XML nodes from one document into another.
- The use of Xerces to generate DOM events, and writing your own event handlers to handle the events generated.
- The use of DOM range and DOM document fragments. The DOM range specification provides an easy to use method for grouped processing of several XML nodes.
The third section contains a discussion of the Load and Save module, an important feature in DOM level 3 which is not yet supported in Xerces.
The last section wraps up this series by explaining the scenarios in which you will most likely use DOM for XML authoring and processing requirements in your web service applications.
W3C DOM and Xerces
Xerces is part of the Apache XML project. It is available for Java and C++. In this article I only cover Xerces for Java, which is commonly called Xerces-J. The most recent version of Xerces-J available at the time of writing is 2.6.
Note that W3C DOM is not the only XML API that Xerces supports. Xerces also supports SAX and a proprietary interface called Xerces Native Interface (XNI). Complete documentation about Xerces is available from the Xerces site. I will discuss only the W3C DOM features of Xerces.
Also note that the Java Web Services Developer Pack (JWSDP) from Sun includes standard XML processing Java APIs, including the Java API for XML Processing (JAXP). The current reference implementation of JAXP uses Xerces as its default XML processing engine. If you download JWSDP from Sun's site, you will get Xerces, and you won't need to download it separately.
However if you are using JDK1.4, you have a small problem to take care of before
to use Xerces. JDK1.4 ships with an older version of Xerces. Even if you include Xerces
in your classpath, the Java runtime will use the older version of Xerces and not the
that comes with JWSDP. The instructions for solving this problem come with the JWSDP
installation. When you install JWSDP under Windows (the latest release for now is
1.3), you will see instructions for JDK1.4 users saying "Create the directory:
<JAVA_HOME>\jre\lib\endorsed and then copy the files in the following
directory to the newly created directory:
The files in the
C:\jwsdp-1.3\jaxp\lib\endorsed directory of JWSDP include a
Xerces-J jar file named xercesImpl.jar. When you create the new
<JAVA_HOME>\jre\lib\endorsed directory and copy the files from the
C:\jwsdp-1.3\jaxp\lib\endorsed directory to the newly created location, you
are telling the Java runtime to use the new version of Xerces instead of the old Xerces
implementation that comes as part of JDK1.4.
However, if you don't want to download and install JWSDP, you can download Xerces and copy the xercesImpl.jar
file into the
Once you have the
xercesImpl.jar file at its correct place, you will not need
to include anything in your classpath to compile and run the samples of this article.
The source code
download contains source and compiled form of all the samples that we are going to use
for demonstration in this article.
Xerces for SOAP authoring
Look at Listing 3
of the first article of this series, which was a SOAP message that we used to describe
the usage model of web services. Notice that the SOAP message contains elements belonging
two XML namespaces. The first is the SOAP namespace and the second is an application
specific namespace (
The use of these namespaces demonstrate that XML and SOAP specifications allow building
layered applications, where the application-specific layer works on top of the SOAP
The SOAP specification defines the
Body elements and allows applications to define their own namespaces to fill
in the header and the body of a SOAP envelope.
This layered architecture is a great strength of XML web services. It allows vendors
develop off-the-shelf standard solutions (e.g. a SOAP client or a SOAP server) and
application developers to add only the application-specific bit of the layered framework.
For example, if you consider the SOAP message of Listing 3 of the first
article, you will see that the only application specific elements are
CityName. The rest of the markup is
We are going to use the same idea of layering application bits. We will have two classes in our sample DOM-based SOAP engine:
DataWrapper class creates the application-specific data that go along
with the SOAP method call (e.g. the
CityName element in Listing 3 of the first
SOAPMessage class creates the SOAP
along with the SOAP
Body. As a SOAP request usually contains the name of a web
service method, so the same
SOAPMessage class will also author the method
element (usually the immediate child of the SOAP
But how do these classes use DOM to create XML?
Look at the
add() method in Listing 1, which
takes three parameters. The first parameter is the name of the data element (e.g.
CityName in Listing 3 of the first
article). The second parameter specifies the namespace to which the data element
belongs. The third parameter specifies the contents of the data element (e.g.
"Karachi" in Listing 3 of the first
add() method simply stores these parameters in a list. An
application can call this method any number of times. Every time an application calls
method, a new set of data will be added to the items already stored in the list.
appendAsChildren() method in Listing 1 takes
just one parameter named
parentElement, which is a DOM element. The
appendAsChildren() method takes all the entries in the list one by one and
adds them as child nodes to the
Notice from Listing
1 that the
appendAsChildren() method first calls the
getOwnerDocument() method of the
parentElement object. The
getOwnerDocument() method belongs to the DOM
Node interface. It
Document object to which a DOM node belongs. We need to know the
owner document whenever we want to add a child element to an existing element.
After getting the owner
Document object, the
method performs the following operations for every entry in the list:
- Create a new element using the
createElementNS()method of the owner
createElementNS()method takes two parameters. The first parameter is the namespace URI string for the element that you want to create. The second parameter is the name of the element. The
createElementNS()method returns the newly created
Elementobject, which represents the name of a parameter that goes along with a SOAP method invocation request (e.g.
CityNamein Listing 3 of the first article).
- Append the newly created DOM
Elementas a child to parentElement by calling the
appendChild()method of parentElement.
- Create a new text node by calling the
createTextNode()method of the owner document object and append the text node as a child to the newly created
Elementnode. This text node represents the value of the parameter that goes with a SOAP message call (e.g. "Karachi" in Listing 3 of the first article).
Just for the sake of demonstration, we have written a simple
main() method in
Listing 1. The
main() method demonstrates how an application will use the functionality of
Now have a look at the
SOAPMessage constructor in Listing 2. It
takes three parameters:
methodName parameter represents the name of the
SOAP method that the SOAP message will invoke on a remote server (e.g.
GetCityWeatherReport in Listing 3 of the first
methodNamespace parameter represents the namespace to which
the methodName element belongs (e.g. "http://www.cityportal.com" in Listing 3 of the first
parameters parameter is a
which wraps all the data that goes with the SOAP method invocation request.
SOAPMessage constructor creates a SOAP message. So you first have to
create a new empty XML document. Creating a new XML DOM document in Xerces takes three
steps. You first instantiate a
DocumentBuidlerFactory, then you create a
DocumentBuilder, and then using the
newDocument() method of the
DocumentBuilder, you create a DOM
Document object. You will use
newDocument() method whenever you want to create a new empty XML DOM
document containing no data. The
Document object that the
newDocument() returns exposes the DOM
Once you have the DOM document, you can author the root
Envelope element by
createElementNS() method discussed earlier.
After creating the
Envelope element, you need to attach the element to its
Envelope is the root element, so the
Document object is
its parent. Therefore, you will call the
appendChild() method of the
Document object to attach the
Envelope element to the document.
Note that an XML document can have only one root element. That's why you can attach
one element node to a
Document object. If you try to attach more than one
element node, you will get an exception at runtime.
In a similar manner we have created the
Body element (the
bodyElement object), attached it to the
created the SOAP method name element (the
methodElement object), and attached
it to the
Finally we have to author the elements that represent parameters associated with
method invocation request. This is the job of the
appendAsChildren() method of
DataWrapper class that we have already explained. You will call the
appendAsChildren() method of the parameters object and pass the
methodElement object along with the method call. This will automatically
append the parameters data to the SOAP method call.
Also look at the
getSOAPRequestText() method in Listing 2, which
was written to demonstrate XML processing in Xerces. It takes a
and returns its XML data in string form. It uses a method called
getElementAsText(), which is recursive and is responsible for creating the
XML data corresponding to the root element and all its children.
The following points are worth noting from the
getElementAsText() method in
- We have used the
getTagName()method of the
Elementobject to read the tag name of the element. The tag name consists of both the prefix and the local name (i.e. if the prefix is "
env" and the local name is "
Envelope", the tag name will be "
- We have used the
getAttributes()method of the
Elementobject to read all the attributes of an element into a
NamedNodeMapobject is used to hold a number of nodes, where each node is accessible by name or index number. We have used
item()methods of the
NamedNodeMapinterface to fetch all attribute nodes . The
getLength()method returns the total number of nodes in a
items()method returns the node at a particular index.
- We have used the
getNamespaceURI()method to get the namespace URI of each element. Recall from earlier discussion that the
createElementNS()method creates an element with a namespace URI and a tag name. The
getNamespaceURI()method returns the same URI.
- We have used the
getPrefix()method to fetch the namespace prefix of all elements.
Node.getNodeType()method tells the type of a node (e.g. whether a node is a text node or an element node). We have used this method to differentiate text nodes from element nodes.
main() method in Listing 2
simulates a simple SOAP application. We have instantiated a
and called its
add() method once to add one parameter. We have then
SOAPMessage object and passed the
object to the
SOAPMessage constructor. Listing 3 shows
the resulting SOAP message.
Some Important DOM Features
This section demonstrates some important DOM features of Xerces that are not covered in the sample SOAP application of the previous section.
Copying DOM Nodes from one document into another
Have a look at Listing 4, which is a simple Java class named DOMCopySample.java. The
main() method of this class demonstrates how to copy DOM nodes from one
document into another.
Notice from Listing
4 that we have used the
parse() method of the
DocumentBuilder object to load an XML file into the DOM
sourceDoc. The name of the file that the
method will parse is "inputXML.xml". We have shown the "inputXML.xml" file in Listing 5, which
Recall that when we were creating the SOAP message document in Listing 2, we used
newDocument() method of the
DocumentBuilder class to create an
empty DOM document with no XML data. You will use the
parse() method (instead
newDocument() method) when you want to create a DOM document from an
existing XML file or an input data stream containing XML data. The
method parses the input XML data, loads the data into a DOM
and returns the
After loading the XML file into the
sourceDoc object, we have called the
getElementsByTagName() method of the
Document object and passed
"invoice" as a parameter. The
getElementsByTagName() method belongs to the DOM
Document interface. It takes the name of an element as a parameter and
NodeList object, which contains a list of all elements in the DOM
document that have names matching the input parameter to the
getElementsByTagName() method call.
NodeList is a DOM interface, which exposes the abstract functionality of a list
of nodes. It contains just two methods,
getLength() method returns the number of nodes in the
NodeList and the
item(int index) method returns the node at a
Some readers may want to compare the
NodeList interface with the
NamedNodeMap interface discussed earlier. The main difference is that you
cannot access individual nodes in a
NodeList by names of nodes, while you can
do this in a
After getting the
NodeList object in Listing 4, we have
created a new empty DOM document object named
targetDoc. We have then created
invoiceWrapper element, which serves as the root element of the newly
Next we have taken each element in the
NodeList and passed it to the
importNode() method of the
targetDoc object. The
importNode() method imports a node from one document into another document.
It takes two parameters. The first parameter is a node which you want to import from
other DOM document. The second parameter is of boolean type. If the second parameter
importNode() method will import the node along with all its child
nodes (i.e. the complete tree of nodes whose root starts at the node being imported).
second parameter is false, the
importNode() method only imports the node
without any of its children.
After importing the
invoice elements from
targetDoc, we have appended the imported elements as children of the
invoiceWrapper element. Listing 6 shows
targetDoc looks like after importing all the
invoice nodes of
sourceDoc (the inputXML.xml file of Listing 5).
Working with DOM events
The DOM level 2 contains a separate specification for events, which can be very helpful in developing XML processing applications. This section demonstrates how to generate and handle DOM events in a Xerces application.
If you want to use DOM events in your Xerces applications, you need to follow the
events architecture. The important components of the DOM events architecture are three
If a particular DOM implementation supports DOM events, all its nodes will implement
EventTarget interface. Thus, you can cast any object that implements the
Node interface (or any interface that extends the
interface, such as the
Document interface) as an
If a DOM implementation does not support DOM events and you try to cast its nodes
EventTarget objects, your application will throw exceptions as runtime. So
you need a mechanism to verify that the DOM implementation you are using supports
before trying to cast a node as an
DOM Level 2 has an interface called
hasFeature() method can help you check whether a particular DOM
implementation supports a particular DOM feature. You can call the getDOMImplementation()
method of the DocumentBuilder object to get a
DOMImplementation object. You can
then call the
hasFeature() method of the
to check whether it supports a particular DOM feature.
hasFeature() method takes two parameters. The first parameter specifies
the name of the feature that you want to verify. The DOM Level 2 Core specification
the names of different DOM features. The name of the events feature is "Events". The
parameter defines a version number of the feature. For all DOM Level 2 features, you
pass "2.0" as the second parameter.
Have a look at Listing 7, where we have tested the Events feature by calling the
DOMImplementation.hasFeature("Events","2.0") method, which returns true
(meaning Xerces supports the DOM Level 2 Events feature).
There are various types of events in DOM Level 2, e.g. mutation events, user interface events, mouse events, etc. The current Xerces implementation only supports mutation events. Mutation events are generated whenever a node gets mutated. For example, a mutation event can be generated whenever the value of an attribute in a DOM tree is changed.
Now let's see how you will use mutation events in Xerces. Have a look at Listing 7 and observe the following sequence:
- After verifying the support of Events feature, we have created a new
Documentobject and added one element node to the newly created document. We have then cast the
Documentobject as an
EventTargetobject. As we have used the
Documentnode as an event target, any node in the document can generate an event for this target.
- Next we have called the
addEventListener()method of the
EventTargetinterface, which adds a listener to the event target (the
addEventListener()method takes three parameters. The first parameter specifies the type of event you want to generate. There can be several types of mutation events. For example, the
DOMAttrModifiedevent occurs whenever a DOM attribute value gets modified. (For a complete list of the possible types of DOM Level 2 mutation events, consult section 1.6.4 of the DOM Level 2 events specification.) The second parameter specifies an event handler object, and the third parameter specifies whether the user wants to initiate capture of an event. We don't want to use this feature, so we have passed "false" as the third parameter.
- Finally, we have to write an event handler class (whose instance we passed as the
parameter to the
addEventListerner()method). In order to write an event handler, you have to implement the DOM's
EventListenerinterface, which contains just one method named
handleEvent()method of the event handler object will receive control whenever a mutation event occurs on the
Documentobject that you registered as an event target.
Notice from Listing
7 that we have written an inner class named
handleEvent() method. The
takes just one parameter, which is an object that implements the
Event object carries information about the event that occurred
and which needs to be handled.
handleEvent() method will normally call the
method to know the type of event that occurred. You can check the type of mutation
that occurred and then take an appropriate event handling action according to the
Notice that in the
main() method of Listing 7, we have
added two new attributes to the DOM
Document object after registering the event
listener. Therefore, if you run the class of Listing 7, the
handleEvent() method of the
MyEventListener class will receive
control twice (once for each attribute added).
The concept of events is especially useful when you have a comprehensive XML application in which there are several DOM Documents with many nodes and each node has a possibility of being edited at several places in your business logic. In such cases, you can use the DOM events architecture. You will only have to write the event handling logic without worrying about calling the event handlers yourself. The DOM events framework will take care of calling the event handlers for you at appropriate time.
A range of DOM nodes and DOM document fragments
The concept of having a DOM range allows you to select a number of DOM nodes into a single range of nodes and then process the full range of nodes together in one go. For example, you can select a number of DOM nodes of a DOM document into a range and then import the range into another DOM document. This will import the whole range of nodes into the new document. Let's see how.
Have a look at Listing 8, which first checks whether the DOM implementation being used supports the
"Range" feature and then casts a
Document object as a
DocumentRange object. This process is similar to what we did earlier while
trying to use the "Events" feature.
DocumentRange interface exposes the
that you can use to create a new
Range object. The
exposes methods that you need to use the DOM range feature.
Range object represents a range of DOM nodes, which starts at a starting
point and ends at an ending point. You can move the starting and ending points to
your range over the set of nodes of your choice. In order to move the two points,
need to use the different methods of the
When a range is initially created, both its starting and ending points are positioned
the beginning of the document with which the range is associated. Notice from Listing 8 that
after creating a new range, we have created six elements i.e. a wrapper (the root
and its five children named
Next we have called the
setEndBefore() method of the
object, passing the
e5 element as a parameter along with the method call. This
sets the end of the range before the
e5 element, which means now the range ends
e4 element. We have also called the setStartAfter() method of the
Range object and passed the e1 element as a parameter. This sets the start of
the range just after the e1 element, which means the range now starts at the
element. Our range now covers the
We can now process the nodes in our range together in one go. For example, we have
cloneContents() method of the
Range object, which returns a
DocumentFragment object. A
DocumentFragment interface is also
part of DOM and extends the
Node interface. It is like a lightweight document,
similar to the
Document interface, but with limited features.
DocumentFragment object that the
returns contains a copy of each of the nodes covered by our
Range object. You
can directly import the
DocumentFragment object into a new DOM document, just
like importing any other type of node. This will result in importing all the nodes
DocumentFragment into the new document.
For example, in Listing 8, after calling the
cloneContents() method, we have created a
new DOM document, added a wrapper root element, and imported the
DocumentFragment into the newly created document. The newly created document
now contains copies of the
and looks like the XML file of Listing 9.
Therefore, you can use the concept of DOM Range by first selecting the start and end positions of the range and then performing the operation of your choice on the range that you have selected.
The Load and Save module in DOM Level 3
DOM Level 3 includes a load and save module which provides a mechanism for loading
data into DOM
Document objects and for serializing DOM
objects as XML data. Before the DOM Level 3, there was no such mechanism in DOM. Therefore
DOM implementations used to build proprietary mechanisms for loading and saving.
The DOM Level 3 load and save module is currently under development for. It is not yet part of the standard Xerces download. So we will not demonstrate how to use the load and save module in Xerces. Instead we'll just describe the important interfaces in the load and save module of DOM Level 3.
The primary interface in the DOM load and save module is
which is meant to extend the features of the
DOMImplementation interface that
we saw earlier. You can check whether a particular DOM implementation supports load
by calling the
hasFeature("LS","3.0") of any
instance. In case the
DOMImplementation.hasFeature() method returns true, you
can cast the
DOMImplementation object as a
DOMImplementation interface contains a method named
createLSInput(), which creates and returns an instance of the
LSInput interface. The
LSInput object is capable of
encapsulating XML data in different forms, such as a textual string, a character stream,
a byte stream. After creating the
LSInput interface, you can set XML data in
one of the data fields of the
The load and save module also contains an
LSParser interface, which you can
instantiate using the
createLSParser() method of the
DOMImplementationLS interface. You can call the
LSParser object and pass on the
LSInput object to the
parse() method. The
parse() method will return the DOM document
representation of the XML data that you set in the
LSInput object, thus
completing the process of loading XML data into a DOM
When you want to serialize a DOM document as XML data, you will use the
LSSerializer interface, which you can instantiate using the
createLSSerizlizer() method of the
DOMImplementationLS instance. You can then
writeToString() method of the
LSSerizlizer object, which
takes a DOM
Node (e.g. a
Document node) and returns the string
representation of the input DOM
When should I use DOM?
We have discussed many DOM features in this series of articles. We have demonstrated that DOM is a powerful API for low level XML authoring and processing. As web services have gained popularity, many higher level XML processing engines have emerged. These higher level engines normally target specific XML-based languages and schemas. For example, the Microsoft .NET framework contains easy to use features that enable WSDL and SOAP processing in web service applications. Similarly, the JWSDP also contains APIs for XML-based Remote Procedure Calls (RPC). Therefore, it is expected that many developers will prefer using higher-level schema-specific APIs rather than using DOM for low level XML processing.
The following are the two common scenarios where you will likely use DOM in your XML applications:
- New XML-based protocols are currently under development. Protocols for XML-based transactions are an example. As new protocols emerge, it will take a bit of time for corresponding higher level APIs and processing engines to appear and mature. DOM will help you in protocol-specific XML authoring and processing during this transient phase of XML-protocol development.
- In addition to protocol specific processing, you will also need DOM for the processing of application-specific XML data in SOAP applications. We have already discussed application-specific namespaces in SOAP messages at the start of the "Xerces for SOAP authoring" section. Many industry specific XML schemas for different requirements (such as invoices, work orders, purchase orders, shipping documentation, payment information, product catalogs, etc.) are expected to emerge and be layered over the SOAP framework. Therefore, it is likely that you will be using high-level protocol-specific engines for the processing of standard markup and low level XML APIs like DOM for the processing of industry-specific XML namespaces.