com.crystaldecisions.sdk.occa.report.data
Interface IFilter

All Known Implementing Classes:

Filter

public interface IFilter

This interface defines filters that are used in record selection and group selection. As the name implies, they are used to select specified data. Initially, the filter is a simple string written in Crystal syntax. When the file is opened, the string is parsed into an array of FilterItems, which is stored in the Filter object's FilterItems property. This is done in such a way that the string is broken up into data components and operator components that act on the data. These components are stored as FieldRangeFilterItem and OperatorFilterItem objects respectively. They are stored in the FilterItems object in the same order that they appear in the formula string. Changing the position of the objects in the array alters the functionality of the formula. Essentially, the FieldRangeFilterItem object is a primitive expression that is joined with other primitive expressions using a OperatorFilterItem object.

Consider a simple record selection formula such as: {Customer.Country} = "USA". This formula filters out all records that do not have the country field equal to USA; it is stored in the FreeEditingText property. After this string is parsed, the FilterItems object will contain one FieldRangeFilterItem object because there is only one data item used to filter the records. There is no OperatorFilterItem object because there is only one primitive expression: the OperatorFilterItem is used to indicate how two primitive expressions are combined.

The FieldRangeFilterItem contains four properties:

• Operation
  This indicates which operation is being performed within the primitive expression; in this case it would be the equals operator.
• Inclusive
  Inclusive indicates if the operation is inclusive, for example if the > operator were used, this would indicate whether the expression would use >= or simply >. Only the less than or greater than operations use this property.
• RangeField
  The RangeField indicates the field that is being used in the expression; in this case it would be the Country field. Not all fields can be used to filter records and groups. To determine whether or not a field can be used for a particular filter, use the canFilterOn method in the RecordFilterController and the GroupFilterController.
• Values
  Values indicates which values are being used in the expression; in this case it is the string "USA". It has one ConstantValue object that stores "USA".

  Note: If the formula were expanded to include an additional field so that the formula looked like {Customer.Country} = "USA" AND {Customer.Region} = "CA", the resulting FilterItems object would contain the following:

  • A FieldRangeFilterItem ({Customer.Country} = "USA")
  • A OperatorFilterItem (AND)
  • Another FieldRangeFilterItem ({Customer.Region} = "CA")
  There is now an OperatorFilterItem object to combine the two primitive expressions ({Customer.Country} = "USA" , {Customer.Region} = "CA"). The OperatorFilterItem object has a method getOperator() to indicate which operator is used to combine the two expressions; in this case it would be the string "AND".

  Tip: When parentheses are included in a complex expression, each parenthesis is parsed into a OperatorFilterItem.

Once the file is opened, and if the filter strings are parsed, the FreeEditingText property that stored these strings is emptied. If the formula is too complex and could not be parsed, the FilterItems property collection is empty and the FreeEditingText property remains. When modifying a filter you have two options:

• You may modify the FreeEditingText property.
• You may modify the FilterItems property.

Be aware, however, that if you use the one property to modify the filter, the other will not be automatically updated. That is, if you modify the FreeEditingText property, it is not re-parsed and the results are not stored in the FilterItems property. You should use only one of these properties per session.

Note: The modifications you make to a filter are saved only if you have used a controller. Use the GroupFilterController and the RecordFilterController to modify the group formula and record formula respectively.

Method Summary

java.lang.String	computeText() Returns a String representation of the field value that can be used in a report formula.
java.lang.String	displayText(FieldDisplayNameType displayNameType, java.util.Locale locale) Returns a UI-friendly string representation of the filter.
FilterItems	getFilterItems() Returns the result of a parsed filter string.
FormulaNullTreatment	getFormulaNullTreatment() Returns how to treat null values in the evaluation of a formula.
java.lang.String	getFreeEditingText() Returns the formula text that was originally used to define the filter.
java.lang.String	getName() Returns the name of the filter.
void	setFilterItems(FilterItems filterItems) Sets the result of a parsed filter string.
void	setFormulaNullTreatment(FormulaNullTreatment treatment) Sets how to treat null values in the evaluation of a formula.
void	setFreeEditingText(java.lang.String freeEditingText) Sets the formula text that will be used to define the filter.
void	setName(java.lang.String name) Sets the name of the filter.

Method Detail

computeText

java.lang.String computeText()

Returns a String representation of the field value that can be used in a report formula. The string is not formatted or localized. The syntax will always be Crystal syntax.

If the field contains a date, computeText returns Date(x, x, x); if it contains a date and time, computeText returns DateTime(x, x, x, x, x, x). However, when the date is 1900, 0, 1 (the Java start date), computeText returns Time(x, x, x). If you want to set a field to a time value only (that is, with no date), you should set the date to 1900, 0, 1, so that computeText will retrieve the correct information.

