In addition to a robust and compliant implementation of the iCalendar specification, it is also important to have an expressive and powerful mechanism for accessing calendar data. iCal4j filters provide a framework for calendar object retrieval whether it be in-memory object models or some other data source.
Filter expressions serve to provide an abstract syntax tree (AST) for modeling an iCalendar filter that can be used to filter data from various data sources.
A unary expression contains a single operand and operator, with the operand being another expression. Unary expressions may be of prefix or postfix form:
<operator> <operand> # prefix unary expression, such as 'not something'
<operand> <operator> # postfix expression, such as 'something exists'
Some example unary expressions include:
not attendee = '[email protected]' # events not including joeb
not due < startOfDay() # todos that are not overdue
attendee[partstat:TENTATIVE] exists # events with tentative attendees
attendee[role:CHAIR] not exists # events without a chair
A binary expression include a left and right operand and and operator.
Some example binary expressions include:
attendee = '[email protected] # events including joeb
due < startOfDay() # todos that are overdue
A specification expression represents an object specification, with a name, optional value and attributes. For example, a specification representing a property would be a property name, (optional) property value and a list of parameter attributes.
A specification match is defined as matching object name and the existence of the specified attributes. If a value is supplied this must also match the object value.
NOTE: The specification value is used to test object equivalence with unary expressions. For binary expression matching the literal expression is used to provide a value.
A literal expression is the mechanism to supply a specification value for binary expressions. Supported literals include String, Integer, Date, Collection and Function, which may be used with both comparison and value matching operators.
Operators are used in binary and unary expressions to specify expression behaviour.
Object Matching Operators
An object matching operator is used to test for existence of an object matching the specification. In addition to the specification used in unary expressions, binary expressions also test for a literal value.
Object matching operators include:
equalTo- a binary expression operator that matches object exactly on both specification and literal value
notEqualTo- the negative of the
in- a binary expression operator that matches exactly any object in the collection literal
notIn- the negative of the
exists- a unary expression operator that tests for the existence of the specified operand (only applicable for specification expression operands)
not exists- the negative of the exists operator
Comparison operators include:
greaterThan- a binary expression operator that matches object comparison greater than the supplied specification value
greaterThanEquala binary expression operator that matches object comparison greater than or equal to the supplied specification value
lessThana binary expression operator that matches object comparison less than the supplied specification value
lessThanEquala binary expression operator that matches object comparison less than or equal to the supplied specification value
betweena binary expression operator that matches object comparison greater than or equal to the first element in the supplied specification collection, and less than or equal to the second specification collection value
Value Matching Operators
Value matching operators include:
containsa binary expression operator that matches object values that contain the supplied specification value string
matchesa binary expression operator that matches object values against the supplied specification regular expression
Logical operators include:
anda binary expression operator that returns the logical and of two expressions (not applicable for specification or literal expression operands)
ora binary expression operator that returns the logical or of two expressions (not applicable for specification or literal expression operands)
not- the negation of the operand expression (not applicable for specification or literal expression operands)
The ComponentFilter is an implementation of a PredicateFactory that is able to convert a filter expression into a Predicate for iCal4j Components.
The PropertyFilter is an implementation of a PredicateFactory that is able to convert a filter expression into a Predicate for iCal4j Properties.