jkesselm 00/12/15 17:40:25
Modified: java/src/org/apache/xpath DOM2Helper.java DOMHelper.java
Log:
Docs, minor code tweak (Seems to pass one more test?)
Revision Changes Path
1.11 +95 -53 xml-xalan/java/src/org/apache/xpath/DOM2Helper.java
Index: DOM2Helper.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/DOM2Helper.java,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- DOM2Helper.java 2000/11/23 04:58:54 1.10
+++ DOM2Helper.java 2000/12/16 01:40:25 1.11
@@ -79,7 +79,7 @@
/**
* <meta name="usage" content="general"/>
* Provides XSLTProcessor an interface to the Xerces XML parser. This
- * liaison should be used if Xerces DOM nodes are being process as
+ * liaison should be used if Xerces DOM nodes are being processed as
* the source tree or as the result tree.
* @see org.apache.xalan.xslt.XSLTProcessor
* @see org.apache.xml.parsers
@@ -94,11 +94,16 @@
/**
* <meta name="usage" content="internal"/>
- * Check node to see if it matches this liaison.
- *
- * NEEDSDOC @param node
- *
- * @throws TransformerException
+ * Check node to see if it was created by a DOM implementation
+ * that this helper is intended to support. This is currently
+ * disabled, and assumes all nodes are acceptable rather than checking
+ * that they implement org.apache.xerces.dom.NodeImpl.
+ *
+ * @param node The node to be tested.
+ *
+ * @throws TransformerException if the node is not one which this
+ * DOM2Helper can support. If we return without throwing the exception,
+ * the node is compatable.
*/
public void checkNode(Node node) throws TransformerException
{
@@ -109,24 +114,28 @@
}
/**
- * Returns true that this implementation does support
- * the SAX ContentHandler interface.
+ * Returns true if the DOM implementation handled by this helper
+ * supports the SAX ContentHandler interface.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true (since Xerces does).
*/
public boolean supportsSAX()
{
return true;
}
- /** NEEDSDOC Field m_doc */
+ /** Field m_doc: Document Node for the document this helper is currently
+ * accessing or building
+ * @see setDocument
+ * @see getDocument
+ * */
private Document m_doc;
/**
- * NEEDSDOC Method setDocument
- *
- *
- * NEEDSDOC @param doc
+ * Specify which document this helper is currently operating on.
+ *
+ * @param doc The DOM Document node for this document.
+ * @see getDocument
*/
public void setDocument(Document doc)
{
@@ -134,10 +143,10 @@
}
/**
- * NEEDSDOC Method getDocument
- *
- *
- * NEEDSDOC (getDocument) @return
+ * Query which document this helper is currently operating on.
+ *
+ * @return The DOM Document node for this document.
+ * @see setDocument
*/
public Document getDocument()
{
@@ -236,12 +245,19 @@
}
/**
- * Given an ID, return the element.
- *
- * NEEDSDOC @param id
- * NEEDSDOC @param doc
- *
- * NEEDSDOC ($objectName$) @return
+ * Given an XML ID, return the element. This requires assistance from the
+ * DOM and parser, and is meaningful only in the context of a DTD
+ * or schema which declares attributes as being of type ID. This
+ * information may or may not be available in all parsers, may or
+ * may not be available for specific documents, and may or may not
+ * be available when validation is not turned on.
+ *
+ * @param id The ID to search for, as a String.
+ * @param doc The document to search within, as a DOM Document node.
+ * @return DOM Element node with an attribute of type ID whose value
+ * uniquely matches the requested id string, or null if there isn't
+ * such an element or if the DOM can't answer the question for other
+ * reasons.
*/
public Element getElementByID(String id, Document doc)
{
@@ -249,16 +265,22 @@
}
/**
- * Figure out if node2 should be placed after node1 when
- * placing nodes in a list that is to be sorted in
- * document order.
- * NOTE: Make sure this does the right thing with attribute nodes!!!
- *
- * NEEDSDOC @param node1
- * NEEDSDOC @param node2
- * @return true if node2 should be placed
- * after node1, and false if node2 should be placed
- * before node1.
+ * Figure out whether node2 should be considered as being later
+ * in the document than node1, in Document Order as defined
+ * by the XPath model. This may not agree with the ordering defined
+ * by other XML applications.
+ * <p>
+ * There are some cases where ordering isn't defined, and neither are
+ * the results of this function -- though we'll generally return true.
+ * <p>
+ * TODO: Make sure this does the right thing with attribute nodes!!!
+ *
+ * @param node1 DOM Node to perform position comparison on.
+ * @param node2 DOM Node to perform position comparison on .
+ *
+ * @return false if node2 comes before node1, otherwise return true.
+ * You can think of this as
+ * <code>(node1.documentOrderPosition <=
node2.documentOrderPosition)</code>.
*/
public boolean isNodeAfter(Node node1, Node node2)
{
@@ -276,32 +298,41 @@
{
// isNodeAfter will return true if node is after countedNode
- // in document order. isDOMNodeAfter is sloooow (relativly).
+ // in document order. The base isNodeAfter is sloooow (relatively)
return super.isNodeAfter(node1, node2);
}
}
/**
- * Get the parent of a node.
- *
- * NEEDSDOC @param node
- *
- * NEEDSDOC ($objectName$) @return
- *
- * @throws RuntimeException
+ * Get the XPath-model parent of a node. This version takes advantage
+ * of the DOM Level 2 Attr.ownerElement() method; the base version we
+ * would otherwise inherit is prepared to fall back on exhaustively
+ * walking the document to find an Attr's parent.
+ *
+ * @param node Node to be examined
+ *
+ * @return the DOM parent of the input node, if there is one, or the
+ * ownerElement if the input node is an Attr, or null if the node is
+ * a Document, a DocumentFragment, or an orphan.
*/
- public Node getParentOfNode(Node node) throws RuntimeException
+ public Node getParentOfNode(Node node)
{
- return (Node.ATTRIBUTE_NODE == node.getNodeType())
- ? ((Attr) node).getOwnerElement() : node.getParentNode();
+ Node parent=node.getParentNode();
+ if(parent==null && (Node.ATTRIBUTE_NODE == node.getNodeType()) )
+ parent=((Attr) node).getOwnerElement();
+ return parent;
}
/**
- * Returns the local name of the given node.
+ * Returns the local name of the given node, as defined by the
+ * XML Namespaces specification. This is prepared to handle documents
+ * built using DOM Level 1 methods by falling back upon explicitly
+ * parsing the node name.
*
- * NEEDSDOC @param n
+ * @param n Node to be examined
*
- * NEEDSDOC ($objectName$) @return
+ * @return String containing the local name, or null if the node
+ * was not assigned a Namespace.
*/
public String getLocalNameOfNode(Node n)
{
@@ -312,17 +343,28 @@
}
/**
- * Returns the namespace of the given node.
+ * Returns the Namespace Name (Namespace URI) for the given node.
+ * In a Level 2 DOM, you can ask the node itself. Note, however, that
+ * doing so conflicts with our decision in getLocalNameOfNode not
+ * to trust the that the DOM was indeed created using the Level 2
+ * methods. If Level 1 methods were used, these two functions will
+ * disagree with each other.
+ * <p>
+ * TODO: Reconcile with getLocalNameOfNode.
*
- * NEEDSDOC @param n
+ * @param n Node to be examined
*
- * NEEDSDOC ($objectName$) @return
+ * @return String containing the Namespace URI bound to this DOM node
+ * at the time the Node was created.
*/
public String getNamespaceOfNode(Node n)
{
return n.getNamespaceURI();
}
- /** NEEDSDOC Field m_useDOM2getNamespaceURI */
- private boolean m_useDOM2getNamespaceURI = false;
+ /** Field m_useDOM2getNamespaceURI is a compile-time flag which
+ * gates some of the parser options used to build a DOM -- but
+ * that code is commented out at this time and nobody else
+ * references it, so I've commented this out as well. */
+ //private boolean m_useDOM2getNamespaceURI = false;
}
1.21 +4 -2 xml-xalan/java/src/org/apache/xpath/DOMHelper.java
Index: DOMHelper.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/DOMHelper.java,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- DOMHelper.java 2000/12/15 21:24:37 1.20
+++ DOMHelper.java 2000/12/16 01:40:25 1.21
@@ -1004,8 +1004,10 @@
// Given how expensive the tree walk may be, we should first ask
// whether this DOM can answer the question for us. The additional
- // test does slow down Level 1 DOMs slightly... should/do
- // we have a DOM2Helper, deciding between them when we first connect?
+ // test does slow down Level 1 DOMs slightly. DOMHelper2, which
+ // is currently specialized for Xerces, assumes it can use the
+ // Level 2 solution. We might want to have an intermediate stage,
+ // which would assume DOM Level 2 but not assume Xerces.
//
// (Shouldn't have to check whether impl is null in a compliant DOM,
// but let's be paranoid for a moment...)
