You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by sb...@locus.apache.org on 2000/12/18 01:04:55 UTC
cvs commit: xml-xalan/java/src/org/apache/xpath Arg.java DOMHelper.java Expression.java NodeSet.java SourceTree.java SourceTreeManager.java VariableStack.java XPath.java XPathAPI.java XPathContext.java XPathException.java XPathFactory.java
sboag 00/12/17 16:04:55
Modified: java/src/org/apache/xpath Arg.java DOMHelper.java
Expression.java NodeSet.java SourceTree.java
SourceTreeManager.java VariableStack.java
XPath.java XPathAPI.java XPathContext.java
XPathException.java XPathFactory.java
Log:
Javadoc work.
Revision Changes Path
1.7 +5 -4 xml-xalan/java/src/org/apache/xpath/Arg.java
Index: Arg.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/Arg.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Arg.java 2000/12/16 17:01:20 1.6
+++ Arg.java 2000/12/18 00:04:53 1.7
@@ -153,9 +153,10 @@
m_expression = expr;
}
- /** NEEDSDOC Field m_isParamVar
+ /**
+ * True if this is a parameter variable.
* Set at the time the object is constructed.
- * */
+ */
private boolean m_isParamVar;
/**
@@ -178,7 +179,7 @@
*
* @param qname Name of the argument, expressed as a QName object.
* @param expression String to be stored as this argument's value expression.
- * NEEDSDOC @param isParamVar
+ * @param isParamVar True if this is a parameter variable.
*/
public Arg(QName qname, String expression, boolean isParamVar)
{
@@ -228,7 +229,7 @@
*
* @param qname Name of the argument, expressed as a QName object.
* @param val Value of the argument, expressed as an XObject
- * NEEDSDOC @param isParamVar
+ * @param isParamVar True if this is a parameter variable.
*/
public Arg(QName qname, XObject val, boolean isParamVar)
{
1.22 +105 -98 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.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- DOMHelper.java 2000/12/16 01:40:25 1.21
+++ DOMHelper.java 2000/12/18 00:04:53 1.22
@@ -207,9 +207,9 @@
if (node1 == node2)
return true;
- // Default return value, if there is no defined ordering
+ // Default return value, if there is no defined ordering
boolean isNodeAfter = true;
-
+
Node parent1 = getParentOfNode(node1);
Node parent2 = getParentOfNode(node2);
@@ -220,13 +220,13 @@
isNodeAfter = isNodeAfterSibling(parent1, node1, node2);
else
{
- // If both parents are null, ordering is not defined.
- // We're returning a value in lieu of throwing an exception.
- // Not a case we expect to arise in XPath, but beware if you
- // try to reuse this method.
-
- // We can just fall through in this case, which allows us
- // to hit the debugging code at the end of the function.
+ // If both parents are null, ordering is not defined.
+ // We're returning a value in lieu of throwing an exception.
+ // Not a case we expect to arise in XPath, but beware if you
+ // try to reuse this method.
+
+ // We can just fall through in this case, which allows us
+ // to hit the debugging code at the end of the function.
//return isNodeAfter;
}
}
@@ -235,13 +235,13 @@
// General strategy: Figure out the lengths of the two
// ancestor chains, reconcile the lengths, and look for
- // the lowest common ancestor. If that ancestor is one of
- // the nodes being compared, it comes before the other.
+ // the lowest common ancestor. If that ancestor is one of
+ // the nodes being compared, it comes before the other.
// Otherwise perform a sibling compare.
- //
- // NOTE: If no common ancestor is found, ordering is undefined
- // and we return the default value of isNodeAfter.
-
+ //
+ // NOTE: If no common ancestor is found, ordering is undefined
+ // and we return the default value of isNodeAfter.
+
// Count parents in each ancestor chain
int nParents1 = 2, nParents2 = 2; // include node & parent obtained above
@@ -259,12 +259,12 @@
parent2 = getParentOfNode(parent2);
}
- // Initially assume scan for common ancestor starts with
- // the input nodes.
+ // Initially assume scan for common ancestor starts with
+ // the input nodes.
Node startNode1 = node1, startNode2 = node2;
// If one ancestor chain is longer, adjust its start point
- // so we're comparing at the same depths
+ // so we're comparing at the same depths
if (nParents1 < nParents2)
{
// Adjust startNode2 to depth of startNode1
@@ -303,7 +303,7 @@
}
else
{
- // Compare ancestors below lowest-common as siblings
+ // Compare ancestors below lowest-common as siblings
isNodeAfter = isNodeAfterSibling(startNode1, prevChild1,
prevChild2);
@@ -311,17 +311,17 @@
}
} // end if(startNode1 == startNode2)
- // Move up one level and try again
+ // Move up one level and try again
prevChild1 = startNode1;
startNode1 = getParentOfNode(startNode1);
prevChild2 = startNode2;
startNode2 = getParentOfNode(startNode2);
} // end while(parents exist to examine)
} // end big else (not immediate siblings)
-
- // WARNING: The following diagnostic won't report the early
- // "same node" case. Fix if/when needed.
-
+
+ // WARNING: The following diagnostic won't report the early
+ // "same node" case. Fix if/when needed.
+
/* -- please do not remove... very useful for diagnostics --
System.out.println("node1 = "+node1.getNodeName()+"("+node1.getNodeType()+")"+
", node2 = "+node2.getNodeName()
@@ -372,7 +372,7 @@
int nNodes = children.getLength();
boolean found1 = false, found2 = false;
- // Count from the start until we find one or the other.
+ // Count from the start until we find one or the other.
for (int i = 0; i < nNodes; i++)
{
Node child = children.item(i);
@@ -403,17 +403,17 @@
}
else
{
- // TODO: Check performance of alternate solution:
- // There are two choices here: Count from the start of
- // the document until we find one or the other, or count
- // from one until we find or fail to find the other.
- // Either can wind up scanning all the siblings in the worst
- // case, which on a wide document can be a lot of work but
- // is more typically is a short list.
- // Scanning from the start involves two tests per iteration,
- // but it isn't clear that scanning from the middle doesn't
- // yield more iterations on average.
- // We should run some testcases.
+ // TODO: Check performance of alternate solution:
+ // There are two choices here: Count from the start of
+ // the document until we find one or the other, or count
+ // from one until we find or fail to find the other.
+ // Either can wind up scanning all the siblings in the worst
+ // case, which on a wide document can be a lot of work but
+ // is more typically is a short list.
+ // Scanning from the start involves two tests per iteration,
+ // but it isn't clear that scanning from the middle doesn't
+ // yield more iterations on average.
+ // We should run some testcases.
Node child = parent.getFirstChild();
boolean found1 = false, found2 = false;
@@ -506,45 +506,45 @@
{
namespace = QName.S_XMLNAMESPACEURI; // Hardcoded, per Namespace spec
}
- else if(prefix.equals("xmlns"))
+ else if(prefix.equals("xmlns"))
{
- // Hardcoded in the DOM spec, expected to be adopted by
- // Namespace spec. NOTE: Namespace declarations _must_ use
- // the xmlns: prefix; other prefixes declared as belonging
- // to this namespace will not be recognized and should
- // probably be rejected by parsers as erroneous declarations.
+ // Hardcoded in the DOM spec, expected to be adopted by
+ // Namespace spec. NOTE: Namespace declarations _must_ use
+ // the xmlns: prefix; other prefixes declared as belonging
+ // to this namespace will not be recognized and should
+ // probably be rejected by parsers as erroneous declarations.
namespace = "http://www.w3.org/2000/xmlns/";
}
else
{
- // Attribute name for this prefix's declaration
- String declname=(prefix=="")
- ? "xmlns"
- : "xmlns:"+prefix;
-
- // Scan until we run out of Elements or have resolved the namespace
+ // Attribute name for this prefix's declaration
+ String declname=(prefix=="")
+ ? "xmlns"
+ : "xmlns:"+prefix;
+
+ // Scan until we run out of Elements or have resolved the namespace
while ((null != parent) && (null == namespace)
&& (((type = parent.getNodeType()) == Node.ELEMENT_NODE)
|| (type == Node.ENTITY_REFERENCE_NODE)))
{
if (type == Node.ELEMENT_NODE)
{
-
- // Look for the appropriate Namespace Declaration attribute,
- // either "xmlns:prefix" or (if prefix is "") "xmlns".
- // TODO: This does not handle "implicit declarations"
- // which may be created when the DOM is edited. DOM Level
- // 3 will define how those should be interpreted. But
- // this issue won't arise in freshly-parsed DOMs.
-
- // NOTE: declname is set earlier, outside the loop.
- Attr attr=((Element)parent).getAttributeNode(declname);
- if(attr!=null)
- {
+
+ // Look for the appropriate Namespace Declaration attribute,
+ // either "xmlns:prefix" or (if prefix is "") "xmlns".
+ // TODO: This does not handle "implicit declarations"
+ // which may be created when the DOM is edited. DOM Level
+ // 3 will define how those should be interpreted. But
+ // this issue won't arise in freshly-parsed DOMs.
+
+ // NOTE: declname is set earlier, outside the loop.
+ Attr attr=((Element)parent).getAttributeNode(declname);
+ if(attr!=null)
+ {
namespace = attr.getNodeValue();
break;
- }
- }
+ }
+ }
parent = getParentOfNode(parent);
}
@@ -558,31 +558,38 @@
*/
Hashtable m_NSInfos = new Hashtable();
- /** NEEDSDOC Field m_NSInfoUnProcWithXMLNS */
+ /** Object to put into the m_NSInfos table that tells that a node has not been
+ * processed, but has xmlns namespace decls. */
protected static final NSInfo m_NSInfoUnProcWithXMLNS = new NSInfo(false,
true);
- /** NEEDSDOC Field m_NSInfoUnProcWithoutXMLNS */
+ /** Object to put into the m_NSInfos table that tells that a node has not been
+ * processed, but has no xmlns namespace decls. */
protected static final NSInfo m_NSInfoUnProcWithoutXMLNS = new NSInfo(false,
false);
- /** NEEDSDOC Field m_NSInfoUnProcNoAncestorXMLNS */
+ /** Object to put into the m_NSInfos table that tells that a node has not been
+ * processed, and has no xmlns namespace decls, and has no ancestor decls. */
protected static final NSInfo m_NSInfoUnProcNoAncestorXMLNS =
new NSInfo(false, false, NSInfo.ANCESTORNOXMLNS);
- /** NEEDSDOC Field m_NSInfoNullWithXMLNS */
+ /** Object to put into the m_NSInfos table that tells that a node has been
+ * processed, and has xmlns namespace decls. */
protected static final NSInfo m_NSInfoNullWithXMLNS = new NSInfo(true,
true);
- /** NEEDSDOC Field m_NSInfoNullWithoutXMLNS */
+ /** Object to put into the m_NSInfos table that tells that a node has been
+ * processed, and has no xmlns namespace decls. */
protected static final NSInfo m_NSInfoNullWithoutXMLNS = new NSInfo(true,
false);
- /** NEEDSDOC Field m_NSInfoNullNoAncestorXMLNS */
+ /** Object to put into the m_NSInfos table that tells that a node has been
+ * processed, and has no xmlns namespace decls. and has no ancestor decls. */
protected static final NSInfo m_NSInfoNullNoAncestorXMLNS =
new NSInfo(true, false, NSInfo.ANCESTORNOXMLNS);
- /** NEEDSDOC Field m_candidateNoAncestorXMLNS */
+ /** Vector of node (odd indexes) and NSInfos (even indexes) that tell if
+ * the given node is a candidate for ancestor namespace processing. */
protected Vector m_candidateNoAncestorXMLNS = new Vector();
/**
@@ -884,9 +891,9 @@
// TODO: I can probably do something to figure out if this
// space is ignorable from just the information in
// the DOM tree.
- // -- You need to be able to distinguish whitespace
- // that is #PCDATA from whitespace that isn't. That requires
- // DTD support, which won't be standardized until DOM Level 3.
+ // -- You need to be able to distinguish whitespace
+ // that is #PCDATA from whitespace that isn't. That requires
+ // DTD support, which won't be standardized until DOM Level 3.
return isIgnorable;
}
@@ -994,7 +1001,7 @@
if (Node.ATTRIBUTE_NODE == nodeType)
{
Document doc = node.getOwnerDocument();
- /*
+ /*
TBD:
if(null == doc)
{
@@ -1002,23 +1009,23 @@
}
*/
- // 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. 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...)
- DOMImplementation impl=doc.getImplementation();
- if(impl!=null && impl.hasFeature("Core","2.0"))
- {
- parent=((Attr)node).getOwnerElement();
- return parent;
- }
+ // 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. 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...)
+ DOMImplementation impl=doc.getImplementation();
+ if(impl!=null && impl.hasFeature("Core","2.0"))
+ {
+ parent=((Attr)node).getOwnerElement();
+ return parent;
+ }
- // DOM Level 1 solution, as fallback. Hugely expensive.
+ // DOM Level 1 solution, as fallback. Hugely expensive.
Element rootElem = doc.getDocumentElement();
@@ -1032,7 +1039,7 @@
parent = locateAttrParent(rootElem, node);
- }
+ }
else
{
parent = node.getParentNode();
@@ -1170,14 +1177,14 @@
Node parent = null;
- // This should only be called for Level 1 DOMs, so we don't have to
- // worry about namespace issues. In later levels, it's possible
- // for a DOM to have two Attrs with the same NodeName but
- // different namespaces, and we'd need to get getAttributeNodeNS...
- // but later levels also have Attr.getOwnerElement.
- Attr check=elem.getAttributeNode(attr.getNodeName());
- if(check==attr)
- parent = elem;
+ // This should only be called for Level 1 DOMs, so we don't have to
+ // worry about namespace issues. In later levels, it's possible
+ // for a DOM to have two Attrs with the same NodeName but
+ // different namespaces, and we'd need to get getAttributeNodeNS...
+ // but later levels also have Attr.getOwnerElement.
+ Attr check=elem.getAttributeNode(attr.getNodeName());
+ if(check==attr)
+ parent = elem;
if (null == parent)
{
1.11 +54 -27 xml-xalan/java/src/org/apache/xpath/Expression.java
Index: Expression.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/Expression.java,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- Expression.java 2000/11/23 04:58:54 1.10
+++ Expression.java 2000/12/18 00:04:53 1.11
@@ -66,35 +66,53 @@
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.TransformerException;
+
import org.apache.xml.utils.SAXSourceLocator;
+
import javax.xml.transform.SourceLocator;
import javax.xml.transform.ErrorListener;
/**
- * <meta name="usage" content="internal"/>
- * NEEDSDOC Class Expression <needs-comment/>
+ * This abstract class serves as the base for all expression objects. An
+ * Expression can be executed to return a {@link org.apache.xpath.objects.XObject},
+ * normally has a location within a document or DOM, can send error and warning
+ * events, and normally do not hold state and are meant to be immutable once
+ * construction has completed. An exception to the immutibility rule is iterators
+ * and walkers, which must be cloned in order to be used -- the original must
+ * still be immutable.
*/
-public abstract class Expression
- implements java.io.Serializable
+public abstract class Expression implements java.io.Serializable
{
- /** NEEDSDOC Field m_xpath */
+ /**
+ * The location where this expression was built from. Need for diagnostic
+ * messages. May be null.
+ */
protected SourceLocator m_slocator;
-
+
+ /**
+ * Set the location where this expression was built from.
+ *
+ *
+ * @param locator the location where this expression was built from, may be
+ * null.
+ */
public void setSourceLocator(SourceLocator locator)
{
m_slocator = locator;
}
/**
- * NEEDSDOC Method execute
+ * Execute an expression in the XPath runtime context, and return the
+ * result of the expression.
*
*
- * NEEDSDOC @param xctxt
+ * @param xctxt The XPath runtime context.
*
- * NEEDSDOC (execute) @return
+ * @return The result of the expression in the form of a <code>XObject</code>.
*
- * @throws javax.xml.transform.TransformerException
+ * @throws javax.xml.transform.TransformerException if a runtime exception
+ * occurs.
*/
public abstract XObject execute(XPathContext xctxt)
throws javax.xml.transform.TransformerException;
@@ -102,18 +120,23 @@
/**
* Warn the user of an problem.
*
- * NEEDSDOC @param xctxt
- * NEEDSDOC @param msg
- * NEEDSDOC @param args
+ * @param xctxt The XPath runtime context.
+ * @param msg An error number that corresponds to one of the numbers found
+ * in {@link org.apache.xpath.res.XPATHErrorResources}, which is
+ * a key for a format string.
+ * @param args An array of arguments represented in the format string, which
+ * may be null.
*
- * @throws javax.xml.transform.TransformerException
+ * @throws TransformerException if the current ErrorListoner determines to
+ * throw an exception.
*/
public void warn(XPathContext xctxt, int msg, Object[] args)
- throws javax.xml.transform.TransformerException
+ throws javax.xml.transform.TransformerException
{
java.lang.String fmsg = XSLMessages.createXPATHWarning(msg, args);
- if(null != xctxt)
+
+ if (null != xctxt)
{
ErrorListener eh = xctxt.getErrorListener();
@@ -125,11 +148,11 @@
/**
* Tell the user of an assertion error, and probably throw an
* exception.
- *
- * NEEDSDOC @param b
- * NEEDSDOC @param msg
*
- * @throws javax.xml.transform.TransformerException
+ * @param b If false, a runtime exception will be thrown.
+ * @param msg The assertion message, which should be informative.
+ *
+ * @throws RuntimeException if the b argument is false.
*/
public void assert(boolean b, java.lang.String msg)
throws javax.xml.transform.TransformerException
@@ -149,24 +172,28 @@
* Tell the user of an error, and probably throw an
* exception.
*
- * NEEDSDOC @param xctxt
- * NEEDSDOC @param msg
- * NEEDSDOC @param args
+ * @param xctxt The XPath runtime context.
+ * @param msg An error number that corresponds to one of the numbers found
+ * in {@link org.apache.xpath.res.XPATHErrorResources}, which is
+ * a key for a format string.
+ * @param args An array of arguments represented in the format string, which
+ * may be null.
*
- * @throws javax.xml.transform.TransformerException
+ * @throws TransformerException if the current ErrorListoner determines to
+ * throw an exception.
*/
public void error(XPathContext xctxt, int msg, Object[] args)
throws javax.xml.transform.TransformerException
{
java.lang.String fmsg = XSLMessages.createXPATHMessage(msg, args);
- if(null != xctxt)
+
+ if (null != xctxt)
{
ErrorListener eh = xctxt.getErrorListener();
-
TransformerException te = new TransformerException(fmsg, m_slocator);
+
eh.fatalError(te);
}
-
}
}
1.9 +41 -41 xml-xalan/java/src/org/apache/xpath/NodeSet.java
Index: NodeSet.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/NodeSet.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- NodeSet.java 2000/12/16 03:59:36 1.8
+++ NodeSet.java 2000/12/18 00:04:53 1.9
@@ -389,7 +389,7 @@
* <code>index</code> is greater than or equal to the number of nodes in
* the list, this returns <code>null</code>.
*
- * NEEDSDOC: What happens if index is out of range?
+ * TODO: What happens if index is out of range?
*
* @param index Index into the collection.
* @return The node at the <code>index</code>th position in the
@@ -561,7 +561,7 @@
* document order. If a node is null, don't add it.
*
* @param nodelist List of nodes to be added
- * NEEDSDOC @param support
+ * @param support The XPath runtime context.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -589,7 +589,7 @@
* document order. If a node is null, don't add it.
*
* @param iterator NodeIterator which yields the nodes to be added.
- * NEEDSDOC @param support
+ * @param support The XPath runtime context.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -608,16 +608,15 @@
}
/**
- * Not yet ready for prime time.
- * I can't use recursion in this.
+ * Add the node list to this node set in document order.
*
- * NEEDSDOC @param start
- * NEEDSDOC @param end
- * NEEDSDOC @param testIndex
- * NEEDSDOC @param nodelist
- * NEEDSDOC @param support
+ * @param start index.
+ * @param end index.
+ * @param testIndex index.
+ * @param nodelist The nodelist to add.
+ * @param support The XPath runtime context.
*
- * NEEDSDOC ($objectName$) @return
+ * @return false always.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -678,9 +677,9 @@
* @param v Vector of nodes, presumably containing Nodes
* @param obj Node object.
*
- * NEEDSDOC @param node
+ * @param node The node to be added.
* @param test true if we should test for doc order
- * NEEDSDOC @param support
+ * @param support The XPath runtime context.
* @return insertIndex.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
@@ -755,10 +754,10 @@
* @param v Vector of nodes, presumably containing Nodes
* @param obj Node object.
*
- * NEEDSDOC @param node
- * NEEDSDOC @param support
+ * @param node The node to be added.
+ * @param support The XPath runtime context.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The index where it was inserted.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -774,7 +773,7 @@
/**
* Get the length of the list.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The size of this node set.
*/
public int size()
{
@@ -784,7 +783,7 @@
/**
* Append a Node onto the vector.
*
- * NEEDSDOC @param value
+ * @param value The node to be added.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -803,8 +802,8 @@
* the specified index is shifted upward to have an index one greater
* than the value it had previously.
*
- * NEEDSDOC @param value
- * NEEDSDOC @param at
+ * @param value The node to be inserted.
+ * @param at The index where the insert should occur.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -820,7 +819,7 @@
/**
* Append the nodes to the list.
*
- * NEEDSDOC @param nodes
+ * @param nodes The nodes to be appended to this node set.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -857,9 +856,9 @@
* downward to have an index one smaller than the value it had
* previously.
*
- * NEEDSDOC @param s
+ * @param s The node to be removed.
*
- * NEEDSDOC ($objectName$) @return
+ * @return True if the node was successfully removed
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -878,7 +877,7 @@
* index is shifted downward to have an index one smaller than
* the value it had previously.
*
- * NEEDSDOC @param i
+ * @param i The index of the node to be removed.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -898,8 +897,8 @@
* The index must be a value greater than or equal to 0 and less
* than the current size of the vector.
*
- * NEEDSDOC @param node
- * NEEDSDOC @param index
+ * @param node The node to be set.
+ * @param index The index of the node to be replaced.
* @exception RuntimeException thrown if this NodeSet is not of
* a mutable type.
*/
@@ -915,9 +914,9 @@
/**
* Get the nth element.
*
- * NEEDSDOC @param i
+ * @param i The index of the requested node.
*
- * NEEDSDOC ($objectName$) @return
+ * @return Node at specified index.
*/
public Node elementAt(int i)
{
@@ -930,9 +929,9 @@
/**
* Tell if the table contains the given node.
*
- * NEEDSDOC @param s
+ * @param s Node to look for
*
- * NEEDSDOC ($objectName$) @return
+ * @return True if the given node was found.
*/
public boolean contains(Node s)
{
@@ -947,8 +946,8 @@
* beginning the search at index, and testing for equality
* using the equals method.
*
- * NEEDSDOC @param elem
- * NEEDSDOC @param index
+ * @param elem Node to look for
+ * @param index Index of where to start the search
* @return the index of the first occurrence of the object
* argument in this vector at position index or later in the
* vector; returns -1 if the object is not found.
@@ -966,7 +965,7 @@
* beginning the search at index, and testing for equality
* using the equals method.
*
- * NEEDSDOC @param elem
+ * @param elem Node to look for
* @return the index of the first occurrence of the object
* argument in this vector at position index or later in the
* vector; returns -1 if the object is not found.
@@ -979,7 +978,8 @@
return super.indexOf(elem);
}
- /** NEEDSDOC Field m_next */
+ /** If this node is being used as an iterator, the next index that nextNode()
+ * will return. */
protected int m_next = 0;
/**
@@ -988,7 +988,7 @@
* you call getCurrentPos() and the return is 0, the next
* fetch will take place at index 1.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The the current position index.
*/
public int getCurrentPos()
{
@@ -1014,7 +1014,7 @@
/**
* Return the last fetched node. Needed to support the UnionPathIterator.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the last fetched node.
* @exception RuntimeException thrown if this NodeSet is not of
* a cached type, and thus doesn't permit indexed access.
*/
@@ -1031,17 +1031,17 @@
return n;
}
- /** NEEDSDOC Field m_mutable */
+ /** True if this list can be mutated. */
protected boolean m_mutable = true;
- /** NEEDSDOC Field m_cacheNodes */
+ /** True if this list is cached. */
protected boolean m_cacheNodes = true;
/**
- * NEEDSDOC Method getShouldCacheNodes
+ * Get whether or not this is a cached node set.
*
*
- * NEEDSDOC (getShouldCacheNodes) @return
+ * @return True if this list is cached.
*/
public boolean getShouldCacheNodes()
{
@@ -1054,7 +1054,7 @@
* be set before the first call to nextNode is made, to ensure
* that all nodes are cached.
*
- * NEEDSDOC @param b
+ * @param b true if this node set should be cached.
* @exception RuntimeException thrown if an attempt is made to
* request caching after we've already begun stepping through the
* nodes in this set.
1.3 +6 -4 xml-xalan/java/src/org/apache/xpath/SourceTree.java
Index: SourceTree.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/SourceTree.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- SourceTree.java 2000/10/30 18:58:23 1.2
+++ SourceTree.java 2000/12/18 00:04:53 1.3
@@ -70,8 +70,9 @@
* Constructor SourceTree
*
*
- * NEEDSDOC @param root
- * NEEDSDOC @param url
+ * @param root The root of the source tree, which may or may not be a
+ * {@link org.w3c.dom.Document} node.
+ * @param url The URI of the source tree.
*/
public SourceTree(Node root, String url)
{
@@ -79,9 +80,10 @@
m_url = url;
}
- /** NEEDSDOC Field m_url */
+ /** The URI of the source tree. */
public String m_url;
- /** NEEDSDOC Field m_root */
+ /** The root of the source tree, which may or may not be a
+ * {@link org.w3c.dom.Document} node. */
public Node m_root;
}
1.18 +87 -101 xml-xalan/java/src/org/apache/xpath/SourceTreeManager.java
Index: SourceTreeManager.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/SourceTreeManager.java,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- SourceTreeManager.java 2000/11/23 04:58:55 1.17
+++ SourceTreeManager.java 2000/12/18 00:04:53 1.18
@@ -75,8 +75,8 @@
import org.xml.sax.XMLReader;
import org.xml.sax.ContentHandler;
import org.xml.sax.EntityResolver;
-// import org.xml.sax.Locator;
+// import org.xml.sax.Locator;
import org.apache.xalan.res.XSLMessages;
import org.apache.xalan.stree.SourceTreeHandler;
import org.apache.xml.utils.SystemIDResolver;
@@ -93,20 +93,24 @@
/**
* This class bottlenecks all management of source trees. The methods
* in this class should allow easy garbage collection of source
- * trees, and should centralize parsing for those source trees.
+ * trees (not yet!), and should centralize parsing for those source trees.
*/
public class SourceTreeManager
{
- /** NEEDSDOC Field m_sourceTree */
+ /** Vector of SourceTree objects that this manager manages. */
private Vector m_sourceTree = new Vector();
-
+
+ /**
+ * Reset the list of SourceTree objects that this manager manages.
+ *
+ */
public void reset()
{
m_sourceTree = new Vector();
}
- /** NEEDSDOC Field m_uriResolver */
+ /** The TrAX URI resolver used to obtain source trees. */
URIResolver m_uriResolver;
/**
@@ -131,29 +135,11 @@
return m_uriResolver;
}
- /** NEEDSDOC Field m_entityResolver */
- EntityResolver m_entityResolver;
-
- /*
- * Allow an application to register an entity resolver.
- */
-
- /**
- * NEEDSDOC Method setEntityResolver
- *
- *
- * NEEDSDOC @param resolver
- */
- public void setEntityResolver(EntityResolver resolver)
- {
- m_entityResolver = resolver;
- }
-
/**
* Given a document, find the URL associated with that document.
* @param owner Document that was previously processed by this liaison.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The base URI of the owner argument.
*/
public String findURIFromDoc(Document owner)
{
@@ -186,14 +172,11 @@
* an xsl:include, xsl:import, or document() function.
*
* @param base The base URI that should be used.
- * @param uri Value from an xsl:import or xsl:include's href attribute,
+ * @param urlString Value from an xsl:import or xsl:include's href attribute,
* or a URI specified in the document() function.
- * @returns a InputSource that can be used to process the resource.
- * NEEDSDOC @param urlString
- * NEEDSDOC @param locator
+ *
+ * @return a Source that can be used to process the resource.
*
- * NEEDSDOC ($objectName$) @return
- *
* @throws IOException
* @throws TransformerException
*/
@@ -201,14 +184,15 @@
String base, String urlString, SourceLocator locator)
throws TransformerException, IOException, TransformerException
{
+
Source source = null;
-
- if(null != m_uriResolver)
+
+ if (null != m_uriResolver)
{
source = m_uriResolver.resolve(urlString, base);
}
-
- if(null == source)
+
+ if (null == source)
{
String uri = SystemIDResolver.getAbsoluteURI(urlString, base);
@@ -222,52 +206,45 @@
* Put the source tree root node in the document cache.
* TODO: This function needs to be a LOT more sophisticated.
*
- * NEEDSDOC @param n
- * NEEDSDOC @param source
+ * @param n The node to cache.
+ * @param source The Source object to cache.
*/
public void putDocumentInCache(Node n, Source source)
{
-
- try
- {
- Node cachedNode = getNode(source);
- if (null != cachedNode)
- {
- if (!cachedNode.equals(n))
- throw new RuntimeException(
- "Programmer's Error! "
- + "putDocumentInCache found reparse of doc: "
- + source.getSystemId());
+ Node cachedNode = getNode(source);
- return;
- }
+ if (null != cachedNode)
+ {
+ if (!cachedNode.equals(n))
+ throw new RuntimeException(
+ "Programmer's Error! "
+ + "putDocumentInCache found reparse of doc: "
+ + source.getSystemId());
- if (null != source.getSystemId())
- {
- m_sourceTree.addElement(new SourceTree(n, source.getSystemId()));
- }
+ return;
}
- catch (TransformerException te)
+
+ if (null != source.getSystemId())
{
- throw new org.apache.xml.utils.WrappedRuntimeException(te);
+ m_sourceTree.addElement(new SourceTree(n, source.getSystemId()));
}
}
/**
- * Given a URL, find the node associated with that document.
- * @param url
+ * Given a Source object, find the node associated with it.
*
- * NEEDSDOC @param source
+ * @param source The Source object to act as the key.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The node that is associated with the Source, or null if not found.
*
* @throws TransformerException
*/
- public Node getNode(Source source) throws TransformerException
+ public Node getNode(Source source)
{
- if(source instanceof DOMSource)
- return ((DOMSource)source).getNode();
+
+ if (source instanceof DOMSource)
+ return ((DOMSource) source).getNode();
// TODO: Not sure if the BaseID is really the same thing as the ID.
String url = source.getSystemId();
@@ -301,16 +278,18 @@
/**
* Get the source tree from the a base URL and a URL string.
*
- * NEEDSDOC @param base
- * NEEDSDOC @param urlString
- * NEEDSDOC @param locator
+ * @param base The base URI to use if the urlString is relative.
+ * @param urlString An absolute or relative URL string.
+ * @param locator The location of the caller, for diagnostic purposes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return should be a non-null reference to the node identified by the
+ * base and urlString.
*
- * @throws TransformerException
+ * @throws TransformerException If the URL can not resolve to a node.
*/
- public Node getSourceTree(String base, String urlString, SourceLocator locator)
- throws TransformerException
+ public Node getSourceTree(
+ String base, String urlString, SourceLocator locator)
+ throws TransformerException
{
// System.out.println("getSourceTree");
@@ -325,25 +304,28 @@
{
throw new TransformerException(ioe.getMessage(), locator, ioe);
}
- /* catch (TransformerException te)
- {
- throw new TransformerException(te.getMessage(), locator, te);
- }*/
+
+ /* catch (TransformerException te)
+ {
+ throw new TransformerException(te.getMessage(), locator, te);
+ }*/
}
/**
* Get the source tree from the input source.
*
- * NEEDSDOC @param source
- * NEEDSDOC @param locator
+ * @param source The Source object that should identify the desired node.
+ * @param locator The location of the caller, for diagnostic purposes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return non-null reference to a node.
*
- * @throws TransformerException
+ * @throws TransformerException if the Source argument can't be resolved to
+ * a node.
*/
public Node getSourceTree(Source source, SourceLocator locator)
throws TransformerException
{
+
Node n = getNode(source);
if (null != n)
@@ -360,20 +342,21 @@
/**
* Try to create a DOM source tree from the input source.
*
- * NEEDSDOC @param source
- * NEEDSDOC @param locator
+ * @param source The Source object that identifies the source node.
+ * @param locator The location of the caller, for diagnostic purposes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return non-null reference to node identified by the source argument.
*
- * @throws TransformerException
+ * @throws TransformerException if the source argument can not be resolved
+ * to a source node.
*/
public Node getDOMNode(Source source, SourceLocator locator)
throws TransformerException
{
-
- if(source instanceof DOMSource)
+
+ if (source instanceof DOMSource)
{
- return ((DOMSource)source).getNode();
+ return ((DOMSource) source).getNode();
}
Node doc = null;
@@ -397,33 +380,36 @@
}
reader.setContentHandler(handler);
- if(handler instanceof org.xml.sax.DTDHandler)
- reader.setDTDHandler((org.xml.sax.DTDHandler)handler);
+
+ if (handler instanceof org.xml.sax.DTDHandler)
+ reader.setDTDHandler((org.xml.sax.DTDHandler) handler);
try
{
- if(handler instanceof org.xml.sax.ext.LexicalHandler)
+ if (handler instanceof org.xml.sax.ext.LexicalHandler)
reader.setProperty("http://xml.org/sax/properties/lexical-handler",
handler);
- if(handler instanceof org.xml.sax.ext.DeclHandler)
- reader.setProperty("http://xml.org/sax/properties/declaration-handler",
- handler);
+
+ if (handler instanceof org.xml.sax.ext.DeclHandler)
+ reader.setProperty(
+ "http://xml.org/sax/properties/declaration-handler", handler);
}
catch (org.xml.sax.SAXException se){}
+
try
{
- if(handler instanceof org.xml.sax.ext.LexicalHandler)
+ if (handler instanceof org.xml.sax.ext.LexicalHandler)
reader.setProperty("http://xml.org/sax/handlers/LexicalHandler",
handler);
- if(handler instanceof org.xml.sax.ext.DeclHandler)
+
+ if (handler instanceof org.xml.sax.ext.DeclHandler)
reader.setProperty("http://xml.org/sax/handlers/DeclHandler",
handler);
- }
- catch(org.xml.sax.SAXNotRecognizedException snre)
- {
}
+ catch (org.xml.sax.SAXNotRecognizedException snre){}
InputSource isource = SAXSource.sourceToInputSource(source);
+
reader.parse(isource);
if (handler instanceof org.apache.xalan.stree.SourceTreeHandler)
@@ -451,13 +437,13 @@
* be free for use (i.e.
* not currently in use for another parse().
*
- * @param inputSource The value returned from the EntityResolver.
- * @returns a SAX2 parser to use with the InputSource.
- * NEEDSDOC @param locator
+ * @param inputSource The value returned from the URIResolver.
+ * @returns a SAX2 XMLReader to use to resolve the inputSource argument.
+ * @param locator The location of the original caller, for diagnostic purposes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return non-null XMLReader reference ready to parse.
*
- * @throws TransformerException
+ * @throws TransformerException if the reader can not be created.
*/
public XMLReader getXMLReader(Source inputSource, SourceLocator locator)
throws TransformerException
@@ -466,7 +452,7 @@
try
{
XMLReader reader = (inputSource instanceof SAXSource)
- ? ((SAXSource)inputSource).getXMLReader() : null;
+ ? ((SAXSource) inputSource).getXMLReader() : null;
if (null == reader)
reader = XMLReaderFactory.createXMLReader();
1.15 +1 -1 xml-xalan/java/src/org/apache/xpath/VariableStack.java
Index: VariableStack.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/VariableStack.java,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- VariableStack.java 2000/12/17 06:23:29 1.14
+++ VariableStack.java 2000/12/18 00:04:53 1.15
@@ -345,7 +345,7 @@
*
* @throws TransformerException
*/
- public Object getVariable(XPathContext xctxt, QName name) throws TransformerException
+ public XObject getVariable(XPathContext xctxt, QName name) throws TransformerException
{
int nElems = (-1 == m_searchStart) ? this.size() : m_searchStart;
1.13 +59 -186 xml-xalan/java/src/org/apache/xpath/XPath.java
Index: XPath.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/XPath.java,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- XPath.java 2000/11/23 04:58:55 1.12
+++ XPath.java 2000/12/18 00:04:53 1.13
@@ -90,27 +90,21 @@
import org.apache.xpath.patterns.NodeTest;
/**
- * <meta name="usage" content="general"/>
- * The XPath class represents the semantic parse tree of the XPath pattern.
- * It is the representation of the grammar which filters out
- * the choice for replacement order of the production rules.
- * In order to conserve memory and reduce object creation, the
- * tree is represented as an array of integers:
- * [op code][length][...]
- * where strings are represented within the array as
- * indexes into the token tree.
+ * <meta name="usage" content="advanced"/>
+ * The XPath class wraps an expression object and provides general services
+ * for execution of that expression.
*/
public class XPath implements Serializable
{
- /** NEEDSDOC Field m_mainExp */
+ /** The top of the expression tree. */
private Expression m_mainExp;
/**
- * NEEDSDOC Method getExpression
+ * Get the raw Expression object that this class wraps.
*
*
- * NEEDSDOC (getExpression) @return
+ * @return the raw Expression object, which should not normally be null.
*/
public Expression getExpression()
{
@@ -118,80 +112,76 @@
}
/**
- * NEEDSDOC Method setExpression
+ * Set the raw expression object for this object.
*
*
- * NEEDSDOC @param exp
+ * @param exp the raw Expression object, which should not normally be null.
*/
public void setExpression(Expression exp)
{
m_mainExp = exp;
}
- /** NEEDSDOC Field m_locator */
- private SourceLocator m_locator;
-
/**
- * NEEDSDOC Method getLocator
+ * Get the SourceLocator on the expression object.
*
*
- * NEEDSDOC (getLocator) @return
+ * @return the SourceLocator on the expression object, which may be null.
*/
public SourceLocator getLocator()
{
- return m_locator;
+ return m_mainExp.m_slocator;
}
/**
- * NEEDSDOC Method setLocator
+ * Set the SourceLocator on the expression object.
*
*
- * NEEDSDOC @param l
+ * @param l the SourceLocator on the expression object, which may be null.
*/
public void setLocator(SourceLocator l)
{
- // Note potential hazards -- l may not be serializable, or may be changed
- // after being assigned here.
- m_locator = l;
+ // Note potential hazards -- l may not be serializable, or may be changed
+ // after being assigned here.
+ m_mainExp.setSourceLocator(l);
}
- /** NEEDSDOC Field m_patternString */
+ /** The pattern string, mainly kept around for diagnostic purposes. */
String m_patternString;
/**
- * NEEDSDOC Method getPatternString
+ * Return the XPath string associated with this object.
*
*
- * NEEDSDOC (getPatternString) @return
+ * @return the XPath string associated with this object.
*/
public String getPatternString()
{
return m_patternString;
}
- /** NEEDSDOC Field SELECT */
+ /** Represents a select type expression. */
public static final int SELECT = 0;
- /** NEEDSDOC Field MATCH */
+ /** Represents a match type expression. */
public static final int MATCH = 1;
/**
* Construct an XPath object. The object must be initialized by the
* XPathParser.initXPath method.
*
- * NEEDSDOC @param exprString
- * NEEDSDOC @param locator
- * NEEDSDOC @param prefixResolver
- * NEEDSDOC @param type
+ * @param exprString The XPath expression.
+ * @param locator The location of the expression, may be null.
+ * @param prefixResolver A prefix resolver to use to resolve prefixes to
+ * namespace URIs.
+ * @param type one of {@link #SELECT} or {@link #MATCH}.
*
- * @throws javax.xml.transform.TransformerException
+ * @throws javax.xml.transform.TransformerException if syntax or other error.
*/
public XPath(
String exprString, SourceLocator locator, PrefixResolver prefixResolver, int type)
throws javax.xml.transform.TransformerException
- {
- m_locator = locator;
-
+ {
m_patternString = exprString;
XPathParser parser = new XPathParser();
@@ -210,8 +200,6 @@
// System.out.println("expr: "+expr);
this.setExpression(expr);
- if (MATCH == type)
- calcTargetStrings(compiler);
}
/**
@@ -273,7 +261,7 @@
String msg = e.getMessage();
msg = (msg == null || msg.length()== 0)? "Error in XPath" : msg;
throw new TransformerException(msg,
- (SAXSourceLocator)m_locator, e);
+ (SAXSourceLocator)getLocator(), e);
}
}
finally
@@ -286,19 +274,20 @@
return xobj;
}
- /** NEEDSDOC Field DEBUG_MATCHES */
+ /** Set to true to get diagnostic messages about the result of
+ * match pattern testing. */
private static final boolean DEBUG_MATCHES = false;
/**
* Get the match score of the given node.
*
- * NEEDSDOC @param xctxt
+ * @param xctxt XPath runtime context.
* @param context The current source tree context node.
- * @returns score, one of MATCH_SCORE_NODETEST,
- * MATCH_SCORE_NONE, MATCH_SCORE_OTHER, MATCH_SCORE_QNAME.
+ *
+ * @return score, one of {@link #MATCH_SCORE_NODETEST},
+ * {@link #MATCH_SCORE_NONE}, {@link #MATCH_SCORE_OTHER},
+ * or {@link #MATCH_SCORE_QNAME}.
*
- * NEEDSDOC ($objectName$) @return
- *
* @throws javax.xml.transform.TransformerException
*/
public double getMatchScore(XPathContext xctxt, Node context)
@@ -340,139 +329,19 @@
FunctionTable.installFunction(func, funcIndex);
}
- /** NEEDSDOC Field m_targetStrings */
- private Vector m_targetStrings;
-
/**
- * NEEDSDOC Method calcTargetStrings
- *
- *
- * NEEDSDOC @param compiler
- */
- private void calcTargetStrings(Compiler compiler)
- {
-
- Vector targetStrings = new Vector();
- int opPos = 2;
-
- while (compiler.getOp(opPos) == OpCodes.OP_LOCATIONPATHPATTERN)
- {
- int nextOpPos = compiler.getNextOpPos(opPos);
-
- opPos = compiler.getFirstChildPos(opPos);
-
- while (compiler.getOp(opPos) != OpCodes.ENDOP)
- {
- int nextStepPos = compiler.getNextOpPos(opPos);
- int nextOp = compiler.getOp(nextStepPos);
-
- if ((nextOp == OpCodes.OP_PREDICATE) || (nextOp == OpCodes.ENDOP))
- {
- int stepType = compiler.getOp(opPos);
-
- opPos += 3;
-
- switch (stepType)
- {
- case OpCodes.OP_FUNCTION :
- targetStrings.addElement(PsuedoNames.PSEUDONAME_ANY);
- break;
- case OpCodes.FROM_ROOT :
- targetStrings.addElement(PsuedoNames.PSEUDONAME_ROOT);
- break;
- case OpCodes.MATCH_ATTRIBUTE :
- case OpCodes.MATCH_ANY_ANCESTOR :
- case OpCodes.MATCH_IMMEDIATE_ANCESTOR :
- int tok = compiler.getOp(opPos);
-
- opPos++;
-
- switch (tok)
- {
- case OpCodes.NODETYPE_COMMENT :
- targetStrings.addElement(PsuedoNames.PSEUDONAME_COMMENT);
- break;
- case OpCodes.NODETYPE_TEXT :
- targetStrings.addElement(PsuedoNames.PSEUDONAME_TEXT);
- break;
- case OpCodes.NODETYPE_NODE :
- targetStrings.addElement(PsuedoNames.PSEUDONAME_ANY);
- break;
- case OpCodes.NODETYPE_ROOT :
- targetStrings.addElement(PsuedoNames.PSEUDONAME_ROOT);
- break;
- case OpCodes.NODETYPE_ANYELEMENT :
- targetStrings.addElement(PsuedoNames.PSEUDONAME_ANY);
- break;
- case OpCodes.NODETYPE_PI :
- targetStrings.addElement(PsuedoNames.PSEUDONAME_ANY);
- break;
- case OpCodes.NODENAME :
-
- // Skip the namespace
- int tokenIndex = compiler.getOp(opPos + 1);
-
- if (tokenIndex >= 0)
- {
- String targetName =
- (String) compiler.m_tokenQueue[tokenIndex];
-
- if (targetName.equals("*"))
- {
- targetStrings.addElement(PsuedoNames.PSEUDONAME_ANY);
- }
- else
- {
- targetStrings.addElement(targetName);
- }
- }
- else
- {
- targetStrings.addElement(PsuedoNames.PSEUDONAME_ANY);
- }
- break;
- default :
- targetStrings.addElement(PsuedoNames.PSEUDONAME_ANY);
- break;
- }
- break;
- }
- }
-
- opPos = nextStepPos;
- }
-
- opPos = nextOpPos;
- }
-
- m_targetStrings = targetStrings;
-
- // for(int i = 0; i < m_targetStrings.size(); i++)
- // System.out.println("targetStrings["+i+"]="+m_targetStrings.elementAt(i));
- }
-
- /**
- * <meta name="usage" content="advanced"/>
- * This method is for building indexes of match patterns for fast lookup.
- * This allows a caller to get the name or type of a node, and quickly
- * find the likely candidates that may match.
- *
- * NEEDSDOC ($objectName$) @return
- */
- public Vector getTargetElementStrings()
- {
- return m_targetStrings;
- }
-
- /**
* Warn the user of an problem.
*
- * NEEDSDOC @param xctxt
- * NEEDSDOC @param sourceNode
- * NEEDSDOC @param msg
- * NEEDSDOC @param args
+ * @param xctxt The XPath runtime context.
+ * @param sourceNode Not used.
+ * @param msg An error number that corresponds to one of the numbers found
+ * in {@link org.apache.xpath.res.XPATHErrorResources}, which is
+ * a key for a format string.
+ * @param args An array of arguments represented in the format string, which
+ * may be null.
*
- * @throws javax.xml.transform.TransformerException
+ * @throws TransformerException if the current ErrorListoner determines to
+ * throw an exception.
*/
public void warn(
XPathContext xctxt, Node sourceNode, int msg, Object[] args)
@@ -493,13 +362,13 @@
/**
* Tell the user of an assertion error, and probably throw an
* exception.
- *
- * NEEDSDOC @param b
- * NEEDSDOC @param msg
*
- * @throws javax.xml.transform.TransformerException
+ * @param b If false, a runtime exception will be thrown.
+ * @param msg The assertion message, which should be informative.
+ *
+ * @throws RuntimeException if the b argument is false.
*/
- public void assert(boolean b, String msg) throws javax.xml.transform.TransformerException
+ public void assert(boolean b, String msg)
{
if (!b)
@@ -516,12 +385,16 @@
* Tell the user of an error, and probably throw an
* exception.
*
- * NEEDSDOC @param xctxt
- * NEEDSDOC @param sourceNode
- * NEEDSDOC @param msg
- * NEEDSDOC @param args
+ * @param xctxt The XPath runtime context.
+ * @param sourceNode Not used.
+ * @param msg An error number that corresponds to one of the numbers found
+ * in {@link org.apache.xpath.res.XPATHErrorResources}, which is
+ * a key for a format string.
+ * @param args An array of arguments represented in the format string, which
+ * may be null.
*
- * @throws javax.xml.transform.TransformerException
+ * @throws TransformerException if the current ErrorListoner determines to
+ * throw an exception.
*/
public void error(
XPathContext xctxt, Node sourceNode, int msg, Object[] args)
1.7 +2 -1 xml-xalan/java/src/org/apache/xpath/XPathAPI.java
Index: XPathAPI.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/XPathAPI.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- XPathAPI.java 2000/11/23 04:58:55 1.6
+++ XPathAPI.java 2000/12/18 00:04:53 1.7
@@ -278,7 +278,8 @@
* @param contextNode The node to start searching from.
* @param str A valid XPath string.
* @param namespaceNode The node from which prefixes in the XPath will be resolved to namespaces.
- * NEEDSDOC @param prefixResolver
+ * @param prefixResolver Will be called if the parser encounters namespace
+ * prefixes, to resolve the prefixes to URLs.
* @return An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.
* @see org.apache.xpath.objects.XObject
* @see org.apache.xpath.objects.XNull
1.16 +61 -95 xml-xalan/java/src/org/apache/xpath/XPathContext.java
Index: XPathContext.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/XPathContext.java,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- XPathContext.java 2000/11/28 00:44:35 1.15
+++ XPathContext.java 2000/12/18 00:04:53 1.16
@@ -130,27 +130,18 @@
}
/**
- * Copy attributes from another liaison.
- *
- * NEEDSDOC @param from
- *
- * @throws TransformerException
- */
- public void copyFromOtherLiaison(XPathContext from) throws TransformerException{}
-
- /**
* Reset for new run.
*/
public void reset(){}
- /** NEEDSDOC Field m_saxLocation */
+ /** The current stylesheet locator. */
SourceLocator m_saxLocation;
/**
- * NEEDSDOC Method setSAXLocator
+ * Set the current locater in the stylesheet.
*
*
- * NEEDSDOC @param location
+ * @param location The location within the stylesheet.
*/
public void setSAXLocator(SourceLocator location)
{
@@ -158,10 +149,10 @@
}
/**
- * NEEDSDOC Method getSAXLocator
+ * Get the current locater in the stylesheet.
*
*
- * NEEDSDOC (getSAXLocator) @return
+ * @return The location within the stylesheet, or null if not known.
*/
public SourceLocator getSAXLocator()
{
@@ -199,7 +190,7 @@
/**
* Get the extensions table object.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The extensions table.
*/
public ExtensionsTable getExtensionsTable()
{
@@ -207,10 +198,10 @@
}
/**
- * NEEDSDOC Method setExtensionsTable
+ * Set the extensions table object.
*
*
- * NEEDSDOC @param table
+ * @param table The extensions table object.
*/
void setExtensionsTable(ExtensionsTable table)
{
@@ -229,7 +220,7 @@
* Get the variable stack, which is in charge of variables and
* parameters.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the variable stack, which should not be null.
*/
public VariableStack getVarStack()
{
@@ -240,7 +231,7 @@
* Get the variable stack, which is in charge of variables and
* parameters.
*
- * NEEDSDOC @param varStack
+ * @param varStack non-null reference to the variable stack.
*/
public void setVarStack(VariableStack varStack)
{
@@ -251,34 +242,31 @@
* Given a name, locate a variable in the current context, and return
* the Object.
*
- * NEEDSDOC @param qname
+ * @param qname The qualified name of a variable.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to variable, or null if not found.
*
* @throws javax.xml.transform.TransformerException
*/
public XObject getVariable(QName qname) throws javax.xml.transform.TransformerException
{
-
- Object obj = getVarStack().getVariable(this, qname);
-
- if ((null != obj) &&!(obj instanceof XObject))
- {
- obj = new XObject(obj);
- }
- return (XObject) obj;
+ return getVarStack().getVariable(this, qname);
}
// ================ DOMHelper ===================
- /** NEEDSDOC Field m_domHelper */
+ /** The basic DOM helper for the root source tree.
+ * Note that I have some worry about different source tree types
+ * being mixed, so this may not be a perfect place for this.
+ * Right now, I think all the DOM helpers can handle a DOM that
+ * they don't know about. */
private DOMHelper m_domHelper;
/**
* Get the DOMHelper associated with this execution context.
*
- * NEEDSDOC ($objectName$) @return
+ * @return non-null reference to a DOM helper.
*/
public final DOMHelper getDOMHelper()
{
@@ -292,7 +280,8 @@
/**
* Set the DOMHelper associated with this execution context.
*
- * NEEDSDOC @param helper
+ * @param helper reference to a dom helper to be associated with this
+ * execution context.
*/
public void setDOMHelper(DOMHelper helper)
{
@@ -301,13 +290,14 @@
// ================ SourceTreeManager ===================
- /** NEEDSDOC Field m_sourceTreeManager */
+ /** The source tree manager, which associates Source objects to source
+ * tree nodes. */
private SourceTreeManager m_sourceTreeManager = new SourceTreeManager();
/**
- * Get the DOMHelper associated with this execution context.
+ * Get the SourceTreeManager associated with this execution context.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the SourceTreeManager associated with this execution context.
*/
public final SourceTreeManager getSourceTreeManager()
{
@@ -315,9 +305,10 @@
}
/**
- * Set the DOMHelper associated with this execution context.
+ * Set the SourceTreeManager associated with this execution context.
*
- * NEEDSDOC @param mgr
+ * @param mgr the SourceTreeManager to be associated with this
+ * execution context.
*/
public void setSourceTreeManager(SourceTreeManager mgr)
{
@@ -378,13 +369,14 @@
// =================================================
- /** NEEDSDOC Field m_uriResolver */
+ /** The TrAX URI Resolver for resolving URIs from the document(...)
+ * function to source tree nodes. */
private URIResolver m_uriResolver;
/**
* Get the URIResolver associated with this execution context.
*
- * NEEDSDOC ($objectName$) @return
+ * @return a URI resolver, which may be null.
*/
public final URIResolver getURIResolver()
{
@@ -394,7 +386,8 @@
/**
* Set the URIResolver associated with this execution context.
*
- * NEEDSDOC @param resolver
+ * @param resolver the URIResolver to be associated with this
+ * execution context, may be null to clear an already set resolver.
*/
public void setURIResolver(URIResolver resolver)
{
@@ -403,13 +396,13 @@
// =================================================
- /** NEEDSDOC Field m_primaryReader */
+ /** The reader of the primary source tree. */
public XMLReader m_primaryReader;
/**
* Get primary XMLReader associated with this execution context.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The reader of the primary source tree.
*/
public final XMLReader getPrimaryReader()
{
@@ -419,7 +412,7 @@
/**
* Set primary XMLReader associated with this execution context.
*
- * NEEDSDOC @param reader
+ * @param reader The reader of the primary source tree.
*/
public void setPrimaryReader(XMLReader reader)
{
@@ -428,48 +421,18 @@
// =================================================
- /**
- * Take a user string (system ID) return the url.
- *
- * NEEDSDOC @param urlString
- * NEEDSDOC @param base
- *
- * NEEDSDOC ($objectName$) @return
- * @exception XSLProcessorException thrown if the active ProblemListener and XPathContext decide
- * the error condition is severe enough to halt processing.
- *
- * @throws TransformerException
- */
- public final String getAbsoluteURI(String urlString, String base)
- throws TransformerException
- {
- try
- {
- Source source = getSourceTreeManager().resolveURI(base, urlString,
- getSAXLocator());
- return source.getSystemId();
- }
- catch (TransformerException te)
- {
- throw new TransformerException(te);
- }
- catch (IOException ioe)
- {
- throw new TransformerException(ioe);
- }
- }
- /** NEEDSDOC Field m_XSLMessages */
+ /** Misnamed string manager for XPath messages. */
private static XSLMessages m_XSLMessages = new XSLMessages();
/**
* Tell the user of an assertion error, and probably throw an
* exception.
*
- * NEEDSDOC @param b
- * NEEDSDOC @param msg
- *
- * @throws javax.xml.transform.TransformerException
+ * @param b If false, a TransformerException will be thrown.
+ * @param msg The assertion message, which should be informative.
+ *
+ * @throws javax.xml.transform.TransformerException if b is false.
*/
private void assert(boolean b, String msg) throws javax.xml.transform.TransformerException
{
@@ -498,7 +461,8 @@
/**
* Get the current context node list.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the <a href="http://www.w3.org/TR/xslt#dt-current-node-list">current node list</a>,
+ * also refered to here as a <term>context node list</term>.
*/
public final ContextNodeList getContextNodeList()
{
@@ -512,10 +476,9 @@
/**
* <meta name="usage" content="internal"/>
* Set the current context node list.
- * @param A nodelist that represents the current context
- * list as defined by XPath.
*
- * NEEDSDOC @param nl
+ * @param nl the <a href="http://www.w3.org/TR/xslt#dt-current-node-list">current node list</a>,
+ * also refered to here as a <term>context node list</term>.
*/
public final void pushContextNodeList(ContextNodeList nl)
{
@@ -538,13 +501,14 @@
*/
PrefixResolver m_currentPrefixResolver = null;
- /** NEEDSDOC Field m_currentNodes */
+ /** The stack of <a href="http://www.w3.org/TR/xslt#dt-current-node">current node</a> objects.
+ * Not to be confused with the current node list. */
private NodeVector m_currentNodes = new NodeVector();
/**
* Get the current context node.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the <a href="http://www.w3.org/TR/xslt#dt-current-node">current node</a>.
*/
public final Node getCurrentNode()
{
@@ -552,10 +516,10 @@
}
/**
- * Set the current context node.
+ * Set the current context node and expression node.
*
- * NEEDSDOC @param cn
- * NEEDSDOC @param en
+ * @param cn the <a href="http://www.w3.org/TR/xslt#dt-current-node">current node</a>.
+ * @param en the sub-expression context node.
*/
public final void pushCurrentNodeAndExpression(Node cn, Node en)
{
@@ -575,7 +539,7 @@
/**
* Set the current context node.
*
- * NEEDSDOC @param n
+ * @param n the <a href="http://www.w3.org/TR/xslt#dt-current-node">current node</a>.
*/
public final void pushCurrentNode(Node n)
{
@@ -590,13 +554,13 @@
m_currentNodes.popQuick();
}
- /** NEEDSDOC Field m_currentExpressionNodes */
+ /** A stack of the current sub-expression nodes. */
private NodeVector m_currentExpressionNodes = new NodeVector();
/**
* Get the current node that is the expression's context (i.e. for current() support).
*
- * NEEDSDOC ($objectName$) @return
+ * @return The current sub-expression node.
*/
public final Node getCurrentExpressionNode()
{
@@ -606,7 +570,7 @@
/**
* Set the current node that is the expression's context (i.e. for current() support).
*
- * NEEDSDOC @param n
+ * @param n The sub-expression node to be current.
*/
public final void pushCurrentExpressionNode(Node n)
{
@@ -624,7 +588,8 @@
/**
* Get the current namespace context for the xpath.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the current prefix resolver for resolving prefixes to
+ * namespace URLs.
*/
public final PrefixResolver getNamespaceContext()
{
@@ -634,7 +599,8 @@
/**
* Get the current namespace context for the xpath.
*
- * NEEDSDOC @param pr
+ * @param pr the prefix resolver to be used for resolving prefixes to
+ * namespace URLs.
*/
public final void setNamespaceContext(PrefixResolver pr)
{
@@ -654,7 +620,7 @@
* <meta name="usage" content="internal"/>
* Push a TreeWalker on the stack.
*
- * NEEDSDOC @param iter
+ * @param iter A sub-context AxesWalker.
*/
public final void pushSubContextList(SubContextList iter)
{
@@ -674,7 +640,7 @@
* <meta name="usage" content="internal"/>
* Get the current axes iterator, or return null if none.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the sub-context node list.
*/
public SubContextList getSubContextList()
{
1.5 +3 -4 xml-xalan/java/src/org/apache/xpath/XPathException.java
Index: XPathException.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/XPathException.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- XPathException.java 2000/12/13 04:16:35 1.4
+++ XPathException.java 2000/12/18 00:04:53 1.5
@@ -72,7 +72,7 @@
public class XPathException extends TransformerException
{
- /** NEEDSDOC Field m_styleNode */
+ /** The home of the expression that caused the error. */
Object m_styleNode = null;
/**
@@ -84,7 +84,7 @@
return m_styleNode;
}
- /** NEEDSDOC Field m_exception */
+ /** A nested exception. */
protected Exception m_exception;
/**
@@ -189,9 +189,8 @@
/**
* Find the most contained message.
- * @returns The error message of the originating exception.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The error message of the originating exception.
*/
public String getMessage()
{
1.5 +8 -5 xml-xalan/java/src/org/apache/xpath/XPathFactory.java
Index: XPathFactory.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/XPathFactory.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- XPathFactory.java 2000/11/23 04:58:56 1.4
+++ XPathFactory.java 2000/12/18 00:04:53 1.5
@@ -73,12 +73,15 @@
/**
* Create an XPath.
*
- * NEEDSDOC @param exprString
- * NEEDSDOC @param locator
- * NEEDSDOC @param prefixResolver
- * NEEDSDOC @param type
+ * @param exprString The XPath expression string.
+ * @param locator The location of the expression string, mainly for diagnostic
+ * purposes.
+ * @param prefixResolver This will be called in order to resolve prefixes
+ * to namespace URIs.
+ * @param type One of {@link org.apache.xpath.XPath#SELECT} or
+ * {@link org.apache.xpath.XPath#MATCH}.
*
- * NEEDSDOC ($objectName$) @return
+ * @return an XPath ready for execution.
*/
XPath create(String exprString, SourceLocator locator,
PrefixResolver prefixResolver, int type);