he DOM 3.0 Validation specification provides for validation of an XML document with a DTD or an XML Schema. The advantage of DOM 3.0 Validation over validation with a validating parser such as the DOMParser is the support for dynamic validation. The DOM 3.0 Validation specification implementation retrieves the metadata definitions from the XML Schema and provides methods to query the validity of DOM operations?for example the addition and removal of attributes and elements?so that you can validate potential document modifications before actually making them.

This article discusses how to use the DOM 3.0 validation implementation classes in XDK 10g Production using an example XML document called catalog.xml (see Listing 1), and showing how to validate it with an example XML Schema document called catalog.xsd (see Listing 2). Copy both the catalog.xml and catalog.xsd files to the same directory, for example, C:/DOM3Validation. XDK 10g is the only XML API which implements the DOM Level 3 Validation specification; however, some of the DOM 3Validation features are not implemented by the Oracle XDK 10g API. A test was run by W3C to determine which of the DOM3 Validation methods are supported by the XDK implementation. You can refer to the results of the DOM3 Validation test when developing a DOM 3 Validation application.

Preliminary Setup
To validate an XML document with the DOM 3.0 Validation API you need to add the org.w3c.dom.validation package classes to your classpath. First, download XDK 10g. Extract the downloaded file xdk_nt_10_1_0_2_0_production.zip to a directory. Add the /lib/xmlparserv2.jar and /lib/xschema.jar files to your classpath, where is a placeholder for the directory in which you installed XDK 10g Production.

Document Node Validation
In XDK 10g Production, the DOM 3.0 Validation specification is implemented with the DocumentEditVAL, ElementEditVAL, and NodeEditVAL interfaces. As the names indicate, you use the three interfaces to dynamically validate a document node?that is, the entire document, an element, or any individual node, respectively.

To validate a document, you use the DocumentEditVAL class. First, import the DOM 3.0 Validation specification classes and the load and save (LS) specification classes.

   import org.w3c.dom.validation.*.   import org.w3c.dom.ls.*;

Create an LSParser instance to parse an XML document. To create a LSParser, first create an XMLDOMImplementation object. Subsequently, create a LSParser object from the XMLDOMImplementation object using the createLSParser(short, String) method. The parameter of type short specifies the parsing mode: MODE_SYNCHRONOUS or MODE_ASYNCHRONOUS. If the mode is set to MODE_SYNCHRONOUS, as in this tutorial, the parse() and parseURI() methods of the LSParser object return an org.w3c.dom.Document object. If the mode is set to MODE_ASYNCHRONOUS the parse() and parseURI() methods return null. The String parameter of the createLSParser() method specifies the schema type. For an XML schema, the schema type value is http://www.w3.org/2001/XMLSchema.

   XMLDOMImplementation impl = new         XMLDOMImplementation();   LSParser parser = impl.createLSParser(      DOMImplementationLS.MODE_SYNCHRONOUS,    "http://www.w3.org/2001/XMLSchema");

Parse the example XML document catalog.xml using the parseURI(String uri) method

   XMLDocument document = (XMLDocument)(      parser.parseURI(      "file://C:/DOM3Validation/catalog.xml"));

You set the XML schema for validating the XML document using an XMLSchema object, which you can obtain from an XSDBuilder object using the build(URL schema) method. The URL parameter specifies the URL for the XML schema. Here’s an example of creating an XMLSchema object.

   XSDBuilder builder = new XSDBuilder();   URL url = new URL(      "file://c:/DOM3Validation/catalog.xsd");          XMLSchema schemadoc = (XMLSchema)builder.build(url);

Set the schema document you want to use to validate the XMLDocument.

   document.setSchema(schemadoc);

Create a DocumentEditVAL object from the XMLDocument object by casting the XMLDocument object to DocumentEditVAL.

   DocumentEditVAL documentEditVAL=(      DocumentEditVAL)document;

Set the validity checking of the DocumentEditVAL document using the method setContinuousValidityChecking(boolean continuousValidityChecking). If you pass true, the validity of the XML document with the XML schema is continuously checked. If set to false (the default value) the XML document’s must be checked with a validation method.

   documentEditVAL.setContinuousValidityChecking(true);

Validate the XML document catalog.xml with the XML schema catalog.xsd.

   short valid=documentEditVAL.validateDocument();

There are three possible return values. If the XML document is valid, the value of the valid variable will be VALID_TRUE; otherwise, it will be VALID_FALSE. If the validity of the XML document is not known, it will be VAL_UNKNOWN.

For the example XML document and XML Schema document the output is

   Document is VALID_TRUE

Global Element Declarations
You can obtain the global element declarations in an XML schema to determine which elements, except the root element, may be added to an XML document. A global element is a top level element in an XML schema declared with xsd:element element. Global elements in an XML document are obtained using the getDefinedElements(String namespaceURI) method, for example:

   NameList elementList =      documentEditVAL.getDefinedElements(null);

Using the sample XML Schema, the elementList would be filled with:

   Element at index 0 is article   Element at index 1 is journal   Element at index 2 is catalog 

