org.basex.query.expr
Class Expr

java.lang.Object
  extended by org.basex.data.ExprInfo
      extended by org.basex.query.expr.Expr
Direct Known Subclasses:
ParseExpr, Value

public abstract class Expr
extends ExprInfo

Abstract class for representing XQuery expressions. Expression are divided into ParseExpr and Value classes.

Author:
BaseX Team 2005-12, BSD License, Christian Gruen

Nested Class Summary
static class Expr.Flag
          Flags that influence query compilation.
 
Constructor Summary
Expr()
           
 
Method Summary
abstract  boolean accept(ASTVisitor visitor)
          Traverses this expression, notifying the visitor of declared and used variables, and checking the tree for other recursive properties.
 Expr addText(QueryContext ctx)
          Optionally adds a text node to an expression for potential index rewriting.
abstract  void checkUp()
          Checks if all updating expressions are correctly placed.
 Expr compEbv(QueryContext ctx)
          This method is overwritten by CmpG, CmpV and FNSimple.
abstract  Expr compile(QueryContext ctx, VarScope scp)
          Compiles and optimizes the expression, assigns data types and cardinalities.
 Expr copy(QueryContext ctx, VarScope scp)
          Copies an expression.
abstract  Expr copy(QueryContext ctx, VarScope scp, IntObjMap<Var> vs)
          Copies an expression.
abstract  VarUsage count(Var v)
          Checks how often a variable is used in this expression.
abstract  Item ebv(QueryContext ctx, InputInfo ii)
          Checks if the iterator can be dissolved into an effective boolean value.
abstract  int exprSize()
          Counts the number of expressions in this expression's sub-tree.
abstract  boolean has(Expr.Flag flag)
          Indicates if an expression has the specified compiler property.
 boolean hasFreeVars()
          Checks if this expression has free variables.
 boolean indexAccessible(IndexCosts ic)
          Checks if an expression can be rewritten to an index access.
 Expr indexEquivalent(IndexCosts ic)
          Returns an equivalent expression which accesses an index structure.
abstract  Expr inline(QueryContext ctx, VarScope scp, Var v, Expr e)
          Inlines an expression into this one, replacing all references to the given variable.
protected static boolean inlineAll(QueryContext ctx, VarScope scp, Expr[] arr, Var v, Expr e)
          Inlines the given expression into all elements of the given array.
 boolean isEmpty()
          Tests if this is an empty sequence.
 boolean isFunction(Function f)
          Checks if this expression is a certain function.
 boolean isItem()
          Tests if this is an item.
 boolean isVacuous()
          Tests if this is a vacuous expression (empty sequence or error function).
 boolean isValue()
          Tests if this is a value.
abstract  Item item(QueryContext ctx, InputInfo ii)
          Evaluates the expression and returns the resulting item or a null reference, if the expression yields an empty sequence.
abstract  Iter iter(QueryContext ctx)
          Evaluates the expression and returns an iterator on the resulting items.
 boolean iterable()
          Returns true if the expression is iterable, i.e., if it will not contain any duplicate nodes and if all nodes will be are sorted.
 Expr markTailCalls()
          Finds and marks tail calls, enabling TCO.
 Expr optimize(QueryContext ctx, VarScope scp)
          Optimizes an already compiled expression without recompiling its sub-expressions.
abstract  boolean removable(Var v)
          Checks if the specified variable is replaceable by a context item.
 boolean sameAs(Expr cmp)
          Compares the current and specified expression for equality.
abstract  long size()
          Returns the sequence size or 1.
abstract  Item test(QueryContext ctx, InputInfo ii)
          Performs a predicate test and returns the item if test was successful.
abstract  SeqType type()
          Returns the static type of the evaluated value.
 boolean uses(Var v)
          Checks if the given variable is used by this expression.
abstract  Value value(QueryContext ctx)
          Evaluates the expression and returns the resulting value.
protected static boolean visitAll(ASTVisitor visitor, Expr... exprs)
          Visit all given expressions with the given visitor.
 
Methods inherited from class org.basex.data.ExprInfo
addPlan, addPlan, description, info, plan, planAttr, planElem, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Expr

