Class Expression

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

        protected int type
    • Constructor Detail

      • Expression

        public Expression()
    • 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.
      • 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
      • 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
      • 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