Returns:

A String representation of the field value that can be used in a report formula.

displayText

java.lang.String displayText(FieldDisplayNameType displayNameType,
                             java.util.Locale locale)

Returns a UI-friendly string representation of the filter. This method attempts to structure the filter formula as close to a localized phrase as possible. If you do not pass in a locale, it attempts to localize the string using the user's default locale.

If the field contains a date, displayText returns a locale-specific Date string; if it contains a date and time, displayText returns a locale-specific DateTime string; if it contains a time string, displayText returns a locale-specific Time string.

Parameters:

displayNameType - Indicates how the name of the field is displayed.

locale - Localizes the string according to a specific locale.

Returns:

A UI-friendly string representation of the filter.

getFilterItems

FilterItems getFilterItems()

Returns the result of a parsed filter string. When a filter string is parsed, it is broken into the following categories:

• The data field that is being filtered (FieldRangeFilterItem).
• The operation used to perform the filter (OperatorFilterItem).

This property contains all of these categories. This property will contain data only if the original filter string was successfully parsed. Use the getFreeEditingText method to check whether the formula was parsed successfully. If it is empty, then the parsing was successful.

Note: If you modify the filter using this method, the FreeEditingText property will not be updated.

Returns:

A FilterItems object containing the result of a parsed filter string.

getFreeEditingText

java.lang.String getFreeEditingText()

Returns the formula text that was originally used to define the filter. This String will be empty if the formula was successfully parsed into the FilterItems property. If the formula text was too complicated to be parsed, this property will still contain the formula text and the getFilterItems method will return null.

Note: If you modify the filter using this property, the FilterItems property will not be updated until the file is saved and reopened--regardless of whether the initial parsing was successful or not.

Returns:

A String containing the formula text that was originally used to define the filter.

getName

java.lang.String getName()

Returns the name of the filter.

Returns:

A String containing the name of the filter.

setFilterItems

void setFilterItems(FilterItems filterItems)

Sets the result of a parsed filter string. When a filter string is parsed, it is broken into the following categories:

• The data field that is being filtered (FieldRangeFilterItem).
• The operation used to perform the filter (OperatorFilterItem).

This property contains all of these categories. This property will contain data only if the original filter string was successfully parsed. Use the getFreeEditingText method to check whether the formula was parsed successfully. If it is empty, then the parsing was successful.

Note: If you modify the filter using this method, the FreeEditingText property will not be updated.

Parameters:

filterItems - A FilterItems object containing the result of a parsed filter string.

setFreeEditingText

void setFreeEditingText(java.lang.String freeEditingText)

Sets the formula text that will be used to define the filter. This String will be empty if the formula is successfully parsed into the FilterItems property. If the formula text is too complicated to be parsed, this property will still contain the formula text and the getFilterItems method will return null.

Note: If you modify the filter using this property, the FilterItems property will not be updated until the file is saved and reopened--regardless of whether the initial parsing was successful or not.

Parameters:

freeEditingText - A String containing the formula text that was originally used to define the filter.

setName

void setName(java.lang.String name)

Sets the name of the filter.

Parameters:

name - A String containing the name of the filter.

getFormulaNullTreatment

FormulaNullTreatment getFormulaNullTreatment()

Returns how to treat null values in the evaluation of a formula.

By default, null values are treated as exceptions, which means that as soon as RAS encounters a null valued field in a formula, it immediately stops evaluating the formula and produces no value.

If you want to handle null field values in your formula, you must explicitly do so by adding a test function such as IsNull(). You also have the option to treat nulls as default values. The following are the default values for different types used in a formula.

• Number: 0
• Currency: $0
• Boolean: False
• Date: NullDate
• Time: NullTime
• DateTime: (NullDate, NullTime)
• String: ""
• Array: 0-length array
• Range: Upper and lower bounds are both default values.

Returns:

The FormulaNullTreatment object that specifies how to treat null values in the evaluation of a formula.

setFormulaNullTreatment

void setFormulaNullTreatment(FormulaNullTreatment treatment)

Sets how to treat null values in the evaluation of a formula.

By default, null values are treated as exceptions, which means that as soon as RAS encounters a null valued field in a formula, it immediately stops evaluating the formula and produces no value.

If you want to handle null field values in your formula, you must explicitly do so by adding a test function such as IsNull(). You also have the option to treat nulls as default values. The following are the default values for different types used in a formula.

• Number: 0
• Currency: $0
• Boolean: False
• Date: NullDate
• Time: NullTime
• DateTime: (NullDate, NullTime)
• String: ""
• Array: 0-length array
• Range: Upper and lower bounds are both default values.

Parameters:

treatment - The FormulaNullTreatment object that specifies how to treat null values in the evaluation of a formula.