Understanding the Filter class

The com.crystaldecisions.sdk.occa.report.data.IFilter interface is used to encapsulate a filter in a report containing a selection formula.
Filters are used during saved data, record, and group selection to select specific data from the data source. Initially, the filter is a simple string formula. When the report is opened, the formula string is parsed into a com.crystaldecisions.sdk.occa.report.data.FilterItems collection, and can be accessed from the getFilterItems method of the IFilter interface. The parsing divides the formula string into primitive field expressions (IFieldRangeFilterItem) and operators (IOperatorFilterItem) that act on the data. Each component is stored in the FilterItems collection in the same order that they appear in the formula string. Changing the position of the objects in the collection alters the functionality of the formula.
Consider a record selection formula such as: {Customer.Region} = "CA" AND {Customer.Country} = "USA". This formula filters out all customer records that do not have a country field equal to "USA" and a region field equal to "CA". Each of these two primitive expressions in the formula is parsed into a IFieldRangeFilterItem object. There is also an IOperatorFilterItem object representing the operator that relates the two primitive expressions; in this case, it is the string "AND".

Note: When parentheses are included in a complex expression, each parenthesis is parsed into an additional IOperatorFilterItem object at the appropriate index of the FilterItems collection.
Each of the two IFieldRangeFilterItem objects has three important methods:
  • setOperation
    Indicates the operation performed within the primitive expression; in this case, it is the equality operator.
  • setRangeField
    Indicates the field that is being used in the expression; in this case, it is the Country field. Not all fields can be used to filter records and groups. Use the FilterController.canFilterOn method to determine whether a field can be used for a particular filter.
  • setValues
    Indicates the values used in the expression; in this case, it is the string "USA".
The representation of a filter string by the FilterItems collection allows you access and manipulate specific parts of the formula. For example, you could display the primitive field expressions and operators in separate UI controls, allow the user to customize their values, and submit a refresh of the report with the new filter formula.

Note: Once the report is opened, and the filter strings are parsed, the IFilter.getFreeEditingText method return nothing. However, if the formula is too complex to be parsed into a FilterItems collection, the getFilterItems method returns nothing and the getFreeEditingText method returns a pure string representation of the entire formula.