zcommon/src/main/java/org/zkoss/idom/package.html
<html>
<head>
<title>org.zkoss.idom</title>
</head>
<body>
<p>The iDOM representation of XML DOM tree.</p>
<hr>
Author: Tom M. Yeh<br>
Contributors: <br>
Copyright (C) 2001 Potix Corporation. All Rights Reserved.
<hr>
<h2>Overview</h2>
<p>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).</p>
<p>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.</p>
<hr>
<h2>Usage</h2>
<h3>Generic Sample</h3>
<h4>Method 1: Let SAXBuilder create the SAX parser</h4>
<code><pre>import org.zkoss.idom.input.SAXBuilder;
import org.zkoss.idom.Document;
SAXBuilder builder = new SAXBuilder(true, false, true);
Document doc = builder.build("file.xml");</pre></code>
<p>Advantages: simple. Caller needs no anything about a SAX parser.</p>
<h4>Method 2: Create a parser explicitly</h4>
<p><code><pre>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");</pre></code></p>
<p>Advantages: a SAX parser could be used in different palces.</p>
<h3>Parsing a XML</h3>
<p><code><pre>for (Iterator it = document.getElements("product").iterator();
it.hasNext();){
String name = ((Element)it.next()).getElementValue("name", true);
...
}</pre></code></p>
<p>The getElements and getElement methods of Group are powerful to drill down
a iDOM tree sequentially.</p>
<p>To select beyond sequence searching (and regular expression),
org.zkoss.xml.XPath could be used.</p>
<hr>
<h2>Extension to W3C DOM</h2>
<ul>
<li>A new item/node is added, called Binary (Item.BINARY_NODE), to hold
any kind of Object (not just String-type).</li>
</ul>
<hr>
<h2>Notes</h2>
<ul>
<li>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.</li>
<li>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.</li>
<li>Some methods in Item look similar to those of Node, but behave
differently as follows.
<table border="1">
<tr>
<th><code>Item</code></th>
<th><code>Node</code></th>
</tr>
<tr>
<td><code>getText</code>
<p>Returns the text content.</p></td>
<td><code>getNodeValue</code>
<p>The same as getText, except Element
whose getValue returns always null.</p></td>
</tr>
</table></li>
</ul>
<hr>
<h2>Histroy</h2>
<table width="100%">
<tr>
<td>September 27, 2001</td>
<td>Tom M. Yeh</td>
<td>Project created. The original plan is to be an extension of JDOM.</td>
</tr>
<tr>
<td>October 4, 2001</td>
<td>Tom M. Yeh</td>
<td>Alpha 1 as an extenstion of JDOM. Tested with JDOM beta 7.</td>
</tr>
<tr>
<td>October 22-26, 2001</td>
<td>Tom M. Yeh</td>
<td>Alpha 1 of the rewritten version.
On October 21, decide to rewrite to be independent of JDOM.</td>
</tr>
<tr>
<td>November 3-4, 2001</td>
<td>Tom M. Yeh</td>
<td>Alpha 2.
<ul>
<li>SAXBuilder is enhance to support more options
like DocumentBuilderFactory.</li>
<li>All un-expanding entities are put under EntityReference (if
isExpandEntityReferences is true).</li>
</ul></td>
</tr>
<tr>
<td>January 7-8, 2002</td>
<td>Tom M. Yeh</td>
<td>Alpha 3.
<ul>
<li>The modification flag is introduced.</li>
<li>The content concept is introduced.</li>
</ul></td>
</tr>
</table>
</body>
</html>