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.