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
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 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 atindex
.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 atindex
.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.
-
-
-
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
-
-
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.
-
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 atindex
. Operand indexing starts at 0.
-
setOperand
public abstract void setOperand(int index, Object value)
Sets a value of operand atindex
. 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 interfaceXMLSerializable
- 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
-
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
-
-