sboag 00/12/16 21:20:11
Modified: java/src/org/apache/xpath/compiler Compiler.java
FuncLoader.java FunctionTable.java Keywords.java
Lexer.java OpCodes.java OpMap.java PsuedoNames.java
XPathParser.java
Log:
Javadoc.
Revision Changes Path
1.17 +206 -226
xml-xalan/java/src/org/apache/xpath/compiler/Compiler.java
Index: Compiler.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/compiler/Compiler.java,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- Compiler.java 2000/12/16 20:01:52 1.16
+++ Compiler.java 2000/12/17 05:20:08 1.17
@@ -96,18 +96,23 @@
import org.w3c.dom.traversal.NodeFilter;
/**
- * <meta name="usage" content="internal"/>
- * NEEDSDOC Class Compiler <needs-comment/>
+ * <meta name="usage" content="advanced"/>
+ * An instance of this class compiles an XPath string expression into
+ * a Expression object. This class compiles the string into a sequence
+ * of operation codes (op map) and then builds from that into an Expression
+ * tree.
*/
public class Compiler extends OpMap
{
/**
- * Constructor Compiler
+ * Construct a Compiler object with a specific ErrorListener and
+ * SourceLocator where the expression is located.
*
- *
- * NEEDSDOC @param errorHandler
- * NEEDSDOC @param locator
+ * @param errorHandler Error listener where messages will be sent, or null
+ * if messages should be sent to System err.
+ * @param locator The location object where the expression lives, which
+ * may be null.
*/
public Compiler(ErrorListener errorHandler, SourceLocator locator)
{
@@ -124,8 +129,8 @@
}
/**
- * Constructor Compiler
- *
+ * Construct a Compiler instance that has a null error listener and a
+ * null source locator.
*/
public Compiler()
{
@@ -143,7 +148,7 @@
* @param callbackInfo Object that will be passed to the
processLocatedNode method.
* @return The result of the XPath.
*
- * @throws TransformerException
+ * @throws TransformerException if there is a syntax or other error.
*/
public Expression compile(int opPos) throws TransformerException
{
@@ -182,8 +187,8 @@
expr = div(opPos); break;
case OpCodes.OP_MOD :
expr = mod(opPos); break;
- case OpCodes.OP_QUO :
- expr = quo(opPos); break;
+// case OpCodes.OP_QUO :
+// expr = quo(opPos); break;
case OpCodes.OP_NEG :
expr = neg(opPos); break;
case OpCodes.OP_STRING :
@@ -227,14 +232,14 @@
}
/**
- * Bottle-neck compilation of an operation.
+ * Bottle-neck compilation of an operation with left and right operands.
*
- * NEEDSDOC @param operation
- * NEEDSDOC @param opPos
+ * @param operation non-null reference to parent operation.
+ * @param opPos The op map position of the parent operation.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.Operation} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if there is a syntax or other error.
*/
private Expression compileOperation(Operation operation, int opPos)
throws TransformerException
@@ -249,14 +254,14 @@
}
/**
- * Bottle-neck compilation of an operation.
+ * Bottle-neck compilation of a unary operation.
*
- * NEEDSDOC @param unary
- * NEEDSDOC @param opPos
+ * @param unary The parent unary operation.
+ * @param opPos The position in the op map of the parent operation.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The unary argument.
*
- * @throws TransformerException
+ * @throws TransformerException if syntax or other error occurs.
*/
private Expression compileUnary(UnaryOperation unary, int opPos)
throws TransformerException
@@ -270,14 +275,13 @@
}
/**
- * OR two expressions and return the boolean result.
- * @param context The current source tree context node.
+ * Compile an 'or' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns XBoolean set to true if the one of the two arguments are true.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.Or}
instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression or(int opPos) throws TransformerException
{
@@ -285,14 +289,13 @@
}
/**
- * AND two expressions and return the boolean result.
- * @param context The current source tree context node.
+ * Compile an 'and' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns XBoolean set to true if the two arguments are both true.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.And}
instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression and(int opPos) throws TransformerException
{
@@ -300,14 +303,13 @@
}
/**
- * Tell if two expressions are functionally not equal.
- * @param context The current source tree context node.
+ * Compile a '!=' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns XBoolean set to true if the two arguments are not equal.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.NotEquals} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression notequals(int opPos) throws TransformerException
{
@@ -315,14 +317,13 @@
}
/**
- * Tell if two expressions are functionally equal.
- * @param context The current source tree context node.
+ * Compile a '=' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns XBoolean set to true if the two arguments are equal.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.Equals} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression equals(int opPos) throws TransformerException
{
@@ -330,14 +331,13 @@
}
/**
- * Tell if one argument is less than or equal to the other argument.
- * @param context The current source tree context node.
+ * Compile a '<=' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns XBoolean set to true if arg 1 is less than or equal to arg 2.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.Lte}
instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression lte(int opPos) throws TransformerException
{
@@ -345,14 +345,13 @@
}
/**
- * Tell if one argument is less than the other argument.
- * @param context The current source tree context node.
+ * Compile a '<' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns XBoolean set to true if arg 1 is less than arg 2.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.Lt}
instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression lt(int opPos) throws TransformerException
{
@@ -360,14 +359,13 @@
}
/**
- * Tell if one argument is greater than or equal to the other argument.
- * @param context The current source tree context node.
+ * Compile a '>=' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns XBoolean set to true if arg 1 is greater than or equal to arg
2.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.Gte}
instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression gte(int opPos) throws TransformerException
{
@@ -375,14 +373,13 @@
}
/**
- * Tell if one argument is greater than the other argument.
- * @param context The current source tree context node.
+ * Compile a '>' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns XBoolean set to true if arg 1 is greater than arg 2.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.Gt}
instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression gt(int opPos) throws TransformerException
{
@@ -390,14 +387,13 @@
}
/**
- * Give the sum of two arguments.
- * @param context The current source tree context node.
+ * Compile a '+' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns sum of arg1 and arg2.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.Plus} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression plus(int opPos) throws TransformerException
{
@@ -405,14 +401,13 @@
}
/**
- * Give the difference of two arguments.
- * @param context The current source tree context node.
+ * Compile a '-' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns difference of arg1 and arg2.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.Minus} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression minus(int opPos) throws TransformerException
{
@@ -420,14 +415,13 @@
}
/**
- * Multiply two arguments.
- * @param context The current source tree context node.
+ * Compile a '*' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns arg1 * arg2.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.Mult} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression mult(int opPos) throws TransformerException
{
@@ -435,14 +429,13 @@
}
/**
- * Divide a number.
- * @param context The current source tree context node.
+ * Compile a 'div' operation.
+ *
* @param opPos The current position in the m_opMap array.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.Div}
instance.
*
- * @throws TransformerException
- * @returns arg1 / arg2.
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression div(int opPos) throws TransformerException
{
@@ -450,45 +443,41 @@
}
/**
- * Return the remainder from a truncating division.
- * @param context The current source tree context node.
+ * Compile a 'mod' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns arg1 mod arg2.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.Mod}
instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression mod(int opPos) throws TransformerException
{
return compileOperation(new Mod(), opPos);
}
- /**
- * Return the remainder from a truncating division.
- * (Quo is no longer supported by xpath).
- * @param context The current source tree context node.
+ /*
+ * Compile a 'quo' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns arg1 mod arg2.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.Quo}
instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
- protected Expression quo(int opPos) throws TransformerException
- {
- return compileOperation(new Quo(), opPos);
- }
+// protected Expression quo(int opPos) throws TransformerException
+// {
+// return compileOperation(new Quo(), opPos);
+// }
/**
- * Return the negation of a number.
- * @param context The current source tree context node.
+ * Compile a unary '-' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns -arg.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED] org.apache.xpath.operations.Neg}
instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression neg(int opPos) throws TransformerException
{
@@ -496,14 +485,13 @@
}
/**
- * Cast an expression to a string.
- * @param context The current source tree context node.
+ * Compile a 'string(...)' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns arg cast to a string.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.String} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression string(int opPos) throws TransformerException
{
@@ -511,14 +499,13 @@
}
/**
- * Cast an expression to a boolean.
- * @param context The current source tree context node.
+ * Compile a 'boolean(...)' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns arg cast to a boolean.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.Bool} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression bool(int opPos) throws TransformerException
{
@@ -526,14 +513,13 @@
}
/**
- * Cast an expression to a number.
- * @param context The current source tree context node.
+ * Compile a 'number(...)' operation.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns arg cast to a number.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.Number} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression number(int opPos) throws TransformerException
{
@@ -541,12 +527,13 @@
}
/**
- * Get a literal value.
- * @param context The current source tree context node.
+ * Compile a literal string value.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns an XString object.
+ *
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.objects.XString} instance.
*
- * NEEDSDOC ($objectName$) @return
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression literal(int opPos)
{
@@ -557,12 +544,13 @@
}
/**
- * Get a literal value.
- * @param context The current source tree context node.
+ * Compile a literal number value.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns an XString object.
+ *
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.objects.XNumber} instance.
*
- * NEEDSDOC ($objectName$) @return
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression numberlit(int opPos)
{
@@ -573,14 +561,13 @@
}
/**
- * Get a literal value.
- * @param context The current source tree context node.
+ * Compile a variable reference.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns an XObject object.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.operations.Variable} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression variable(int opPos) throws TransformerException
{
@@ -603,14 +590,13 @@
}
/**
- * Execute an expression as a group.
- * @param context The current source tree context node.
+ * Compile an expression group.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns arg.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to the contained expression.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression group(int opPos) throws TransformerException
{
@@ -620,14 +606,13 @@
}
/**
- * Execute a function argument.
- * @param context The current source tree context node.
+ * Compile a function argument.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns the result of the argument expression.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to the argument expression.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression arg(int opPos) throws TransformerException
{
@@ -637,16 +622,14 @@
}
/**
- * Computes the union of its operands which must be node-sets.
- * @param context The current source tree context node.
+ * Compile a location path union. The UnionPathIterator itself may create
+ * [EMAIL PROTECTED] org.apache.xpath.axes.LocPathIterator} children.
+ *
* @param opPos The current position in the m_opMap array.
- * @param callback Interface that implements the processLocatedNode method.
- * @param callbackInfo Object that will be passed to the
processLocatedNode method.
- * @returns the union of node-set operands.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.axes.UnionPathIterator} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression union(int opPos) throws TransformerException
{
@@ -656,17 +639,14 @@
private int locPathDepth = -1;
/**
- * <meta name="usage" content="advanced"/>
- * Execute a location path.
- * @param context The current source tree context node.
+ * Compile a location path. The LocPathIterator itself may create
+ * [EMAIL PROTECTED] org.apache.xpath.axes.AxesWalker} children.
+ *
* @param opPos The current position in the m_opMap array.
- * @param callback Interface that implements the processLocatedNode method.
- * @param callbackInfo Object that will be passed to the
processLocatedNode method.
- * @returns a node-set.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.axes.LocPathIterator} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
public Expression locationPath(int opPos) throws TransformerException
{
@@ -679,15 +659,13 @@
}
/**
- * <meta name="usage" content="advanced"/>
- * Evaluate a predicate.
- * @param context The current source tree context node.
+ * Compile a location step predicate expression.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns either a boolean or a number.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the contained predicate expression.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
public Expression predicate(int opPos) throws TransformerException
{
@@ -695,14 +673,13 @@
}
/**
- * Computes the union of its operands which must be node-sets.
- * @param context The current source tree context node.
+ * Compile an entire match pattern expression.
+ *
* @param opPos The current position in the m_opMap array.
- * @returns the match score in the form of an XObject.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.patterns.UnionPattern} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected Expression matchPattern(int opPos) throws TransformerException
{
@@ -735,18 +712,13 @@
}
/**
- * Execute a a location path pattern. This will return a score
- * of MATCH_SCORE_NONE, MATCH_SCORE_NODETEST,
- * MATCH_SCORE_OTHER, MATCH_SCORE_QNAME.
- * @param xpath The xpath that is executing.
- * @param context The current source tree context node.
- * @param opPos The current position in the xpath.m_opMap array.
- * @returns score, one of MATCH_SCORE_NODETEST,
- * MATCH_SCORE_NONE, MATCH_SCORE_OTHER, MATCH_SCORE_QNAME.
+ * Compile a location match pattern unit expression.
+ *
+ * @param opPos The current position in the m_opMap array.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.patterns.StepPattern} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
public Expression locationPathPattern(int opPos)
throws TransformerException
@@ -758,12 +730,13 @@
}
/**
- * NEEDSDOC Method getWhatToShow
+ * Get a [EMAIL PROTECTED] org.w3c.dom.traversal.NodeFilter} bit set that
tells what
+ * to show for a given node test.
*
+ * @param opPos the op map position for the location step.
*
- * NEEDSDOC @param opPos
- *
- * NEEDSDOC (getWhatToShow) @return
+ * @return [EMAIL PROTECTED] org.w3c.dom.traversal.NodeFilter} bit set
that tells what
+ * to show for a given node test.
*/
public int getWhatToShow(int opPos)
{
@@ -831,17 +804,16 @@
}
/**
- * Execute a step in a location path.
- * @param xpath The xpath that is executing.
- * @param context The current source tree context node.
- * @param opPos The current position in the xpath.m_opMap array.
- * @returns the last matched context node.
- * NEEDSDOC @param stepCount
- * NEEDSDOC @param ancestorPattern
+ * Compile a step pattern unit expression, used for both location paths
+ * and match patterns.
+ *
+ * @param opPos The current position in the m_opMap array.
+ * @param stepCount The number of steps to expect.
+ * @param ancestorPattern The owning StepPattern, which may be null.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.patterns.StepPattern} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
protected StepPattern stepPattern(
int opPos, int stepCount, StepPattern ancestorPattern)
@@ -910,14 +882,13 @@
}
/**
- * NEEDSDOC Method getCompiledPredicates
- *
+ * Compile a zero or more predicates for a given match pattern.
+ *
+ * @param opPos The position of the first predicate the m_opMap array.
*
- * NEEDSDOC @param opPos
+ * @return reference to array of [EMAIL PROTECTED]
org.apache.xpath.Expression} instances.
*
- * NEEDSDOC (getCompiledPredicates) @return
- *
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
public Expression[] getCompiledPredicates(int opPos)
throws TransformerException
@@ -940,11 +911,11 @@
/**
* Count the number of predicates in the step.
*
- * NEEDSDOC @param opPos
+ * @param opPos The position of the first predicate the m_opMap array.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The number of predicates for this step.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
public int countPredicates(int opPos) throws TransformerException
{
@@ -962,10 +933,11 @@
}
/**
- * Allocate predicates in the step.
+ * Compiles predicates in the step.
*
- * NEEDSDOC @param opPos
- * NEEDSDOC @param predicates
+ * @param opPos The position of the first predicate the m_opMap array.
+ * @param predicates An empty pre-determined array of
+ * [EMAIL PROTECTED] org.apache.xpath.Expression}s, that will
be filled in.
*
* @throws TransformerException
*/
@@ -981,13 +953,13 @@
}
/**
- * Execute a function from an op code.
- *
- * NEEDSDOC @param opPos
+ * Compile a built-in XPath function.
+ *
+ * @param opPos The current position in the m_opMap array.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.functions.Function} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
Expression compileFunction(int opPos) throws TransformerException
{
@@ -1037,13 +1009,13 @@
}
/**
- * Execute an extension function from an op code.
- *
- * NEEDSDOC @param opPos
+ * Compile an extension function.
+ *
+ * @param opPos The current position in the m_opMap array.
*
- * NEEDSDOC ($objectName$) @return
+ * @return reference to [EMAIL PROTECTED]
org.apache.xpath.functions.FuncExtFunction} instance.
*
- * @throws TransformerException
+ * @throws TransformerException if a error occurs creating the Expression.
*/
private Expression compileExtension(int opPos)
throws TransformerException
@@ -1093,10 +1065,14 @@
/**
* Warn the user of an problem.
*
- * NEEDSDOC @param msg
- * NEEDSDOC @param args
+ * @param msg An error number that corresponds to one of the numbers found
+ * in [EMAIL PROTECTED]
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 TransformerException
+ * @throws TransformerException if the current ErrorListoner determines to
+ * throw an exception.
*/
public void warn(int msg, Object[] args) throws TransformerException
{
@@ -1119,14 +1095,13 @@
/**
* Tell the user of an assertion error, and probably throw an
* exception.
- *
- * NEEDSDOC @param b
- * NEEDSDOC @param msg
*
- * @throws 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 TransformerException
{
if (!b)
@@ -1143,10 +1118,14 @@
* Tell the user of an error, and probably throw an
* exception.
*
- * NEEDSDOC @param msg
- * NEEDSDOC @param args
+ * @param msg An error number that corresponds to one of the numbers found
+ * in [EMAIL PROTECTED]
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 TransformerException
+ * @throws TransformerException if the current ErrorListoner determines to
+ * throw an exception.
*/
public void error(int msg, Object[] args) throws TransformerException
{
@@ -1176,7 +1155,7 @@
/**
* Get the current namespace context for the xpath.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The current prefix resolver, *may* be null, though hopefully
not.
*/
public PrefixResolver getNamespaceContext()
{
@@ -1186,16 +1165,17 @@
/**
* Set the current namespace context for the xpath.
*
- * NEEDSDOC @param pr
+ * @param pr The resolver for prefixes in the XPath expression.
*/
public void setNamespaceContext(PrefixResolver pr)
{
m_currentPrefixResolver = pr;
}
- /** NEEDSDOC Field m_errorHandler */
+ /** The error listener where errors will be sent. If this is null, errors
+ * and warnings will be sent to System.err. May be null. */
ErrorListener m_errorHandler;
- /** NEEDSDOC Field m_locator */
+ /** The source locator for the expression being compiled. May be null. */
SourceLocator m_locator;
}
1.4 +22 -15
xml-xalan/java/src/org/apache/xpath/compiler/FuncLoader.java
Index: FuncLoader.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/compiler/FuncLoader.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- FuncLoader.java 2000/11/13 16:27:31 1.3
+++ FuncLoader.java 2000/12/17 05:20:08 1.4
@@ -71,22 +71,26 @@
/**
* <meta name="usage" content="advanced"/>
- * Load functions in function table as needed
+ * Lazy load of functions into the function table as needed, so we don't
+ * have to load all the functions allowed in XPath and XSLT on startup.
*/
public class FuncLoader
{
- /** NEEDSDOC Field m_funcID */
+ /** The function ID, which may correspond to one of the FUNC_XXX values
+ * found in [EMAIL PROTECTED] org.apache.xpath.compiler.FunctionTable},
but may
+ * be a value installed by an external module. */
private int m_funcID;
- /** NEEDSDOC Field m_funcName, test */
- private String m_funcName, test;
+ /** The class name of the function. Must not be null. */
+ private String m_funcName;
/**
- * NEEDSDOC Method getName
+ * Get the local class name of the function class. If function name does
+ * not have a '.' in it, it is assumed to be relative to
+ * 'org.apache.xpath.functions'.
*
- *
- * NEEDSDOC (getName) @return
+ * @return The class name of the {org.apache.xpath.functions.Function}
class.
*/
public String getName()
{
@@ -94,11 +98,14 @@
}
/**
- * Constructor FuncLoader
- *
+ * Construct a function loader
*
- * NEEDSDOC @param funcName
- * NEEDSDOC @param funcID
+ * @param funcName The class name of the
{org.apache.xpath.functions.Function}
+ * class, which, if it does not have a '.' in it, is assumed
to
+ * be relative to 'org.apache.xpath.functions'.
+ * @param funcID The function ID, which may correspond to one of the
FUNC_XXX
+ * values found in [EMAIL PROTECTED]
org.apache.xpath.compiler.FunctionTable}, but may
+ * be a value installed by an external module.
*/
public FuncLoader(String funcName, int funcID)
{
@@ -110,12 +117,12 @@
}
/**
- * NEEDSDOC Method getFunction
- *
+ * Get a Function instance that this instance is liaisoning for.
*
- * NEEDSDOC (getFunction) @return
+ * @return non-null reference to Function derivative.
*
- * @throws javax.xml.transform.TransformerException
+ * @throws javax.xml.transform.TransformerException if
ClassNotFoundException,
+ * IllegalAccessException, or InstantiationException is thrown.
*/
public Function getFunction() throws
javax.xml.transform.TransformerException
{
1.4 +48 -49
xml-xalan/java/src/org/apache/xpath/compiler/FunctionTable.java
Index: FunctionTable.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/compiler/FunctionTable.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- FunctionTable.java 2000/11/13 16:27:31 1.3
+++ FunctionTable.java 2000/12/17 05:20:08 1.4
@@ -65,117 +65,113 @@
public class FunctionTable
{
- /** NEEDSDOC Field FUNC_CURRENT */
+ /** The 'current()' id. */
public static final int FUNC_CURRENT = 0;
- /** NEEDSDOC Field FUNC_LAST */
+ /** The 'last()' id. */
public static final int FUNC_LAST = 1;
- /** NEEDSDOC Field FUNC_POSITION */
+ /** The 'position()' id. */
public static final int FUNC_POSITION = 2;
- /** NEEDSDOC Field FUNC_COUNT */
+ /** The 'count()' id. */
public static final int FUNC_COUNT = 3;
- /** NEEDSDOC Field FUNC_ID */
+ /** The 'id()' id. */
public static final int FUNC_ID = 4;
- /** NEEDSDOC Field FUNC_KEY */
+ /** The 'key()' id (XSLT). */
public static final int FUNC_KEY = 5;
- // public static final int FUNC_DOC = 6;
-
- /** NEEDSDOC Field FUNC_LOCAL_PART */
+ /** The 'local-name()' id. */
public static final int FUNC_LOCAL_PART = 7;
- /** NEEDSDOC Field FUNC_NAMESPACE */
+ /** The 'namespace-uri()' id. */
public static final int FUNC_NAMESPACE = 8;
- /** NEEDSDOC Field FUNC_QNAME */
+ /** The 'name()' id. */
public static final int FUNC_QNAME = 9;
- /** NEEDSDOC Field FUNC_GENERATE_ID */
+ /** The 'generate-id()' id. */
public static final int FUNC_GENERATE_ID = 10;
- /** NEEDSDOC Field FUNC_NOT */
+ /** The 'not()' id. */
public static final int FUNC_NOT = 11;
- /** NEEDSDOC Field FUNC_TRUE */
+ /** The 'true()' id. */
public static final int FUNC_TRUE = 12;
- /** NEEDSDOC Field FUNC_FALSE */
+ /** The 'false()' id. */
public static final int FUNC_FALSE = 13;
- /** NEEDSDOC Field FUNC_BOOLEAN */
+ /** The 'boolean()' id. */
public static final int FUNC_BOOLEAN = 14;
- /** NEEDSDOC Field FUNC_NUMBER */
+ /** The 'number()' id. */
public static final int FUNC_NUMBER = 15;
- /** NEEDSDOC Field FUNC_FLOOR */
+ /** The 'floor()' id. */
public static final int FUNC_FLOOR = 16;
- /** NEEDSDOC Field FUNC_CEILING */
+ /** The 'ceiling()' id. */
public static final int FUNC_CEILING = 17;
- /** NEEDSDOC Field FUNC_ROUND */
+ /** The 'round()' id. */
public static final int FUNC_ROUND = 18;
- /** NEEDSDOC Field FUNC_SUM */
+ /** The 'sum()' id. */
public static final int FUNC_SUM = 19;
- /** NEEDSDOC Field FUNC_STRING */
+ /** The 'string()' id. */
public static final int FUNC_STRING = 20;
- /** NEEDSDOC Field FUNC_STARTS_WITH */
+ /** The 'starts-with()' id. */
public static final int FUNC_STARTS_WITH = 21;
- /** NEEDSDOC Field FUNC_CONTAINS */
+ /** The 'contains()' id. */
public static final int FUNC_CONTAINS = 22;
- /** NEEDSDOC Field FUNC_SUBSTRING_BEFORE */
+ /** The 'substring-before()' id. */
public static final int FUNC_SUBSTRING_BEFORE = 23;
- /** NEEDSDOC Field FUNC_SUBSTRING_AFTER */
+ /** The 'substring-after()' id. */
public static final int FUNC_SUBSTRING_AFTER = 24;
- /** NEEDSDOC Field FUNC_NORMALIZE_SPACE */
+ /** The 'normalize-space()' id. */
public static final int FUNC_NORMALIZE_SPACE = 25;
- /** NEEDSDOC Field FUNC_TRANSLATE */
+ /** The 'translate()' id. */
public static final int FUNC_TRANSLATE = 26;
- /** NEEDSDOC Field FUNC_CONCAT */
+ /** The 'concat()' id. */
public static final int FUNC_CONCAT = 27;
-
- // public static final int FUNC_FORMAT_NUMBER = 28;
- /** NEEDSDOC Field FUNC_SUBSTRING */
+ /** The 'substring()' id. */
public static final int FUNC_SUBSTRING = 29;
- /** NEEDSDOC Field FUNC_STRING_LENGTH */
+ /** The 'string-length()' id. */
public static final int FUNC_STRING_LENGTH = 30;
- /** NEEDSDOC Field FUNC_SYSTEM_PROPERTY */
+ /** The 'system-property()' id. */
public static final int FUNC_SYSTEM_PROPERTY = 31;
- /** NEEDSDOC Field FUNC_LANG */
+ /** The 'lang()' id. */
public static final int FUNC_LANG = 32;
- /** NEEDSDOC Field FUNC_EXT_FUNCTION_AVAILABLE */
+ /** The 'function-available()' id (XSLT). */
public static final int FUNC_EXT_FUNCTION_AVAILABLE = 33;
- /** NEEDSDOC Field FUNC_EXT_ELEM_AVAILABLE */
+ /** The 'element-available()' id (XSLT). */
public static final int FUNC_EXT_ELEM_AVAILABLE = 34;
+ /** The 'unparsed-entity-uri()' id (XSLT). */
+ public static final int FUNC_UNPARSED_ENTITY_URI = 36;
+
// Proprietary
- /** NEEDSDOC Field FUNC_DOCLOCATION */
+ /** The 'document-location()' id (Proprietary). */
public static final int FUNC_DOCLOCATION = 35;
- /** NEEDSDOC Field FUNC_UNPARSED_ENTITY_URI */
- public static final int FUNC_UNPARSED_ENTITY_URI = 36;
-
/**
* The function table.
*/
@@ -260,14 +256,16 @@
}
/**
- * NEEDSDOC Method getFunction
+ * Obtain a new Function object from a function ID.
*
+ * @param which The function ID, which may correspond to one of the
FUNC_XXX
+ * values found in [EMAIL PROTECTED]
org.apache.xpath.compiler.FunctionTable}, but may
+ * be a value installed by an external module.
*
- * NEEDSDOC @param which
+ * @return a a new Function instance.
*
- * NEEDSDOC (getFunction) @return
- *
- * @throws javax.xml.transform.TransformerException
+ * @throws javax.xml.transform.TransformerException if
ClassNotFoundException,
+ * IllegalAccessException, or InstantiationException is thrown.
*/
public static Function getFunction(int which)
throws javax.xml.transform.TransformerException
@@ -308,10 +306,11 @@
}
/**
- * Install a built-in function at a specific index.
- * @param name The unqualified name of the function.
+ * Install a function loader at a specific index.
* @param func A Implementation of an XPath Function object.
- * NEEDSDOC @param funcIndex
+ * @param which The function ID, which may correspond to one of the
FUNC_XXX
+ * values found in [EMAIL PROTECTED]
org.apache.xpath.compiler.FunctionTable}, but may
+ * be a value installed by an external module.
* @return the position of the function in the internal index.
*/
public static void installFunction(Expression func, int funcIndex)
1.6 +76 -109
xml-xalan/java/src/org/apache/xpath/compiler/Keywords.java
Index: Keywords.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/compiler/Keywords.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Keywords.java 2000/11/28 18:14:23 1.5
+++ Keywords.java 2000/12/17 05:20:08 1.6
@@ -62,225 +62,193 @@
/**
* <meta name="usage" content="internal"/>
- * NEEDSDOC Class Keywords <needs-comment/>
+ * Table of strings to operation code lookups.
*/
public class Keywords
{
- /** NEEDSDOC Field m_keywords */
+ /** Table of keywords to opcode associations. */
static Hashtable m_keywords = new Hashtable();
- /** NEEDSDOC Field m_axisnames */
+ /** Table of axes names to opcode associations. */
static Hashtable m_axisnames = new Hashtable();
- /** NEEDSDOC Field m_functions */
+ /** Table of function name to function ID associations. */
static Hashtable m_functions = new Hashtable();
- /** NEEDSDOC Field m_nodetypes */
+ /** Table of node type strings to opcode associations. */
static Hashtable m_nodetypes = new Hashtable();
- /** NEEDSDOC Field FROM_ANCESTORS_STRING */
+ /** ancestor axes string. */
private static final String FROM_ANCESTORS_STRING = "ancestor";
- /** NEEDSDOC Field FROM_ANCESTORS_OR_SELF_STRING */
+ /** ancestor-or-self axes string. */
private static final String FROM_ANCESTORS_OR_SELF_STRING =
"ancestor-or-self";
- /** NEEDSDOC Field FROM_ATTRIBUTES_STRING */
+ /** attribute axes string. */
private static final String FROM_ATTRIBUTES_STRING = "attribute";
- /** NEEDSDOC Field FROM_CHILDREN_STRING */
+ /** child axes string. */
private static final String FROM_CHILDREN_STRING = "child";
- /** NEEDSDOC Field FROM_DESCENDANTS_STRING */
+ /** descendant-or-self axes string. */
private static final String FROM_DESCENDANTS_STRING = "descendant";
- /** NEEDSDOC Field FROM_DESCENDANTS_OR_SELF_STRING */
+ /** ancestor axes string. */
private static final String FROM_DESCENDANTS_OR_SELF_STRING =
"descendant-or-self";
- /** NEEDSDOC Field FROM_FOLLOWING_STRING */
+ /** following axes string. */
private static final String FROM_FOLLOWING_STRING = "following";
- /** NEEDSDOC Field FROM_FOLLOWING_SIBLINGS_STRING */
+ /** following-sibling axes string. */
private static final String FROM_FOLLOWING_SIBLINGS_STRING =
"following-sibling";
- /** NEEDSDOC Field FROM_PARENT_STRING */
+ /** parent axes string. */
private static final String FROM_PARENT_STRING = "parent";
- /** NEEDSDOC Field FROM_PRECEDING_STRING */
+ /** preceding axes string. */
private static final String FROM_PRECEDING_STRING = "preceding";
- /** NEEDSDOC Field FROM_PRECEDING_SIBLINGS_STRING */
+ /** preceding-sibling axes string. */
private static final String FROM_PRECEDING_SIBLINGS_STRING =
"preceding-sibling";
- /** NEEDSDOC Field FROM_SELF_STRING */
+ /** self axes string. */
private static final String FROM_SELF_STRING = "self";
- /** NEEDSDOC Field FROM_NAMESPACE_STRING */
+ /** namespace axes string. */
private static final String FROM_NAMESPACE_STRING = "namespace";
- /** NEEDSDOC Field FROM_SELF_ABBREVIATED_STRING */
+ /** self axes abreviated string. */
private static final String FROM_SELF_ABBREVIATED_STRING = ".";
- /** NEEDSDOC Field NODETYPE_COMMENT_STRING */
+ /** comment node test string. */
private static final String NODETYPE_COMMENT_STRING = "comment";
- /** NEEDSDOC Field NODETYPE_TEXT_STRING */
+ /** text node test string. */
private static final String NODETYPE_TEXT_STRING = "text";
- /** NEEDSDOC Field NODETYPE_PI_STRING */
+ /** processing-instruction node test string. */
private static final String NODETYPE_PI_STRING = "processing-instruction";
- /** NEEDSDOC Field NODETYPE_NODE_STRING */
+ /** Any node test string. */
private static final String NODETYPE_NODE_STRING = "node";
- /** NEEDSDOC Field FROM_ATTRIBUTE_STRING */
- private static final String FROM_ATTRIBUTE_STRING = "@";
-
- /** NEEDSDOC Field FROM_DOC_STRING */
- private static final String FROM_DOC_STRING = "document";
-
- /** NEEDSDOC Field FROM_DOCREF_STRING */
- private static final String FROM_DOCREF_STRING = "document";
-
- /** NEEDSDOC Field FROM_ID_STRING */
- private static final String FROM_ID_STRING = "id";
-
- /** NEEDSDOC Field FROM_IDREF_STRING */
- private static final String FROM_IDREF_STRING = "idref";
-
- /** NEEDSDOC Field NODETYPE_ANYELEMENT_STRING */
+ /** Wildcard element string. */
private static final String NODETYPE_ANYELEMENT_STRING = "*";
- /** NEEDSDOC Field FUNC_CURRENT_STRING */
+ /** current function string. */
private static final String FUNC_CURRENT_STRING = "current";
- /** NEEDSDOC Field FUNC_LAST_STRING */
+ /** last function string. */
private static final String FUNC_LAST_STRING = "last";
- /** NEEDSDOC Field FUNC_POSITION_STRING */
+ /** position function string. */
private static final String FUNC_POSITION_STRING = "position";
- /** NEEDSDOC Field FUNC_COUNT_STRING */
+ /** count function string. */
private static final String FUNC_COUNT_STRING = "count";
- /** NEEDSDOC Field FUNC_ID_STRING */
+ /** id function string. */
static final String FUNC_ID_STRING = "id";
- /** NEEDSDOC Field FUNC_IDREF_STRING */
- private static final String FUNC_IDREF_STRING = "idref";
-
- /** NEEDSDOC Field FUNC_KEY_STRING */
+ /** key function string (XSLT). */
public static final String FUNC_KEY_STRING = "key";
-
- /** NEEDSDOC Field FUNC_KEYREF_STRING */
- private static final String FUNC_KEYREF_STRING = "keyref";
-
- /** NEEDSDOC Field FUNC_DOC_STRING */
- private static final String FUNC_DOC_STRING = "doc";
-
- /** NEEDSDOC Field FUNC_DOCUMENT_STRING */
- private static final String FUNC_DOCUMENT_STRING = "document";
- /** NEEDSDOC Field FUNC_DOCREF_STRING */
- private static final String FUNC_DOCREF_STRING = "docref";
-
- /** NEEDSDOC Field FUNC_LOCAL_PART_STRING */
+ /** local-name function string. */
private static final String FUNC_LOCAL_PART_STRING = "local-name";
- /** NEEDSDOC Field FUNC_NAMESPACE_STRING */
+ /** namespace-uri function string. */
private static final String FUNC_NAMESPACE_STRING = "namespace-uri";
- /** NEEDSDOC Field FUNC_NAME_STRING */
+ /** name function string. */
private static final String FUNC_NAME_STRING = "name";
- /** NEEDSDOC Field FUNC_GENERATE_ID_STRING */
+ /** generate-id function string (XSLT). */
private static final String FUNC_GENERATE_ID_STRING = "generate-id";
- /** NEEDSDOC Field FUNC_NOT_STRING */
+ /** not function string. */
private static final String FUNC_NOT_STRING = "not";
- /** NEEDSDOC Field FUNC_TRUE_STRING */
+ /** true function string. */
private static final String FUNC_TRUE_STRING = "true";
- /** NEEDSDOC Field FUNC_FALSE_STRING */
+ /** false function string. */
private static final String FUNC_FALSE_STRING = "false";
- /** NEEDSDOC Field FUNC_BOOLEAN_STRING */
+ /** boolean function string. */
private static final String FUNC_BOOLEAN_STRING = "boolean";
- /** NEEDSDOC Field FUNC_LANG_STRING */
+ /** lang function string. */
private static final String FUNC_LANG_STRING = "lang";
- /** NEEDSDOC Field FUNC_NUMBER_STRING */
+ /** number function string. */
private static final String FUNC_NUMBER_STRING = "number";
- /** NEEDSDOC Field FUNC_FLOOR_STRING */
+ /** floor function string. */
private static final String FUNC_FLOOR_STRING = "floor";
- /** NEEDSDOC Field FUNC_CEILING_STRING */
+ /** ceiling function string. */
private static final String FUNC_CEILING_STRING = "ceiling";
- /** NEEDSDOC Field FUNC_ROUND_STRING */
+ /** round function string. */
private static final String FUNC_ROUND_STRING = "round";
- /** NEEDSDOC Field FUNC_SUM_STRING */
+ /** sum function string. */
private static final String FUNC_SUM_STRING = "sum";
- /** NEEDSDOC Field FUNC_STRING_STRING */
+ /** string function string. */
private static final String FUNC_STRING_STRING = "string";
- /** NEEDSDOC Field FUNC_STARTS_WITH_STRING */
+ /** starts-with function string. */
private static final String FUNC_STARTS_WITH_STRING = "starts-with";
- /** NEEDSDOC Field FUNC_CONTAINS_STRING */
+ /** contains function string. */
private static final String FUNC_CONTAINS_STRING = "contains";
- /** NEEDSDOC Field FUNC_SUBSTRING_BEFORE_STRING */
+ /** substring-before function string. */
private static final String FUNC_SUBSTRING_BEFORE_STRING =
"substring-before";
- /** NEEDSDOC Field FUNC_SUBSTRING_AFTER_STRING */
+ /** substring-after function string. */
private static final String FUNC_SUBSTRING_AFTER_STRING =
"substring-after";
- /** NEEDSDOC Field FUNC_NORMALIZE_SPACE_STRING */
+ /** normalize-space function string. */
private static final String FUNC_NORMALIZE_SPACE_STRING =
"normalize-space";
- /** NEEDSDOC Field FUNC_TRANSLATE_STRING */
+ /** translate function string. */
private static final String FUNC_TRANSLATE_STRING = "translate";
- /** NEEDSDOC Field FUNC_CONCAT_STRING */
+ /** concat function string. */
private static final String FUNC_CONCAT_STRING = "concat";
-
- //private static final String FUNC_FORMAT_NUMBER_STRING = "format-number";
- /** NEEDSDOC Field FUNC_SYSTEM_PROPERTY_STRING */
+ /** system-property function string. */
private static final String FUNC_SYSTEM_PROPERTY_STRING =
"system-property";
- /** NEEDSDOC Field FUNC_EXT_FUNCTION_AVAILABLE_STRING */
+ /** function-available function string (XSLT). */
private static final String FUNC_EXT_FUNCTION_AVAILABLE_STRING =
"function-available";
- /** NEEDSDOC Field FUNC_EXT_ELEM_AVAILABLE_STRING */
+ /** element-available function string (XSLT). */
private static final String FUNC_EXT_ELEM_AVAILABLE_STRING =
"element-available";
- /** NEEDSDOC Field FUNC_SUBSTRING_STRING */
+ /** substring function string. */
private static final String FUNC_SUBSTRING_STRING = "substring";
- /** NEEDSDOC Field FUNC_STRING_LENGTH_STRING */
+ /** string-length function string. */
private static final String FUNC_STRING_LENGTH_STRING = "string-length";
- /** NEEDSDOC Field FUNC_UNPARSED_ENTITY_URI_STRING */
+ /** unparsed-entity-uri function string (XSLT). */
private static final String FUNC_UNPARSED_ENTITY_URI_STRING =
"unparsed-entity-uri";
// Proprietary, built in functions
- /** NEEDSDOC Field FUNC_DOCLOCATION_STRING */
+ /** current function string (Proprietary). */
private static final String FUNC_DOCLOCATION_STRING = "document-location";
static
@@ -323,18 +291,10 @@
new Integer(OpCodes.NODETYPE_ANYELEMENT));
m_keywords.put(new StringKey(FROM_SELF_ABBREVIATED_STRING),
new Integer(OpCodes.FROM_SELF));
-
- // m_keywords.put(new StringKey(FROM_ATTRIBUTE_STRING), new
Integer(OpCodes.FROM_ATTRIBUTE));
- // m_keywords.put(new StringKey(FROM_DOC_STRING), new
Integer(OpCodes.FROM_DOC));
- // m_keywords.put(new StringKey(FROM_DOCREF_STRING), new
Integer(OpCodes.FROM_DOCREF));
- // m_keywords.put(new StringKey(FROM_ID_STRING), new
Integer(OpCodes.FROM_ID));
- // m_keywords.put(new StringKey(FROM_IDREF_STRING), new
Integer(OpCodes.FROM_IDREF));
m_keywords.put(new StringKey(FUNC_ID_STRING),
new Integer(FunctionTable.FUNC_ID));
m_keywords.put(new StringKey(FUNC_KEY_STRING),
new Integer(FunctionTable.FUNC_KEY));
-
- // m_keywords.put(new StringKey(FUNC_DOCUMENT_STRING), new
Integer(FunctionTable.FUNC_DOC));
m_functions.put(new StringKey(FUNC_CURRENT_STRING),
new Integer(FunctionTable.FUNC_CURRENT));
m_functions.put(new StringKey(FUNC_LAST_STRING),
@@ -347,8 +307,6 @@
new Integer(FunctionTable.FUNC_ID));
m_functions.put(new StringKey(FUNC_KEY_STRING),
new Integer(FunctionTable.FUNC_KEY));
-
- // m_functions.put(new StringKey(FUNC_DOCUMENT_STRING), new
Integer(FunctionTable.FUNC_DOC));
m_functions.put(new StringKey(FUNC_LOCAL_PART_STRING),
new Integer(FunctionTable.FUNC_LOCAL_PART));
m_functions.put(new StringKey(FUNC_NAMESPACE_STRING),
@@ -421,25 +379,34 @@
new Integer(FunctionTable.FUNC_DOCLOCATION));
}
+ /**
+ * Tell if a built-in, non-namespaced function is available.
+ *
+ * @param methName The local name of the function.
+ *
+ * @return True if the function can be executed.
+ */
public static boolean functionAvailable(String methName)
{
try
{
Object tblEntry = m_functions.get(methName);
+
if (null == tblEntry)
return false;
+
int funcType = ((Integer) tblEntry).intValue();
+
switch (funcType)
{
- case OpCodes.NODETYPE_COMMENT:
- case OpCodes.NODETYPE_TEXT:
- case OpCodes.NODETYPE_PI:
- case OpCodes.NODETYPE_NODE:
- return false; // These look like functions but
they're NodeTests.
-
- default:
- return true;
+ case OpCodes.NODETYPE_COMMENT :
+ case OpCodes.NODETYPE_TEXT :
+ case OpCodes.NODETYPE_PI :
+ case OpCodes.NODETYPE_NODE :
+ return false; // These look like functions but they're NodeTests.
+ default :
+ return true;
}
}
catch (Exception e)
1.5 +21 -20 xml-xalan/java/src/org/apache/xpath/compiler/Lexer.java
Index: Lexer.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/compiler/Lexer.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Lexer.java 2000/11/23 04:59:05 1.4
+++ Lexer.java 2000/12/17 05:20:08 1.5
@@ -113,9 +113,10 @@
/**
* Create a Lexer object.
*
- * NEEDSDOC @param compiler
- * NEEDSDOC @param resolver
- * NEEDSDOC @param xpathProcessor
+ * @param compiler The owning compiler for this lexer.
+ * @param resolver The prefix resolver for mapping qualified name prefixes
+ * to namespace URIs.
+ * @param xpathProcessor The parser that is processing strings to opcodes.
*/
Lexer(Compiler compiler, PrefixResolver resolver,
XPathParser xpathProcessor)
@@ -415,11 +416,11 @@
* this is a top-level element. Must be called before the
* next token is added to the m_tokenQueue.
*
- * NEEDSDOC @param nesting
- * NEEDSDOC @param isStart
- * NEEDSDOC @param isAttrName
+ * @param nesting The nesting count for the pattern element.
+ * @param isStart true if this is the start of a pattern.
+ * @param isAttrName true if we have determined that this is an attribute
name.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true if this is the start of a pattern.
*/
private boolean mapPatternElemPos(int nesting, boolean isStart,
boolean isAttrName)
@@ -446,9 +447,9 @@
/**
* Given a map pos, return the corresponding token queue pos.
*
- * NEEDSDOC @param i
+ * @param i The index in the m_patternMap.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the token queue position.
*/
private int getTokenQueuePosFromMap(int i)
{
@@ -487,9 +488,9 @@
/**
* Given a string, return the corresponding keyword token.
*
- * NEEDSDOC @param key
+ * @param key The keyword.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An opcode value.
*/
final int getKeywordToken(String key)
{
@@ -515,9 +516,9 @@
}
/**
- * Record the correct token string in the passed vector.
+ * Record the current token in the passed vector.
*
- * NEEDSDOC @param targetStrings
+ * @param targetStrings Vector of string.
*/
private void recordTokenString(Vector targetStrings)
{
@@ -573,10 +574,10 @@
}
/**
- * NEEDSDOC Method addToTokenQueue
+ * Add a token to the token queue.
*
*
- * NEEDSDOC @param s
+ * @param s The token.
*/
private final void addToTokenQueue(String s)
{
@@ -587,12 +588,12 @@
* When a seperator token is found, see if there's a element name or
* the like to map.
*
- * NEEDSDOC @param pat
- * NEEDSDOC @param startSubstring
- * NEEDSDOC @param posOfNSSep
- * NEEDSDOC @param posOfScan
+ * @param pat The XPath name string.
+ * @param startSubstring The start of the name string.
+ * @param posOfNSSep The position of the namespace seperator (':').
+ * @param posOfScan The end of the name index.
*
- * NEEDSDOC ($objectName$) @return
+ * @return -1 always.
*/
private int mapNSTokens(String pat, int startSubstring, int posOfNSSep,
int posOfScan)
1.6 +19 -18 xml-xalan/java/src/org/apache/xpath/compiler/OpCodes.java
Index: OpCodes.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/compiler/OpCodes.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- OpCodes.java 2000/11/09 19:13:50 1.5
+++ OpCodes.java 2000/12/17 05:20:09 1.6
@@ -348,7 +348,8 @@
*/
public static final int OP_LITERAL = 21;
- /** NEEDSDOC Field FIRST_NODESET_OP */
+ /** The low opcode for nodesets, needed by getFirstPredicateOpPos and
+ * getNextStepPos. */
static final int FIRST_NODESET_OP = 22;
/**
@@ -415,7 +416,7 @@
*/
public static final int OP_FUNCTION = 25;
- /** NEEDSDOC Field LAST_NODESET_OP */
+ /** The last opcode for stuff that can be a nodeset. */
static final int LAST_NODESET_OP = 25;
/**
@@ -599,46 +600,46 @@
*/
public static final int AXES_START_TYPES = 37;
- /** NEEDSDOC Field FROM_ANCESTORS */
+ /** ancestor axes opcode. */
public static final int FROM_ANCESTORS = 37;
- /** NEEDSDOC Field FROM_ANCESTORS_OR_SELF */
+ /** ancestor-or-self axes opcode. */
public static final int FROM_ANCESTORS_OR_SELF = 38;
- /** NEEDSDOC Field FROM_ATTRIBUTES */
+ /** attribute axes opcode. */
public static final int FROM_ATTRIBUTES = 39;
- /** NEEDSDOC Field FROM_CHILDREN */
+ /** children axes opcode. */
public static final int FROM_CHILDREN = 40;
- /** NEEDSDOC Field FROM_DESCENDANTS */
+ /** descendants axes opcode. */
public static final int FROM_DESCENDANTS = 41;
- /** NEEDSDOC Field FROM_DESCENDANTS_OR_SELF */
+ /** descendants-of-self axes opcode. */
public static final int FROM_DESCENDANTS_OR_SELF = 42;
- /** NEEDSDOC Field FROM_FOLLOWING */
+ /** following axes opcode. */
public static final int FROM_FOLLOWING = 43;
- /** NEEDSDOC Field FROM_FOLLOWING_SIBLINGS */
+ /** following-siblings axes opcode. */
public static final int FROM_FOLLOWING_SIBLINGS = 44;
- /** NEEDSDOC Field FROM_PARENT */
+ /** parent axes opcode. */
public static final int FROM_PARENT = 45;
- /** NEEDSDOC Field FROM_PRECEDING */
+ /** preceding axes opcode. */
public static final int FROM_PRECEDING = 46;
- /** NEEDSDOC Field FROM_PRECEDING_SIBLINGS */
+ /** preceding-sibling axes opcode. */
public static final int FROM_PRECEDING_SIBLINGS = 47;
- /** NEEDSDOC Field FROM_SELF */
+ /** self axes opcode. */
public static final int FROM_SELF = 48;
- /** NEEDSDOC Field FROM_NAMESPACE */
+ /** namespace axes opcode. */
public static final int FROM_NAMESPACE = 49;
- /** NEEDSDOC Field FROM_ROOT */
+ /** '/' axes opcode. */
public static final int FROM_ROOT = 50;
/**
@@ -659,9 +660,9 @@
*/
public static final int MATCH_IMMEDIATE_ANCESTOR = 53;
- /** NEEDSDOC Field AXES_END_TYPES */
+ /** The end of the axes types. */
public static final int AXES_END_TYPES = 53;
- /** NEEDSDOC Field NEXT_FREE_ID */
+ /** The next free ID. Please keep this up to date. */
private static final int NEXT_FREE_ID = 99;
}
1.7 +39 -167 xml-xalan/java/src/org/apache/xpath/compiler/OpMap.java
Index: OpMap.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/compiler/OpMap.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- OpMap.java 2000/11/23 04:59:06 1.6
+++ OpMap.java 2000/12/17 05:20:09 1.7
@@ -74,10 +74,9 @@
protected String m_currentPattern;
/**
- * NEEDSDOC Method toString
+ * Return the expression as a string for diagnostics.
*
- *
- * NEEDSDOC (toString) @return
+ * @return The expression string.
*/
public String toString()
{
@@ -85,9 +84,9 @@
}
/**
- * Get the pattern string.
+ * Return the expression as a string for diagnostics.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The expression string.
*/
public String getPatternString()
{
@@ -107,10 +106,9 @@
public Object[] m_tokenQueue = new Object[MAXTOKENQUEUESIZE];
/**
- * <meta name="usage" content="advanced"/>
* Get the XPath as a list of tokens.
*
- * NEEDSDOC ($objectName$) @return
+ * @return an array of string tokens.
*/
public Object[] getTokenQueue()
{
@@ -118,12 +116,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
* Get the XPath as a list of tokens.
*
- * NEEDSDOC @param pos
+ * @param pos index into token queue.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The token, normally a string.
*/
public Object getToken(int pos)
{
@@ -136,10 +133,9 @@
public int m_tokenQueueSize = 0;
/**
- * <meta name="usage" content="advanced"/>
- * Get size of the token queue.
+ * Get size of the token queue.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The size of the token queue.
*/
public int getTokenQueueSize()
{
@@ -155,13 +151,12 @@
public int m_opMap[] = null;
/**
- * <meta name="usage" content="advanced"/>
- * Get the opcode list that describes the XPath operations. It contains
+ * Get the opcode list that describes the XPath operations. It contains
* operations codes and indexes into the m_tokenQueue.
* I use an array instead of a full parse tree in order to cut down
* on the number of objects created.
*
- * NEEDSDOC ($objectName$) @return
+ * @return
*/
public int[] getOpMap()
{
@@ -171,7 +166,6 @@
// Position indexes
/**
- * <meta name="usage" content="advanced"/>
* The length is always the opcode position + 1.
* Length is always expressed as the opcode+length bytes,
* so it is always 2 or greater.
@@ -218,11 +212,10 @@
}
/**
- * <meta name="usage" content="advanced"/>
- * Given an operation position, return the current op.
+ * Given an operation position, return the current op.
*
- * NEEDSDOC @param opPos
- * @return position of next operation in m_opMap.
+ * @param opPos index into op map.
+ * @return the op that corresponds to the opPos argument.
*/
public int getOp(int opPos)
{
@@ -230,11 +223,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
* Given an operation position, return the end position, i.e. the
* beginning of the next operation.
*
- * NEEDSDOC @param opPos
+ * @param opPos An op position of an operation for which there is a size
+ * entry following.
* @return position of next operation in m_opMap.
*/
public int getNextOpPos(int opPos)
@@ -243,12 +236,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
- * Given an operation position, return the end position, i.e. the
- * beginning of the next operation.
+ * Given a location step position, return the end position, i.e. the
+ * beginning of the next step.
*
- * NEEDSDOC @param opPos
- * @return position of next operation in m_opMap.
+ * @param opPos the position of a location step.
+ * @return the position of the next location step.
*/
public int getNextStepPos(int opPos)
{
@@ -289,12 +281,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
* Given an operation position, return the end position, i.e. the
* beginning of the next operation.
*
- * NEEDSDOC @param opMap
- * NEEDSDOC @param opPos
+ * @param opMap The operations map.
+ * @param opPos index to operation, for which there is a size entry
following.
* @return position of next operation in m_opMap.
*/
public static int getNextOpPos(int[] opMap, int opPos)
@@ -303,7 +294,6 @@
}
/**
- * <meta name="usage" content="advanced"/>
* Given an FROM_stepType position, return the position of the
* first predicate, if there is one, or else this will point
* to the end of the FROM_stepType.
@@ -312,7 +302,7 @@
* boolean hasPredicates =
* OpCodes.OP_PREDICATE == xpath.getOp(posOfPredicate);
*
- * NEEDSDOC @param opPos
+ * @param opPos position of FROM_stepType op.
* @return position of predicate in FROM_stepType structure.
*/
public int getFirstPredicateOpPos(int opPos)
@@ -339,12 +329,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
* Go to the first child of a given operation.
*
- * NEEDSDOC @param opPos
+ * @param opPos position of operation.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The position of the first child of the operation.
*/
public static int getFirstChildPos(int opPos)
{
@@ -352,12 +341,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
- * Go to the first child of a given operation.
+ * Get the length of an operation.
*
- * NEEDSDOC @param opPos
+ * @param opPos The position of the operation in the op map.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The size of the operation.
*/
public int getArgLength(int opPos)
{
@@ -365,12 +353,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
- * Go to the first child of a given operation.
+ * Given a location step, get the length of that step.
*
- * NEEDSDOC @param opPos
+ * @param opPos Position of location step in op map.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The length of the step.
*/
public int getArgLengthOfStep(int opPos)
{
@@ -378,12 +365,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
- * Go to the first child of a given operation.
+ * Get the first child position of a given location step.
*
- * NEEDSDOC @param opPos
+ * @param opPos Position of location step in the location map.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The first child position of the step.
*/
public static int getFirstChildPosOfStep(int opPos)
{
@@ -391,11 +377,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
* Get the test type of the step, i.e. NODETYPE_XXX value.
+ *
* @param opPosOfStep The position of the FROM_XXX step.
*
- * NEEDSDOC ($objectName$) @return
+ * @return NODETYPE_XXX value.
*/
public int getStepTestType(int opPosOfStep)
{
@@ -403,11 +389,11 @@
}
/**
- * <meta name="usage" content="advanced"/>
* Get the namespace of the step.
+ *
* @param opPosOfStep The position of the FROM_XXX step.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The step's namespace, NodeTest.WILD, or null for null namespace.
*/
public String getStepNS(int opPosOfStep)
{
@@ -431,11 +417,10 @@
}
/**
- * <meta name="usage" content="advanced"/>
* Get the local name of the step.
* @param opPosOfStep The position of the FROM_XXX step.
*
- * NEEDSDOC ($objectName$) @return
+ * @return OpCodes.EMPTY, OpCodes.ELEMWILDCARD, or the local name.
*/
public String getStepLocalName(int opPosOfStep)
{
@@ -474,117 +459,4 @@
return null;
}
- /**
- * <meta name="usage" content="advanced"/>
- * This method is for building indexes of match patterns for fast lookup.
- * This allows a caller to get the QName, and quickly
- * find the likely candidates that may match. Note that this will
- * produce QName objects that aren't strictly legal, like "*".
- *
- * NEEDSDOC ($objectName$) @return
- */
- public Vector getTargetElementQNames()
- {
-
- Vector targetQNames = new Vector();
- int opPos = 2;
-
- while (m_opMap[opPos] == OpCodes.OP_LOCATIONPATHPATTERN)
- {
- int nextOpPos = getNextOpPos(opPos);
-
- opPos = getFirstChildPos(opPos);
-
- while (m_opMap[opPos] != OpCodes.ENDOP)
- {
- int nextStepPos = getNextOpPos(opPos);
- int nextOp = m_opMap[nextStepPos];
-
- if ((nextOp == OpCodes.OP_PREDICATE) || (nextOp == OpCodes.ENDOP))
- {
- int stepType = m_opMap[opPos];
-
- opPos += 3;
-
- switch (stepType)
- {
- case OpCodes.OP_FUNCTION :
- targetQNames.addElement(new QName(PsuedoNames.PSEUDONAME_ANY));
- break;
- case OpCodes.FROM_ROOT :
- targetQNames.addElement(new QName(PsuedoNames.PSEUDONAME_ROOT));
- break;
- case OpCodes.MATCH_ATTRIBUTE :
- case OpCodes.MATCH_ANY_ANCESTOR :
- case OpCodes.MATCH_IMMEDIATE_ANCESTOR :
- int tok = m_opMap[opPos];
-
- opPos++;
-
- switch (tok)
- {
- case OpCodes.NODETYPE_COMMENT :
- targetQNames.addElement(
- new QName(PsuedoNames.PSEUDONAME_COMMENT));
- break;
- case OpCodes.NODETYPE_TEXT :
- targetQNames.addElement(new
QName(PsuedoNames.PSEUDONAME_TEXT));
- break;
- case OpCodes.NODETYPE_NODE :
- targetQNames.addElement(new QName(PsuedoNames.PSEUDONAME_ANY));
- break;
- case OpCodes.NODETYPE_ROOT :
- targetQNames.addElement(new
QName(PsuedoNames.PSEUDONAME_ROOT));
- break;
- case OpCodes.NODETYPE_ANYELEMENT :
- targetQNames.addElement(new QName(PsuedoNames.PSEUDONAME_ANY));
- break;
- case OpCodes.NODETYPE_PI :
- targetQNames.addElement(new QName(PsuedoNames.PSEUDONAME_ANY));
- break;
- case OpCodes.NODENAME :
- int tokenIndex = m_opMap[opPos + 1];
- String namespace = (tokenIndex >= 0)
- ? (String) m_tokenQueue[tokenIndex] : null;
-
- tokenIndex = m_opMap[opPos + 1];
-
- if (tokenIndex >= 0)
- {
- String targetName = (String) m_tokenQueue[tokenIndex];
-
- if (targetName.equals("*"))
- {
- targetQNames.addElement(
- new QName(namespace, PsuedoNames.PSEUDONAME_ANY));
- }
- else
- {
- targetQNames.addElement(new QName(namespace, targetName));
- }
- }
- else
- {
-
- // ?? -sboag
- targetQNames.addElement(
- new QName(namespace, PsuedoNames.PSEUDONAME_ANY));
- }
- break;
- default :
- targetQNames.addElement(new QName(PsuedoNames.PSEUDONAME_ANY));
- break;
- }
- break;
- }
- }
-
- opPos = nextStepPos;
- }
-
- opPos = nextOpPos;
- }
-
- return targetQNames;
- }
}
1.3 +8 -20
xml-xalan/java/src/org/apache/xpath/compiler/PsuedoNames.java
Index: PsuedoNames.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/compiler/PsuedoNames.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- PsuedoNames.java 2000/10/30 18:59:25 1.2
+++ PsuedoNames.java 2000/12/17 05:20:09 1.3
@@ -57,51 +57,39 @@
package org.apache.xpath.compiler;
/**
- * <meta name="usage" content="internal"/>
- * NEEDSDOC Class PsuedoNames <needs-comment/>
+ * This is used to represent names of nodes that may not be named, like a
+ * comment node.
*/
public class PsuedoNames
{
/**
- * <meta name="usage" content="advanced"/>
- * used mainly for keys in the pattern lookup table,
- * for those nodes that don't have unique lookup values.
+ * Psuedo name for a wild card pattern ('*').
*/
public static final String PSEUDONAME_ANY = "*";
/**
- * <meta name="usage" content="advanced"/>
- * used mainly for keys in the pattern lookup table,
- * for those nodes that don't have unique lookup values.
+ * Psuedo name for the root node.
*/
public static final String PSEUDONAME_ROOT = "/";
/**
- * <meta name="usage" content="advanced"/>
- * used mainly for keys in the pattern lookup table,
- * for those nodes that don't have unique lookup values.
+ * Psuedo name for a text node.
*/
public static final String PSEUDONAME_TEXT = "#text";
/**
- * <meta name="usage" content="advanced"/>
- * used mainly for keys in the pattern lookup table,
- * for those nodes that don't have unique lookup values.
+ * Psuedo name for a comment node.
*/
public static final String PSEUDONAME_COMMENT = "#comment";
/**
- * <meta name="usage" content="advanced"/>
- * used mainly for keys in the pattern lookup table,
- * for those nodes that don't have unique lookup values.
+ * Psuedo name for a processing instruction node.
*/
public static final String PSEUDONAME_PI = "#pi";
/**
- * <meta name="usage" content="advanced"/>
- * used mainly for keys in the pattern lookup table,
- * for those nodes that don't have unique lookup values.
+ * Psuedo name for an unknown type value.
*/
public static final String PSEUDONAME_OTHER = "*";
}
1.9 +80 -149
xml-xalan/java/src/org/apache/xpath/compiler/XPathParser.java
Index: XPathParser.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/compiler/XPathParser.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- XPathParser.java 2000/11/23 04:59:06 1.8
+++ XPathParser.java 2000/12/17 05:20:09 1.9
@@ -119,9 +119,9 @@
* Given an string, init an XPath object for selections,
* in order that a parse doesn't
* have to be done each time the expression is evaluated.
+ *
* @param compiler The compiler object.
- * @param expresson A String representing the OpMap.
- * NEEDSDOC @param expression
+ * @param expression A string conforming to the XPath grammar.
* @param namespaceContext An object that is able to resolve prefixes in
* the XPath to namespaces.
*
@@ -164,23 +164,14 @@
}
compiler.shrink();
- doStaticAnalysis(compiler);
}
/**
- * Analyze the XPath object to give optimization information.
- *
- * NEEDSDOC @param compiler
- */
- void doStaticAnalysis(Compiler compiler){}
-
- /**
* Given an string, init an XPath object for pattern matches,
* in order that a parse doesn't
* have to be done each time the expression is evaluated.
* @param compiler The XPath object to be initialized.
- * @param expresson A String representing the XPath.
- * NEEDSDOC @param expression
+ * @param expression A String representing the XPath.
* @param namespaceContext An object that is able to resolve prefixes in
* the XPath to namespaces.
*
@@ -229,36 +220,39 @@
m_ops.shrink();
}
- /** NEEDSDOC Field m_errorHandler */
- private ErrorListener m_errorHandler;
+ /** The error listener where syntax errors are to be sent. */
+ private ErrorListener m_errorListener;
/**
- * Allow an application to register an error event handler.
- *
- * NEEDSDOC @param handler
+ * Allow an application to register an error event handler, where syntax
+ * errors will be sent. If the error listener is not set, syntax errors
+ * will be sent to System.err.
+ *
+ * @param handler Reference to error listener where syntax errors will be
+ * sent.
*/
public void setErrorHandler(ErrorListener handler)
{
- m_errorHandler = handler;
+ m_errorListener = handler;
}
/**
- * Return the current error handler.
+ * Return the current error listener.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The error listener, which should not normally be null, but may
be.
*/
public ErrorListener getErrorListener()
{
- return m_errorHandler;
+ return m_errorListener;
}
/**
- * Check whether m_token==s. If m_token is null, returns false (or true if
s is also null);
- * do not throw an exception.
+ * Check whether m_token matches the target string.
*
- * NEEDSDOC @param s
+ * @param s A string reference or null.
*
- * NEEDSDOC ($objectName$) @return
+ * @return If m_token is null, returns false (or true if s is also null),
or
+ * return true if the current token matches the string, else false.
*/
final boolean tokenIs(String s)
{
@@ -266,12 +260,12 @@
}
/**
- * Check whether m_token==c. If m_token is null, returns false (or true if
c is also null);
- * do not throw an exception.
+ * Check whether m_tokenChar==c.
*
- * NEEDSDOC @param c
+ * @param c A character to be tested.
*
- * NEEDSDOC ($objectName$) @return
+ * @return If m_token is null, returns false, or return true if c matches
+ * the current token.
*/
final boolean tokenIs(char c)
{
@@ -281,13 +275,12 @@
/**
* Look ahead of the current token in order to
* make a branching decision.
- * @param s the string to compare it to.
*
- * NEEDSDOC @param c
+ * @param c the character to be tested for.
* @param n number of tokens to look ahead. Must be
* greater than 1.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true if the next token matches the character argument.
*/
final boolean lookahead(char c, int n)
{
@@ -313,6 +306,7 @@
/**
* Look behind the first character of the current token in order to
* make a branching decision.
+ *
* @param c the character to compare it to.
* @param n number of tokens to look behind. Must be
* greater than 1. Note that the look behind terminates
@@ -320,7 +314,8 @@
* character. Because of this, this method should only
* be used for pattern matching.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true if the token behind the current token matches the
character
+ * argument.
*/
private final boolean lookbehind(char c, int n)
{
@@ -354,11 +349,13 @@
/**
* look behind the current token in order to
* see if there is a useable token.
+ *
* @param n number of tokens to look behind. Must be
* greater than 1. Note that the look behind terminates
* at either the beginning of the string or on a '|'
* character. Because of this, this method should only
* be used for pattern matching.
+ *
* @return true if look behind has a token, false otherwise.
*/
private final boolean lookbehindHasToken(int n)
@@ -384,11 +381,13 @@
/**
* Look ahead of the current token in order to
* make a branching decision.
+ *
* @param s the string to compare it to.
* @param n number of tokens to lookahead. Must be
* greater than 1.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true if the token behind the current token matches the string
+ * argument.
*/
private final boolean lookahead(String s, int n)
{
@@ -430,9 +429,11 @@
/**
* Retrieve a token relative to the current token.
+ *
* @param i Position relative to current token.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The string at the given index, or null if the index is out
+ * of range.
*/
private final String getTokenRelative(int i)
{
@@ -477,7 +478,7 @@
* Consume an expected token, throwing an exception if it
* isn't there.
*
- * NEEDSDOC @param expected
+ * @param expected The string to be expected.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -500,7 +501,7 @@
* Consume an expected token, throwing an exception if it
* isn't there.
*
- * NEEDSDOC @param expected
+ * @param expected the character to be expected.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -523,10 +524,14 @@
/**
* Warn the user of a problem.
*
- * NEEDSDOC @param msg
- * NEEDSDOC @param args
+ * @param msg An error number that corresponds to one of the numbers found
+ * in [EMAIL PROTECTED]
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 TransformerException
+ * @throws TransformerException if the current ErrorListoner determines to
+ * throw an exception.
*/
void warn(int msg, Object[] args) throws TransformerException
{
@@ -542,7 +547,7 @@
else
{
// Should never happen.
- System.out.println(fmsg);
+ System.err.println(fmsg);
}
}
@@ -550,8 +555,10 @@
* Notify the user of an assertion error, and probably throw an
* exception.
*
- * NEEDSDOC @param b
- * NEEDSDOC @param msg
+ * @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.
*/
private void assert(boolean b, String msg)
{
@@ -570,10 +577,14 @@
* Notify the user of an error, and probably throw an
* exception.
*
- * NEEDSDOC @param msg
- * NEEDSDOC @param args
+ * @param msg An error number that corresponds to one of the numbers found
+ * in [EMAIL PROTECTED]
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 TransformerException
+ * @throws TransformerException if the current ErrorListoner determines to
+ * throw an exception.
*/
void error(int msg, Object[] args) throws TransformerException
{
@@ -588,7 +599,7 @@
}
else
{
- System.out.println(fmsg);
+ System.err.println(fmsg);
}
}
@@ -596,7 +607,8 @@
* Dump the remaining token queue.
* Thanks to Craig for this.
*
- * NEEDSDOC ($objectName$) @return
+ * @return A dump of the remaining token queue, which may be appended to
+ * an error message.
*/
protected String dumpRemainingTokenQueue()
{
@@ -628,9 +640,11 @@
/**
* Given a string, return the corresponding function token.
*
- * NEEDSDOC @param key
+ * @param key A local name of a function.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The function ID, which may correspond to one of the FUNC_XXX
+ * values found in [EMAIL PROTECTED]
org.apache.xpath.compiler.FunctionTable}, but may
+ * be a value installed by an external module.
*/
final int getFunctionToken(String key)
{
@@ -658,9 +672,9 @@
* the length value of the operation, but will update
* the length value for the total expression.
*
- * NEEDSDOC @param pos
- * NEEDSDOC @param length
- * NEEDSDOC @param op
+ * @param pos The position where the op is to be inserted.
+ * @param length The length of the operation space in the op map.
+ * @param op The op code to the inserted.
*/
void insertOp(int pos, int length, int op)
{
@@ -681,8 +695,8 @@
* the length value of the operation, and will update
* the length value for the total expression.
*
- * NEEDSDOC @param length
- * NEEDSDOC @param op
+ * @param length The length of the operation.
+ * @param op The op code to the inserted.
*/
void appendOp(int length, int op)
{
@@ -772,9 +786,9 @@
* | EqualityExpr '=' RelationalExpr
*
*
- * NEEDSDOC @param addPos
+ * @param addPos Position where expression is to be added, or -1 for
append.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the position at the end of the equality expression.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -832,9 +846,9 @@
* | RelationalExpr '>=' AdditiveExpr
*
*
- * NEEDSDOC @param addPos
+ * @param addPos Position where expression is to be added, or -1 for
append.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the position at the end of the relational expression.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -898,21 +912,19 @@
}
/**
- * XXXX.
- * @returns an Object which is either a String, a Number, a Boolean, or a
vector
- * of nodes.
* This has to handle construction of the operations so that they are
evaluated
* in pre-fix order. So, for 9+7-6, instead of |+|9|-|7|6|, this needs to
be
* evaluated as |-|+|9|7|6|.
- * @param addPos The position where the op should be inserted.
*
* AdditiveExpr ::= MultiplicativeExpr
* | AdditiveExpr '+' MultiplicativeExpr
* | AdditiveExpr '-' MultiplicativeExpr
*
*
- * NEEDSDOC ($objectName$) @return
+ * @param addPos Position where expression is to be added, or -1 for
append.
*
+ * @return the position at the end of the equality expression.
+ *
* @throws javax.xml.transform.TransformerException
*/
protected int AdditiveExpr(int addPos) throws
javax.xml.transform.TransformerException
@@ -957,13 +969,9 @@
}
/**
- * XXXX.
- * @returns an Object which is either a String, a Number, a Boolean, or a
vector
- * of nodes.
* This has to handle construction of the operations so that they are
evaluated
* in pre-fix order. So, for 9+7-6, instead of |+|9|-|7|6|, this needs to
be
* evaluated as |-|+|9|7|6|.
- * @param addPos The position where the op should be inserted.
*
* MultiplicativeExpr ::= UnaryExpr
* | MultiplicativeExpr MultiplyOperator UnaryExpr
@@ -971,8 +979,9 @@
* | MultiplicativeExpr 'mod' UnaryExpr
* | MultiplicativeExpr 'quo' UnaryExpr
*
+ * @param addPos Position where expression is to be added, or -1 for
append.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the position at the end of the equality expression.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -1042,9 +1051,6 @@
}
/**
- * XXXX.
- * @returns an Object which is either a String, a Number, a Boolean, or a
vector
- * of nodes.
*
* UnaryExpr ::= UnionExpr
* | '-' UnaryExpr
@@ -1187,81 +1193,6 @@
}
/**
- * Analyze a union pattern and tell if the axes are
- * all descendants.
- * (Move to XPath?)
- *
- * NEEDSDOC @param opmap
- * NEEDSDOC @param opPos
- *
- * NEEDSDOC ($objectName$) @return
- */
- private static boolean isLocationPathSimpleFollowing(OpMap opmap, int
opPos)
- {
-
- if (true)
- {
-
- // int posOfLastOp = OpMap.getNextOpPos(opPos)-1;
- opPos = OpMap.getFirstChildPos(opPos);
-
- // step
- int stepType = opmap.m_opMap[opPos];
-
- // make sure all step types are going forwards
- switch (stepType)
- {
- case OpCodes.FROM_SELF :
- case OpCodes.FROM_ATTRIBUTES :
- case OpCodes.FROM_CHILDREN :
- case OpCodes.FROM_DESCENDANTS :
- case OpCodes.FROM_DESCENDANTS_OR_SELF :
- case OpCodes.FROM_FOLLOWING :
- case OpCodes.FROM_FOLLOWING_SIBLINGS :
- if (opmap.m_opMap[opmap.getNextOpPos(opPos)] == OpCodes.ENDOP)
- {
-
- // Add the length of the step itself, plus the length of the op,
- // and two length arguments, to the op position.
- opPos = (opmap.getArgLengthOfStep(opPos)
- + opmap.getFirstChildPosOfStep(opPos));
-
- int nextStepType = opmap.m_opMap[opPos];
-
- if (OpCodes.OP_PREDICATE == nextStepType)
- {
- int firstPredPos = opPos + 2;
- int predicateType = opmap.m_opMap[firstPredPos];
-
- if ((OpCodes.OP_NUMBERLIT == predicateType)
- || (OpCodes.OP_NUMBER == predicateType)
- || (FunctionTable.FUNC_NUMBER == predicateType))
- {
- return false;
- }
-
- opPos = opmap.getNextOpPos(opPos);
- nextStepType = opmap.m_opMap[opPos];
-
- // Multiple predicates?
- if (OpCodes.OP_PREDICATE == nextStepType)
- return false;
- }
-
- return true;
- }
- break;
- }
-
- return false;
- }
- else
- {
- return false;
- }
- }
-
- /**
* PathExpr ::= LocationPath
* | FilterExpr
* | FilterExpr '/' RelativeLocationPath
@@ -1716,7 +1647,7 @@
* Basis ::= AxisName '::' NodeTest
* | AbbreviatedBasis
*
- * NEEDSDOC ($objectName$) @return
+ * @return FROM_XXX axes type, found in [EMAIL PROTECTED]
org.apache.xpath.compiler.Keywords}.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -1744,7 +1675,7 @@
* | NodeType '(' ')'
* | 'processing-instruction' '(' Literal ')'
*
- * NEEDSDOC @param axesType
+ * @param axesType FROM_XXX axes type, found in [EMAIL PROTECTED]
org.apache.xpath.compiler.Keywords}.
*
* @throws javax.xml.transform.TransformerException
*/
