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.