Package org.apache.cayenne.exp

# Class Expression

java.lang.Object
org.apache.cayenne.exp.Expression

All Implemented Interfaces:
  `Serializable`, `XMLSerializable`

Direct Known Subclasses:
  `SimpleNode`

public abstract class Expression extends Object implements Serializable, XMLSerializable
Superclass of Cayenne expressions that defines basic API for expressions use.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `ADD`
  `static final int`
  `ALL`
  `static final int`
  `AND`
  `static final int`
  `ANY`
  `static final int`
  `ASTERISK`
  `static final int`
  `BETWEEN`
  `static final int`
  `BITWISE_AND`
  `static final int`
  `BITWISE_LEFT_SHIFT`
  `static final int`
  `BITWISE_NOT`
  `static final int`
  `BITWISE_OR`
  `static final int`
  `BITWISE_RIGHT_SHIFT`
  `static final int`
  `BITWISE_XOR`
  `static final int`
  `CASE_WHEN`
  `static final int`
  `CUSTOM_OP`
  `static final int`
  `DB_PATH`
  Expression describes a path relative to a DbEntity.
  `static final int`
  `DBID_PATH`
  `static final int`
  `DIVIDE`
  `static final int`
  `ELSE`
  `static final int`
  `ENCLOSING_OBJECT`
  `static final int`
  `EQUAL_TO`
  `static final int`
  `EXISTS`
  `static final int`
  `FALSE`
  `static final int`
  `FULL_OBJECT`
  `static final int`
  `FUNCTION_CALL`
  `static final int`
  `GREATER_THAN`
  `static final int`
  `GREATER_THAN_EQUAL_TO`
  `static final int`
  `IN`
  `static final int`
  `LESS_THAN`
  `static final int`
  `LESS_THAN_EQUAL_TO`
  `static final int`
  `LIKE`
  `static final int`
  `LIKE_IGNORE_CASE`
  `static final int`
  `LIST`
  Interpreted as a comma-separated list of literals.
  `static final int`
  `MULTIPLY`
  `static final int`
  `NEGATIVE`
  `static final int`
  `NOT`
  `static final int`
  `NOT_BETWEEN`
  `static final int`
  `NOT_EQUAL_TO`
  `static final int`
  `NOT_EXISTS`
  `static final int`
  `NOT_IN`
  `static final int`
  `NOT_LIKE`
  `static final int`
  `NOT_LIKE_IGNORE_CASE`
  `static final int`
  `OBJ_PATH`
  Expression describes a path relative to an ObjEntity.
  `static final int`
  `OR`
  `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.
  `static final int`
  `SCALAR`
  `static final int`
  `SUBQUERY`
  `static final int`
  `SUBTRACT`
  `static final int`
  `THEN`
  `static final int`
  `TRUE`
  `protected int`
  `type`
  `static final int`
  `WHEN`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Expression()`