public Expr()
Method Detail

checkUp

public abstract void checkUp()
                      throws QueryException
Checks if all updating expressions are correctly placed. This function is only called if any updating expression was found in the query.

Throws:
QueryException - query exception

compile

public abstract Expr compile(QueryContext ctx,
                             VarScope scp)
                      throws QueryException
Compiles and optimizes the expression, assigns data types and cardinalities.

Parameters:
ctx - query context
scp - variable scope
Returns:
optimized expression
Throws:
QueryException - query exception

optimize

public Expr optimize(QueryContext ctx,
                     VarScope scp)
              throws QueryException
Optimizes an already compiled expression without recompiling its sub-expressions.

Parameters:
ctx - query context
scp - variable scope
Returns:
optimized expression
Throws:
QueryException - query exception

iter

public abstract Iter iter(QueryContext ctx)
                   throws QueryException
Evaluates the expression and returns an iterator on the resulting items. If this method is not overwritten, item(org.basex.query.QueryContext, org.basex.util.InputInfo) must be implemented by an expression, as it may be called by this method.

Parameters:
ctx - query context
Returns:
resulting item
Throws:
QueryException - query exception

item

public abstract Item item(QueryContext ctx,
                          InputInfo ii)
                   throws QueryException
Evaluates the expression and returns the resulting item or a null reference, if the expression yields an empty sequence. If this method is not overwritten, iter(org.basex.query.QueryContext) must be implemented by an expression, as it may be called by this method.

Parameters:
ctx - query context
ii - input info
Returns:
iterator
Throws:
QueryException - query exception

value

public abstract Value value(QueryContext ctx)
                     throws QueryException
Evaluates the expression and returns the resulting value.

Parameters:
ctx - query context
Returns:
iterator
Throws:
QueryException - query exception

ebv

public abstract Item ebv(QueryContext ctx,
                         InputInfo ii)
                  throws QueryException
Checks if the iterator can be dissolved into an effective boolean value. If not, returns an error. If yes, returns the first value - which can be also be e.g. an integer, which is later evaluated as numeric predicate.

Parameters:
ctx - query context
ii - input info
Returns:
item
Throws:
QueryException - query exception

test

public abstract Item test(QueryContext ctx,
                          InputInfo ii)
                   throws QueryException
Performs a predicate test and returns the item if test was successful.

Parameters:
ctx - query context
ii - input info
Returns:
item
Throws:
QueryException - query exception

isEmpty

public boolean isEmpty()
Tests if this is an empty sequence. This function is only overwritten by the Empty class, which represents the empty sequence.

Returns:
result of check

isVacuous

public boolean isVacuous()
Tests if this is a vacuous expression (empty sequence or error function). This check is needed for updating queries.

Returns:
result of check

isValue

public boolean isValue()
Tests if this is a value.

Returns:
result of check

isItem

public boolean isItem()
Tests if this is an item.

Returns:
result of check

size

public abstract long size()
Returns the sequence size or 1.

Returns:
result of check

has

public abstract boolean has(Expr.Flag flag)
Indicates if an expression has the specified compiler property. This method is called by numerous compile(org.basex.query.QueryContext, org.basex.query.var.VarScope) methods to test properties of sub-expressions. It returns true if at least one test is successful.

Parameters:
flag - flag to be found
Returns:
result of check

uses

public final boolean uses(Var v)
Checks if the given variable is used by this expression.

Parameters:
v - variable to be checked
Returns:
true if the variable is used, false otherwise

removable

public abstract boolean removable(Var v)
Checks if the specified variable is replaceable by a context item. The following tests might return false: This method is called by GFLWOR.compile(org.basex.query.QueryContext, org.basex.query.var.VarScope) to rewrite where clauses into predicates.

Parameters:
v - variable to be replaced
Returns:
result of check

count

public abstract VarUsage count(Var v)
Checks how often a variable is used in this expression.

Parameters:
v - variable to look for
Returns:
how often the variable is used, see VarUsage

inline

public abstract Expr inline(QueryContext ctx,
                            VarScope scp,
                            Var v,
                            Expr e)
                     throws QueryException
Inlines an expression into this one, replacing all references to the given variable.

