org.apache.xpath.compiler
Class XPathParser

java.lang.Object
  org.apache.xpath.compiler.XPathParser

public class XPathParser

extends Object

Tokenizes and parses XPath expressions. This should really be named XPathParserImpl, and may be renamed in the future.

Field Summary

static String	CONTINUE_AFTER_FATAL_ERROR
protected static int	FILTER_MATCH_FAILED Results from checking FilterExpr syntax
protected static int	FILTER_MATCH_PREDICATES
protected static int	FILTER_MATCH_PRIMARY
private javax.xml.transform.ErrorListener	m_errorListener The error listener where syntax errors are to be sent.
(package private) PrefixResolver	m_namespaceContext The prefix resolver to map prefixes to namespaces in the OpMap.
private OpMap	m_ops The XPath to be processed.
(package private) int	m_queueMark The position in the token queue is tracked by m_queueMark.
(package private) javax.xml.transform.SourceLocator	m_sourceLocator The source location of the XPath.
(package private) String	m_token The next token in the pattern.
(package private) char	m_tokenChar The first char in m_token, the theory being that this is an optimization because we won't have to do charAt(0) as often.

Constructor Summary

XPathParser(javax.xml.transform.ErrorListener errorListener, javax.xml.transform.SourceLocator sourceLocator)
The parser constructor.

Method Summary