The elements title and author in the XML Schema do not get listed, because they aren’t global elements.

Element Node Validation
The ElementEditVAL interface provides methods for dynamically validating an element node. Some of the commonly used methods of ElementEditVAL interface are discussed in Table 1. I’ve provided a more detailed description and examples of these methods in the following sections of this article.

Table 1. ElementEditVAL Methods: The table shows common ElementEditVal methods you’ll use when dynamically validating elements in an XML document.

The canAppendChild() MethodYou can test the validity of appending an element using the canAppendChild() method.

As an example, suppose you want to append a journal element to the catalog element in the sample document. You first get a reference to the catalog element, create the journal element, and then use the canAppendChild() method to check whether appending it to the catalog element would be a valid operation, as shown below:

   XMLElement catalogElement = (XMLElement)       (document.getDocumentElement());   ElementEditVAL elementEditVAL = (ElementEditVAL)       (catalogElement);   Element journalElement =       document.createElement("journal");   short editValJournal =       elementEditVAL.canAppendChild(journalElement);

In this case, because the journal element is defined in the catalog element (see Listing 2), the output in the example validation program is:

   Element Addition is VALID_TRUE

The canRemoveChild() Method
The canRemoveChild() method checks the validity of removing an element. As an example, if you check to see if you can remove the journal element, you’ll get a VALID_TRUE return value, because the schema specifies it as minOccurs=0.

   XMLElement journal = (XMLElement)       (catalogElement.getElementsByTagName(      "journal").item(0));   short elementRemove = documentEditVAL.canRemoveChild(      journal);

The isElementDefined() method checks whether a global element is defined in a schema. For example, to check whether a title element is defined in the sample schema, you can write:

   short elementDefined =       elementEditVAL.isElementDefined("title");

Because the title element defined in the catalog.xsd schema is not a global element the return value is VALID_FALSE.

The getAllowedChildren() Method
The getAllowedChildren() method returns a list of elements allowed in an element, providing another way to determine whether adding an element would be a valid action. As an example, here’s how to output the elements which can be added to the article element.

   XMLElement articleNode = (XMLElement)       (document.selectSingleNode(      "catalog/journal/article"));   ElementEditVAL articleVAL = (ElementEditVAL)       (articleNode);   elementList=articleVAL.getAllowedChildren();

After running the preceding code, you’ll find that the elementList return value contains two elements: author and title.

The getContentType() Method
The getContentType() method returns the content type an element is allowed to have. For example, this code retrieves the valid content type for an article element:

   short contentType=articleVAL.getContentType();

If the value of the short variable returned by the getContentType() method is VAL_ANY_CONTENTTYPE, the element content is element, processing instruction, unexpanded entity reference, character, and comment information items.

The return value is a short that represents the valid content type as shown in Table 2.

Table 2. Content Types: The table shows valid content type short values.

For the article element, getContentType() returns VAL_ELEMENTS_CONTENTTYPE?in other words, the article element can contain a sequence of elements.

The nodeValidity() method checks the validity of a node. As an example, checking the validity of an article node with the following code returns VALID_TRUE.

   short nodeValid = articleVAL.nodeValidity(      ElementEditVAL.VAL_SCHEMA);

The getAllowedAttributes() Method
The getAllowedAttributes() method returns a list of allowed attributes for an element. For example, to discover the allowable attributes for the catalog element, you can write:

   NameList attr = elementEditVAL.getAllowedAttributes();

After running the preceding validation code, the attr NameList contains two attributes: title and publisher.

The getRequiredAttributes() Method
The getRequiredAttributes() method returns a list of required attributes for an element, letting you know in advance which attributes you’ll need to add to an element to insert or append it into a valid document. In an XML schema, you specify a required attribute using the use=”required” syntax. For example, to get the required attributes in the catalog element, you can use:

   NameList attrRequired =       elementEditVAL.getRequiredAttributes();

After running the preceding line of code, for the sample documents, the attrRequired NameList would contain publisher, because that’s the only catalog element attribute specified with use=”required” in the sample schema.

The canSetAttribute() Method
The canSetAttribute() method checks the validity of adding an attribute to an element. As an example, try adding a section attribute to the catalog element.

   short attrSet = elementEditVAL.canSetAttribute(      "section", "SQL");

Because the catalog.xsd schema does not define a section attribute for the catalog element the result is VALID_FALSE.

The canRemoveAttribute() Method
The canRemoveAttribute() checks the validity of removing an attribute from an element. As an example, try removing the publisher element from the catalog element. The publisher attribute is a required attribute of element catalog, so the return value is VALID_FALSE.

The methods you’ve seen in this article cover DOM Level 3.0 validation, letting you test whether you can add or remove elements and attributes from an XML document according to a given schema. The downloadable example validation program, DOM3Validation.java works with the two sample catalog.xml and catalog.xsd files to illustrate the methods. After you download the code, copy the DOM3Validation.java file to the same directory as catalog.xml.