org.exist.xquery
Interface Expression

All Known Implementing Classes:
AbstractExpression

public interface Expression

Base interface implemented by all classes which are part of an XQuery/XPath expression. The main method is eval(Sequence, Item). Please read the description there.


Field Summary
static int DOT_TEST
           
static int EXPRESSION_ID_INVALID
          Marks an invalid expression id.
static int IGNORE_CONTEXT
           
static int IN_PREDICATE
          Indicates that the expression is within a predicate or the where clause of a FLWOR.
static int IN_UPDATE
          Indicates that the expression is used within an update statement.
static int IN_WHERE_CLAUSE
          Indicates that the expression is within a where clause of a FLWOR.
static int NO_CONTEXT_ID
          Indicates that no context id is supplied to an expression.
static int SINGLE_STEP_EXECUTION
          Indicates that the query engine will call the expression once for every item in the context sequence.
 
Method Summary
 void accept(ExpressionVisitor visitor)
          Start traversing the expression tree using the specified ExpressionVisitor.
 void analyze(AnalyzeContextInfo contextInfo)
          Statically analyze the expression and its subexpressions.
 void dump(ExpressionDumper dumper)
          Write a diagnostic dump of the expression to the passed ExpressionDumper.
 Sequence eval(Sequence contextSequence)
          Evaluate the expression represented by this object.
 Sequence eval(Sequence contextSequence, Item contextItem)
          Evaluate the expression represented by this object.
 XQueryAST getASTNode()
          Returns the XQueryAST node from which this expression has been constructed by the parser.
 int getCardinality()
          The expected cardinality of the return value of the expression.
 DocumentSet getContextDocSet()
           
 int getContextId()
           
 int getDependencies()
          Returns a set of bit-flags, indicating some of the parameters on which this expression depends.
 int getExpressionId()
          Returns an id which uniquely identifies this expression within the compiled expression tree of the query.
 void resetState()
          Called to inform an expression that it should reset to its initial state.
 int returnsType()
          The static return type of the expression.
 void setASTNode(XQueryAST ast)
           
 void setContextDocSet(DocumentSet contextSet)
           
 void setPrimaryAxis(int axis)
           
 

Field Detail

SINGLE_STEP_EXECUTION

public static final int SINGLE_STEP_EXECUTION
Indicates that the query engine will call the expression once for every item in the context sequence. This is what you would expect to be the normal behaviour of an XQuery processor. However, eXist tries to process some types of expressions in one single step for the whole input sequence. So if the flag is not set, the expression is only called once.

See Also:
Constant Field Values

IN_PREDICATE

public static final int IN_PREDICATE
Indicates that the expression is within a predicate or the where clause of a FLWOR.

See Also:
Constant Field Values

IN_WHERE_CLAUSE

public static final int IN_WHERE_CLAUSE
Indicates that the expression is within a where clause of a FLWOR. This flag will be set in addition to IN_PREDICATE.

See Also:
Constant Field Values

IN_UPDATE

public static final int IN_UPDATE
Indicates that the expression is used within an update statement. Subexpressions should not cache any relevant data as it may be subject to change.

See Also:
Constant Field Values

DOT_TEST

public static final int DOT_TEST
See Also:
Constant Field Values

NO_CONTEXT_ID

public static final int NO_CONTEXT_ID
Indicates that no context id is supplied to an expression.

See Also:
Constant Field Values

IGNORE_CONTEXT

public static final int IGNORE_CONTEXT
See Also:
Constant Field Values

EXPRESSION_ID_INVALID

public static final int EXPRESSION_ID_INVALID
Marks an invalid expression id.

See Also:
Constant Field Values
Method Detail

getExpressionId

public int getExpressionId()
Returns an id which uniquely identifies this expression within the compiled expression tree of the query.

Returns:
unique id or EXPRESSION_ID_INVALID

analyze

public void analyze(AnalyzeContextInfo contextInfo)
             throws XPathException
Statically analyze the expression and its subexpressions. During the static analysis phase, the query engine can detect unknown variables and some type errors.

Throws:
XPathException

eval

public Sequence eval(Sequence contextSequence,
                     Item contextItem)
              throws XPathException
Evaluate the expression represented by this object. Depending on the context in which this expression is executed, either the context sequence, the context item or both of them may be set. An implementing class should know how to handle this. The general contract is as follows: if the Dependency.CONTEXT_ITEM bit is set in the bit field returned by getDependencies(), the eval method will be called once for every item in the context sequence. The contextItem parameter will be set to the current item. Otherwise, the eval method will only be called once for the whole context sequence and contextItem will be null. eXist tries to process the entire context set in one, single step whenever possible. Thus, most classes only expect context to contain a list of nodes which represents the current context of the expression. The position() function in XPath is an example for an expression, which requires both, context sequence and context item to be set. The context sequence might be a node set, a sequence of atomic values or a single node or atomic value.

Parameters:
contextSequence - the current context sequence.
contextItem - a single item, taken from context. This defines the item, the expression should work on.
Throws:
XPathException

eval

public Sequence eval(Sequence contextSequence)
              throws XPathException
Evaluate the expression represented by this object. An overloaded method which just passes the context sequence depending on the expression context.

Throws:
XPathException

setPrimaryAxis

public void setPrimaryAxis(int axis)

returnsType

public int returnsType()
The static return type of the expression. This method should return one of the type constants defined in class Type. If the return type cannot be determined statically, return Type.ITEM.


getCardinality

public int getCardinality()
The expected cardinality of the return value of the expression. Should return a bit mask with bits set as defined in class Cardinality.


getDependencies

public int getDependencies()
Returns a set of bit-flags, indicating some of the parameters on which this expression depends. The flags are defined in Dependency.

Returns:
set of bit-flags

resetState

public void resetState()
Called to inform an expression that it should reset to its initial state. All cached data in the expression object should be dropped. For example, the document() function calls this method whenever the input document set has changed.


accept

public void accept(ExpressionVisitor visitor)
Start traversing the expression tree using the specified ExpressionVisitor.

Parameters:
visitor -

dump

public void dump(ExpressionDumper dumper)
Write a diagnostic dump of the expression to the passed ExpressionDumper.

Parameters:
dumper - the expression dumper to write to

setContextDocSet

public void setContextDocSet(DocumentSet contextSet)

getContextId

public int getContextId()

getContextDocSet

public DocumentSet getContextDocSet()

getASTNode

public XQueryAST getASTNode()
Returns the XQueryAST node from which this expression has been constructed by the parser. This node contains location information (line number and column) important for error reports.

Returns:
XQueryAST node

setASTNode

public void setASTNode(XQueryAST ast)


Copyright (C) Wolfgang Meier. All rights reserved.