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:

  • Field Details

    • 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:

    • OR

      public static final int OR
      See Also:

    • NOT

      public static final int NOT
      See Also:

    • EQUAL_TO

      public static final int EQUAL_TO
      See Also:

    • NOT_EQUAL_TO

      public static final int NOT_EQUAL_TO
      See Also:

    • LESS_THAN

      public static final int LESS_THAN
      See Also:

    • GREATER_THAN

      public static final int GREATER_THAN
      See Also:

    • LESS_THAN_EQUAL_TO

      public static final int LESS_THAN_EQUAL_TO
      See Also:

    • GREATER_THAN_EQUAL_TO

      public static final int GREATER_THAN_EQUAL_TO
      See Also:

    • BETWEEN

      public static final int BETWEEN
      See Also:

    • IN

      public static final int IN
      See Also:

    • LIKE

      public static final int LIKE
      See Also:

    • LIKE_IGNORE_CASE

      public static final int LIKE_IGNORE_CASE
      See Also:

    • ADD

      public static final int ADD
      See Also:

    • SUBTRACT

      public static final int SUBTRACT
      See Also:

    • MULTIPLY

      public static final int MULTIPLY
      See Also:

    • DIVIDE

      public static final int DIVIDE
      See Also:

    • NEGATIVE

      public static final int NEGATIVE
      See Also:

    • TRUE

      public static final int TRUE
      See Also:

    • FALSE

      public static final int FALSE
      See Also:

    • 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:

    • 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:

    • LIST

      public static final int LIST
      Interpreted as a comma-separated list of literals.
      See Also:

    • NOT_BETWEEN

      public static final int NOT_BETWEEN
      See Also:

    • NOT_IN

      public static final int NOT_IN
      See Also:

    • NOT_LIKE

      public static final int NOT_LIKE
      See Also:

    • NOT_LIKE_IGNORE_CASE

      public static final int NOT_LIKE_IGNORE_CASE
      See Also:

    • BITWISE_NOT

      public static final int BITWISE_NOT
      Since:
      3.1
      See Also:

    • BITWISE_AND

      public static final int BITWISE_AND
      Since:
      3.1
      See Also:

    • BITWISE_OR

      public static final int BITWISE_OR
      Since:
      3.1
      See Also:

    • BITWISE_XOR

      public static final int BITWISE_XOR
      Since:
      3.1
      See Also:

    • BITWISE_LEFT_SHIFT

      public static final int BITWISE_LEFT_SHIFT
      Since:
      4.0
      See Also:

    • BITWISE_RIGHT_SHIFT

      public static final int BITWISE_RIGHT_SHIFT
      Since:
      4.0
      See Also:

    • FUNCTION_CALL

      public static final int FUNCTION_CALL
      Since:
      4.0
      See Also:

    • ASTERISK

      public static final int ASTERISK
      Since:
      4.0
      See Also:

    • FULL_OBJECT

      public static final int FULL_OBJECT
      Since:
      4.0
      See Also:

    • ENCLOSING_OBJECT

      public static final int ENCLOSING_OBJECT
      Since:
      4.2
      See Also:

    • EXISTS

      public static final int EXISTS
      Since:
      4.2
      See Also:

    • NOT_EXISTS

      public static final int NOT_EXISTS
      Since:
      4.2
      See Also:

    • SUBQUERY

      public static final int SUBQUERY
      Since:
      4.2
      See Also:

    • DBID_PATH

      public static final int DBID_PATH
      Since:
      4.2
      See Also:

    • CUSTOM_OP

      public static final int CUSTOM_OP
      Since:
      4.2
      See Also:

    • type

      protected int type

  • Constructor Details

    • Expression

      public Expression()

  • Method Details

    • 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