- ## 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`
  `appendAsEJBQL(Appendable out, String rootId)`
  Stores a String representation of Expression as EJBQL using a provided Appendable.
  `abstract void`
  `appendAsEJBQL(List<Object> parameterAccumulator, Appendable out, String rootId)`
  Stores a String representation of Expression as EJBQL using a provided PrintWriter.
  `abstract void`
  `appendAsString(Appendable out)`
  Appends own content as a String to the provided Appendable.
  `Expression`
  `deepCopy()`
  Clones this expression.
  `void`
  `encodeAsXML(XMLEncoder encoder, ConfigurationNodeVisitor delegate)`
  Encodes itself, wrapping the string into XML CDATA section.
  `boolean`
  `equals(Object object)`
  `abstract Object`
  `evaluate(Object o)`
  Calculates expression value with object as a context for path expressions.
  `abstract 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.
  `<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 abstract void`
  `flattenTree()`
  Restructures expression to make sure that there are no children of the same type as this expression.
  `abstract Object`
  `getOperand(int index)`
  Returns a value of operand at `index`.
  `abstract int`
  `getOperandCount()`
  Returns a count of operands of this expression.
  `abstract Map<String,String>`
  `getPathAliases()`
  Returns a map of path aliases for this expression.
  `int`
  `getType()`
  Returns a type of expression.
  `int`
  `hashCode()`
  `Expression`
  `joinExp(int type, Expression exp)`
  Creates a new expression that joins this object with another expression, using specified join type.
  `Expression`
  `joinExp(int type, Expression exp, Expression... expressions)`
  Creates a new expression that joins this object with other expressions, using specified join type.
  `boolean`
  `match(Object o)`
  Calculates expression boolean value with object as a context for path expressions.
  `abstract 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).
  `abstract 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 abstract boolean`
  `pruneNodeForPrunedChild(Object prunedChild)`
  Returns true if this node should be pruned from expression tree in the event a child is removed.
  `abstract void`
  `setOperand(int index, Object value)`
  Sets a value of operand at `index`.
  `void`
  `setType(int type)`
  `abstract Expression`
  `shallowCopy()`
  Creates a copy of this expression node, without copying children.
  `String`
  `toEJBQL(String rootId)`
  Produces an EJBQL string that represents this expression.
  `String`
  `toEJBQL(List<Object> parameterAccumulator, String rootId)`
  Produces an EJBQL string that represents this expression.
  `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 java.lang.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

  - ### AND

    public static final int AND
    See Also:
      - Constant Field Values

  - ### OR

    public static final int OR
    See Also:
      - Constant Field Values

  - ### NOT

    public static final int NOT
    See Also:
      - Constant Field Values

  - ### EQUAL_TO

    public static final int EQUAL_TO
    See Also:
      - Constant Field Values

  - ### NOT_EQUAL_TO

    public static final int NOT_EQUAL_TO
    See Also:
      - Constant Field Values

  - ### LESS_THAN

    public static final int LESS_THAN
    See Also:
      - Constant Field Values

  - ### GREATER_THAN

    public static final int GREATER_THAN
    See Also:
      - Constant Field Values

  - ### LESS_THAN_EQUAL_TO

    public static final int LESS_THAN_EQUAL_TO
    See Also:
      - Constant Field Values

  - ### GREATER_THAN_EQUAL_TO

    public static final int GREATER_THAN_EQUAL_TO
    See Also:
      - Constant Field Values

  - ### BETWEEN

    public static final int BETWEEN
    See Also:
      - Constant Field Values

  - ### IN

    public static final int IN
    See Also:
      - Constant Field Values

  - ### LIKE

    public static final int LIKE
    See Also:
      - Constant Field Values

  - ### LIKE_IGNORE_CASE

    public static final int LIKE_IGNORE_CASE
    See Also:
      - Constant Field Values

  - ### ADD

    public static final int ADD
    See Also:
      - Constant Field Values

  - ### SUBTRACT

    public static final int SUBTRACT
    See Also:
      - Constant Field Values

  - ### MULTIPLY

    public static final int MULTIPLY
    See Also:
      - Constant Field Values

  - ### DIVIDE

    public static final int DIVIDE
    See Also:
      - Constant Field Values

  - ### NEGATIVE

    public static final int NEGATIVE
    See Also:
      - Constant Field Values

  - ### TRUE

    public static final int TRUE
    See Also:
      - Constant Field Values

  - ### FALSE

    public static final int FALSE
    See Also:
      - Constant Field Values

  - ### OBJ_PATH

    public static final int OBJ_PATH
    Expression describes a path relative to an ObjEntity. OBJ_PATH expression is resolved relative to some root ObjEntity. Path expression components are separated by "." (dot). Path can point to either one of these:
    - An attribute of root ObjEntity. For entity Gallery OBJ_PATH expression "galleryName" will point to ObjAttribute "galleryName"
    - Another ObjEntity related to root ObjEntity via a chain of relationships. For entity Gallery OBJ_PATH expression "paintingArray.toArtist" will point to ObjEntity "Artist"
    - ObjAttribute of another ObjEntity related to root ObjEntity via a chain of relationships. For entity Gallery OBJ_PATH expression "paintingArray.toArtist.artistName" will point to ObjAttribute "artistName"
    See Also:
      - Constant Field Values

  - ### DB_PATH

    public static final int DB_PATH
    Expression describes a path relative to a DbEntity. DB_PATH expression is resolved relative to some root DbEntity. Path expression components are separated by "." (dot). Path can point to either one of these:
    - An attribute of root DbEntity. For entity GALLERY, DB_PATH expression "GALLERY_NAME" will point to a DbAttribute "GALLERY_NAME".
    - Another DbEntity related to root DbEntity via a chain of relationships. For entity GALLERY DB_PATH expression "paintingArray.toArtist" will point to DbEntity "ARTIST".
    - DbAttribute of another ObjEntity related to root DbEntity via a chain of relationships. For entity GALLERY DB_PATH expression "paintingArray.toArtist.ARTIST_NAME" will point to DbAttribute "ARTIST_NAME".
    See Also:
      - Constant Field Values

  - ### LIST

    public static final int LIST
    Interpreted as a comma-separated list of literals.
    See Also:
      - Constant Field Values

  - ### NOT_BETWEEN

    public static final int NOT_BETWEEN
    See Also:
      - Constant Field Values

  - ### NOT_IN

    public static final int NOT_IN
    See Also:
      - Constant Field Values

  - ### NOT_LIKE

    public static final int NOT_LIKE
    See Also:
      - Constant Field Values

  - ### NOT_LIKE_IGNORE_CASE

    public static final int NOT_LIKE_IGNORE_CASE
    See Also:
      - Constant Field Values

  - ### BITWISE_NOT

    public static final int BITWISE_NOT
    Since:
      3.1
    See Also:
      - Constant Field Values

  - ### BITWISE_AND

    public static final int BITWISE_AND
    Since:
      3.1
    See Also:
      - Constant Field Values

  - ### BITWISE_OR

    public static final int BITWISE_OR
    Since:
      3.1
    See Also:
      - Constant Field Values

  - ### BITWISE_XOR

    public static final int BITWISE_XOR
    Since:
      3.1
    See Also:
      - Constant Field Values

  - ### BITWISE_LEFT_SHIFT

    public static final int BITWISE_LEFT_SHIFT
    Since:
      4.0
    See Also:
      - Constant Field Values

  - ### BITWISE_RIGHT_SHIFT

    public static final int BITWISE_RIGHT_SHIFT
    Since:
      4.0
    See Also:
      - Constant Field Values

  - ### FUNCTION_CALL

    public static final int FUNCTION_CALL
    Since:
      4.0
    See Also:
      - Constant Field Values

  - ### ASTERISK

    public static final int ASTERISK
    Since:
      4.0
    See Also:
      - Constant Field Values

  - ### FULL_OBJECT

    public static final int FULL_OBJECT
    Since:
      4.0
    See Also:
      - Constant Field Values

  - ### ENCLOSING_OBJECT

    public static final int ENCLOSING_OBJECT
    Since:
      4.2
    See Also:
      - Constant Field Values

  - ### EXISTS

    public static final int EXISTS
    Since:
      4.2
    See Also:
      - Constant Field Values

  - ### NOT_EXISTS

    public static final int NOT_EXISTS
    Since:
      4.2
    See Also:
      - Constant Field Values

  - ### SUBQUERY

    public static final int SUBQUERY
    Since:
      4.2
    See Also:
      - Constant Field Values

  - ### DBID_PATH

    public static final int DBID_PATH
    Since:
      4.2
    See Also:
      - Constant Field Values

  - ### CUSTOM_OP

    public static final int CUSTOM_OP
    Since:
      4.2
    See Also:
      - Constant Field Values

  - ### ALL

    public static final int ALL
    Since:
      5.0
    See Also:
      - Constant Field Values

  - ### ANY

    public static final int ANY
    Since:
      5.0
    See Also:
      - Constant Field Values

  - ### SCALAR

    public static final int SCALAR
    Since:
      5.0
    See Also:
      - Constant Field Values

  - ### CASE_WHEN

    public static final int CASE_WHEN
    Since:
      5.0
    See Also:
      - Constant Field Values

  - ### WHEN

    public static final int WHEN
    Since:
      5.0
    See Also:
      - Constant Field Values

  - ### THEN

    public static final int THEN
    Since:
      5.0
    See Also:
      - Constant Field Values

  - ### ELSE

    public static final int ELSE
    Since:
      5.0
    See Also:
      - Constant Field Values

  - ### type

    protected int type

- ## Constructor Details

  - ### Expression

    public Expression()

- ## Method Details

  - ### getPathAliases

    public abstract 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. Used for debugging.

  - ### equals

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

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### getType

    public int getType()
    Returns a type of expression. Most common types are defined as public static fields of this interface.

  - ### setType

    public void setType(int type)

  - ### 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

  - ### joinExp

    public Expression joinExp(int type, Expression exp)
    Creates a new expression that joins this object with another expression, using specified join type. It is very useful for incrementally building chained expressions, like long AND or OR statements.

  - ### joinExp

    public Expression joinExp(int type, Expression exp, Expression... expressions)
    Creates a new expression that joins this object with other expressions, using specified join type. It is very useful for incrementally building chained expressions, like long AND or OR statements.
    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 abstract Expression notExp()
    Returns a logical NOT of current expression.
    Since:
      1.0.6

  - ### exists

    public abstract 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:
      - `ExpressionFactory.exists(Expression)`

  - ### notExists

    public abstract 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:
      - `ExpressionFactory.notExists(Expression)`

  - ### getOperandCount

    public abstract 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 abstract Object getOperand(int index)
    Returns a value of operand at `index`. Operand indexing starts at 0.

  - ### setOperand

    public abstract void setOperand(int index, Object value)
    Sets a value of operand at `index`. Operand indexing starts at 0.

  - ### evaluate

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

  - ### 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 abstract 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 abstract void flattenTree()
    Restructures expression to make sure that there are no children of the same type as this expression.
    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, ConfigurationNodeVisitor delegate)
    Encodes itself, wrapping the string into XML CDATA section.
    Specified by:
      `encodeAsXML` in interface `XMLSerializable`
    Since:
      1.1

  - ### appendAsString

    public abstract void appendAsString(Appendable out) throws IOException
    Appends own content as a String to the provided Appendable.
    Throws:
      `IOException`
    Since:
      4.0

  - ### appendAsEJBQL

    public void appendAsEJBQL(Appendable out, String rootId) throws IOException
    Stores a String representation of Expression as EJBQL using a provided Appendable. DB path expressions produce non-standard EJBQL path expressions.
    Throws:
      `IOException`
    Since:
      4.0

  - ### appendAsEJBQL

    public abstract void appendAsEJBQL(List<Object> parameterAccumulator, Appendable out, String rootId) throws IOException
    Stores a String representation of Expression as EJBQL using a provided PrintWriter. DB path expressions produce non-standard EJBQL path expressions. If the parameterAccumulator is supplied then as the EJBQL is output, it may load parameters into this list. In this case, the EJBQL output will contain reference to positional parameters. If no parameterAccumulator is supplied and a scalar type is encountered for which there is no EJBQL literal representation (such as dates) then this method will throw a runtime exception to indicate that it was not possible to generate a string-only representation of the Expression in EJBQL.
    Throws:
      `IOException`
    Since:
      4.0

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### toEJBQL

    public String toEJBQL(List<Object> parameterAccumulator, String rootId)
    Produces an EJBQL string that represents this expression. If the parameterAccumulator is supplied then, where appropriate, parameters to the EJBQL may be written into the parameterAccumulator. If this method encounters a scalar type which is not able to be represented as an EJBQL literal then this method will throw a runtime exception to indicate that it was not possible to generate a string-only representation of the Expression as EJBQL.
    Since:
      3.1

  - ### toEJBQL

    public String toEJBQL(String rootId)
    Produces an EJBQL string that represents this expression. If this method encounters a scalar type which is not able to be represented as an EJBQL literal then this method will throw a runtime exception.
    Since:
      3.0