public interface

WebExpression

com.microstrategy.web.objects.WebExpression

Class Overview

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.

Summary

Public Methods
abstract WebOperatorNode changeMetricFunctionType(WebOperatorNode rootOperatorNode, int functionType, int function)
Changes the metric function type to the given type.
abstract void clear()
Removes all nodes from the expression tree, leaving only a single "AND" operator node with no child nodes at the root of the tree.
abstract WebBigDecimalNode createBigDecimalNode(String value, WebNode parent)
Creates a WebBigDecimalNode object.
abstract WebBigDecimalNode createBigDecimalNode(String value)
Creates a WebBigDecimalNode object.
abstract WebConstantNode createConstantNode(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.
abstract WebConstantNode createConstantNode(String value, int dataType, WebNode parent)
Creates a constant node with the given value and datatype, and appends it to the given node.
abstract WebElementsObjectNode createElementsInListNode(WebObjectInfo wa, int func)
abstract WebElementsObjectNode createElementsInListNode(WebObjectInfo wa, int func, WebNode parent)
abstract WebElementsObjectNode createElementsObjectNode(WebObjectInfo source, WebNode parent)
Creates an element list node which contains elements from the given attribute.
abstract WebElementsObjectNode createElementsObjectNode(WebObjectInfo source)
Creates an element list node which contains elements from the given attribute.
abstract WebElementsObjectNode createElementsObjectNode(WebNode parent)
Creates an element list node, which is used to represent a list of elements in an expression.
abstract WebElementsObjectNode createElementsObjectNode()
Creates an element list node, which is used to represent a list of elements in an expression.
abstract WebFormShortcutNode createFormShortcutNode(WebAttribute attributeInfo, WebAttributeForm formInfo, WebNode parent)
Creates a form shortcut node to the given attribute form, and appends it to the given node.
abstract WebFormShortcutNode createFormShortcutNode(WebAttribute attributeInfo, WebAttributeForm formInfo)
Creates a form shortcut node to the given attribute form, and appends it to the current root node.
abstract WebGroupNode createGroupNode(WebNode parent)
Creates a WebNode object with type DSSXmlNodeGroup enumeration defined in EnumDSSXMLNodeType.
abstract WebNode createMeNode(WebNode parent)
Creates a me node, and appends it to the given node.
abstract WebOperatorNode createMetricPercentOperatorNode(WebObjectInfo metricInfo, int mrpOperator, WebNode parent)
Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a percent function.
abstract WebOperatorNode createMetricPercentOperatorNode(WebObjectInfo metricInfo, int mrpOperator, boolean ascending)
Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a rank function.
abstract WebOperatorNode createMetricPercentOperatorNode(WebObjectInfo metricInfo, int mrpOperator)
Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a percent function.
abstract WebOperatorNode createMetricRankOperatorNode(WebObjectInfo metricInfo, int mrpOperator, WebNode parent)
Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a rank function.
abstract WebOperatorNode createMetricRankOperatorNode(WebObjectInfo metricInfo, int mrpOperator, boolean ascending)
Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a rank function.
abstract WebOperatorNode createMetricRankOperatorNode(WebObjectInfo metricInfo, int mrpOperator)
Creates a node and all the required sub-nodes to enable users to build expression that qualify on metric using a rank function.
abstract WebNode createNode(String expression)
Creates a new WebNode object using the expression provided and appends it to the root node.
abstract WebNode createNode(String expression, WebNode parent)
Creates a new WebNode object using the expression provided and appends it to the given node.
abstract 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.
abstract 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.
abstract WebRefNode createRefNode(WebDerivedElement objectInfo, WebNode parent)
abstract WebRelationshipNode createRelationshipNode(WebNode parentNode)
Creates a new relationship node, and appends it to the given node.
abstract WebRelationshipNode createRelationshipNode()
Creates a new relationship node, and appends it to the root of the expression.
abstract WebResidueNode createResidueNode(WebAttribute attribute, WebNode parent)
abstract WebShortcutNode createShortcutNode(WebObjectInfo objectInfo)
Creates a shortcut node to the given object, and appends it to the root node of the expression tree.
abstract WebShortcutNode createShortcutNode(WebObjectInfo objectInfo, WebNode parent)
Creates a shortcut node to the given object, and appends it to the given node.
abstract WebTimeNode createTimeNode(String time)
Creates a WebTimeNode object as a child of the root of the expression.
abstract WebTimeNode createTimeNode(String time, WebNode parent)
Creates a WebTimeNode object.
abstract WebNode findNode(int key)
Returns the WebNode within the expression tree with the given key.
abstract WebNode findNodeOrNull(int key)
abstract WebNode findTaggedNode(String tag)
This method will search the expression for a node with the given tag.
abstract WebExpressionHelper getExpressionHelper()
This method is used to obtain a WebExpressionHelper object linked to this expression.
abstract List<WebNodePlaceHolder> getPlaceHolders()
Returns a list of placeholders defined in the nodes of this expression.
abstract WebNode getRootNode()
Returns the current root node of the expression.
abstract int getSubExpressionCount()
Returns the number of subexpressions of the root node.
abstract String getXML(boolean removeEmpty)
Builds an expression XML
abstract String getXML()
abstract WebNode importNode(WebNode otherNode)
This method is used to transfer node subtrees between two expressions.
abstract boolean isModified()
Returns whether this expression object has been modified.
abstract void populate(WebExpression expr)
Populates the current expression from the definition of the given expression.
abstract void populate(String expressionText)
Populates WebExpression based on a string expression.
abstract void setExpressionHelper(WebExpressionHelper value)
abstract void setModified(boolean isModified)
This method allows the user to mark this expression object as modified or unmodified.

Public Methods

public abstract 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.

public abstract void clear ()

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
UnsupportedOperationException Thrown if the object is read-only.

public abstract WebBigDecimalNode createBigDecimalNode (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

public abstract WebBigDecimalNode createBigDecimalNode (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

public abstract WebConstantNode createConstantNode (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

public abstract WebConstantNode createConstantNode (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

public abstract WebElementsObjectNode createElementsInListNode (WebObjectInfo wa, int func)

public abstract WebElementsObjectNode createElementsInListNode (WebObjectInfo wa, int func, WebNode parent)

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract WebFormShortcutNode createFormShortcutNode (WebAttribute attributeInfo, WebAttributeForm formInfo, WebNode parent)

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
Throws
IllegalArgumentException Thrown if the WebObjectInfo objects are null.

public abstract WebFormShortcutNode createFormShortcutNode (WebAttribute attributeInfo, WebAttributeForm formInfo)

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
Throws
IllegalArgumentException Thrown if the WebObjectInfo objects are null.

public abstract WebGroupNode createGroupNode (WebNode parent)

Creates a WebNode object with type DSSXmlNodeGroup enumeration defined in EnumDSSXMLNodeType. This is not used in OOTB Web. @deprecated

Throws
IllegalArgumentException

public abstract WebNode createMeNode (WebNode parent)

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
Throws
IllegalArgumentException Thrown if the value of the WebObjectInfo object is null.

public abstract WebOperatorNode createMetricPercentOperatorNode (WebObjectInfo metricInfo, int mrpOperator, WebNode parent)

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
IllegalArgumentException Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

public abstract WebOperatorNode createMetricPercentOperatorNode (WebObjectInfo metricInfo, int mrpOperator, boolean ascending)

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
IllegalArgumentException Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

public abstract WebOperatorNode createMetricPercentOperatorNode (WebObjectInfo metricInfo, int mrpOperator)

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
IllegalArgumentException Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

public abstract WebOperatorNode createMetricRankOperatorNode (WebObjectInfo metricInfo, int mrpOperator, WebNode parent)

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
IllegalArgumentException Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

public abstract WebOperatorNode createMetricRankOperatorNode (WebObjectInfo metricInfo, int mrpOperator, boolean ascending)

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
IllegalArgumentException Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

public abstract WebOperatorNode createMetricRankOperatorNode (WebObjectInfo metricInfo, int mrpOperator)

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
IllegalArgumentException Thrown if the metricInfo node is null or is not of type metric. Also thrown if the MRP operator is invalid.

public abstract WebNode createNode (String expression)

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
WebObjectsException

public abstract WebNode createNode (String expression, WebNode parent)

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
WebObjectsException

public abstract 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

public abstract 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

public abstract WebRefNode createRefNode (WebDerivedElement objectInfo, WebNode parent)

Throws
IllegalArgumentException

public abstract 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

public abstract WebRelationshipNode createRelationshipNode ()

Creates a new relationship node, and appends it to the root of the expression.

Returns

public abstract WebResidueNode createResidueNode (WebAttribute attribute, WebNode parent)

Throws
IllegalArgumentException

public abstract WebShortcutNode createShortcutNode (WebObjectInfo objectInfo)

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
Throws
IllegalArgumentException Thrown if the value of the WebObjectInfo object is null.

public abstract WebShortcutNode createShortcutNode (WebObjectInfo objectInfo, WebNode parent)

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
Throws
IllegalArgumentException Thrown if the value of the WebObjectInfo object is null.

public abstract WebTimeNode createTimeNode (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

public abstract WebTimeNode createTimeNode (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

public abstract WebNode findNode (int key)

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
IllegalArgumentException Thrown if the key is not found in the expression.

public abstract WebNode findNodeOrNull (int key)

public abstract WebNode findTaggedNode (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.

public abstract WebExpressionHelper getExpressionHelper ()

This method is used to obtain a WebExpressionHelper object linked to this expression. The WebExpressionHelper object has several helper methods for manipulating the expression tree.

Returns

public abstract List<WebNodePlaceHolder> getPlaceHolders ()

Returns a list of placeholders defined in the nodes of this expression.

Returns
  • An immutable list of placeholders

public abstract 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.

public abstract 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.

public abstract 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

public abstract String getXML ()

public abstract WebNode importNode (WebNode otherNode)

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
IllegalArgumentException Thrown if the parameter is null.

public abstract boolean isModified ()

Returns whether this expression object has been modified.

Returns
  • True if the expression has been modified, false otherwise.

public abstract 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.

public abstract void populate (String expressionText)

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

public abstract void setExpressionHelper (WebExpressionHelper value)

public abstract 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.