blob: 93557dd9b8ed18177fad9d1903a3f4b9f9d62cc1 [file] [log] [blame]
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
* The Apache Software License, Version 1.1
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation ("
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
* ====================================================================
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 2001, Sun
* Microsystems., For more
* information on the Apache Software Foundation, please see
* <>.
<s1 title="XSLTC Internal DOM">
<li><link anchor="functionality">General functionlaity</link></li>
<li><link anchor="components">Components of the internal DOM</link></li>
<li><link anchor="structure">Internal structure</link></li>
<li><link anchor="navigation">Tree navigation</link></li>
<li><link anchor="namespaces">Namespaces</link></li>
<li><link anchor="w3c">W3C DOM2 navigation support</link></li>
<li><link anchor="adapter">The DOM adapter - DOMAdapter</link></li>
<li><link anchor="multiplexer">The DOM multiplexer - MultiDOM</link></li>
<li><link anchor="builder">The DOM builder - DOMImpl$DOMBuilder</link></li>
<anchor name="functionality"/>
<s2 title="General functionality">
<p>The internal DOM gives the translet access to the XML document(s) it has
to transform. The interface to the internal DOM is specified in the
class. This is the interface that the translet uses to access the DOM.
There is also an interface specified for DOM caches --</p>
</s2><anchor name="components"/>
<s2 title="Components of the internal DOM">
<p>This DOM interface is implemented by three classes:</p>
This is the main DOM class. An instance of this class contains the nodes
of a <em>single</em> XML document.<br/>br/>
This class is best described as a DOM multiplexer. XSLTC was initially
designed to operate on a single XML document, and the initial DOM and
the DOM interface were designed and implemented without the
<code>document()</code> function in mind. This class will allow a translet
to access multiple DOMs through the original DOM interface.<br/><br/>
The DOM adapter is a mediator between a DOMImpl or a MultiDOM object and
a single translet. A DOMAdapter object contains mappings and reverse
mappings between node types in the DOM(s) and node types in the translet.
This mediator is needed to allow several translets access to a single DOM.
A sample DOM cache (implementing DOMCache) that is used with our sample
transformation applications.
<p><img src="DOMInterface.gif" alt="DOMInterface.gif"/></p>
<p><ref>Figure 1: Main components of the internal DOM</ref></p>
<p>The figure above shows how several translets can access one or more
internal DOM from a shared pool of cached DOMs. A translet can also access a
DOM tree outside of a cache. The Stylesheet class that represents the XSL
stylesheet to compile contains a flag that indicates if the translet uses the
<code>document()</code> function. The code compiled into the translet will act
accordingly and instanciate a MultiDOM object if needed (this code is compiled
in the compiler's <code>Stylesheet.compileTransform()</code> method).</p>
</s2><anchor name="structure"/>
<s2 title="Internal Structure">
<li><link anchor="node-id">Node identification</link></li>
<li><link anchor="element-nodes">Element nodes</link></li>
<li><link anchor="attribute-nodes">Attribute nodes</link></li>
<li><link anchor="text-nodes">Text nodes</link></li>
<li><link anchor="comment-nodes">Comment nodes</link></li>
<li><link anchor="pi"></link>Processing instructions</li>
<anchor name="node-id"/>
<s3 title="Node identifation">
<p>Each node in the DOM is represented by an integer. This integer is an
index into a series of arrays that describes the node. Most important is
the <code>_type[]</code> array, which holds the (DOM internal) node type. There
are some general node types that are described in the interface:</p>
public final static int ROOT = 0;
public final static int TEXT = 1;
public final static int UNUSED = 2;
public final static int ELEMENT = 3;
public final static int ATTRIBUTE = 4;
public final static int PROCESSING_INSTRUCTION = 5;
public final static int COMMENT = 6;
public final static int NTYPES = 7;
<p>Element and attribute nodes will be assigned types based on their expanded
QNames. The <code>_type[]</code> array is used for this:</p>
int type = _type[node]; // get node type
<p>The node type can be used to look up the element/attribute name in the
element/attribute name array <code>_namesArray[]</code>:</p>
String name = _namesArray[type-NTYPES]; // get node element name
<p>The resulting string contains the full, expanded QName of the element or
attribute. Retrieving the namespace URI of an element/attribute is done in a
very similar fashion:</p>
int nstype = _namespace[type-NTYPES]; // get namespace type
String namespace = _nsNamesArray[nstype]; // get node namespace name
</s3><anchor name="element-nodes"/>
<s3 title="Element nodes">
<p>The contents of an element node (child nodes) can be identified using
the <code>_offsetOrChild[]</code> and <code>_nextSibling[]</code> arrays. The
<code>_offsetOrChild[]</code> array will give you the first child of an element
int child = _offsetOrChild[node]; // first child
child = _nextSibling[child]; // next child
<p>The last child will have a &quot;<code>_nextSibling[]</code>&quot; of 0 (zero).
This value is OK since the root node (the 0 node) will not be a child of
any element.</p>
</s3><anchor name="attribute-nodes"/>
<s3 title="Attribute nodes">
<p>The first attribute node of an element is found by a lookup in the
<code>_lengthOrAttr[]</code> array using the node index:</p>
int attribute = _offsetOrChild[node]; // first attribute
attribute = _nextSibling[attribute]; // next attribute
<p>The names of attributes are contained in the <code>_namesArray[]</code> just
like the names of element nodes. The value of attributes are store the same
way as text nodes:</p>
int offset = _offsetOrChild[attribute]; // offset into character array
int length = _lengthOrAttr[attribute]; // length of attribute value
String value = new String(_text, offset, length);
</s3><anchor name="text-nodes"/>
<s3 title="Text nodes">
<p>Text nodes are stored identically to attribute values. See the previous
section on <link anchor="attribute-nodes">attribute nodes</link>.</p>
</s3><anchor name="comment-nodes"/>
<s3 title="Comment nodes">
<p>The internal DOM does currently <em>not</em> contain comment nodes. Yes, I
am quite aware that the DOM has a type assigned to comment nodes, but comments
are still not inserted into the DOM.</p>
</s3><anchor name="pi"/>
<s3 title="Processing instructions">
<p>Processing instructions are handled as text nodes. These nodes are stored
identically to attribute values. See the previous section on
<link anchor="attribute-nodes">attribute nodes</link>.</p>
</s3></s2><anchor name="navigation"/>
<s2 title="Tree navigation">
<p>The DOM implementation contains a series of iterator that implement the
XPath axis. All these iterators implement the NodeIterator interface and
extend the NodeIteratorBase base class. These iterators do the job of
navigating the tree using the <code>_offsetOrChild[]</code>, <code>_nextSibling</code>
and <code>_parent[]</code> arrays. All iterators that handles XPath axis are
implemented as a private inner class of DOMImpl. The translet uses a handful
of methods to instanciate these iterators:</p>
public NodeIterator getIterator();
public NodeIterator getChildren(final int node);
public NodeIterator getTypedChildren(final int type);
public NodeIterator getAxisIterator(final int axis);
public NodeIterator getTypedAxisIterator(final int axis, final int type);
public NodeIterator getNthDescendant(int node, int n);
public NodeIterator getNamespaceAxisIterator(final int axis, final int ns);
public NodeIterator orderNodes(NodeIterator source, int node);
<p>There are a few iterators in addition to these, such as sorting/ordering
iterators and filtering iterators. These iterators are implemented in
separate classes and can be instanciated directly by the translet.</p>
</s2><anchor name="namespaces"/>
<s2 title="Namespaces">
<p>Namespace support was added to the internal DOM at a late stage, and the
design and implementation of the DOM bears a few scars because of this.
There is a separate <link idref="xsltc_namespace">design
document</link> that covers namespaces.</p>
</s2><anchor name="w3c"/>
<s2 title="W3C DOM2 navigation support">
<p>The DOM has a few methods that give basic W3C-type DOM navigation. These
methods are:</p>
public Node makeNode(int index);
public Node makeNode(NodeIterator iter);
public NodeList makeNodeList(int index);
public NodeList makeNodeList(NodeIterator iter);
<p>These methods return instances of inner classes of the DOM that implement
the W3C Node and NodeList interfaces.</p>
</s2><anchor name="adapter"/>
<s2 title="The DOM adapter - DOMAdapter">
<li><link anchor="translet-dom">Translet/DOM type mapping</link></li>
<li><link anchor="whitespace">Whitespace text-node stripping</link></li>
<li><link anchor="method-mapping">Method mapping</link></li>
<anchor name="translet-dom"/>
<s3 title="Translet/DOM type mapping">
<p>The DOMAdapter class performs the mappings between DOM and translet node
types, and vice versa. These mappings are necessary in order for the translet
to correctly identify an element/attribute in the DOM and for the DOM to
correctly identify the element/attribute type of a typed iterator requested
by the translet. Note that the DOMAdapter also maps translet namespace types
to DOM namespace types, and vice versa.</p>
<p>The DOMAdapter class has four global tables that hold the translet/DOM
type and namespace-type mappings. If the DOM knows an element as type
19, the DOMAdapter will translate this to some other integer using the
<code>_mapping[]</code> array:</p>
int domType = _mapping[transletType];
<p>This action will be performed when the DOM asks what type a specific node
is. The reverse is done then the translet wants an iterator for a specific
node type. The DOMAdapter must translate the translet-type to the type used
internally in the DOM by looking up the <code>_reverse[]</code> array:</p>
int transletType = _mapping[domType];
<p>There are two additional mapping tables: <code>_NSmapping[]</code> and
<code>_NSreverse[]</code> that do the same for namespace types.</p>
</s3><anchor name="whitespace"/>
<s3 title="Whitespace text-node stripping">
<p>The DOMAdapter class has the additional function of stripping whitespace
nodes in the DOM. This functionality had to be put in the DOMAdapter, as
different translets will have different preferences for node stripping.</p>
</s3><anchor name="method-mapping"/>
<s3 title="Method mapping">
<p>The DOMAdapter class implements the same <code>DOM</code> interface as the
DOMImpl class. A DOMAdapter object will look like a DOMImpl tree, but the
translet can access it directly without being concerned with type mapping
and whitespace stripping. The <code>getTypedChildren()</code> demonstrates very
well how this is done:</p>
public NodeIterator getTypedChildren(int type) {
// Get the DOM type for the requested typed iterator
final int domType = _reverse[type];
// Now get the typed child iterator from the DOMImpl object
NodeIterator iterator = _domImpl.getTypedChildren(domType);
// Wrap the iterator in a WS stripping iterator if child-nodes are text nodes
if ((domType == DOM.TEXT) &amp;&amp; (_filter != null))
iterator = _domImpl.strippingIterator(iterator,_mapping,_filter);
</s3></s2><anchor name="multiplexer"/>
<s2 title="The DOM multiplexer - MultiDOM">
<p>The DOM multiplexer class is only used when the compiled stylesheet uses
the <code>document()</code> function. An instance of the MultiDOM class also
implements the DOM interface, so that it can be accessed in the same way
as a DOMAdapter object.</p>
<p>A node in the DOM is identified by an integer. The first 8 bits of this
integer are used to identify the DOM in which the node belongs, while the
lower 24 bits are used to identify the node within the DOM:</p>
<td>DOM id</td>
<td colspan="3">node id</td>
<p>The DOM multiplexer has an array of DOMAdapter objects. The topmost 8
bits of the identifier is used to find the correct DOM from the array. Then
the lower 24 bits are used in calls to methods in the DOMAdapter object:</p>
public int getParent(int node) {
return _adapters[node>>>24].getParent(node &amp; 0x00ffffff) | node &amp; 0xff000000;
<p>Note that the node identifier returned by this method has the same upper 8
bits as the input node. This is why we <code>OR</code> the result from
<code>DOMAdapter.getParent()</code> with the top 8 bits of the input node.</p>
</s2><anchor name="builder"/>
<s2 title="The DOM builder - DOMImpl$DOMBuilder">
<li><link anchor="startelement">startElement()</link></li>
<li><link anchor="endelement">endElement()</link></li>
<li><link anchor="startprefixmapping">startPrefixMapping()</link></li>
<li><link anchor="endprefixmapping">endPrefixMapping()</link></li>
<li><link anchor="characters">characters()</link></li>
<li><link anchor="startdocument">startDocument()</link></li>
<li><link anchor="enddocument">endDocument()</link></li>
<p>The DOM builder is an inner class of the DOM implementation. The builder
implements the SAX2 <code>ContentHandler</code> interface and populates the DOM
by receiving SAX2 events from a SAX2 parser (presently xerces). An instance
of the DOM builder class can be retrieved from <code>DOMImpl.getBuilder()</code>
method, and this handler can be set as an XMLReader's content handler:</p>
final SAXParserFactory factory = SAXParserFactory.newInstance();
final SAXParser parser = factory.newSAXParser();
final XMLReader reader = parser.getXMLReader();
final DOMImpl dom = new DOMImpl();
<p>The DOM builder will start to populate the DOM once the XML parser starts
generating SAX2 events:</p>
<anchor name="startelement"/>
<s3 title="startElement()">
<p>This method can be called in one of two ways; either with the expanded
QName (the element's separate uri and local name are supplied) or as a
normal QName (one String on the format prefix:local-name). The DOM stores
elements as expanded QNames so it needs to know the element's namespace URI.
Since the URI is not supplied with this call, we have to keep track of
namespace prefix/uri mappings while we're building the DOM. See
<code><link anchor="startprefixmapping">startPrefixMapping()</link></code> below for details on
namespace handling.</p>
<p>The <code>startElement()</code> inserts the element as a child of the current
parent element, creates attribute nodes for all attributes in the supplied
&quot;<code>Attributes</code>&quot; attribute list (by a series of calls to
<code>makeAttributeNode()</code>), and finally creates the actual element node
(by calling <code>internElement()</code>, which inserts a new entry in the
<code>_type[]</code> array).</p>
</s3><anchor name="endelement"/>
<s3 title="endElement()">
<p>This method does some cleanup after the <code>startElement()</code> method,
such as revering <code>xml:space</code> settings and linking the element's
child nodes.</p>
</s3><anchor name="startprefixmapping"/>
<s3 title="startPrefixMapping()">
<p>This method is called for each namespace declaration in the source
document. The parser should call this method before the prefix is referenced
in a QName that is passed to the <code>startElement()</code> call. Namespace
prefix/uri mappings are stored in a Hashtable structure. Namespace prefixes
are used as the keys in the Hashtable, and each key maps to a Stack that
contains the various URIs that the prefix maps to. The URI on top of the
stack is the URI that the prefix currently maps to.</p>
<p><img src="namespace_stack.gif" alt="namespace_stack.gif"/></p>
<p><ref>Figure 2: Namespace handling in the DOM builder</ref></p>
<p>Each call to <code>startPrefixMapping()</code> results in a lookup in the
Hashtable (using the prefix), and a <code>push()</code> of the URI onto the
Stack that the prefix maps to.</p>
</s3><anchor name="endprefixmapping"/>
<s3 title="endPrefixMapping()">
<p>A namespace prefix/uri mapping is closed by locating the Stack for the
prefix, and then <code>pop()</code>'ing the topmost URI off this Stack.</p>
</s3><anchor name="characters"/>
<s3 title="characters()">
<p>Text nodes are stored as simple character sequences in the character array
<code>_text[]</code>. The start and lenght of a node's text can be determined by
using the node index to look up <code>_offsetOrChild[]</code> and
<p>We want to re-use character sequences if two or more text nodes have
identical content. This can be achieved by having two different text node
indexes map to the same character sequence. The <code>maybeReuseText()</code>
method is always called before a new character string is stored in the
<code>_text[]</code> array. This method will locate the offset of an existing
instance of a character sequence.</p>
</s3><anchor name="startdocument"/>
<s3 title="startDocument()">
<p>This method initialises a bunch of data structures that are used by the
builder. It also pushes the default namespace on the namespace stack (so that
the &quot;&quot; prefix maps to the <code>null</code> namespace).</p>
</s3><anchor name="enddocument"/>
<s3 title="endDocument()">
<p>This method builds the <code>_namesArray[]</code>, <code>_namespace[]</code>
and <code>_nsNamesArray[]</code> structures from temporary datastructures used
in the DOM builder.</p>