Filter text expressions

The parsing filter editors do not perform the parsing of the text expressions by themselves, delegating this task to separated components; it is possible to provide more or less powerful parsers, making therefore this library more or less useful.

The library is delivered with two parsers:

The library also supports customized parsers, which must implement a quite simple interface. The default parser implementation is called FilterTextParser, in the package net.coderazzi.filters.parser.generic, while the generic interfaces are defined in the net.coderazzi.filters.parser.

Default filter text parser

The provided filter text parser can handle simple expressions mixing values related to one or more variables, where each variable is, in this context, the content of a cell in a table's row. Note that the parser has no direct relation with a Swing table: it only knows about identifiers and values, although the description below assumes that these identifiers are the header strings for each column.

The minimum filter expression has the syntax: [ [ identifier ] operand ] constant | identifier

For example:

These examples show some relational operands (>, <, ~); however, it is possible to customize the parser and define different operands.

It is not possible, however, to customize the logical operands used to compose more complex filters. The default parser uses the following hardcoded symbols:

In addition, it is possible to group filters using parenthesis ( )

For example, it supports the following expression: ( age > 30 | age < 20 ) & male = true

If any expression would require using these hardcoded symbols, it should escape these characters with the symbol \.

There are important restrictions concerning the comparison between identifiers; these restrictions are intended to keep simple the grammar of the parser:

Relational operands

The supplied relational operands are:

If possible, the first set of operators (comparison operators) work with the types themselves, not with their string representation. Note that the number 2 is, as a string, higher than the number 12, so this distinction is quite important.

Default relational operand

If the user specifies no operand, the default one is '~'. That is, the filter will work using limited wildcard expressions. For example, if a column has type Integer, the user can enter 1* to filter out all the rows not containing an integer starting with 1, on this specific column.

This behavior is new from version 2.1; on previous versions, the default operator was '=' when the associated type was not a string. It is possible to revert to the original behaviour, but only by subclassing the OperandFactory class, redefining the getDefaultOperand method.

"null"

The default parser has hardcoded the notion of null, making possible to build filters asking whether a given cell is null or not.

The default value associated to null is the string null, although using the method setNullString in the filter parser, other representations could be provided. In special, pay attention to the system properties way to alter this library behaviour.

A cell matches this filter when it contains a null object or when it is handled as a string and it is empty.

Supported types

This section has been moved.

Customizing the default parser

It is possible to create the FilterTextParser, with a different set of operands and / or supported types.

Implementing the interface IRelationalOperandFactory, or inheriting the default implementation OperandFactory, is the minimum requirement to modify the supported operators, but such operation is not described here. If this is needed, please study the source code or contact me for additional support.

The easiest way to define the text parser to be used by default is to override the system property "net.coderazzi.filters.TextParser.class" or, more easily, to redefine the value TableFilter.Settings.filterTextParserClass