nokogiri-backport 1.11.0

data/ext/java/nokogiri/internals/dom2dtm/DOM2DTM.java

@@ -0,0 +1,1745 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the  "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package nokogiri.internals.dom2dtm;
+
+import javax.xml.transform.SourceLocator;
+import javax.xml.transform.dom.DOMSource;
+
+import org.apache.xml.dtm.DTM;
+import org.apache.xml.dtm.DTMManager;
+import org.apache.xml.dtm.DTMWSFilter;
+import org.apache.xml.dtm.ref.DTMDefaultBaseIterators;
+import org.apache.xml.dtm.ref.DTMManagerDefault;
+import org.apache.xml.dtm.ref.ExpandedNameTable;
+import org.apache.xml.dtm.ref.IncrementalSAXSource;
+import org.apache.xml.res.XMLErrorResources;
+import org.apache.xml.res.XMLMessages;
+import org.apache.xml.utils.FastStringBuffer;
+import org.apache.xml.utils.QName;
+import org.apache.xml.utils.StringBufferPool;
+import org.apache.xml.utils.TreeWalker;
+import org.apache.xml.utils.XMLCharacterRecognizer;
+import org.apache.xml.utils.XMLString;
+import org.apache.xml.utils.XMLStringFactory;
+import org.w3c.dom.Attr;
+import org.w3c.dom.Document;
+import org.w3c.dom.DocumentType;
+import org.w3c.dom.Element;
+import org.w3c.dom.Entity;
+import org.w3c.dom.NamedNodeMap;
+import org.w3c.dom.Node;
+import org.xml.sax.ContentHandler;
+
+/** The <code>DOM2DTM</code> class serves up a DOM's contents via the
+ * DTM API.
+ *
+ * Note that it doesn't necessarily represent a full Document
+ * tree. You can wrap a DOM2DTM around a specific node and its subtree
+ * and the right things should happen. (I don't _think_ we currently
+ * support DocumentFrgment nodes as roots, though that might be worth
+ * considering.)
+ *
+ * Note too that we do not currently attempt to track document
+ * mutation. If you alter the DOM after wrapping DOM2DTM around it,
+ * all bets are off.
+ * */
+public class DOM2DTM extends DTMDefaultBaseIterators
+{
+//    static final boolean JJK_DEBUG=false;
+//    static final boolean JJK_NEWCODE=true;
+
+    /** Manefest constant
+     */
+    static final String NAMESPACE_DECL_NS="http://www.w3.org/XML/1998/namespace";
+
+    /** The current position in the DOM tree. Last node examined for
+     * possible copying to DTM. */
+    transient private Node m_pos;
+    /** The current position in the DTM tree. Who children get appended to. */
+    private int m_last_parent=0;
+    /** The current position in the DTM tree. Who children reference as their
+     * previous sib. */
+    private int m_last_kid=NULL;
+
+    /** The top of the subtree.
+     * %REVIEW%: 'may not be the same as m_context if "//foo" pattern.'
+     * */
+    transient private Node m_root;
+
+    /** True iff the first element has been processed. This is used to control
+     synthesis of the implied xml: namespace declaration node. */
+    boolean m_processedFirstElement=false;
+
+    /** true if ALL the nodes in the m_root subtree have been processed;
+     * false if our incremental build has not yet finished scanning the
+     * DOM tree.  */
+    transient private boolean m_nodesAreProcessed;
+
+    /** The node objects.  The instance part of the handle indexes
+     * directly into this vector.  Each DTM node may actually be
+     * composed of several DOM nodes (for example, if logically-adjacent
+     * Text/CDATASection nodes in the DOM have been coalesced into a
+     * single DTM Text node); this table points only to the first in
+     * that sequence. */
+    protected final java.util.List<Node> m_nodes = new java.util.ArrayList<Node>(12);
+
+    /**
+     * Construct a DOM2DTM object from a DOM node.
+     *
+     * @param mgr The DTMManager who owns this DTM.
+     * @param domSource the DOM source that this DTM will wrap.
+     * @param dtmIdentity The DTM identity ID for this DTM.
+     * @param whiteSpaceFilter The white space filter for this DTM, which may
+     *                         be null.
+     * @param xstringfactory XMLString factory for creating character content.
+     * @param doIndexing true if the caller considers it worth it to use
+     *                   indexing schemes.
+     */
+    public DOM2DTM(DTMManager mgr, DOMSource domSource,
+                   int dtmIdentity, DTMWSFilter whiteSpaceFilter,
+                   XMLStringFactory xstringfactory,
+                   boolean doIndexing)
+    {
+        super(mgr, domSource, dtmIdentity, whiteSpaceFilter,
+            xstringfactory, doIndexing);
+
+        // Initialize DOM navigation
+        m_pos=m_root = domSource.getNode();
+        // Initialize DTM navigation
+        m_last_parent=m_last_kid=NULL;
+        m_last_kid=addNode(m_root, m_last_parent,m_last_kid, NULL);
+
+        // Apparently the domSource root may not actually be the
+        // Document node. If it's an Element node, we need to immediately
+        // add its attributes. Adapted from nextNode().
+        // %REVIEW% Move this logic into addNode and recurse? Cleaner!
+        //
+        // (If it's an EntityReference node, we're probably in
+        // seriously bad trouble. For now
+        // I'm just hoping nobody is ever quite that foolish... %REVIEW%)
+        //
+        // %ISSUE% What about inherited namespaces in this case?
+        // Do we need to special-case initialize them into the DTM model?
+        if(ELEMENT_NODE == m_root.getNodeType())
+        {
+            NamedNodeMap attrs=m_root.getAttributes();
+            int attrsize=(attrs==null) ? 0 : attrs.getLength();
+            if(attrsize>0)
+            {
+                int attrIndex=NULL; // start with no previous sib
+                for(int i=0;i<attrsize;++i)
+                {
+                    // No need to force nodetype in this case;
+                    // addNode() will take care of switching it from
+                    // Attr to Namespace if necessary.
+                    attrIndex=addNode(attrs.item(i),0,attrIndex,NULL);
+                    m_firstch.setElementAt(DTM.NULL,attrIndex);
+                }
+                // Terminate list of attrs, and make sure they aren't
+                // considered children of the element
+                m_nextsib.setElementAt(DTM.NULL,attrIndex);
+
+                // IMPORTANT: This does NOT change m_last_parent or m_last_kid!
+            } // if attrs exist
+        } //if(ELEMENT_NODE)
+
+        // Initialize DTM-completed status
+        m_nodesAreProcessed = false;
+    }
+
+    /**
+     * Construct the node map from the node.
+     *
+     * @param node The node that is to be added to the DTM.
+     * @param parentIndex The current parent index.
+     * @param previousSibling The previous sibling index.
+     * @param forceNodeType If not DTM.NULL, overrides the DOM node type.
+     *	Used to force nodes to Text rather than CDATASection when their
+     *	coalesced value includes ordinary Text nodes (current DTM behavior).
+     *
+     * @return The index identity of the node that was added.
+     */
+    protected int addNode(Node node, int parentIndex,
+                          int previousSibling, int forceNodeType)
+    {
+        int nodeIndex = m_nodes.size();
+
+        // Have we overflowed a DTM Identity's addressing range?
+        if(m_dtmIdent.size() == (nodeIndex>>>DTMManager.IDENT_DTM_NODE_BITS))
+        {
+            try
+            {
+                if(m_mgr==null)
+                    throw new ClassCastException();
+
+                // Handle as Extended Addressing
+                DTMManagerDefault mgrD=(DTMManagerDefault)m_mgr;
+                int id=mgrD.getFirstFreeDTMID();
+                mgrD.addDTM(this,id,nodeIndex);
+                m_dtmIdent.addElement(id<<DTMManager.IDENT_DTM_NODE_BITS);
+            }
+            catch(ClassCastException e)
+            {
+                // %REVIEW% Wrong error message, but I've been told we're trying
+                // not to add messages right not for I18N reasons.
+                // %REVIEW% Should this be a Fatal Error?
+                error(XMLMessages.createXMLMessage(XMLErrorResources.ER_NO_DTMIDS_AVAIL, null));//"No more DTM IDs are available";
+            }
+        }
+
+        m_size++;
+        // ensureSize(nodeIndex);
+
+        int type;
+        if(NULL==forceNodeType)
+            type = node.getNodeType();
+        else
+            type=forceNodeType;
+
+        // %REVIEW% The Namespace Spec currently says that Namespaces are
+        // processed in a non-namespace-aware manner, by matching the
+        // QName, even though there is in fact a namespace assigned to
+        // these nodes in the DOM. If and when that changes, we will have
+        // to consider whether we check the namespace-for-namespaces
+        // rather than the node name.
+        //
+        // %TBD% Note that the DOM does not necessarily explicitly declare
+        // all the namespaces it uses. DOM Level 3 will introduce a
+        // namespace-normalization operation which reconciles that, and we
+        // can request that users invoke it or otherwise ensure that the
+        // tree is namespace-well-formed before passing the DOM to Xalan.
+        // But if they don't, what should we do about it? We probably
+        // don't want to alter the source DOM (and may not be able to do
+        // so if it's read-only). The best available answer might be to
+        // synthesize additional DTM Namespace Nodes that don't correspond
+        // to DOM Attr Nodes.
+        if (Node.ATTRIBUTE_NODE == type)
+        {
+            String name = node.getNodeName();
+
+            if (name.startsWith("xmlns:") || name.equals("xmlns"))
+            {
+                type = DTM.NAMESPACE_NODE;
+            }
+        }
+
+        m_nodes.add(node);
+
+        m_firstch.setElementAt(NOTPROCESSED,nodeIndex);
+        m_nextsib.setElementAt(NOTPROCESSED,nodeIndex);
+        m_prevsib.setElementAt(previousSibling,nodeIndex);
+        m_parent.setElementAt(parentIndex,nodeIndex);
+
+        if(DTM.NULL != parentIndex &&
+            type != DTM.ATTRIBUTE_NODE &&
+            type != DTM.NAMESPACE_NODE)
+        {
+            // If the DTM parent had no children, this becomes its first child.
+            if(NOTPROCESSED == m_firstch.elementAt(parentIndex))
+                m_firstch.setElementAt(nodeIndex,parentIndex);
+        }
+
+        String nsURI = node.getNamespaceURI();
+
+        // Deal with the difference between Namespace spec and XSLT
+        // definitions of local name. (The former says PIs don't have
+        // localnames; the latter says they do.)
+        String localName =  (type == Node.PROCESSING_INSTRUCTION_NODE) ?
+            node.getNodeName() :
+            node.getLocalName();
+
+        // Hack to make DOM1 sort of work...
+        if(((type == Node.ELEMENT_NODE) || (type == Node.ATTRIBUTE_NODE))
+            && null == localName)
+            localName = node.getNodeName(); // -sb
+
+        ExpandedNameTable exnt = m_expandedNameTable;
+
+        // %TBD% Nodes created with the old non-namespace-aware DOM
+        // calls createElement() and createAttribute() will never have a
+        // localname. That will cause their expandedNameID to be just the
+        // nodeType... which will keep them from being matched
+        // successfully by name. Since the DOM makes no promise that
+        // those will participate in namespace processing, this is
+        // officially accepted as Not Our Fault. But it might be nice to
+        // issue a diagnostic message!
+        if(node.getLocalName()==null &&
+            (type==Node.ELEMENT_NODE || type==Node.ATTRIBUTE_NODE))
+        {
+            // warning("DOM 'level 1' node "+node.getNodeName()+" won't be mapped properly in DOM2DTM.");
+        }
+
+        int expandedNameID = (null != localName)
+            ? exnt.getExpandedTypeID(nsURI, localName, type) :
+            exnt.getExpandedTypeID(type);
+
+        m_exptype.setElementAt(expandedNameID,nodeIndex);
+
+        indexNode(expandedNameID, nodeIndex);
+
+        if (DTM.NULL != previousSibling)
+            m_nextsib.setElementAt(nodeIndex,previousSibling);
+
+        // This should be done after m_exptype has been set, and probably should
+        // always be the last thing we do
+        if (type == DTM.NAMESPACE_NODE)
+            declareNamespaceInContext(parentIndex,nodeIndex);
+
+        return nodeIndex;
+    }
+
+    /**
+     * Get the number of nodes that have been added.
+     */
+    public int getNumberOfNodes()
+    {
+        return m_nodes.size();
+    }
+
+    /**
+     * This method iterates to the next node that will be added to the table.
+     * Each call to this method adds a new node to the table, unless the end
+     * is reached, in which case it returns null.
+     *
+     * @return The true if a next node is found or false if
+     *         there are no more nodes.
+     */
+    protected boolean nextNode()
+    {
+        // Non-recursive one-fetch-at-a-time depth-first traversal with
+        // attribute/namespace nodes and white-space stripping.
+        // Navigating the DOM is simple, navigating the DTM is simple;
+        // keeping track of both at once is a trifle baroque but at least
+        // we've avoided most of the special cases.
+        if (m_nodesAreProcessed)
+            return false;
+
+        // %REVIEW% Is this local copy Really Useful from a performance
+        // point of view?  Or is this a false microoptimization?
+        Node pos=m_pos;
+        Node next=null;
+        int nexttype=NULL;
+
+        // Navigate DOM tree
+        do
+        {
+            // Look down to first child.
+            if (pos.hasChildNodes())
+            {
+                next = pos.getFirstChild();
+
+                // %REVIEW% There's probably a more elegant way to skip
+                // the doctype. (Just let it go and Suppress it?
+                if(next!=null && DOCUMENT_TYPE_NODE==next.getNodeType())
+                    next=next.getNextSibling();
+
+                // Push DTM context -- except for children of Entity References,
+                // which have no DTM equivalent and cause no DTM navigation.
+                if(ENTITY_REFERENCE_NODE!=pos.getNodeType())
+                {
+                    m_last_parent=m_last_kid;
+                    m_last_kid=NULL;
+                    // Whitespace-handler context stacking
+                    if(null != m_wsfilter)
+                    {
+                        short wsv =
+                            m_wsfilter.getShouldStripSpace(makeNodeHandle(m_last_parent),this);
+                        boolean shouldStrip = (DTMWSFilter.INHERIT == wsv)
+                            ? getShouldStripWhitespace()
+                            : (DTMWSFilter.STRIP == wsv);
+                        pushShouldStripWhitespace(shouldStrip);
+                    } // if(m_wsfilter)
+                }
+            }
+
+            // If that fails, look up and right (but not past root!)
+            else
+            {
+                if(m_last_kid!=NULL)
+                {
+                    // Last node posted at this level had no more children
+                    // If it has _no_ children, we need to record that.
+                    if(m_firstch.elementAt(m_last_kid)==NOTPROCESSED)
+                        m_firstch.setElementAt(NULL,m_last_kid);
+                }
+
+                while(m_last_parent != NULL)
+                {
+                    // %REVIEW% There's probably a more elegant way to
+                    // skip the doctype. (Just let it go and Suppress it?
+                    next = pos.getNextSibling();
+                    if(next!=null && DOCUMENT_TYPE_NODE==next.getNodeType())
+                        next=next.getNextSibling();
+
+                    if(next!=null)
+                        break; // Found it!
+
+                    // No next-sibling found. Pop the DOM.
+                    pos=pos.getParentNode();
+//                    if(pos==null)
+//                    {
+//                        // %TBD% Should never arise, but I want to be sure of that...
+//                        if(JJK_DEBUG)
+//                        {
+//                            System.out.println("***** DOM2DTM Pop Control Flow problem");
+//                            for(;;); // Freeze right here!
+//                        }
+//                    }
+
+                    // The only parents in the DTM are Elements.  However,
+                    // the DOM could contain EntityReferences.  If we
+                    // encounter one, pop it _without_ popping DTM.
+                    if(pos!=null && ENTITY_REFERENCE_NODE == pos.getNodeType())
+                    {
+//                        // Nothing needs doing
+//                        if(JJK_DEBUG) System.out.println("***** DOM2DTM popping EntRef");
+                    }
+                    else
+                    {
+                        popShouldStripWhitespace();
+                        // Fix and pop DTM
+                        if(m_last_kid==NULL)
+                            m_firstch.setElementAt(NULL,m_last_parent); // Popping from an element
+                        else
+                            m_nextsib.setElementAt(NULL,m_last_kid); // Popping from anything else
+                        m_last_parent=m_parent.elementAt(m_last_kid=m_last_parent);
+                    }
+                }
+                if(m_last_parent==NULL) next=null;
+            }
+
+            if(next!=null) nexttype=next.getNodeType();
+
+            // If it's an entity ref, advance past it.
+            //
+            // %REVIEW% Should we let this out the door and just suppress it?
+            // More work, but simpler code, more likely to be correct, and
+            // it doesn't happen very often. We'd get rid of the loop too.
+            if (ENTITY_REFERENCE_NODE == nexttype) pos=next;
+        }
+        while (ENTITY_REFERENCE_NODE == nexttype);
+
+        // Did we run out of the tree?
+        if(next==null)
+        {
+            m_nextsib.setElementAt(NULL,0);
+            m_nodesAreProcessed = true;
+            m_pos=null;
+
+//            if(JJK_DEBUG)
+//            {
+//                System.out.println("***** DOM2DTM Crosscheck:");
+//                for(int i=0;i<m_nodes.size();++i)
+//                    System.out.println(i+":\t"+m_firstch.elementAt(i)+"\t"+m_nextsib.elementAt(i));
+//            }
+
+            return false;
+        }
+
+        // Text needs some special handling:
+        //
+        // DTM may skip whitespace. This is handled by the suppressNode flag, which
+        // when true will keep the DTM node from being created.
+        //
+        // DTM only directly records the first DOM node of any logically-contiguous
+        // sequence. The lastTextNode value will be set to the last node in the
+        // contiguous sequence, and -- AFTER the DTM addNode -- can be used to
+        // advance next over this whole block. Should be simpler than special-casing
+        // the above loop for "Was the logically-preceeding sibling a text node".
+        //
+        // Finally, a DTM node should be considered a CDATASection only if all the
+        // contiguous text it covers is CDATASections. The first Text should
+        // force DTM to Text.
+
+        boolean suppressNode=false;
+        Node lastTextNode=null;
+
+        nexttype=next.getNodeType();
+
+        // nexttype=pos.getNodeType();
+        if(TEXT_NODE == nexttype || CDATA_SECTION_NODE == nexttype)
+        {
+            // If filtering, initially assume we're going to suppress the node
+            suppressNode=((null != m_wsfilter) && getShouldStripWhitespace());
+
+            // Scan logically contiguous text (siblings, plus "flattening"
+            // of entity reference boundaries).
+            if (suppressNode) {
+                Node n = next;
+                while (n != null) {
+                    lastTextNode=n;
+                    // Any Text node means DTM considers it all Text
+                    if (TEXT_NODE == n.getNodeType()) nexttype = TEXT_NODE;
+                    // Any non-whitespace in this sequence blocks whitespace
+                    // suppression
+                    suppressNode &= XMLCharacterRecognizer.isWhiteSpace(n.getNodeValue());
+
+                    n = logicalNextDOMTextNode(n);
+                }
+            }
+        }
+
+        // Special handling for PIs: Some DOMs represent the XML
+        // Declaration as a PI. This is officially incorrect, per the DOM
+        // spec, but is considered a "wrong but tolerable" temporary
+        // workaround pending proper handling of these fields in DOM Level
+        // 3. We want to recognize and reject that case.
+        else if(PROCESSING_INSTRUCTION_NODE==nexttype)
+        {
+            suppressNode = (pos.getNodeName().toLowerCase().equals("xml"));
+        }
+
+
+        if(!suppressNode)
+        {
+            // Inserting next. NOTE that we force the node type; for
+            // coalesced Text, this records CDATASections adjacent to
+            // ordinary Text as Text.
+            int nextindex=addNode(next, m_last_parent, m_last_kid, nexttype);
+
+            m_last_kid=nextindex;
+
+            if(ELEMENT_NODE == nexttype)
+            {
+                int attrIndex=NULL; // start with no previous sib
+                // Process attributes _now_, rather than waiting.
+                // Simpler control flow, makes NS cache available immediately.
+                NamedNodeMap attrs=next.getAttributes();
+                int attrsize=(attrs==null) ? 0 : attrs.getLength();
+                if(attrsize>0)
+                {
+                    for(int i=0;i<attrsize;++i)
+                    {
+                        // No need to force nodetype in this case;
+                        // addNode() will take care of switching it from
+                        // Attr to Namespace if necessary.
+                        attrIndex=addNode(attrs.item(i), nextindex, attrIndex, NULL);
+                        m_firstch.setElementAt(DTM.NULL,attrIndex);
+
+                        // If the xml: prefix is explicitly declared
+                        // we don't need to synthesize one.
+                        //
+                        // NOTE that XML Namespaces were not originally
+                        // defined as being namespace-aware (grrr), and
+                        // while the W3C is planning to fix this it's
+                        // safer for now to test the QName and trust the
+                        // parsers to prevent anyone from redefining the
+                        // reserved xmlns: prefix
+                        if(!m_processedFirstElement
+                            && "xmlns:xml".equals(attrs.item(i).getNodeName()))
+                            m_processedFirstElement=true;
+                    }
+                    // Terminate list of attrs, and make sure they aren't
+                    // considered children of the element
+                } // if attrs exist
+                if(!m_processedFirstElement)
+                {
+                    // The DOM might not have an explicit declaration for the
+                    // implicit "xml:" prefix, but the XPath data model
+                    // requires that this appear as a Namespace Node so we
+                    // have to synthesize one. You can think of this as
+                    // being a default attribute defined by the XML
+                    // Namespaces spec rather than by the DTD.
+                    attrIndex=addNode(new DOM2DTMdefaultNamespaceDeclarationNode(
+                            (Element)next,"xml",NAMESPACE_DECL_NS,
+                            makeNodeHandle(((attrIndex==NULL)?nextindex:attrIndex)+1)
+                        ),
+                        nextindex,attrIndex,NULL);
+                    m_firstch.setElementAt(DTM.NULL,attrIndex);
+                    m_processedFirstElement=true;
+                }
+                if(attrIndex!=NULL) m_nextsib.setElementAt(DTM.NULL,attrIndex);
+            } //if(ELEMENT_NODE)
+        } // (if !suppressNode)
+
+        // Text postprocessing: Act on values stored above
+        //if(TEXT_NODE == nexttype || CDATA_SECTION_NODE == nexttype)
+        //{
+            // %TBD% If nexttype was forced to TEXT, patch the DTM node
+            if (lastTextNode != null) next=lastTextNode;      // Advance the DOM cursor over contiguous text
+        //}
+
+        // Remember where we left off.
+        m_pos=next;
+        return true;
+    }
+
+
+    /**
+     * Return an DOM node for the given node.
+     *
+     * @param nodeHandle The node ID.
+     *
+     * @return A node representation of the DTM node.
+     */
+    public Node getNode(int nodeHandle)
+    {
+
+        int identity = makeNodeIdentity(nodeHandle);
+
+        return (Node) m_nodes.get(identity);
+    }
+
+    /**
+     * Get a Node from an identity index.
+     *
+     * NEEDSDOC @param nodeIdentity
+     *
+     * NEEDSDOC ($objectName$) @return
+     */
+    protected Node lookupNode(int nodeIdentity)
+    {
+        return (Node) m_nodes.get(nodeIdentity);
+    }
+
+    /**
+     * Get the next node identity value in the list, and call the iterator
+     * if it hasn't been added yet.
+     *
+     * @param identity The node identity (index).
+     * @return identity+1, or DTM.NULL.
+     */
+    protected int getNextNodeIdentity(int identity)
+    {
+
+        identity += 1;
+
+        if (identity >= m_nodes.size())
+        {
+            if (!nextNode())
+                identity = DTM.NULL;
+        }
+
+        return identity;
+    }
+
+    /**
+     * Get the handle from a Node.
+     * <p>%OPT% This will be pretty slow.</p>
+     *
+     * <p>%OPT% An XPath-like search (walk up DOM to root, tracking path;
+     * walk down DTM reconstructing path) might be considerably faster
+     * on later nodes in large documents. That might also imply improving
+     * this call to handle nodes which would be in this DTM but
+     * have not yet been built, which might or might not be a Good Thing.</p>
+     *
+     * %REVIEW% This relies on being able to test node-identity via
+     * object-identity. DTM2DOM proxying is a great example of a case where
+     * that doesn't work. DOM Level 3 will provide the isSameNode() method
+     * to fix that, but until then this is going to be flaky.
+     *
+     * @param node A node, which may be null.
+     *
+     * @return The node handle or <code>DTM.NULL</code>.
+     */
+    public int getHandleFromNode(Node node)
+    {
+        if (null != node)
+        {
+            int len = m_nodes.size();
+            boolean isMore;
+            int i = 0;
+            do
+            {
+                for (; i < len; i++)
+                {
+                    if (m_nodes.get(i) == node)
+                        return makeNodeHandle(i);
+                }
+
+                isMore = nextNode();
+
+                len = m_nodes.size();
+
+            }
+            while(isMore || i < len);
+        }
+
+        return DTM.NULL;
+    }
+
+    /** Get the handle from a Node. This is a more robust version of
+     * getHandleFromNode, intended to be usable by the public.
+     *
+     * <p>%OPT% This will be pretty slow.</p>
+     *
+     * %REVIEW% This relies on being able to test node-identity via
+     * object-identity. DTM2DOM proxying is a great example of a case where
+     * that doesn't work. DOM Level 3 will provide the isSameNode() method
+     * to fix that, but until then this is going to be flaky.
+     *
+     * @param node A node, which may be null.
+     *
+     * @return The node handle or <code>DTM.NULL</code>.  */
+    public int getHandleOfNode(Node node)
+    {
+        if (null != node)
+        {
+            // Is Node actually within the same document? If not, don't search!
+            // This would be easier if m_root was always the Document node, but
+            // we decided to allow wrapping a DTM around a subtree.
+            if((m_root==node) ||
+                (m_root.getNodeType()==DOCUMENT_NODE &&
+                    m_root==node.getOwnerDocument()) ||
+                (m_root.getNodeType()!=DOCUMENT_NODE &&
+                    m_root.getOwnerDocument()==node.getOwnerDocument())
+                )
+            {
+                // If node _is_ in m_root's tree, find its handle
+                //
+                // %OPT% This check may be improved significantly when DOM
+                // Level 3 nodeKey and relative-order tests become
+                // available!
+                for(Node cursor=node;
+                    cursor!=null;
+                    cursor=
+                        (cursor.getNodeType()!=ATTRIBUTE_NODE)
+                            ? cursor.getParentNode()
+                            : ((org.w3c.dom.Attr)cursor).getOwnerElement())
+                {
+                    if(cursor==m_root)
+                        // We know this node; find its handle.
+                        return getHandleFromNode(node);
+                } // for ancestors of node
+            } // if node and m_root in same Document
+        } // if node!=null
+
+        return DTM.NULL;
+    }
+
+    /**
+     * Retrieves an attribute node by by qualified name and namespace URI.
+     *
+     * @param nodeHandle int Handle of the node upon which to look up this attribute..
+     * @param namespaceURI The namespace URI of the attribute to
+     *   retrieve, or null.
+     * @param name The local name of the attribute to
+     *   retrieve.
+     * @return The attribute node handle with the specified name (
+     *   <code>nodeName</code>) or <code>DTM.NULL</code> if there is no such
+     *   attribute.
+     */
+    public int getAttributeNode(int nodeHandle, String namespaceURI,
+                                String name)
+    {
+
+        // %OPT% This is probably slower than it needs to be.
+        if (null == namespaceURI)
+            namespaceURI = "";
+
+        int type = getNodeType(nodeHandle);
+
+        if (DTM.ELEMENT_NODE == type)
+        {
+
+            // Assume that attributes immediately follow the element.
+            int identity = makeNodeIdentity(nodeHandle);
+
+            while (DTM.NULL != (identity = getNextNodeIdentity(identity)))
+            {
+                // Assume this can not be null.
+                type = _type(identity);
+
+                // %REVIEW%
+                // Should namespace nodes be retrievable DOM-style as attrs?
+                // If not we need a separate function... which may be desirable
+                // architecturally, but which is ugly from a code point of view.
+                // (If we REALLY insist on it, this code should become a subroutine
+                // of both -- retrieve the node, then test if the type matches
+                // what you're looking for.)
+                if (type == DTM.ATTRIBUTE_NODE || type==DTM.NAMESPACE_NODE)
+                {
+                    Node node = lookupNode(identity);
+                    String nodeuri = node.getNamespaceURI();
+
+                    if (null == nodeuri)
+                        nodeuri = "";
+
+                    String nodelocalname = node.getLocalName();
+
+                    if (nodeuri.equals(namespaceURI) && name.equals(nodelocalname))
+                        return makeNodeHandle(identity);
+                }
+
+                else // if (DTM.NAMESPACE_NODE != type)
+                {
+                    break;
+                }
+            }
+        }
+
+        return DTM.NULL;
+    }
+
+    /**
+     * Get the string-value of a node as a String object
+     * (see http://www.w3.org/TR/xpath#data-model
+     * for the definition of a node's string-value).
+     *
+     * @param nodeHandle The node ID.
+     *
+     * @return A string object that represents the string-value of the given node.
+     */
+    public XMLString getStringValue(int nodeHandle)
+    {
+
+        int type = getNodeType(nodeHandle);
+        Node node = getNode(nodeHandle);
+        // %TBD% If an element only has one text node, we should just use it
+        // directly.
+        if(DTM.ELEMENT_NODE == type || DTM.DOCUMENT_NODE == type
+            || DTM.DOCUMENT_FRAGMENT_NODE == type)
+        {
+            FastStringBuffer buf = StringBufferPool.get();
+            String s;
+
+            try
+            {
+                getNodeData(node, buf);
+
+                s = (buf.length() > 0) ? buf.toString() : "";
+            }
+            finally
+            {
+                StringBufferPool.free(buf);
+            }
+
+            return m_xstrf.newstr( s );
+        }
+        else if(TEXT_NODE == type || CDATA_SECTION_NODE == type)
+        {
+            // If this is a DTM text node, it may be made of multiple DOM text
+            // nodes -- including navigating into Entity References. DOM2DTM
+            // records the first node in the sequence and requires that we
+            // pick up the others when we retrieve the DTM node's value.
+            //
+            // %REVIEW% DOM Level 3 is expected to add a "whole text"
+            // retrieval method which performs this function for us.
+            FastStringBuffer buf = StringBufferPool.get();
+            while(node!=null)
+            {
+                buf.append(node.getNodeValue());
+                node=logicalNextDOMTextNode(node);
+            }
+            String s=(buf.length() > 0) ? buf.toString() : "";
+            StringBufferPool.free(buf);
+            return m_xstrf.newstr( s );
+        }
+        else
+            return m_xstrf.newstr( node.getNodeValue() );
+    }
+
+    /**
+     * Determine if the string-value of a node is whitespace
+     *
+     * @param nodeHandle The node Handle.
+     *
+     * @return Return true if the given node is whitespace.
+     */
+    public boolean isWhitespace(int nodeHandle)
+    {
+        int type = getNodeType(nodeHandle);
+        Node node = getNode(nodeHandle);
+        if(TEXT_NODE == type || CDATA_SECTION_NODE == type)
+        {
+            // If this is a DTM text node, it may be made of multiple DOM text
+            // nodes -- including navigating into Entity References. DOM2DTM
+            // records the first node in the sequence and requires that we
+            // pick up the others when we retrieve the DTM node's value.
+            //
+            // %REVIEW% DOM Level 3 is expected to add a "whole text"
+            // retrieval method which performs this function for us.
+            FastStringBuffer buf = StringBufferPool.get();
+            while(node!=null)
+            {
+                buf.append(node.getNodeValue());
+                node=logicalNextDOMTextNode(node);
+            }
+            boolean b = buf.isWhitespace(0, buf.length());
+            StringBufferPool.free(buf);
+            return b;
+        }
+        return false;
+    }
+
+    /**
+     * Retrieve the text content of a DOM subtree, appending it into a
+     * user-supplied FastStringBuffer object. Note that attributes are
+     * not considered part of the content of an element.
+     * <p>
+     * There are open questions regarding whitespace stripping.
+     * Currently we make no special effort in that regard, since the standard
+     * DOM doesn't yet provide DTD-based information to distinguish
+     * whitespace-in-element-context from genuine #PCDATA. Note that we
+     * should probably also consider xml:space if/when we address this.
+     * DOM Level 3 may solve the problem for us.
+     * <p>
+     * %REVIEW% Actually, since this method operates on the DOM side of the
+     * fence rather than the DTM side, it SHOULDN'T do
+     * any special handling. The DOM does what the DOM does; if you want
+     * DTM-level abstractions, use DTM-level methods.
+     *
+     * @param node Node whose subtree is to be walked, gathering the
+     * contents of all Text or CDATASection nodes.
+     * @param buf FastStringBuffer into which the contents of the text
+     * nodes are to be concatenated.
+     */
+    protected static void getNodeData(Node node, FastStringBuffer buf)
+    {
+
+        switch (node.getNodeType())
+        {
+            case Node.DOCUMENT_FRAGMENT_NODE :
+            case Node.DOCUMENT_NODE :
+            case Node.ELEMENT_NODE :
+            {
+                for (Node child = node.getFirstChild(); null != child;
+                     child = child.getNextSibling())
+                {
+                    getNodeData(child, buf);
+                }
+            }
+            break;
+            case Node.TEXT_NODE :
+            case Node.CDATA_SECTION_NODE :
+            case Node.ATTRIBUTE_NODE :	// Never a child but might be our starting node
+                buf.append(node.getNodeValue());
+                break;
+            case Node.PROCESSING_INSTRUCTION_NODE :
+                // warning(XPATHErrorResources.WG_PARSING_AND_PREPARING);
+                break;
+            default :
+                // ignore
+                break;
+        }
+    }
+
+    /**
+     * Given a node handle, return its DOM-style node name. This will
+     * include names such as #text or #document.
+     *
+     * @param nodeHandle the id of the node.
+     * @return String Name of this node, which may be an empty string.
+     * %REVIEW% Document when empty string is possible...
+     * %REVIEW-COMMENT% It should never be empty, should it?
+     */
+    public String getNodeName(int nodeHandle)
+    {
+
+        Node node = getNode(nodeHandle);
+
+        // Assume non-null.
+        return node.getNodeName();
+    }
+
+    /**
+     * Given a node handle, return the XPath node name.  This should be
+     * the name as described by the XPath data model, NOT the DOM-style
+     * name.
+     *
+     * @param nodeHandle the id of the node.
+     * @return String Name of this node, which may be an empty string.
+     */
+    public String getNodeNameX(int nodeHandle)
+    {
+
+        String name;
+        short type = getNodeType(nodeHandle);
+
+        switch (type)
+        {
+            case DTM.NAMESPACE_NODE :
+            {
+                Node node = getNode(nodeHandle);
+
+                // assume not null.
+                name = node.getNodeName();
+                if(name.startsWith("xmlns:"))
+                {
+                    name = QName.getLocalPart(name);
+                }
+                else if(name.equals("xmlns"))
+                {
+                    name = "";
+                }
+            }
+            break;
+            case DTM.ATTRIBUTE_NODE :
+            case DTM.ELEMENT_NODE :
+            case DTM.ENTITY_REFERENCE_NODE :
+            case DTM.PROCESSING_INSTRUCTION_NODE :
+            {
+                Node node = getNode(nodeHandle);
+
+                // assume not null.
+                name = node.getNodeName();
+            }
+            break;
+            default :
+                name = "";
+        }
+
+        return name;
+    }
+
+    /**
+     * Given a node handle, return its XPath-style localname.
+     * (As defined in Namespaces, this is the portion of the name after any
+     * colon character).
+     *
+     * @param nodeHandle the id of the node.
+     * @return String Local name of this node.
+     */
+    public String getLocalName(int nodeHandle)
+    {
+//        if(JJK_NEWCODE)
+//        {
+            int id=makeNodeIdentity(nodeHandle);
+            if(NULL==id) return null;
+            Node newnode=(Node)m_nodes.get(id);
+            String newname=newnode.getLocalName();
+            if (null == newname)
+            {
+                // XSLT treats PIs, and possibly other things, as having QNames.
+                String qname = newnode.getNodeName();
+                if('#'==qname.charAt(0))
+                {
+                    //  Match old default for this function
+                    // This conversion may or may not be necessary
+                    newname="";
+                }
+                else
+                {
+                    int index = qname.indexOf(':');
+                    newname = (index < 0) ? qname : qname.substring(index + 1);
+                }
+            }
+            return newname;
+//        }
+//        else
+//        {
+//            String name;
+//            short type = getNodeType(nodeHandle);
+//            switch (type)
+//            {
+//                case DTM.ATTRIBUTE_NODE :
+//                case DTM.ELEMENT_NODE :
+//                case DTM.ENTITY_REFERENCE_NODE :
+//                case DTM.NAMESPACE_NODE :
+//                case DTM.PROCESSING_INSTRUCTION_NODE :
+//                {
+//                    Node node = getNode(nodeHandle);
+//
+//                    // assume not null.
+//                    name = node.getLocalName();
+//
+//                    if (null == name)
+//                    {
+//                        String qname = node.getNodeName();
+//                        int index = qname.indexOf(':');
+//
+//                        name = (index < 0) ? qname : qname.substring(index + 1);
+//                    }
+//                }
+//                break;
+//                default :
+//                    name = "";
+//            }
+//            return name;
+//        }
+    }
+
+    /**
+     * Given a namespace handle, return the prefix that the namespace decl is
+     * mapping.
+     * Given a node handle, return the prefix used to map to the namespace.
+     *
+     * <p> %REVIEW% Are you sure you want "" for no prefix?  </p>
+     * <p> %REVIEW-COMMENT% I think so... not totally sure. -sb  </p>
+     *
+     * @param nodeHandle the id of the node.
+     * @return String prefix of this node's name, or "" if no explicit
+     * namespace prefix was given.
+     */
+    public String getPrefix(int nodeHandle)
+    {
+
+        String prefix;
+        short type = getNodeType(nodeHandle);
+
+        switch (type)
+        {
+            case DTM.NAMESPACE_NODE :
+            {
+                Node node = getNode(nodeHandle);
+
+                // assume not null.
+                String qname = node.getNodeName();
+                int index = qname.indexOf(':');
+
+                prefix = (index < 0) ? "" : qname.substring(index + 1);
+            }
+            break;
+            case DTM.ATTRIBUTE_NODE :
+            case DTM.ELEMENT_NODE :
+            {
+                Node node = getNode(nodeHandle);
+
+                // assume not null.
+                String qname = node.getNodeName();
+                int index = qname.indexOf(':');
+
+                prefix = (index < 0) ? "" : qname.substring(0, index);
+            }
+            break;
+            default :
+                prefix = "";
+        }
+
+        return prefix;
+    }
+
+    /**
+     * Given a node handle, return its DOM-style namespace URI
+     * (As defined in Namespaces, this is the declared URI which this node's
+     * prefix -- or default in lieu thereof -- was mapped to.)
+     *
+     * <p>%REVIEW% Null or ""? -sb</p>
+     *
+     * @param nodeHandle the id of the node.
+     * @return String URI value of this node's namespace, or null if no
+     * namespace was resolved.
+     */
+    public String getNamespaceURI(int nodeHandle)
+    {
+//        if(JJK_NEWCODE)
+//        {
+            int id=makeNodeIdentity(nodeHandle);
+            if(id==NULL) return null;
+            Node node=(Node)m_nodes.get(id);
+            return node.getNamespaceURI();
+//        }
+//        else
+//        {
+//            String nsuri;
+//            short type = getNodeType(nodeHandle);
+//
+//            switch (type)
+//            {
+//                case DTM.ATTRIBUTE_NODE :
+//                case DTM.ELEMENT_NODE :
+//                case DTM.ENTITY_REFERENCE_NODE :
+//                case DTM.NAMESPACE_NODE :
+//                case DTM.PROCESSING_INSTRUCTION_NODE :
+//                {
+//                    Node node = getNode(nodeHandle);
+//
+//                    // assume not null.
+//                    nsuri = node.getNamespaceURI();
+//
+//                    // %TBD% Handle DOM1?
+//                }
+//                break;
+//                default :
+//                    nsuri = null;
+//            }
+//
+//            return nsuri;
+//        }
+    }
+
+    /** Utility function: Given a DOM Text node, determine whether it is
+     * logically followed by another Text or CDATASection node. This may
+     * involve traversing into Entity References.
+     *
+     * %REVIEW% DOM Level 3 is expected to add functionality which may
+     * allow us to retire this.
+     */
+    private Node logicalNextDOMTextNode(Node n)
+    {
+        Node p=n.getNextSibling();
+        if(p==null)
+        {
+            // Walk out of any EntityReferenceNodes that ended with text
+            for(n=n.getParentNode();
+                n!=null && ENTITY_REFERENCE_NODE == n.getNodeType();
+                n=n.getParentNode())
+            {
+                p=n.getNextSibling();
+                if(p!=null)
+                    break;
+            }
+        }
+        n=p;
+        while(n!=null && ENTITY_REFERENCE_NODE == n.getNodeType())
+        {
+            // Walk into any EntityReferenceNodes that start with text
+            if(n.hasChildNodes())
+                n=n.getFirstChild();
+            else
+                n=n.getNextSibling();
+        }
+        if(n!=null)
+        {
+            // Found a logical next sibling. Is it text?
+            int ntype=n.getNodeType();
+            if(TEXT_NODE != ntype && CDATA_SECTION_NODE != ntype)
+                n=null;
+        }
+        return n;
+    }
+
+    /**
+     * Given a node handle, return its node value. This is mostly
+     * as defined by the DOM, but may ignore some conveniences.
+     * <p>
+     *
+     * @param nodeHandle The node id.
+     * @return String Value of this node, or null if not
+     * meaningful for this node type.
+     */
+    public String getNodeValue(int nodeHandle)
+    {
+        // The _type(nodeHandle) call was taking the lion's share of our
+        // time, and was wrong anyway since it wasn't coverting handle to
+        // identity. Inlined it.
+        int type = _exptype(makeNodeIdentity(nodeHandle));
+        type=(NULL != type) ? getNodeType(nodeHandle) : NULL;
+
+        if(TEXT_NODE!=type && CDATA_SECTION_NODE!=type)
+            return getNode(nodeHandle).getNodeValue();
+
+        // If this is a DTM text node, it may be made of multiple DOM text
+        // nodes -- including navigating into Entity References. DOM2DTM
+        // records the first node in the sequence and requires that we
+        // pick up the others when we retrieve the DTM node's value.
+        //
+        // %REVIEW% DOM Level 3 is expected to add a "whole text"
+        // retrieval method which performs this function for us.
+        Node node = getNode(nodeHandle);
+        Node n=logicalNextDOMTextNode(node);
+        if(n==null)
+            return node.getNodeValue();
+
+        FastStringBuffer buf = StringBufferPool.get();
+        buf.append(node.getNodeValue());
+        while(n!=null)
+        {
+            buf.append(n.getNodeValue());
+            n=logicalNextDOMTextNode(n);
+        }
+        String s = (buf.length() > 0) ? buf.toString() : "";
+        StringBufferPool.free(buf);
+        return s;
+    }
+
+    /**
+     *   A document type declaration information item has the following properties:
+     *
+     *     1. [system identifier] The system identifier of the external subset, if
+     *        it exists. Otherwise this property has no value.
+     *
+     * @return the system identifier String object, or null if there is none.
+     */
+    public String getDocumentTypeDeclarationSystemIdentifier()
+    {
+
+        Document doc;
+
+        if (m_root.getNodeType() == Node.DOCUMENT_NODE)
+            doc = (Document) m_root;
+        else
+            doc = m_root.getOwnerDocument();
+
+        if (null != doc)
+        {
+            DocumentType dtd = doc.getDoctype();
+
+            if (null != dtd)
+            {
+                return dtd.getSystemId();
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Return the public identifier of the external subset,
+     * normalized as described in 4.2.2 External Entities [XML]. If there is
+     * no external subset or if it has no public identifier, this property
+     * has no value.
+     *
+     * @return the public identifier String object, or null if there is none.
+     */
+    public String getDocumentTypeDeclarationPublicIdentifier()
+    {
+
+        Document doc;
+
+        if (m_root.getNodeType() == Node.DOCUMENT_NODE)
+            doc = (Document) m_root;
+        else
+            doc = m_root.getOwnerDocument();
+
+        if (null != doc)
+        {
+            DocumentType dtd = doc.getDoctype();
+
+            if (null != dtd)
+            {
+                return dtd.getPublicId();
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Returns the <code>Element</code> whose <code>ID</code> is given by
+     * <code>elementId</code>. If no such element exists, returns
+     * <code>DTM.NULL</code>. Behavior is not defined if more than one element
+     * has this <code>ID</code>. Attributes (including those
+     * with the name "ID") are not of type ID unless so defined by DTD/Schema
+     * information available to the DTM implementation.
+     * Implementations that do not know whether attributes are of type ID or
+     * not are expected to return <code>DTM.NULL</code>.
+     *
+     * <p>%REVIEW% Presumably IDs are still scoped to a single document,
+     * and this operation searches only within a single document, right?
+     * Wouldn't want collisions between DTMs in the same process.</p>
+     *
+     * @param elementId The unique <code>id</code> value for an element.
+     * @return The handle of the matching element.
+     */
+    public int getElementById(String elementId)
+    {
+
+        Document doc = (m_root.getNodeType() == Node.DOCUMENT_NODE)
+            ? (Document) m_root : m_root.getOwnerDocument();
+
+        if(null != doc)
+        {
+            Node elem = doc.getElementById(elementId);
+            if(null != elem)
+            {
+                int elemHandle = getHandleFromNode(elem);
+
+                if(DTM.NULL == elemHandle)
+                {
+                    int identity = m_nodes.size()-1;
+                    while (DTM.NULL != (identity = getNextNodeIdentity(identity)))
+                    {
+                        Node node = getNode(identity);
+                        if(node == elem)
+                        {
+                            elemHandle = getHandleFromNode(elem);
+                            break;
+                        }
+                    }
+                }
+
+                return elemHandle;
+            }
+
+        }
+        return DTM.NULL;
+    }
+
+    /**
+     * The getUnparsedEntityURI function returns the URI of the unparsed
+     * entity with the specified name in the same document as the context
+     * node (see [3.3 Unparsed Entities]). It returns the empty string if
+     * there is no such entity.
+     * <p>
+     * XML processors may choose to use the System Identifier (if one
+     * is provided) to resolve the entity, rather than the URI in the
+     * Public Identifier. The details are dependent on the processor, and
+     * we would have to support some form of plug-in resolver to handle
+     * this properly. Currently, we simply return the System Identifier if
+     * present, and hope that it a usable URI or that our caller can
+     * map it to one.
+     * TODO: Resolve Public Identifiers... or consider changing function name.
+     * <p>
+     * If we find a relative URI
+     * reference, XML expects it to be resolved in terms of the base URI
+     * of the document. The DOM doesn't do that for us, and it isn't
+     * entirely clear whether that should be done here; currently that's
+     * pushed up to a higher level of our application. (Note that DOM Level
+     * 1 didn't store the document's base URI.)
+     * TODO: Consider resolving Relative URIs.
+     * <p>
+     * (The DOM's statement that "An XML processor may choose to
+     * completely expand entities before the structure model is passed
+     * to the DOM" refers only to parsed entities, not unparsed, and hence
+     * doesn't affect this function.)
+     *
+     * @param name A string containing the Entity Name of the unparsed
+     * entity.
+     *
+     * @return String containing the URI of the Unparsed Entity, or an
+     * empty string if no such entity exists.
+     */
+    public String getUnparsedEntityURI(String name)
+    {
+
+        String url = "";
+        Document doc = (m_root.getNodeType() == Node.DOCUMENT_NODE)
+            ? (Document) m_root : m_root.getOwnerDocument();
+
+        if (null != doc)
+        {
+            DocumentType doctype = doc.getDoctype();
+
+            if (null != doctype)
+            {
+                NamedNodeMap entities = doctype.getEntities();
+                if(null == entities)
+                    return url;
+                Entity entity = (Entity) entities.getNamedItem(name);
+                if(null == entity)
+                    return url;
+
+                String notationName = entity.getNotationName();
+
+                if (null != notationName)  // then it's unparsed
+                {
+                    // The draft says: "The XSLT processor may use the public
+                    // identifier to generate a URI for the entity instead of the URI
+                    // specified in the system identifier. If the XSLT processor does
+                    // not use the public identifier to generate the URI, it must use
+                    // the system identifier; if the system identifier is a relative
+                    // URI, it must be resolved into an absolute URI using the URI of
+                    // the resource containing the entity declaration as the base
+                    // URI [RFC2396]."
+                    // So I'm falling a bit short here.
+                    url = entity.getSystemId();
+
+                    if (null == url)
+                    {
+                        url = entity.getPublicId();
+                    }
+                    else
+                    {
+                        // This should be resolved to an absolute URL, but that's hard
+                        // to do from here.
+                    }
+                }
+            }
+        }
+
+        return url;
+    }
+
+    /**
+     *     5. [specified] A flag indicating whether this attribute was actually
+     *        specified in the start-tag of its element, or was defaulted from the
+     *        DTD.
+     *
+     * @param attributeHandle the attribute handle
+     * @return <code>true</code> if the attribute was specified;
+     *         <code>false</code> if it was defaulted.
+     */
+    public boolean isAttributeSpecified(int attributeHandle)
+    {
+        int type = getNodeType(attributeHandle);
+
+        if (DTM.ATTRIBUTE_NODE == type)
+        {
+            Attr attr = (Attr)getNode(attributeHandle);
+            return attr.getSpecified();
+        }
+        return false;
+    }
+
+    /** Bind an IncrementalSAXSource to this DTM. NOT RELEVANT for DOM2DTM, since
+     * we're wrapped around an existing DOM.
+     *
+     * @param source The IncrementalSAXSource that we want to recieve events from
+     * on demand.
+     */
+    public void setIncrementalSAXSource(IncrementalSAXSource source)
+    {
+    }
+
+    /** getContentHandler returns "our SAX builder" -- the thing that
+     * someone else should send SAX events to in order to extend this
+     * DTM model.
+     *
+     * @return null if this model doesn't respond to SAX events,
+     * "this" if the DTM object has a built-in SAX ContentHandler,
+     * the IncrmentalSAXSource if we're bound to one and should receive
+     * the SAX stream via it for incremental build purposes...
+     * */
+    public org.xml.sax.ContentHandler getContentHandler()
+    {
+        return null;
+    }
+
+    /**
+     * Return this DTM's lexical handler.
+     *
+     * %REVIEW% Should this return null if constrution already done/begun?
+     *
+     * @return null if this model doesn't respond to lexical SAX events,
+     * "this" if the DTM object has a built-in SAX ContentHandler,
+     * the IncrementalSAXSource if we're bound to one and should receive
+     * the SAX stream via it for incremental build purposes...
+     */
+    public org.xml.sax.ext.LexicalHandler getLexicalHandler()
+    {
+
+        return null;
+    }
+
+
+    /**
+     * Return this DTM's EntityResolver.
+     *
+     * @return null if this model doesn't respond to SAX entity ref events.
+     */
+    public org.xml.sax.EntityResolver getEntityResolver()
+    {
+
+        return null;
+    }
+
+    /**
+     * Return this DTM's DTDHandler.
+     *
+     * @return null if this model doesn't respond to SAX dtd events.
+     */
+    public org.xml.sax.DTDHandler getDTDHandler()
+    {
+
+        return null;
+    }
+
+    /**
+     * Return this DTM's ErrorHandler.
+     *
+     * @return null if this model doesn't respond to SAX error events.
+     */
+    public org.xml.sax.ErrorHandler getErrorHandler()
+    {
+
+        return null;
+    }
+
+    /**
+     * Return this DTM's DeclHandler.
+     *
+     * @return null if this model doesn't respond to SAX Decl events.
+     */
+    public org.xml.sax.ext.DeclHandler getDeclHandler()
+    {
+
+        return null;
+    }
+
+    /** @return true iff we're building this model incrementally (eg
+     * we're partnered with a IncrementalSAXSource) and thus require that the
+     * transformation and the parse run simultaneously. Guidance to the
+     * DTMManager.
+     * */
+    public boolean needsTwoThreads()
+    {
+        return false;
+    }
+
+    // ========== Direct SAX Dispatch, for optimization purposes ========
+
+    /**
+     * Returns whether the specified <var>ch</var> conforms to the XML 1.0 definition
+     * of whitespace.  Refer to <A href="http://www.w3.org/TR/1998/REC-xml-19980210#NT-S">
+     * the definition of <CODE>S</CODE></A> for details.
+     * @param   ch      Character to check as XML whitespace.
+     * @return          =true if <var>ch</var> is XML whitespace; otherwise =false.
+     */
+    private static boolean isSpace(char ch)
+    {
+        return XMLCharacterRecognizer.isWhiteSpace(ch);  // Take the easy way out for now.
+    }
+
+    /**
+     * Directly call the
+     * characters method on the passed ContentHandler for the
+     * string-value of the given node (see http://www.w3.org/TR/xpath#data-model
+     * for the definition of a node's string-value). Multiple calls to the
+     * ContentHandler's characters methods may well occur for a single call to
+     * this method.
+     *
+     * @param nodeHandle The node ID.
+     * @param ch A non-null reference to a ContentHandler.
+     *
+     * @throws org.xml.sax.SAXException
+     */
+    public void dispatchCharactersEvents(
+        int nodeHandle, org.xml.sax.ContentHandler ch,
+        boolean normalize)
+        throws org.xml.sax.SAXException
+    {
+        if(normalize)
+        {
+            XMLString str = getStringValue(nodeHandle);
+            str = str.fixWhiteSpace(true, true, false);
+            str.dispatchCharactersEvents(ch);
+        }
+        else
+        {
+            int type = getNodeType(nodeHandle);
+            Node node = getNode(nodeHandle);
+            dispatchNodeData(node, ch, 0);
+            // Text coalition -- a DTM text node may represent multiple
+            // DOM nodes.
+            if(TEXT_NODE == type || CDATA_SECTION_NODE == type)
+            {
+                while( null != (node=logicalNextDOMTextNode(node)) )
+                {
+                    dispatchNodeData(node, ch, 0);
+                }
+            }
+        }
+    }
+
+    /**
+     * Retrieve the text content of a DOM subtree, appending it into a
+     * user-supplied FastStringBuffer object. Note that attributes are
+     * not considered part of the content of an element.
+     * <p>
+     * There are open questions regarding whitespace stripping.
+     * Currently we make no special effort in that regard, since the standard
+     * DOM doesn't yet provide DTD-based information to distinguish
+     * whitespace-in-element-context from genuine #PCDATA. Note that we
+     * should probably also consider xml:space if/when we address this.
+     * DOM Level 3 may solve the problem for us.
+     * <p>
+     * %REVIEW% Note that as a DOM-level operation, it can be argued that this
+     * routine _shouldn't_ perform any processing beyond what the DOM already
+     * does, and that whitespace stripping and so on belong at the DTM level.
+     * If you want a stripped DOM view, wrap DTM2DOM around DOM2DTM.
+     *
+     * @param node Node whose subtree is to be walked, gathering the
+     * contents of all Text or CDATASection nodes.
+     */
+    protected static void dispatchNodeData(Node node,
+                                           org.xml.sax.ContentHandler ch,
+                                           int depth)
+        throws org.xml.sax.SAXException
+    {
+
+        switch (node.getNodeType())
+        {
+            case Node.DOCUMENT_FRAGMENT_NODE :
+            case Node.DOCUMENT_NODE :
+            case Node.ELEMENT_NODE :
+            {
+                for (Node child = node.getFirstChild(); null != child;
+                     child = child.getNextSibling())
+                {
+                    dispatchNodeData(child, ch, depth+1);
+                }
+            }
+            break;
+            case Node.PROCESSING_INSTRUCTION_NODE : // %REVIEW%
+            case Node.COMMENT_NODE :
+                if(0 != depth)
+                    break;
+                // NOTE: Because this operation works in the DOM space, it does _not_ attempt
+                // to perform Text Coalition. That should only be done in DTM space.
+            case Node.TEXT_NODE :
+            case Node.CDATA_SECTION_NODE :
+            case Node.ATTRIBUTE_NODE :
+                String str = node.getNodeValue();
+                if(ch instanceof org.apache.xml.dtm.ref.dom2dtm.DOM2DTM.CharacterNodeHandler)
+                {
+                    ((org.apache.xml.dtm.ref.dom2dtm.DOM2DTM.CharacterNodeHandler)ch).characters(node);
+                }
+                else
+                {
+                    ch.characters(str.toCharArray(), 0, str.length());
+                }
+                break;
+//    /* case Node.PROCESSING_INSTRUCTION_NODE :
+//      // warning(XPATHErrorResources.WG_PARSING_AND_PREPARING);
+//      break; */
+            default :
+                // ignore
+                break;
+        }
+    }
+
+    TreeWalker m_walker = new TreeWalker(null);
+
+    /**
+     * Directly create SAX parser events from a subtree.
+     *
+     * @param nodeHandle The node ID.
+     * @param ch A non-null reference to a ContentHandler.
+     *
+     * @throws org.xml.sax.SAXException
+     */
+    public void dispatchToEvents(int nodeHandle, org.xml.sax.ContentHandler ch)
+        throws org.xml.sax.SAXException
+    {
+        TreeWalker treeWalker = m_walker;
+        ContentHandler prevCH = treeWalker.getContentHandler();
+
+        if(null != prevCH)
+        {
+            treeWalker = new TreeWalker(null);
+        }
+        treeWalker.setContentHandler(ch);
+
+        try
+        {
+            Node node = getNode(nodeHandle);
+            treeWalker.traverseFragment(node);
+        }
+        finally
+        {
+            treeWalker.setContentHandler(null);
+        }
+    }
+
+    /**
+     * For the moment all the run time properties are ignored by this
+     * class.
+     *
+     * @param property a <code>String</code> value
+     * @param value an <code>Object</code> value
+     */
+    public void setProperty(String property, Object value)
+    {
+    }
+
+    /**
+     * No source information is available for DOM2DTM, so return
+     * <code>null</code> here.
+     *
+     * @param node an <code>int</code> value
+     * @return null
+     */
+    public SourceLocator getSourceLocatorFor(int node)
+    {
+        return null;
+    }
+
+}
+
+