Package ubic.gemma.rest.util.args

Class FilterArg<O extends Identifiable>

  • All Implemented Interfaces:
    Arg<FilterArg.Filter>
    public class FilterArg<O extends Identifiable>
extends AbstractArg<FilterArg.Filter>
    Represent a filter argument designed to generate a Filters from user input.

    Filtering is done by constructing predicates in the property operator requiredValue form. Properties, operators and required values must be delimited by spaces.

    Properties

    Filtering can be done on any property or nested property of an entity managed by a FilteringService. E.g: 'curationDetails' or 'curationDetails.lastTroubledEvent.date'.

    The available filterable properties on an entity can be retrieved from FilteringService.getFilterableProperties().

    Any property of a supported type. Currently, supported types are:

    String
    Property of String type. Strings that contain parenthesis (), comma , or space ' ' characters, or empty strings must be quoted with double-quotes ". Double-quotes can be escaped with a backslash character: \".
    Number
    Any Number subclasses (i.e. Float, Double, Integer, Long). Required value must be a string parseable to the specific number type.
    Boolean
    Required value will be parsed to true only if the string matches true, ignoring case.
    Date
    Property of Date, required value must be an ISO 8601 formatted date or datetime, UTC is assumed of no timezone is supplied.
    Collection
    Property of a Collection of any type aforementioned, nested collections are not supported. The format of collection is a sequence of comma-delimited values surrounded by parenthesis. The values must be compatible with the type contained in the collection.
    Example: (1,2,3,4)

    Operators

    Accepted operator keywords are:
    =
    Equality
    !=
    Non-equality
    <
    Smaller than (only Number and Date types)
    >
    Larger than (only Number and Date types)
    <=
    Smaller or equal (only Number and Date types)
    >=
    Larger or equal (only Number and Date types)
    like or LIKE
    Similar string, effectively means 'begins with', translates to the SQL LIKE operator where a '%' is appended to the given value (only String type)
    not like or NOT LIKE
    Similar string, effectively means 'does not begins with', translates to the SQL NOT LIKE operator where a '%' is appended to the given value (only String type)
    in or IN
    Required value in the given collection with the semantic of the '=' equality operator (only for Collection types)
    not in or NOT IN
    Required value not in the given collection with the semantic of '=' equality operator (only for Collection types)
    See Filter.Operator for more details on the available operators.

    Quantifiers

    If the property refers to a collection of entities, an quantifier can be used to indicate the desired behavior:
    any(predicate)
    True if any element of the collection satisfies the predicate.
    all(predicate)
    True if all elements of the collection satisfies the predicate. Note that this is true for an empty collection.
    none(predicate)
    True if no element of the collection satisfies the predicate. Note that this is true for an empty collection.
    By default, any(predicate) is used.

    Logical expressions

    Multiple filters can be chained using conjunctions (i.e. AND, and) or disjunctions (i.e. OR, or, ',') keywords. Example:
    property1 < value1 AND property2 like value2

    Queries mixing conjunctions and disjunctions are interpreted in conjunctive normal form (CNF) without any parentheses. Every AND conjunctions separates blocks of OR disjunctions.

    Example:
    p1 = v1 OR p1 != v2 AND p2 <=v2 AND p3 > v3, p3 < v4

    Above query will translate to:
    (p1 = v1 OR p1 != v2) AND (p2 <= v2) AND (p3 > v3 OR p3 < v4)

    Breaking the CNF results in an error.

    Author:
    tesarst, poirigui
    See Also:
    Filters, Filter, Filter.Operator, FilteringService

    • Field Detail

      • MAX_CLAUSES

        public static final int MAX_CLAUSES
        Maximum number of clauses that can appear in a filter expression.
        See Also:
        Constant Field Values

    • Method Detail

      • valueOf

        public static <O extends Identifiable> FilterArg<O> valueOf​(String s)
        Used by RS to parse value of request parameters.

        The filter string may be compressed and base64-encoded.

        Parameters:
        s - the request filter string.
        Returns:
        an instance of DatasetFilterArg representing the filtering options in the given string.