org.apache.cayenne.exp
Class Expression

java.lang.Object
  extended by 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
static int ADD
           
static int AND
           
static int BETWEEN
           
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
Expression()
           
 
Method Summary
 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.
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:

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:

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

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

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-2011 Apache Cayenne. All Rights Reserved.