Set the filter for the query.

The filter specification is a String containing a Boolean expression that is to be evaluated for each of the instances in the candidate collection. If the filter is not specified, then it defaults to "true", which has the effect of filtering the input Collection only for class type.

An element of the candidate collection is returned in the result if:

• it is assignment compatible to the candidate Class of the Query; and
• for all variables there exists a value for which the filter expression evaluates to true.

The user may denote uniqueness in the filter expression by explicitly declaring an expression (for example, e1 != e2).

Rules for constructing valid expressions follow the Java language, except for these differences:

• Equality and ordering comparisons between primitives and instances of wrapper classes are valid.
• Equality and ordering comparisons of Date fields and Date parameters are valid.
• White space (non-printing characters space, tab, carriage return, and line feed) is a separator and is otherwise ignored.
• The assignment operators =, +=, etc. and pre- and post-increment and -decrement are not supported. Therefore, there are no side effects from evaluation of any expressions.
• Methods, including object construction, are not supported, except for Collection.contains(Object o), Collection.isEmpty(), String.startsWith(String s), and String.endsWith(String e). Implementations might choose to support non-mutating method calls as non-standard extensions.
• Navigation through a null-valued field, which would throw NullPointerException, is treated as if the filter expression returned false for the evaluation of the current set of variable values. Other values for variables might still qualify the candidate instance for inclusion in the result set.
• Navigation through multi-valued fields (Collection types) is specified using a variable declaration and the Collection.contains(Object o) method.

Identifiers in the expression are considered to be in the name space of the specified class, with the addition of declared imports, parameters and variables. As in the Java language, this is a reserved word which means the element of the collection being evaluated.

Navigation through single-valued fields is specified by the Java language syntax of field_name.field_name....field_name.

A JDO implementation is allowed to reorder the filter expression for optimization purposes.