Package com.microstrategy.web.objects

Interface WebExpression

  • public interface WebExpression
    The WebExpression interface represents a filter expression, which is composed of one or more WebNode objects. The root node of an expression can never be null, and cannot be changed by the user. The root node is generally an operator node with function type "and" or "or". However, if an expression is obtained from the server, then it does not necessarily have to be rooted at an and or or node. The expression usually exists as part of WebPrompt, WebElementSource, WebFilter, and WebTemplate objects.
    Since:
    MicroStrategy Web 7.3.1 or earlier

    • Method Detail

      • getRootNode

        WebNode getRootNode()
        Returns the current root node of the expression. While this node's properties can be changed (for example, the function being applied), the actual root node cannot be replaced.
        Returns:
        The current root operator node of the expression.

      • getSubExpressionCount

        int getSubExpressionCount()
        Returns the number of subexpressions of the root node. This will be a simple count of the number of children of the root node.
        Returns:
        The number of subexpressions of the root node.

      • findNode

        WebNode findNode​(int key)
          throws java.lang.IllegalArgumentException
        Returns the WebNode within the expression tree with the given key.
        Parameters:
        key - The key to find within the expression tree.
        Returns:
        A WebNode object corresponding to the given key, or null if the key does not exist in the expression tree.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the key is not found in the expression.

      • importNode

        WebNode importNode​(WebNode otherNode)
            throws java.lang.IllegalArgumentException
        This method is used to transfer node subtrees between two expressions. This must be done before appending a node from one expression to a node in another expression. If a node from another expression is passed to this method, a copy of the node is returned. This copy will be associated with the instance of WebExpression which this method was called on. Note that the import process will cause the keys of the subexpression to be reassigned. Finally, the copy of the node will be returned from this method; this copy can be appended anywhere within the expression that this method is called upon.
        Parameters:
        otherNode - The node to import into this expression. This node will remain untouched in it's original expression.
        Returns:
        A copy of the node passed to this method. The copy will be associated with this expression object.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the parameter is null.

      • clear

        void clear()
    throws java.lang.UnsupportedOperationException
        Removes all nodes from the expression tree, leaving only a single "AND" operator node with no child nodes at the root of the tree.
        Throws:
        java.lang.UnsupportedOperationException - Thrown if the object is read-only.

      • createOperatorNode

        WebOperatorNode createOperatorNode​(int expressionType,
                                   int function)
        Creates an operator node with the given expression type and function type, and appends it to the root node of the tree.
        Parameters:
        expressionType - The type of the subexpression rooted at the operator node, from EnumDSSXMLExpressionType.
        function - The function to assign to the operator node, from EnumDSSXMLFunction.
        Returns:
        The newly created node, of type WebOperatorNode.

      • createOperatorNode

        WebOperatorNode createOperatorNode​(int expressionType,
                                   int function,
                                   WebNode parent)
        Creates an operator node with the given expression type and function type, and appends it to the given node within the expression tree.
        Parameters:
        expressionType - The type of the subexpression rooted at the operator node, from EnumDSSXMLExpressionType.
        function - The function to assign to the operator node, from EnumDSSXMLFunction.
        parent - A WebOperatorNode object which will serve as the parent of the newly created operator node
        Returns:
        The newly created node, of type WebOperatorNode.

      • createOperatorNode

        WebOperatorNode createOperatorNode​(int expressionType,
                                   int function,
                                   WebNode parent,
                                   int nodeProperty)

      • createConstantNode

        WebConstantNode createConstantNode​(java.lang.String value,
                                   int dataType)
        Creates a constant node with the given value and datatype, and appends it to the root node of the expression tree.
        Parameters:
        value - The constant value being represented by the constant node. This value should be in string format regardless of the data type.
        dataType - The data type of the constant value. This should be a value from EnumDSSXMLDataType.
        Returns:
        The newly created node, of type WebConstantNode.

      • createConstantNode

        WebConstantNode createConstantNode​(java.lang.String value,
                                   int dataType,
                                   WebNode parent)
        Creates a constant node with the given value and datatype, and appends it to the given node.
        Parameters:
        value - The constant value being represented by the constant node. This value should be in string format regardless of the data type.
        dataType - The data type of the constant value. This should be a value from EnumDSSXMLDataType.
        parent - The node which the newly created node should be appended to.
        Returns:
        The newly created WebConstantNode object.

      • createTimeNode

        WebTimeNode createTimeNode​(java.lang.String time)
        Creates a WebTimeNode object as a child of the root of the expression. This is used when creating a qualification on an attribute form with a time-based datatype.
        Parameters:
        time - The string representation of the time to use for the node.
        Returns:
        The newly created WebTimeNode object.

      • createTimeNode

        WebTimeNode createTimeNode​(java.lang.String time,
                           WebNode parent)
        Creates a WebTimeNode object. This is used when creating a qualification on an attribute form with a time-based datatype.
        Parameters:
        time - The string representation of the time to use for the node.
        parent - The node to append the newly created one to.
        Returns:
        The newly created WebTimeNode object.

      • createBigDecimalNode

        WebBigDecimalNode createBigDecimalNode​(java.lang.String value)
        Creates a WebBigDecimalNode object. This is used when creating a qualification on an attribute form with a big decimal datatype.
        Parameters:
        value - The string representation of the node value.
        Returns:
        The newly created WebBigDecimalNode object.
        Since:
        MicroStrategy Web 8.0.0

      • createBigDecimalNode

        WebBigDecimalNode createBigDecimalNode​(java.lang.String value,
                                       WebNode parent)
        Creates a WebBigDecimalNode object. This is used when creating a qualification on an attribute form with a big decimal datatype.
        Parameters:
        value - The string representation of the node value.
        parent - The node to append the newly created one to.
        Returns:
        The newly created WebBigDecimalNode object.
        Since:
        MicroStrategy Web 8.0.0

      • createShortcutNode

        WebShortcutNode createShortcutNode​(WebObjectInfo objectInfo)
                            throws java.lang.IllegalArgumentException
        Creates a shortcut node to the given object, and appends it to the root node of the expression tree.
        Parameters:
        objectInfo - The WebObjectInfo object which a shortcut is being made to.
        Returns:
        The newly created WebShortcutNode object.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the value of the WebObjectInfo object is null.

      • createShortcutNode

        WebShortcutNode createShortcutNode​(WebObjectInfo objectInfo,
                                   WebNode parent)
                            throws java.lang.IllegalArgumentException
        Creates a shortcut node to the given object, and appends it to the given node.
        Parameters:
        objectInfo - The WebObjectInfo object which a shortcut is being made to.
        parent - The node which the newly created node will be appended to.
        Returns:
        The newly created WebShortcutNode object.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the value of the WebObjectInfo object is null.

      • createMeNode

        WebNode createMeNode​(WebNode parent)
              throws java.lang.IllegalArgumentException
        Creates a me node, and appends it to the given node.
        Parameters:
        parent - The node which the newly created node will be appended to.
        Returns:
        The newly created WebShortcutNode object.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the value of the WebObjectInfo object is null.
        Since:
        MicroStrategy Web 9.0.0

      • createFormShortcutNode

        WebFormShortcutNode createFormShortcutNode​(WebAttribute attributeInfo,
                                           WebAttributeForm formInfo)
                                    throws java.lang.IllegalArgumentException
        Creates a form shortcut node to the given attribute form, and appends it to the current root node.
        Parameters:
        attributeInfo - The attribute whose form the shortcut points to.
        formInfo - The attribute form which the shortcut refers to.
        Returns:
        The newly created WebFormShortcutNode object.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the WebObjectInfo objects are null.

      • createFormShortcutNode

        WebFormShortcutNode createFormShortcutNode​(WebAttribute attributeInfo,
                                           WebAttributeForm formInfo,
                                           WebNode parent)
                                    throws java.lang.IllegalArgumentException
        Creates a form shortcut node to the given attribute form, and appends it to the given node.
        Parameters:
        attributeInfo - The attribute whose form the shortcut points to.
        formInfo - The attribute form which the shortcut refers to.
        parent - The node which the new node will be appended to.
        Returns:
        The newly created WebFormShortcutNode object.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the WebObjectInfo objects are null.

      • createRelationshipNode

        WebRelationshipNode createRelationshipNode()
        Creates a new relationship node, and appends it to the root of the expression.
        Returns:
        The newly created WebRelationshipNode object.

      • createRelationshipNode

        WebRelationshipNode createRelationshipNode​(WebNode parentNode)
        Creates a new relationship node, and appends it to the given node.
        Parameters:
        parentNode - The node which is meant to be the parent of the newly created node.
        Returns:
        The newly created WebRelationshipNode object.

      • createElementsObjectNode

        WebElementsObjectNode createElementsObjectNode()
        Creates an element list node, which is used to represent a list of elements in an expression. The new node will be appended to the root of the expression tree.
        Returns:
        The newly created WebElementsObjectNode object.

      • createElementsObjectNode

        WebElementsObjectNode createElementsObjectNode​(WebObjectInfo source)
        Creates an element list node which contains elements from the given attribute. The new node will be appended to the root of the expression tree.
        Parameters:
        source - A WebAttribute object representing the attribute which the element list will come from.
        Returns:
        The newly created WebElementsObjectNode object.

      • createElementsObjectNode

        WebElementsObjectNode createElementsObjectNode​(WebNode parent)
        Creates an element list node, which is used to represent a list of elements in an expression. The new node will be appended to the given parent node.
        Parameters:
        parent - The node to append the newly created node to.
        Returns:
        The newly created WebElementsObjectNode object.

      • createElementsObjectNode

        WebElementsObjectNode createElementsObjectNode​(WebObjectInfo source,
                                               WebNode parent)
        Creates an element list node which contains elements from the given attribute. The new node will be appended to the given parent node.
        Parameters:
        source - A WebAttribute object representing the attribute which the element list will come from.
        parent - The node to append the newly created node to.
        Returns:
        The newly created WebElementsObjectNode object.

      • createMetricRankOperatorNode

        WebOperatorNode createMetricRankOperatorNode​(WebObjectInfo metricInfo,
                                             int mrpOperator)
                                      throws java.lang.IllegalArgumentException
        Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a rank function. This method will assume that the parent node of this one will be the root node of the expression.
        Parameters:
        metricInfo - Specifies the metric to be qualified upon.
        mrpOperator - Specifies the operator for metric qualification. This value should come from EnumWebMRPFunction.
        Returns:
        Returns the root WebOperatorNode of the nodes which are created for this operation.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

      • createMetricRankOperatorNode

        WebOperatorNode createMetricRankOperatorNode​(WebObjectInfo metricInfo,
                                             int mrpOperator,
                                             WebNode parent)
                                      throws java.lang.IllegalArgumentException
        Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a rank function. The newly-created node will be appended to the given node.
        Parameters:
        metricInfo - Specifies the metric to be qualified upon.
        mrpOperator - Specifies the operator for metric qualification. This value should come from EnumWebMRPFunction.
        parent - The parent node of the newly created node.
        Returns:
        Returns the root WebOperatorNode of the nodes which are created for this operation.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

      • createMetricRankOperatorNode

        WebOperatorNode createMetricRankOperatorNode​(WebObjectInfo metricInfo,
                                             int mrpOperator,
                                             boolean ascending)
                                      throws java.lang.IllegalArgumentException
        Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a rank function. The newly-created node will be appended to the given node.
        Parameters:
        metricInfo - Specifies the metric to be qualified upon.
        mrpOperator - Specifies the operator for metric qualification. This value should come from EnumWebMRPFunction.
        ascending - The boolean value which indicate the order of rank function
        Returns:
        Returns the root WebOperatorNode of the nodes which are created for this operation.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.
        Since:
        MicroStrategy Web 9.0.0

      • createMetricPercentOperatorNode

        WebOperatorNode createMetricPercentOperatorNode​(WebObjectInfo metricInfo,
                                                int mrpOperator)
                                         throws java.lang.IllegalArgumentException
        Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a percent function. This method will assume that the parent node of this one will be the root node of the expression.
        Parameters:
        metricInfo - Specifies the metric to be qualified upon.
        mrpOperator - Specifies the operator for metric qualification. This value should come from EnumWebMRPFunction.
        Returns:
        Returns the root WebOperatorNode of the nodes which are created for this operation.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

      • createMetricPercentOperatorNode

        WebOperatorNode createMetricPercentOperatorNode​(WebObjectInfo metricInfo,
                                                int mrpOperator,
                                                WebNode parent)
                                         throws java.lang.IllegalArgumentException
        Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a percent function. The newly-created node will be appended to the given node.
        Parameters:
        metricInfo - Specifies the metric to be qualified upon.
        mrpOperator - Specifies the operator for metric qualification. This value should come from EnumWebMRPFunction.
        parent - The parent node of the newly created node.
        Returns:
        Returns the root WebOperatorNode of the nodes which are created for this operation.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

      • createMetricPercentOperatorNode

        WebOperatorNode createMetricPercentOperatorNode​(WebObjectInfo metricInfo,
                                                int mrpOperator,
                                                boolean ascending)
                                         throws java.lang.IllegalArgumentException
        Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a rank function. The newly-created node will be appended to the given node.
        Parameters:
        metricInfo - Specifies the metric to be qualified upon.
        mrpOperator - Specifies the operator for metric qualification. This value should come from EnumWebMRPFunction.
        ascending - The boolean value which indicate the order of rank function
        Returns:
        Returns the root WebOperatorNode of the nodes which are created for this operation.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.
        Since:
        MicroStrategy Web 9.0.0

      • setExpressionHelper

        void setExpressionHelper​(WebExpressionHelper value)
        Since:
        MicroStrategy Web 8.0.2

      • findTaggedNode

        WebNode findTaggedNode​(java.lang.String tag)
        This method will search the expression for a node with the given tag. Either the first one found, or null if none are found, will be returned. There is no guarantee as to which node will be returned from this method if more than one has the tag passed to this method.
        Parameters:
        tag - The tag to search for in the expression.
        Returns:
        The first WebNode found with the given tag, or null if no node with the given tag is found.

      • populate

        void populate​(WebExpression expr)
        Populates the current expression from the definition of the given expression. This will effectively make a copy of the structure of the expression passed in within this expression.
        Parameters:
        expr - A WebExpression object whose definition is to be copied into this object.
        Since:
        MicroStrategy Web 8.0.0

      • isModified

        boolean isModified()
        Returns whether this expression object has been modified.
        Returns:
        True if the expression has been modified, false otherwise.
        Since:
        MicroStrategy Web 8.0.0

      • setModified

        void setModified​(boolean isModified)
        This method allows the user to mark this expression object as modified or unmodified. This is useful when using a copy of an expression to save previous expression state.
        Parameters:
        isModified - The new value for isModified. This will override the current setting for this parameter.
        Since:
        MicroStrategy Web 8.0.0

      • changeMetricFunctionType

        WebOperatorNode changeMetricFunctionType​(WebOperatorNode rootOperatorNode,
                                         int functionType,
                                         int function)
        Changes the metric function type to the given type. This method assumes that the operator node is well-formed, i.e. that it has a shortcut to the metric which is being qualified upon set up appropriately. It will then change the function type of the node, setting up the rest of the tree properly.
        Parameters:
        rootOperatorNode - The operator node whose function type is being changed.
        functionType - The function type, from EnumWebFunctionType, to change the node to.
        function - The function, from either EnumDSSXMLFunction for a generic qualification, or from EnumWebMRPFunction for a metric rank/percent function.
        Returns:
        The modified node. In practice, this will be the same as the node passed in.
        Since:
        MicroStrategy Web 8.0.0

      • getXML

        java.lang.String getXML()
        Since:
        MicroStrategy Web 8.0.2

      • getXML

        java.lang.String getXML​(boolean removeEmpty)
        Builds an expression XML
        Parameters:
        removeEmpty - Indicates whethe empty nodes shall be removed from the expression before building.
        Returns:
        XML string

      • createRefNode

        WebRefNode createRefNode​(WebDerivedElement objectInfo,
                         WebNode parent)
                  throws java.lang.IllegalArgumentException
        Throws:
        java.lang.IllegalArgumentException
        Since:
        MicroStrategy Web 9.0.0

      • createGroupNode

        WebGroupNode createGroupNode​(WebNode parent)
                      throws java.lang.IllegalArgumentException
        Deprecated.
        Creates a WebNode object with type DSSXmlNodeGroup enumeration defined in EnumDSSXMLNodeType. This is not used in OOTB Web.
        Throws:
        java.lang.IllegalArgumentException
        Since:
        MicroStrategy Web 9.0.0

      • createResidueNode

        WebResidueNode createResidueNode​(WebAttribute attribute,
                                 WebNode parent)
                          throws java.lang.IllegalArgumentException
        Throws:
        java.lang.IllegalArgumentException
        Since:
        MicroStrategy Web 9.0.0

      • populate

        void populate​(java.lang.String expressionText)
       throws WebObjectsException
        Populates WebExpression based on a string expression. It supports everything that the backend expression parser supports like Region@ID=2 or Region@Desc in ("North-East"). This is not currently used by OOTB Web but it is used by the Command Manager.
        Throws:
        WebObjectsException
        Since:
        MicroStrategy Web 9.0.0

      • createNode

        WebNode createNode​(java.lang.String expression)
            throws WebObjectsException
        Creates a new WebNode object using the expression provided and appends it to the root node.
        Parameters:
        expression - Expression string, like "[Customer Age]@ID < 25.0" for example.
        Returns:
        Newly created node
        Throws:
        WebObjectsException
        Since:
        MicroStrategy Web 9.0.0

      • createNode

        WebNode createNode​(java.lang.String expression,
                   WebNode parent)
            throws WebObjectsException
        Creates a new WebNode object using the expression provided and appends it to the given node.
        Parameters:
        expression - Expression string, like "[Customer Age]@ID < 25.0" for example.
        parent - Node to which to append the new node
        Returns:
        Newly created node
        Throws:
        WebObjectsException
        Since:
        MicroStrategy Web 9.0.0

      • findNodeOrNull

        WebNode findNodeOrNull​(int key)
        Since:
        MicroStrategy Web 9.0.1

      • getPlaceHolders

        java.util.List<WebNodePlaceHolder> getPlaceHolders()
        Returns a list of placeholders defined in the nodes of this expression.
        Returns:
        An immutable list of placeholders