Class Expression

java.lang.Object
org.apache.cayenne.exp.Expression
All Implemented Interfaces:
XMLSerializable
Direct Known Subclasses:
AggregateConditionExp, AsteriskExp, CaseWhenExp, ConditionExp, CustomOperatorExp, ElseExp, EnclosingObjectExp, FullObjectExp, ListExp, NegateExp, PathExp, ScalarExp, SubqueryExp, ThenExp, ValueExp
public abstract sealed class Expression extends Object implements XMLSerializable permits AggregateConditionExp, AsteriskExp, CaseWhenExp, ConditionExp, CustomOperatorExp, ElseExp, EnclosingObjectExp, FullObjectExp, ListExp, NegateExp, PathExp, ScalarExp, SubqueryExp, ThenExp, ValueExp
Superclass of Cayenne expressions: a tree node holding its operands. An operand is either a nested expression or a plain value. A node does not know its parent, so it can be shared between trees.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Object[]
    operands
     
    static final Object
    PRUNED_NODE
    A value that a Transformer might return to indicate that a node has to be pruned from the expression during the transformation.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Expression(Object... operands)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    Expression
    andExp(Expression exp)
    Chains this expression with another expression using "and".
    Expression
    andExp(Expression exp, Expression... expressions)
    Chains this expression with other expressions using "and".
    void
    appendAsString(Appendable out)
    Appends own content as a String to the provided Appendable: the operands separated by the operator.
    protected void
    appendOperandAsString(int index, Appendable out)
    Appends the operand at the given index to the output: a nested node as itself, wrapped in parentheses if it asks for it via parenthesizeAsOperand(), a plain value as a literal.
    Expression
    deepCopy()
    Clones this expression.
    void
    encodeAsXML(XMLEncoder encoder, ProjectNodeVisitor delegate)
    Encodes itself, wrapping the string into XML CDATA section.
    boolean
    equals(Object object)
     
    Object
    evaluate(Object o)
    Calculates expression value with object as a context for path expressions.
    protected abstract Object
    evaluateNode(Object o)
    Evaluates itself with object, pushing result on the stack.
    protected Object
    evaluateOperand(int index, Object o)
    Evaluates the operand at the given index: a nested node is evaluated against the object, a plain value is returned as is.
    Expression
    exists()
    Returns expression that will be dynamically resolved to proper subqueries based on a relationships used (if no relationships are present in the original expression no subqueries will be used).
    String
    expName()
    Returns String label for this expression: the class name without the "Exp" suffix.
    <T> Collection<?>
    filter(Collection<T> source, Collection<T> target)
    Adds objects matching this expression from the source collection to the target collection.
    <T> List<T>
    filterObjects(Collection<T> objects)
    Returns a list of objects that match the expression.
    <T> T
    first(List<T> objects)
    Returns the first object in the list that matches the expression.
    protected void
    flattenTree()
    Flattens the tree under this node by eliminating any operands that are nodes of the same class as this node and copying their operands to this node.
    protected abstract String
    getExpressionOperator(int index)
    Returns the operator printed between the operands, before the operand at the given index.
    Object
    getOperand(int index)
    Returns a value of operand at index: a nested expression or a plain value.
    int
    getOperandCount()
    Returns a count of operands of this expression.
    Map<String,String>
    getPathAliases()
    Returns a map of path aliases for this expression.
    int
    hashCode()
     
    protected boolean
    isValidParent(Expression parent)
    Whether this node can be an operand of the given node.
    boolean
    match(Object o)
    Calculates expression boolean value with object as a context for path expressions.
    Expression
    notExists()
    Returns expression that will be dynamically resolved to proper subqueries based on a relationships used (if no relationships are present in the original expression no subqueries will be used).
    Expression
    notExp()
    Returns a logical NOT of current expression.
    Expression
    orExp(Expression exp)
    Chains this expression with another expression using "or".
    Expression
    orExp(Expression exp, Expression... expressions)
    Chains this expression with other expressions using "or".
    Expression
    params(Map<String,?> parameters)
    Creates and returns a new Expression instance based on this expression, but with named parameters substituted with provided values.
    Expression
    params(Map<String,?> parameters, boolean pruneMissing)
    Creates and returns a new Expression instance based on this expression, but with named parameters substituted with provided values.If any subexpressions containing parameters not matching the "name" argument are found, the behavior depends on "pruneMissing" argument.
    Expression
    paramsArray(Object... parameters)
    Creates and returns a new Expression instance based on this expression, but with parameters substituted with provided values.
    protected boolean
    parenthesizeAsOperand()
    Whether this node is wrapped in parentheses when printed as an operand of another node.
    protected boolean
    pruneNodeForPrunedChild(Object prunedChild)
    Returns true if this node should be pruned from expression tree in the event a child is removed.
    void
    setOperand(int index, Object value)
    Sets a value of operand at index, growing the operands array if needed.
    void
    setOperands(Object... operands)
    Replaces all the operands of this node with the given ones.
    abstract Expression
    shallowCopy()
    Creates a copy of this expression node, without copying children.
    String
    toString()
     
    Expression
    transform(Function<Object,Object> transformer)
    Creates a transformed copy of this expression, applying transformation provided by Transformer to all its nodes.
    protected Object
    transformExpression(Function<Object,Object> transformer)
    A recursive method called from "transform" to do the actual transformation.
    protected void
    traverse(Expression parentExp, TraversalHandler visitor)
    Traverses itself and child expressions, notifying visitor via callback methods as it goes.
    void
    traverse(TraversalHandler visitor)
    Traverses itself and child expressions, notifying visitor via callback methods as it goes.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • PRUNED_NODE

      public static final Object PRUNED_NODE
      A value that a Transformer might return to indicate that a node has to be pruned from the expression during the transformation.
      Since:
      1.2

    • operands

      protected Object[] operands

  • Constructor Details

    • Expression

      protected Expression(Object... operands)

  • Method Details

    • getPathAliases

      public Map<String,String> getPathAliases()
      Returns a map of path aliases for this expression. It returns a non-empty map only if this is a path expression and the aliases are known at the expression creation time. Otherwise an empty map is returned.
      Since:
      3.0

    • expName

      public String expName()
      Returns String label for this expression: the class name without the "Exp" suffix. Used for debugging.

    • equals

      public boolean equals(Object object)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • paramsArray

      public Expression paramsArray(Object... parameters)
      Creates and returns a new Expression instance based on this expression, but with parameters substituted with provided values. This is a positional style of binding. If a given parameter name is used more than once, only the first occurrence is treated as "position", subsequent occurrences are bound with the same value as the first one. If expression parameters count is different from the array parameter count, an exception will be thrown.

      positional style would not allow subexpression pruning.

      Since:
      4.0

    • params

      public Expression params(Map<String,?> parameters)
      Creates and returns a new Expression instance based on this expression, but with named parameters substituted with provided values. Any subexpressions containing parameters not matching the "name" argument will be pruned.

      Note that if you want matching against nulls to be preserved, you must place NULL values for the corresponding keys in the map.

      Since:
      4.0

    • params

      public Expression params(Map<String,?> parameters, boolean pruneMissing)
      Creates and returns a new Expression instance based on this expression, but with named parameters substituted with provided values.If any subexpressions containing parameters not matching the "name" argument are found, the behavior depends on "pruneMissing" argument. If it is false an Exception will be thrown, otherwise subexpressions with missing parameters will be pruned from the resulting expression.

      Note that if you want matching against nulls to be preserved, you must place NULL values for the corresponding keys in the map.

      Since:
      4.0

    • andExp

      public Expression andExp(Expression exp)
      Chains this expression with another expression using "and".

    • andExp

      public Expression andExp(Expression exp, Expression... expressions)
      Chains this expression with other expressions using "and".
      Since:
      4.0

    • orExp

      public Expression orExp(Expression exp)
      Chains this expression with another expression using "or".

    • orExp

      public Expression orExp(Expression exp, Expression... expressions)
      Chains this expression with other expressions using "or".
      Since:
      4.0

    • notExp

      public Expression notExp()
      Returns a logical NOT of current expression.
      Since:
      1.0.6

    • exists

      public Expression exists()
      Returns expression that will be dynamically resolved to proper subqueries based on a relationships used (if no relationships are present in the original expression no subqueries will be used).
      Returns:
      exists expression
      Since:
      5.0
      See Also:

    • notExists

      public Expression notExists()
      Returns expression that will be dynamically resolved to proper subqueries based on a relationships used (if no relationships are present in the original expression no subqueries will be used).
      Returns:
      not exists expression
      Since:
      5.0
      See Also:

    • getOperandCount

      public int getOperandCount()
      Returns a count of operands of this expression. In real life there are unary (count == 1), binary (count == 2) and ternary (count == 3) expressions.

    • getOperand

      public Object getOperand(int index)
      Returns a value of operand at index: a nested expression or a plain value. Operand indexing starts at 0.

    • setOperand

      public void setOperand(int index, Object value)
      Sets a value of operand at index, growing the operands array if needed. Operand indexing starts at 0. A Persistent is replaced with its ObjectId. A nested expression is asked first whether this node is a valid parent for it, see isValidParent(Expression).

    • setOperands

      public void setOperands(Object... operands)
      Replaces all the operands of this node with the given ones. Called by the constructor and by the parser once all the operands of a node are known, so a node that post-processes its operands overrides this method.
      Since:
      5.0

    • isValidParent

      protected boolean isValidParent(Expression parent)
      Whether this node can be an operand of the given node. Called by the parent when the operand is set, to check what the grammar can't: e.g. a condition can only be an operand of a condition aggregate. By default any parent is valid.
      Since:
      5.0

    • evaluate

      public Object evaluate(Object o)
      Calculates expression value with object as a context for path expressions.
      Since:
      1.1

    • evaluateNode

      protected abstract Object evaluateNode(Object o) throws Exception
      Evaluates itself with object, pushing result on the stack.
      Throws:
      Exception

    • evaluateOperand

      protected Object evaluateOperand(int index, Object o) throws Exception
      Evaluates the operand at the given index: a nested node is evaluated against the object, a plain value is returned as is.
      Throws:
      Exception

    • match

      public boolean match(Object o)
      Calculates expression boolean value with object as a context for path expressions.
      Since:
      1.1

    • first

      public <T> T first(List<T> objects)
      Returns the first object in the list that matches the expression.
      Since:
      3.1

    • filterObjects

      public <T> List<T> filterObjects(Collection<T> objects)
      Returns a list of objects that match the expression.

    • filter

      public <T> Collection<?> filter(Collection<T> source, Collection<T> target)
      Adds objects matching this expression from the source collection to the target collection.
      Since:
      1.1

    • deepCopy

      public Expression deepCopy()
      Clones this expression.
      Since:
      1.1

    • shallowCopy

      public abstract Expression shallowCopy()
      Creates a copy of this expression node, without copying children.
      Since:
      1.1

    • pruneNodeForPrunedChild

      protected boolean pruneNodeForPrunedChild(Object prunedChild)
      Returns true if this node should be pruned from expression tree in the event a child is removed.
      Since:
      1.1

    • flattenTree

      protected void flattenTree()
      Flattens the tree under this node by eliminating any operands that are nodes of the same class as this node and copying their operands to this node.
      Since:
      1.1

    • traverse

      public void traverse(TraversalHandler visitor)
      Traverses itself and child expressions, notifying visitor via callback methods as it goes. This is an Expression-specific implementation of the "Visitor" design pattern.
      Since:
      1.1

    • traverse

      protected void traverse(Expression parentExp, TraversalHandler visitor)
      Traverses itself and child expressions, notifying visitor via callback methods as it goes.
      Since:
      1.1

    • transform

      public Expression transform(Function<Object,Object> transformer)
      Creates a transformed copy of this expression, applying transformation provided by Transformer to all its nodes. Null transformer will result in an identical deep copy of this expression.

      To force a node and its children to be pruned from the copy, Transformer should return Expression.PRUNED_NODE. Otherwise an expectation is that if a node is an Expression it must be transformed to null or another Expression. Any other object type would result in a ExpressionException.

      Since:
      1.1

    • transformExpression

      protected Object transformExpression(Function<Object,Object> transformer)
      A recursive method called from "transform" to do the actual transformation.
      Returns:
      null, Expression.PRUNED_NODE or transformed expression.
      Since:
      1.2

    • encodeAsXML

      public void encodeAsXML(XMLEncoder encoder, ProjectNodeVisitor delegate)
      Encodes itself, wrapping the string into XML CDATA section.
      Specified by:
      encodeAsXML in interface XMLSerializable
      Since:
      1.1

    • appendAsString

      public void appendAsString(Appendable out) throws IOException
      Appends own content as a String to the provided Appendable: the operands separated by the operator.
      Throws:
      IOException
      Since:
      4.0

    • getExpressionOperator

      protected abstract String getExpressionOperator(int index)
      Returns the operator printed between the operands, before the operand at the given index.

    • parenthesizeAsOperand

      protected boolean parenthesizeAsOperand()
      Whether this node is wrapped in parentheses when printed as an operand of another node. Compound nodes are, leaves and nodes with their own delimiters (function calls, lists) are not.

    • appendOperandAsString

      protected void appendOperandAsString(int index, Appendable out) throws IOException
      Appends the operand at the given index to the output: a nested node as itself, wrapped in parentheses if it asks for it via parenthesizeAsOperand(), a plain value as a literal.
      Throws:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object