Package org.zkoss.idom

The iDOM representation of XML DOM tree.

See: Description

Interface Summary

Interface	Description
Attributable	Represents a class that has attributes.
Binable	Represent a class that allows any type of objects, not just String.
Group	Represents an item might have children.
Item	Represents an item (a.k.a., node) of a iDOM tree.
Namespaceable	Represents a class that supports namespace.
Textual	Represents an object that is mainly for storing "text".

Class Summary

Class	Description
Attribute	The iDOM attribute.
Binary	The binary item.
CData	The iDOM CDATA.
Comment	The iDOM Comment.
DocType	The iDOM DocType.
Document	Represents Document which is also W3C/DOM's document, i.e., org.w3c.dom.Document.
Element	The iDOM element.
EntityReference	The iDOM entity reference.
Namespace	Represents the namespace.
ProcessingInstruction	The iDOM processing instruction.
Text	The iDOM Text.
Verifier	The verifier to verify W3C/DOM related constraints.

Exception Summary

Exception	Description
DOMException	Denotes an operation is not supported.

Package org.zkoss.idom Description

The iDOM representation of XML DOM tree.

Author: Tom M. Yeh
Contributors:
Copyright (C) 2001 Potix Corporation. All Rights Reserved.

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).

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

September 27, 2001	Tom M. Yeh	Project created. The original plan is to be an extension of JDOM.
October 4, 2001	Tom M. Yeh	Alpha 1 as an extenstion of JDOM. Tested with JDOM beta 7.
October 22-26, 2001	Tom M. Yeh	Alpha 1 of the rewritten version. On October 21, decide to rewrite to be independent of JDOM.
November 3-4, 2001	Tom M. Yeh	Alpha 2. SAXBuilder is enhance to support more options like DocumentBuilderFactory. All un-expanding entities are put under EntityReference (if isExpandEntityReferences is true).
January 7-8, 2002	Tom M. Yeh	Alpha 3. The modification flag is introduced. The content concept is introduced.