Expression (cayenne-doc: Cayenne Documentation 4.0.2 API)

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`	`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`	`DB_PATH` Expression describes a path relative to a DbEntity.
`static int`	`DIVIDE`
`static int`	`EQUAL_TO`
`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_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()

Constructors
Constructor and Description
`Expression()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and 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.
`abstract void`	`encodeAsEJBQL(PrintWriter pw, String rootId)` Deprecated. since 4.0 use `appendAsEJBQL(Appendable, String)`
`abstract void`	`encodeAsString(PrintWriter pw)` Deprecated. since 4.0 use `appendAsString(Appendable)`.
`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)` Deprecated. since 4.0 use `params(Map)`
`Expression`	`expWithParameters(Map<String,?> parameters, boolean pruneMissing)` Deprecated. since 4.0 use `params(Map, boolean)` instead.
`<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.
`static Expression`	`fromString(String expressionString)` Deprecated. since 4.0 use `ExpressionFactory.exp(String, Object...)`
`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(List<Object> parameterAccumulator, String rootId)` Produces an EJBQL string that represents this expression.
`String`	`toEJBQL(String rootId)` Produces an EJBQL string that represents this expression.
`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, 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
  - type
```
protected int type
```
- Constructor Detail
  - Expression
```
public Expression()
```
- Method Detail
  - fromString
```
@Deprecated
public static Expression fromString(String expressionString)
```
    Deprecated. since 4.0 use ExpressionFactory.exp(String, Object...)
    
    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
  - 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
  - expWithParameters
```
@Deprecated
public Expression expWithParameters(Map<String,?> parameters)
```
    Deprecated. since 4.0 use params(Map)
    
    A shortcut for expWithParams(params, true).
  - expWithParameters
```
@Deprecated
public Expression expWithParameters(Map<String,?> parameters,
                                                boolean pruneMissing)
```
    Deprecated. since 4.0 use params(Map, boolean) instead.
    
    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.
  - 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(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
```
@Deprecated
public abstract void encodeAsString(PrintWriter pw)
```
    Deprecated. since 4.0 use appendAsString(Appendable).
    
    Stores a String representation of Expression using a provided PrintWriter.
    
    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
  - encodeAsEJBQL
```
@Deprecated
public abstract void encodeAsEJBQL(PrintWriter pw,
                                               String rootId)
```
    Deprecated. since 4.0 use appendAsEJBQL(Appendable, String)
    
    Stores a String representation of Expression as EJBQL using a provided PrintWriter. DB path expressions produce non-standard EJBQL path expressions.
    
    Since:
    
    3.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

Class Expression

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PRUNED_NODE

AND

OR

NOT

EQUAL_TO

NOT_EQUAL_TO

LESS_THAN

GREATER_THAN

LESS_THAN_EQUAL_TO

GREATER_THAN_EQUAL_TO

BETWEEN

IN

LIKE

LIKE_IGNORE_CASE

ADD

SUBTRACT

MULTIPLY

DIVIDE

NEGATIVE

TRUE

FALSE

OBJ_PATH

DB_PATH

LIST

NOT_BETWEEN

NOT_IN

NOT_LIKE

NOT_LIKE_IGNORE_CASE

BITWISE_NOT

BITWISE_AND

BITWISE_OR

BITWISE_XOR

BITWISE_LEFT_SHIFT

BITWISE_RIGHT_SHIFT

FUNCTION_CALL

ASTERISK

FULL_OBJECT

type

Constructor Detail

Expression

Method Detail

fromString

getPathAliases

expName

equals

hashCode

getType

setType

paramsArray

params

params

expWithParameters

expWithParameters

joinExp

joinExp

andExp

andExp

orExp

orExp

notExp

getOperandCount

getOperand

setOperand

evaluate

match

first

filterObjects

filter

deepCopy

shallowCopy

pruneNodeForPrunedChild

flattenTree

traverse

traverse