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:
- A parser that handles java regular expressions: REFilterTextParser, which is a simple wrapper around the java regular expression functionality.
- A generic text parser, supporting complex expressions, and limited wildcard expressions, which is detailed below.
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:
- age > 30 : the column age should contain a value above 30.
- startDate < endDate : the column startDate should contain a value lower than the value in the column endDate.
- A*b: the current column value must start with uppercase a and end with lowercase b
- = A*b: the current column value must be, exactly, A*b (no wildcard substitution here)
- 45: the current column must have the value 45.
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:
- &: the AND operator
- |: the OR operator
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:
- The types associated to both identifiers must be identical.
- This type cannot be the string class (or handled as a string).
Relational operands
The supplied relational operands are:
- Comparison operators:
-
>
<
>=
<=
=
<>
- Comparison operators ignoring the case, which work on the
stringfied contents of the table; these are the same comparison operators,
with the symbol @ added:
-
>@
<@
>=@
<=@
=@
<>@
- Wildcard operators, supporting expressions that can contain the
wildcard characters *, which match zero or more characters,
and ?, which match exactly one any character:
- ~: matching operator.
- !~: not matching operator.
- ~@: matching operator, ignoring case.
- !~@: not matching operator, ignoring case.
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
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