org.zkoss.idom

The iDOM representation of XML DOM tree.

Overview

It is Potix's DOM representation for XML. The concept is similar to JDOM -- using Java collections and concrete classes. However, we do have many enhancements (many of them are the reasons we don't extend JDOM, but writing a new one). Refer to Port from JDOM to iDOM for more details.

Although iDOM supports W3C/DOM, W3C/DOM's API is generated deprecated unless using them with third part utilities, like Xalan's XPath. The reason is that W3C/DOM API is another complete set of API that is easily confusing with iDOM API. The iDOM API is designed to avoid making any connection between their names. However, some cases are hardly avoided. For example, org.w3c.dom.Element.getAttribute returns an empty string if the attribute not found, while Element.getAttributeValue returns null if the attribute not found.

Usage

Generic Sample

Method 1: Let SAXBuilder create the SAX parser

import org.zkoss.idom.input.SAXBuilder;
import org.zkoss.idom.Document;

SAXBuilder builder = new SAXBuilder(true, false, true);
Document doc = builder.build("file.xml");

Advantages: simple. Caller needs no anything about a SAX parser.

Method 2: Create a parser explicitly

import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import org.zkoss.idom.input.SAXBuilder;
import org.zkoss.idom.Document;

SAXParserFactory factory = SAXParserFactory.newInstance();
...//configure factory as you want
SAXParser parser = factory.newSAXParser();
SAXBuilder builder = new SAXBuilder(parser);
Document doc = builder.build("file.xml");

Advantages: a SAX parser could be used in different palces.

Parsing a XML

for (Iterator it = document.getElements("product").iterator();
it.hasNext();){
  String name = ((Element)it.next()).getElementValue("name", true);
  ...
}

The getElements and getElement methods of Group are powerful to drill down a iDOM tree sequentially.

To select beyond sequence searching (and regular expression), org.zkoss.xml.XPath could be used.

Extension to W3C DOM

• A new item/node is added, called Binary (Item.BINARY_NODE), to hold any kind of Object (not just String-type).

Notes

• Adding attributes with namespace might cause the tree to be illegal W3C/DOM. Examples, conflict prefix (same prefix but different URI). We will implement a method to check the consistency, which will be done before output.
• Every item has zero or one owning document. To be safe, only vertices without any owning document are allowed to be added to other tree. Otherwise, Item.detach or clone must be called explicitly.
• Some methods in Item look similar to those of Node, but behave differently as follows.

  Item	Node
  getText Returns the text content.	getNodeValue The same as getText, except Element whose getValue returns always null.

Histroy

Design decision: Attribute is also a item.

A "text" is usually a string (e.g., Text, Comment and CDATA) but could be any object (e.g., Binary).

The getText method of some parent, e.g., Element, catenates the text of its children if they implement this interface and Textual.isPartOfParentText returns true.

Note: the class that implement this interface must have a constructor with a single argument whose type is String.