Parameters:
ctx - query context for recompilation
scp - variable scope for recompilation
v - variable to replace
e - expression to inline
Returns:
resulting expression in something changed, null otherwise
Throws:
QueryException - query exception

inlineAll

protected static boolean inlineAll(QueryContext ctx,
                                   VarScope scp,
                                   Expr[] arr,
                                   Var v,
                                   Expr e)
                            throws QueryException
Inlines the given expression into all elements of the given array.

Parameters:
ctx - query context
scp - variable scope
arr - array
v - variable to replace
e - expression to inline
Returns:
true if the array has changed, false otherwise
Throws:
QueryException - query exception

copy

public final Expr copy(QueryContext ctx,
                       VarScope scp)
Copies an expression. Will be useful for inlining functions, or for copying static queries.

Parameters:
ctx - query context
scp - variable scope for creating new variables
Returns:
copied expression

copy

public abstract Expr copy(QueryContext ctx,
                          VarScope scp,
                          IntObjMap<Var> vs)
Copies an expression. Will be useful for inlining functions, or for copying static queries.

Parameters:
ctx - query context
scp - variable scope for creating new variables
vs - mapping from old variable IDs to new variable copies
Returns:
copied expression

compEbv

public Expr compEbv(QueryContext ctx)

This method is overwritten by CmpG, CmpV and FNSimple. It is called at compile time by expressions that perform effective boolean value tests (e.g. If or Preds). If the arguments of the called expression return a boolean anyway, the expression will be simplified.

Example in CmpV: if($x eq true()) is rewritten to if($x), if $x is known to return a single boolean.

Parameters:
ctx - query context
Returns:
optimized expression

type

public abstract SeqType type()
Returns the static type of the evaluated value. For simplicity, some types have been merged to super types. As an example, many numeric types are treated as integers.

Returns:
result of check

iterable

public boolean iterable()
Returns true if the expression is iterable, i.e., if it will not contain any duplicate nodes and if all nodes will be are sorted. The return value of this method is only relevant for node sequences. It is e.g. called by AxisPath.

Returns:
result of check

indexAccessible

public boolean indexAccessible(IndexCosts ic)
                        throws QueryException
Checks if an expression can be rewritten to an index access. If this method is implemented, indexEquivalent(org.basex.query.util.IndexCosts) must be implemented as well.

Parameters:
ic - index costs analyzer
Returns:
true if an index can be used
Throws:
QueryException - query exception

indexEquivalent

public Expr indexEquivalent(IndexCosts ic)
                     throws QueryException
Returns an equivalent expression which accesses an index structure. Will be called if indexAccessible(org.basex.query.util.IndexCosts) is returns true for an expression.

Parameters:
ic - index costs analyzer
Returns:
equivalent index-expression
Throws:
QueryException - query exception

sameAs

public boolean sameAs(Expr cmp)
Compares the current and specified expression for equality.

Parameters:
cmp - expression to be compared
Returns:
result of check

isFunction

public boolean isFunction(Function f)
Checks if this expression is a certain function.

Parameters:
f - function definition
Returns:
result of check

addText

public Expr addText(QueryContext ctx)
Optionally adds a text node to an expression for potential index rewriting.

Parameters:
ctx - query context
Returns:
expression

hasFreeVars

public boolean hasFreeVars()
Checks if this expression has free variables.

Returns:
true if there are variables which are used but not declared in this expression, false otherwise

markTailCalls

public Expr markTailCalls()
Finds and marks tail calls, enabling TCO.

Returns:
the expression, with tail calls marked

accept

public abstract boolean accept(ASTVisitor visitor)
Traverses this expression, notifying the visitor of declared and used variables, and checking the tree for other recursive properties.

Parameters:
visitor - visitor
Returns:
if the walk should be continued

visitAll

protected static final boolean visitAll(ASTVisitor visitor,
                                        Expr... exprs)
Visit all given expressions with the given visitor.

Parameters:
visitor - visitor
exprs - expressions to visit
Returns:
success flag

exprSize

public abstract int exprSize()
Counts the number of expressions in this expression's sub-tree.

Returns:
number of expressions