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

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Expression()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    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.
    `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` | `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 Detail

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

    - #### type

          protected int type

  - ### Constructor Detail

    - #### Expression

          public Expression()

  - ### Method Detail

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

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