protected boolean	AbbreviatedNodeTestStep(boolean isLeadingSlashPermitted) AbbreviatedNodeTestStep ::= '@'?
protected int	AdditiveExpr(int addPos) This has to handle construction of the operations so that they are evaluated in pre-fix order.
protected void	AndExpr() AndExpr ::= EqualityExpr | AndExpr 'and' EqualityExpr
(package private) void	appendOp(int length, int op) Insert room for operation.
protected void	Argument() Argument ::= Expr
private void	assertion(boolean b, String msg) Notify the user of an assertion error, and probably throw an exception.
protected int	AxisName() Basis ::= AxisName '::' NodeTest | AbbreviatedBasis
protected void	Basis() Basis ::= AxisName '::' NodeTest | AbbreviatedBasis
protected void	BooleanExpr() StringExpr ::= Expr
private void	consumeExpected(char expected) Consume an expected token, throwing an exception if it isn't there.
private void	consumeExpected(String expected) Consume an expected token, throwing an exception if it isn't there.
protected String	dumpRemainingTokenQueue() Dump the remaining token queue.
protected int	EqualityExpr(int addPos)
(package private) void	error(String msg, Object[] args) Notify the user of an error, and probably throw an exception.
protected void	Expr() Expr ::= OrExpr
protected int	FilterExpr() FilterExpr ::= PrimaryExpr | FilterExpr Predicate
protected boolean	FunctionCall() FunctionCall ::= FunctionName '(' ( Argument ( ',' Argument)*)?
javax.xml.transform.ErrorListener	getErrorListener() Return the current error listener.
(package private) int	getFunctionToken(String key) Given a string, return the corresponding function token.
private String	getTokenRelative(int i) Retrieve a token relative to the current token.
protected void	IdKeyPattern() IdKeyPattern ::= 'id' '(' Literal ')' | 'key' '(' Literal ',' Literal ')' (Also handle doc())
void	initMatchPattern(Compiler compiler, String expression, PrefixResolver namespaceContext) 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.
void	initXPath(Compiler compiler, String expression, PrefixResolver namespaceContext) 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.
(package private) void	insertOp(int pos, int length, int op) Insert room for operation.
protected void	Literal() The value of the Literal is the sequence of characters inside the " or ' characters>.
protected void	LocationPath() LocationPath ::= RelativeLocationPath | AbsoluteLocationPath
protected void	LocationPathPattern() LocationPathPattern ::= '/' RelativePathPattern?
(package private) boolean	lookahead(char c, int n) Look ahead of the current token in order to make a branching decision.
private boolean	lookahead(String s, int n) Look ahead of the current token in order to make a branching decision.
private boolean	lookbehind(char c, int n) Look behind the first character of the current token in order to make a branching decision.
private boolean	lookbehindHasToken(int n) look behind the current token in order to see if there is a useable token.
protected int	MultiplicativeExpr(int addPos) This has to handle construction of the operations so that they are evaluated in pre-fix order.
protected void	NCName() NCName ::= (Letter | '_') (NCNameChar) NCNameChar ::= Letter | Digit | '.' | '-' | '_' | CombiningChar | Extender
private void	nextToken() Retrieve the next token from the command and store it in m_token string.
protected void	NodeTest(int axesType) NodeTest ::= WildcardName | NodeType '(' ')' | 'processing-instruction' '(' Literal ')'
protected void	Number() Number ::= [0-9]+('
protected void	NumberExpr() NumberExpr ::= Expr
protected void	OrExpr() OrExpr ::= AndExpr | OrExpr 'or' AndExpr
protected void	PathExpr() PathExpr ::= LocationPath | FilterExpr | FilterExpr '/' RelativeLocationPath | FilterExpr '//' RelativeLocationPath
protected void	Pattern() Pattern ::= LocationPathPattern | Pattern '|' LocationPathPattern
protected void	Predicate() Predicate ::= '[' PredicateExpr ']'
protected void	PredicateExpr() PredicateExpr ::= Expr
private void	prevToken() Retrieve the previous token from the command and store it in m_token string.
protected boolean	PrimaryExpr() PrimaryExpr ::= VariableReference | '(' Expr ')' | Literal | Number | FunctionCall
protected void	QName() QName ::= (Prefix ':')?
protected int	RelationalExpr(int addPos) .
protected boolean	RelativeLocationPath() RelativeLocationPath ::= Step | RelativeLocationPath '/' Step | AbbreviatedRelativeLocationPath
protected void	RelativePathPattern() RelativePathPattern ::= StepPattern | RelativePathPattern '/' StepPattern | RelativePathPattern '//' StepPattern
void	setErrorHandler(javax.xml.transform.ErrorListener handler) Allow an application to register an error event handler, where syntax errors will be sent.
protected boolean	Step() Step ::= Basis Predicate | AbbreviatedStep
protected boolean	StepPattern(boolean isLeadingSlashPermitted) StepPattern ::= AbbreviatedNodeTestStep
protected void	StringExpr() StringExpr ::= Expr
(package private) boolean	tokenIs(char c) Check whether m_tokenChar==c.
(package private) boolean	tokenIs(String s) Check whether m_token matches the target string.
protected void	UnaryExpr() UnaryExpr ::= UnionExpr | '-' UnaryExpr
protected void	UnionExpr() The context of the right hand side expressions is the context of the left hand side expression.
(package private) void	warn(String msg, Object[] args) Warn the user of a problem.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONTINUE_AFTER_FATAL_ERROR

public static final String CONTINUE_AFTER_FATAL_ERROR

See Also:

Constant Field Values

m_ops

private OpMap m_ops

The XPath to be processed.

m_token

transient String m_token

The next token in the pattern.

m_tokenChar

transient char m_tokenChar

The first char in m_token, the theory being that this is an optimization because we won't have to do charAt(0) as often.

m_queueMark

int m_queueMark

The position in the token queue is tracked by m_queueMark.

FILTER_MATCH_FAILED

protected static final int FILTER_MATCH_FAILED

Results from checking FilterExpr syntax

See Also:

Constant Field Values

FILTER_MATCH_PRIMARY

protected static final int FILTER_MATCH_PRIMARY

See Also:

Constant Field Values

FILTER_MATCH_PREDICATES

protected static final int FILTER_MATCH_PREDICATES

See Also:

Constant Field Values

m_namespaceContext

PrefixResolver m_namespaceContext

The prefix resolver to map prefixes to namespaces in the OpMap.

m_errorListener

private javax.xml.transform.ErrorListener m_errorListener

The error listener where syntax errors are to be sent.

m_sourceLocator

javax.xml.transform.SourceLocator m_sourceLocator

The source location of the XPath.

Constructor Detail

XPathParser

public XPathParser(javax.xml.transform.ErrorListener errorListener,
                   javax.xml.transform.SourceLocator sourceLocator)

The parser constructor.

Method Detail

initXPath

public void initXPath(Compiler compiler,
                      String expression,
                      PrefixResolver namespaceContext)
               throws javax.xml.transform.TransformerException

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.

Parameters:

compiler - The compiler object.

expression - A string conforming to the XPath grammar.

namespaceContext - An object that is able to resolve prefixes in the XPath to namespaces.

Throws:

javax.xml.transform.TransformerException

initMatchPattern

public void initMatchPattern(Compiler compiler,
                             String expression,
                             PrefixResolver namespaceContext)
                      throws javax.xml.transform.TransformerException

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.

Parameters:

compiler - The XPath object to be initialized.

expression - A String representing the XPath.

namespaceContext - An object that is able to resolve prefixes in the XPath to namespaces.

Throws:

javax.xml.transform.TransformerException

setErrorHandler

public void setErrorHandler(javax.xml.transform.ErrorListener 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.

Parameters:

handler - Reference to error listener where syntax errors will be sent.

getErrorListener

public javax.xml.transform.ErrorListener getErrorListener()

Return the current error listener.

Returns:

The error listener, which should not normally be null, but may be.

tokenIs

final boolean tokenIs(String s)

Check whether m_token matches the target string.

Parameters:

s - A string reference or null.

Returns:

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.

tokenIs

final boolean tokenIs(char c)

Check whether m_tokenChar==c.

Parameters:

c - A character to be tested.

Returns:

If m_token is null, returns false, or return true if c matches the current token.

lookahead

final boolean lookahead(char c,
                        int n)

Look ahead of the current token in order to make a branching decision.

Parameters:

c - the character to be tested for.

n - number of tokens to look ahead. Must be greater than 1.

Returns:

true if the next token matches the character argument.

lookbehind

private final boolean lookbehind(char c,
                                 int n)

Look behind the first character of the current token in order to make a branching decision.

Parameters:

c - the character to compare it to.

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.

Returns:

true if the token behind the current token matches the character argument.

lookbehindHasToken

private final boolean lookbehindHasToken(int n)

look behind the current token in order to see if there is a useable token.

Parameters:

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.

Returns:

true if look behind has a token, false otherwise.

lookahead

private final boolean lookahead(String s,
                                int n)

Look ahead of the current token in order to make a branching decision.

Parameters:

s - the string to compare it to.

n - number of tokens to lookahead. Must be greater than 1.

Returns:

true if the token behind the current token matches the string argument.

nextToken

private final void nextToken()

Retrieve the next token from the command and store it in m_token string.

getTokenRelative

private final String getTokenRelative(int i)

Retrieve a token relative to the current token.

Parameters:

i - Position relative to current token.

Returns:

The string at the given index, or null if the index is out of range.

prevToken

private final void prevToken()

Retrieve the previous token from the command and store it in m_token string.

consumeExpected

private final void consumeExpected(String expected)
                            throws javax.xml.transform.TransformerException

Consume an expected token, throwing an exception if it isn't there.

Parameters:

expected - The string to be expected.

Throws:

javax.xml.transform.TransformerException

consumeExpected

private final void consumeExpected(char expected)
                            throws javax.xml.transform.TransformerException

Consume an expected token, throwing an exception if it isn't there.

Parameters:

expected - the character to be expected.

Throws:

javax.xml.transform.TransformerException

warn

void warn(String msg,
          Object[] args)
    throws javax.xml.transform.TransformerException

Warn the user of a problem.

Parameters:

msg - An error msgkey that corresponds to one of the constants found in XPATHErrorResources, which is a key for a format string.

args - An array of arguments represented in the format string, which may be null.

Throws:

javax.xml.transform.TransformerException - if the current ErrorListoner determines to throw an exception.

assertion

private void assertion(boolean b,
                       String msg)

Notify the user of an assertion error, and probably throw an exception.

Parameters:

b - If false, a runtime exception will be thrown.

msg - The assertion message, which should be informative.

Throws:

RuntimeException - if the b argument is false.

error

void error(String msg,
           Object[] args)
     throws javax.xml.transform.TransformerException

Notify the user of an error, and probably throw an exception.

Parameters:

msg - An error msgkey that corresponds to one of the constants found in XPATHErrorResources, which is a key for a format string.

args - An array of arguments represented in the format string, which may be null.

Throws:

javax.xml.transform.TransformerException - if the current ErrorListoner determines to throw an exception.

dumpRemainingTokenQueue

protected String dumpRemainingTokenQueue()

Dump the remaining token queue. Thanks to Craig for this.

Returns:

A dump of the remaining token queue, which may be appended to an error message.

getFunctionToken

final int getFunctionToken(String key)

Given a string, return the corresponding function token.

Parameters:

key - A local name of a function.

Returns:

The function ID, which may correspond to one of the FUNC_XXX values found in FunctionTable, but may be a value installed by an external module.

insertOp

void insertOp(int pos,
              int length,
              int op)

Insert room for operation. This will NOT set the length value of the operation, but will update the length value for the total expression.

Parameters:

pos - The position where the op is to be inserted.

length - The length of the operation space in the op map.

op - The op code to the inserted.

appendOp

void appendOp(int length,
              int op)

Insert room for operation. This WILL set the length value of the operation, and will update the length value for the total expression.

Parameters:

length - The length of the operation.

op - The op code to the inserted.

Expr

protected void Expr()
             throws javax.xml.transform.TransformerException

Expr ::= OrExpr

Throws:

javax.xml.transform.TransformerException

OrExpr

protected void OrExpr()
               throws javax.xml.transform.TransformerException

OrExpr ::= AndExpr | OrExpr 'or' AndExpr

Throws:

javax.xml.transform.TransformerException

AndExpr

protected void AndExpr()
                throws javax.xml.transform.TransformerException

AndExpr ::= EqualityExpr | AndExpr 'and' EqualityExpr

Throws:

javax.xml.transform.TransformerException

EqualityExpr

protected int EqualityExpr(int addPos)
                    throws javax.xml.transform.TransformerException

Parameters:

addPos - Position where expression is to be added, or -1 for append.

Returns:

the position at the end of the equality expression.

Throws:

javax.xml.transform.TransformerException

RelationalExpr

protected int RelationalExpr(int addPos)
                      throws javax.xml.transform.TransformerException

.

Parameters:

addPos - Position where expression is to be added, or -1 for append.

Returns:

the position at the end of the relational expression.

Throws:

javax.xml.transform.TransformerException

AdditiveExpr

protected int AdditiveExpr(int addPos)
                    throws javax.xml.transform.TransformerException

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|. AdditiveExpr ::= MultiplicativeExpr | AdditiveExpr '+' MultiplicativeExpr | AdditiveExpr '-' MultiplicativeExpr

Parameters:

addPos - Position where expression is to be added, or -1 for append.

Returns:

the position at the end of the equality expression.

Throws:

javax.xml.transform.TransformerException

MultiplicativeExpr

protected int MultiplicativeExpr(int addPos)
                          throws javax.xml.transform.TransformerException

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|. MultiplicativeExpr ::= UnaryExpr | MultiplicativeExpr MultiplyOperator UnaryExpr | MultiplicativeExpr 'div' UnaryExpr | MultiplicativeExpr 'mod' UnaryExpr | MultiplicativeExpr 'quo' UnaryExpr

Parameters:

addPos - Position where expression is to be added, or -1 for append.

Returns:

the position at the end of the equality expression.

Throws:

javax.xml.transform.TransformerException

UnaryExpr

protected void UnaryExpr()
                  throws javax.xml.transform.TransformerException

UnaryExpr ::= UnionExpr | '-' UnaryExpr

Throws:

javax.xml.transform.TransformerException

StringExpr

protected void StringExpr()
                   throws javax.xml.transform.TransformerException

StringExpr ::= Expr

Throws:

javax.xml.transform.TransformerException

BooleanExpr

protected void BooleanExpr()
                    throws javax.xml.transform.TransformerException

StringExpr ::= Expr

Throws:

javax.xml.transform.TransformerException

NumberExpr

protected void NumberExpr()
                   throws javax.xml.transform.TransformerException

NumberExpr ::= Expr

Throws:

javax.xml.transform.TransformerException

UnionExpr

protected void UnionExpr()
                  throws javax.xml.transform.TransformerException

The context of the right hand side expressions is the context of the left hand side expression. The results of the right hand side expressions are node sets. The result of the left hand side UnionExpr is the union of the results of the right hand side expressions. UnionExpr ::= PathExpr | UnionExpr '|' PathExpr

Throws:

javax.xml.transform.TransformerException

PathExpr

protected void PathExpr()
                 throws javax.xml.transform.TransformerException

PathExpr ::= LocationPath | FilterExpr | FilterExpr '/' RelativeLocationPath | FilterExpr '//' RelativeLocationPath

Throws:

XSLProcessorException - thrown if the active ProblemListener and XPathContext decide the error condition is severe enough to halt processing.

javax.xml.transform.TransformerException

FilterExpr

protected int FilterExpr()
                  throws javax.xml.transform.TransformerException

FilterExpr ::= PrimaryExpr | FilterExpr Predicate

Returns:

FILTER_MATCH_PREDICATES, if this method successfully matched a FilterExpr with one or more Predicates; FILTER_MATCH_PRIMARY, if this method successfully matched a FilterExpr that was just a PrimaryExpr; or FILTER_MATCH_FAILED, if this method did not match a FilterExpr

Throws:

XSLProcessorException - thrown if the active ProblemListener and XPathContext decide the error condition is severe enough to halt processing.

javax.xml.transform.TransformerException

PrimaryExpr

protected boolean PrimaryExpr()
                       throws javax.xml.transform.TransformerException

PrimaryExpr ::= VariableReference | '(' Expr ')' | Literal | Number | FunctionCall

Returns:

true if this method successfully matched a PrimaryExpr

Throws:

javax.xml.transform.TransformerException

Argument

protected void Argument()
                 throws javax.xml.transform.TransformerException

Argument ::= Expr

Throws:

javax.xml.transform.TransformerException

FunctionCall

protected boolean FunctionCall()
                        throws javax.xml.transform.TransformerException

FunctionCall ::= FunctionName '(' ( Argument ( ',' Argument)*)? ')'

Returns:

true if, and only if, a FunctionCall was matched

Throws:

javax.xml.transform.TransformerException

LocationPath

protected void LocationPath()
                     throws javax.xml.transform.TransformerException

LocationPath ::= RelativeLocationPath | AbsoluteLocationPath

Throws:

javax.xml.transform.TransformerException

RelativeLocationPath

protected boolean RelativeLocationPath()
                                throws javax.xml.transform.TransformerException

RelativeLocationPath ::= Step | RelativeLocationPath '/' Step | AbbreviatedRelativeLocationPath

Throws:

javax.xml.transform.TransformerException

Step

protected boolean Step()
                throws javax.xml.transform.TransformerException

Step ::= Basis Predicate | AbbreviatedStep

Throws:

javax.xml.transform.TransformerException

Basis

protected void Basis()
              throws javax.xml.transform.TransformerException

Basis ::= AxisName '::' NodeTest | AbbreviatedBasis

Throws:

javax.xml.transform.TransformerException

AxisName

protected int AxisName()
                throws javax.xml.transform.TransformerException

Basis ::= AxisName '::' NodeTest | AbbreviatedBasis

Returns:

FROM_XXX axes type, found in Keywords.

Throws:

javax.xml.transform.TransformerException

NodeTest

protected void NodeTest(int axesType)
                 throws javax.xml.transform.TransformerException

NodeTest ::= WildcardName | NodeType '(' ')' | 'processing-instruction' '(' Literal ')'

Parameters:

axesType - FROM_XXX axes type, found in Keywords.

Throws:

javax.xml.transform.TransformerException

Predicate

protected void Predicate()
                  throws javax.xml.transform.TransformerException

Predicate ::= '[' PredicateExpr ']'

Throws:

javax.xml.transform.TransformerException

PredicateExpr

protected void PredicateExpr()
                      throws javax.xml.transform.TransformerException

PredicateExpr ::= Expr

Throws:

javax.xml.transform.TransformerException

QName

protected void QName()
              throws javax.xml.transform.TransformerException

QName ::= (Prefix ':')? LocalPart Prefix ::= NCName LocalPart ::= NCName

Throws:

javax.xml.transform.TransformerException

NCName

protected void NCName()

NCName ::= (Letter | '_') (NCNameChar) NCNameChar ::= Letter | Digit | '.' | '-' | '_' | CombiningChar | Extender

Literal

protected void Literal()
                throws javax.xml.transform.TransformerException

The value of the Literal is the sequence of characters inside the " or ' characters>. Literal ::= '"' [^"]* '"' | "'" [^']* "'"

Throws:

javax.xml.transform.TransformerException

Number

protected void Number()
               throws javax.xml.transform.TransformerException

Number ::= [0-9]+('.'[0-9]+)? | '.'[0-9]+

Throws:

javax.xml.transform.TransformerException

Pattern

protected void Pattern()
                throws javax.xml.transform.TransformerException

Pattern ::= LocationPathPattern | Pattern '|' LocationPathPattern

Throws:

javax.xml.transform.TransformerException

LocationPathPattern

protected void LocationPathPattern()
                            throws javax.xml.transform.TransformerException

LocationPathPattern ::= '/' RelativePathPattern? | IdKeyPattern (('/' | '//') RelativePathPattern)? | '//'? RelativePathPattern

Throws:

javax.xml.transform.TransformerException

IdKeyPattern

protected void IdKeyPattern()
                     throws javax.xml.transform.TransformerException

IdKeyPattern ::= 'id' '(' Literal ')' | 'key' '(' Literal ',' Literal ')' (Also handle doc())

Throws:

javax.xml.transform.TransformerException

RelativePathPattern

protected void RelativePathPattern()
                            throws javax.xml.transform.TransformerException

RelativePathPattern ::= StepPattern | RelativePathPattern '/' StepPattern | RelativePathPattern '//' StepPattern

Throws:

javax.xml.transform.TransformerException

StepPattern

protected boolean StepPattern(boolean isLeadingSlashPermitted)
                       throws javax.xml.transform.TransformerException

StepPattern ::= AbbreviatedNodeTestStep

Parameters:

isLeadingSlashPermitted - a boolean indicating whether a slash can appear at the start of this step

Returns:

boolean indicating whether a slash following the step was consumed

Throws:

javax.xml.transform.TransformerException

AbbreviatedNodeTestStep

protected boolean AbbreviatedNodeTestStep(boolean isLeadingSlashPermitted)
                                   throws javax.xml.transform.TransformerException

AbbreviatedNodeTestStep ::= '@'? NodeTest Predicate

Parameters:

isLeadingSlashPermitted - a boolean indicating whether a slash can appear at the start of this step

Returns:

boolean indicating whether a slash following the step was consumed

Throws:

javax.xml.transform.TransformerException