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 and Description
    --- | ---
    `static int` | `ADD`
    `static int` | `AND`
    `static int` | `BETWEEN`
    `static int` | `BITWISE_AND`
    `static int` | `BITWISE_NOT`
    `static int` | `BITWISE_OR`
    `static int` | `BITWISE_XOR`
    `static int` | `DB_PATH` Expression describes a path relative to a DbEntity.
    `static int` | `DIVIDE`
    `static int` | `EQUAL_TO`
    `static int` | `FALSE`
    `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_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` | `SUBTRACT`
    `static int` | `TRUE`
    `protected int` | `type`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Expression()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Expression` | `andExp(Expression exp)` Chains this expression with another expression using "and".
    `Expression` | `deepCopy()` Clones this expression.
    `abstract void` | `encodeAsEJBQL(PrintWriter pw, String rootId)` Stores a String representation of Expression as EJBQL using a provided PrintWriter.
    `abstract void` | `encodeAsString(PrintWriter pw)` Stores a String representation of Expression using a provided PrintWriter.
    `void` | `encodeAsXML(XMLEncoder encoder)` 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.
    `Expression` | `expWithParameters(Map<String,?> parameters)` A shortcut for `expWithParams(params, true)`.
    `Expression` | `expWithParameters(Map<String,?> parameters, boolean pruneMissing)` Creates and returns a new Expression instance using this expression as a prototype.
    `<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(List<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.
    `static Expression` | `fromString(String expressionString)` Parses string, converting it to 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.
    `Expression` | `joinExp(int type, Expression exp)` Creates a new expression that joins this object with another expression, 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".
    `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)`
    `String` | `toString()`
    `Expression` | `transform(org.apache.commons.collections.Transformer transformer)` Creates a transformed copy of this expression, applying transformation provided by Transformer to all its nodes.
    `protected Object` | `transformExpression(org.apache.commons.collections.Transformer 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, hashCode, 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

    - #### type

          protected int type

  - ### Constructor Detail

    - #### Expression

          public Expression()

  - ### Method Detail

    - #### fromString

          public static Expression fromString(String expressionString)

      Parses string, converting it to Expression. If string does not represent a semantically correct expression, an ExpressionException is thrown.
      Since:
        1.1

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

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

    - #### expWithParameters

          public Expression expWithParameters(Map<String,?> parameters)

      A shortcut for `expWithParams(params, true)`.

    - #### expWithParameters

          public Expression expWithParameters(Map<String,?> parameters,
                                     boolean pruneMissing)

      Creates and returns a new Expression instance using this expression as a prototype. All ExpressionParam operands are substituted with the values in the `params` map.

      Null values in the `params` map should be explicitly created in the map for the corresponding key.

      Parameters:
        `parameters` - a map of parameters, with each key being a string name of an expression parameter, and value being the value that should be used in the final expression.
        `pruneMissing` - If `true`, subexpressions that rely on missing parameters will be pruned from the resulting tree. If `false` , any missing values will generate an exception.
      Returns:
        Expression resulting from the substitution of parameters with real values, or null if the whole expression was pruned, due to the missing parameters.

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

    - #### andExp

          public Expression andExp(Expression exp)

      Chains this expression with another expression using "and".

    - #### orExp

          public Expression orExp(Expression exp)

      Chains this expression with another expression using "or".

    - #### 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(List<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(org.apache.commons.collections.Transformer 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(org.apache.commons.collections.Transformer 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)

      Encodes itself, wrapping the string into XML CDATA section.
      Specified by:
        `encodeAsXML` in interface `XMLSerializable`
      Since:
        1.1

    - #### encodeAsString

          public abstract void encodeAsString(PrintWriter pw)

      Stores a String representation of Expression using a provided PrintWriter.
      Since:
        1.1

    - #### encodeAsEJBQL

          public abstract void encodeAsEJBQL(PrintWriter pw,
                           String rootId)

      Stores a String representation of Expression as EJBQL using a provided PrintWriter. DB path expressions produce non-standard EJBQL path expressions.
      Since:
        3.0

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toEJBQL

          public String toEJBQL(String rootId)

      Since:
        3.0

Copyright © 2001–2014 Apache Cayenne. All rights reserved.