Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.objectstyle.cayenne.exp
Class Expression

    java.lang.Object
      org.objectstyle.cayenne.exp.Expression

All Implemented Interfaces:
  java.io.Serializable, XMLSerializable

Direct Known Subclasses:
  BinaryExpression, ListExpression, SimpleNode, TernaryExpression, UnaryExpression

    public abstract class Expression

extends java.lang.Object
implements java.io.Serializable, XMLSerializable

Superclass of Cayenne expressions that defines basic API for expressions use.

See Also:
  Serialized Form

Field Summary
`static int` | `ADD`
`static int` | `ALL` Deprecated. since 1.2
`static int` | `AND`
`static int` | `ANY` Deprecated. since 1.2
`static int` | `AVG` Deprecated. since 1.2
`static int` | `BETWEEN`
`static int` | `COUNT` Deprecated. since 1.2
`static int` | `DB_PATH` Expression describes a path relative to a DbEntity.
`static int` | `DIVIDE`
`static int` | `EQUAL_TO`
`static int` | `EXISTS` Deprecated. since 1.2
`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` | `MAX` Deprecated. since 1.2
`static int` | `MIN` Deprecated. since 1.2
`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 int` | `POSITIVE` Deprecated. since 1.2
`static java.lang.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` | `RAW_SQL` Deprecated. since 1.2
`static int` | `SOME` Deprecated. since 1.2
`static int` | `SUBQUERY` Deprecated. since 1.2
`static int` | `SUBTRACT`
`static int` | `SUM` Deprecated. since 1.2
`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` | `encodeAsString(java.io.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(java.lang.Object object)`
`abstract java.lang.Object` | `evaluate(java.lang.Object o)` Calculates expression value with object as a context for path expressions.
`java.lang.String` | `expName()` Returns String label for this expression.
`Expression` | `expWithParameters(java.util.Map parameters)` A shortcut for `expWithParams(params, true)`.
`Expression` | `expWithParameters(java.util.Map parameters, boolean pruneMissing)` Creates and returns a new Expression instance using this expression as a prototype.
`java.util.Collection` | `filter(java.util.Collection source, java.util.Collection target)` Adds objects matching this expression from the source collection to the target collection.
`java.util.List` | `filterObjects(java.util.List 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(java.lang.String expressionString)` Parses string, converting it to Expression.
`abstract java.lang.Object` | `getOperand(int index)` Returns a value of operand at `index`.
`abstract int` | `getOperandCount()` Returns a count of operands of 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(java.lang.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(java.lang.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, java.lang.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.
`java.lang.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 java.lang.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 java.lang.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

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

### EXISTS

    public static final int EXISTS

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### POSITIVE

    public static final int POSITIVE

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### ALL

    public static final int ALL

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### SOME

    public static final int SOME

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### ANY

    public static final int ANY

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### RAW_SQL

    public static final int RAW_SQL

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### SUBQUERY

    public static final int SUBQUERY

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### SUM

    public static final int SUM

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### COUNT

    public static final int COUNT

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### AVG

    public static final int AVG

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### MAX

    public static final int MAX

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### MIN

    public static final int MIN

  Deprecated. since 1.2
  See Also:
    Constant Field Values

### type

    protected int type

Constructor Detail

### Expression

    public Expression()

Method Detail

### fromString

    public static Expression fromString(java.lang.String expressionString)

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

  Since:
    1.1

### expName

    public java.lang.String expName()

  Returns String label for this expression. Used for debugging.

### equals

    public boolean equals(java.lang.Object object)

  Overrides:
    `equals` in class `java.lang.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(java.util.Map parameters)

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

### expWithParameters

    public Expression expWithParameters(java.util.Map 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 java.lang.Object getOperand(int index)

  Returns a value of operand at `index`. Operand indexing starts at 0.

### setOperand

    public abstract void setOperand(int index,
                                    java.lang.Object value)

  Sets a value of operand at `index`. Operand indexing starts at 0.

### evaluate

    public abstract java.lang.Object evaluate(java.lang.Object o)

  Calculates expression value with object as a context for path expressions.

  Since:
    1.1

### match

    public boolean match(java.lang.Object o)

  Calculates expression boolean value with object as a context for path expressions.

  Since:
    1.1

### filterObjects

    public java.util.List filterObjects(java.util.List objects)

  Returns a list of objects that match the expression.

### filter

    public java.util.Collection filter(java.util.Collection source,
                                       java.util.Collection 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(java.lang.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 java.lang.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(java.io.PrintWriter pw)

  Stores a String representation of Expression using a provided PrintWriter.

  Since:
    1.1

### toString

    public java.lang.String toString()

  Overrides:
    `toString` in class `java.lang.Object`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2006 ObjectStyle.org All Rights Reserved.