Package com.tangosol.util

Class QueryHelper

  • public final class QueryHelper
extends Object

    QueryHelper is a utility class that provides a set of factory methods used for building instances of Filter or ValueExtractor.

    The QueryHelper API accepts a String that specifies the creation of rich Filters in a format similar to SQL WHERE clauses. For example, the String "street = 'Main' and state = 'TX'" will create a tree of Filters similar to the following Java code:

    new AndFilter(
      new EqualsFilter("getStreet","Main"),
      new EqualsFilter("getState","TX"));

    The following keywords are currently supported (words between brackets are optional):

    • Comparison operators: =, >, >=, <, <=, <> [ NOT ] BETWEEN, [ NOT ] LIKE, [ NOT ] IN, IS [ NOT ] NULL , CONTAINS [ ALL | ANY ]
    • Logical operators: (AND, OR, NOT)
    • Literal numbers, and the constants true, false, and null

    Each argument to an operator is converted into a ReflectionExtractor. Additionally, the "." operator will use ChainedExtractor. Pseudo functions key() and value() may be used to specify the use of a key as in "key() between 10 and 50". The value() pseudo function is a shorthand for IdentityExtractor.

    Query bind variables are supported in two forms. One form is a "?" followed by a position number; for example: "dept = ?1 and serviceCode in [10,20,30]". For this usage, supply an Object array of parameters to createFilter(String, Object[]). Note: this scheme treats 1 as the starting index into the array.

    Additionally, named bind parameters are supported. The above example could be: "dept = :deptNum and serviceCode in :myList". This style requires the use of a Map with createFilter(String, Map). Both forms can be used in the same specification.

    The factory methods catch a number of Exceptions from the implementation stages and subsequently may throw an unchecked FilterBuildingException.

    Author:
    djl 2009.9.3

    • Method Detail

      • createFilter

        public static Filter createFilter​(String sWhereClause)
        Make a new Filter from the given String.
        Parameters:
        sWhereClause - a String in the Coherence Query Language representing a Filter
        Returns:
        the constructed Filter
        Throws:
        FilterBuildingException - may be thrown

      • createFilter

        public static Filter createFilter​(String sWhereClause,
                                  Object[] aoBindings)
        Make a new Filter from the given String.
        Parameters:
        sWhereClause - a String in the Coherence Query Language representing a Filter
        aoBindings - the array of Objects to use for Bind variables
        Returns:
        the constructed Filter
        Throws:
        FilterBuildingException - may be thrown

      • createFilter

        public static Filter createFilter​(String sWhereClause,
                                  Map mapBindings)
        Make a new Filter from the given String.
        Parameters:
        sWhereClause - a String in the Coherence Query Language representing a Filter
        mapBindings - the Map of Objects to use for Bind variables
        Returns:
        the constructed Filter
        Throws:
        FilterBuildingException - may be thrown

      • createFilter

        public static Filter createFilter​(String sWhereClause,
                                  Object[] aBindings,
                                  Map mapBindings)
        Make a new Filter from the given String.
        Parameters:
        sWhereClause - a String in the Coherence Query Language representing a Filter
        aBindings - the array of Objects to use for Bind variables
        mapBindings - the Map of Objects to use for Bind variables
        Returns:
        the constructed Filter
        Throws:
        FilterBuildingException - may be thrown

      • createFilter

        public static Filter createFilter​(String sWhereClause,
                                  Object[] aBindings,
                                  Map mapBindings,
                                  CoherenceQueryLanguage language)
        Make a new Filter from the given String.
        Parameters:
        sWhereClause - a String in the Coherence Query Language representing a Filter
        aBindings - the array of Objects to use for indexed Bind variables
        mapBindings - the Map of Objects to use for named Bind variables
        language - the CoherenceQueryLanguage instance to use
        Returns:
        the constructed Filter
        Throws:
        FilterBuildingException - may be thrown

      • createExtractor

        public static ValueExtractor createExtractor​(String s)
        Make a new ValueExtractor from the given String.
        Parameters:
        s - a String in the Coherence Query Language representing a ValueExtractor
        Returns:
        the constructed ValueExtractor
        Throws:
        FilterBuildingException - may be thrown

      • createExtractor

        public static ValueExtractor createExtractor​(String sQuery,
                                             CoherenceQueryLanguage language)
        Make a new ValueExtractor from the given String.
        Parameters:
        sQuery - a String in the Coherence Query Language representing a ValueExtractor
        language - the CoherenceQueryLanguage instance to use
        Returns:
        the constructed ValueExtractor
        Throws:
        FilterBuildingException - may be thrown

      • parse

        protected static Term parse​(String sQuery)
        Return the Term representing the AST produced by parsing the specified CohQL query String.
        Parameters:
        sQuery - the CohQL query to be parsed
        Returns:
        the Term representing the AST produced by parsing the specified CohQL query String

      • parse

        protected static Term parse​(String sQuery,
                            CoherenceQueryLanguage language)
        Return the Term representing the AST produced by parsing the specified CohQL query String. This method takes a CoherenceQueryLanguage parameter which allows CohQL customisations to be applied to the CohQL syntax.
        Parameters:
        sQuery - the CohQL query to be parsed
        language - the CoherenceQueryLanguage instance to use
        Returns:
        the Term representing the AST produced by parsing the specified CohQL query String

      • executeStatement

        public static Object executeStatement​(String sStatement)
        Execute a CohQL statement. This method accepts a complete query string as the argument. The type of object returned depends on the query:
        Examples on CohQL
        Return Type Query Description
        Cache entry value If the statement is an INSERT operation the previous entry for the given key will be returned; otherwise null
        Number If the query is an aggregation that returns a single numerical value; for example: count(), avg(), max(), min()
        Map If query has a grouping
        Collection For all other SELECT, DELETE, UPDATE statements
        null If the query returns no results or for create/delete index or drop/create cache, or backup/restore
        Parameters:
        sStatement - a Coherence Query Language statement
        Returns:
        the query results
        Throws:
        RuntimeException - if an invalid query is provided

      • createCommonExecutionContext

        protected static ExecutionContext createCommonExecutionContext()
        Create a new ExecutionContext. The following properties will be set on the returned context:
        • silent mode is enabled
        • sanity checking is enabled
        • extended language support enabled
        • the coherence query language
        Returns:
        a new ExecutionContext
        Throws:
        IllegalArgumentException - if session is null
        Since:
        21.06

      • executeStatement

        public static Object executeStatement​(String sStatement,
                                      ExecutionContext context)
        Execute a CohQL statement. This method accepts a complete query string as the argument. The type of object returned depends on the query:
        Query return types
        Return Type Query Description
        Cache entry value If the statement is an INSERT operation the previous entry for the given key will be returned; otherwise null
        Number If the query is an aggregation that returns a single numerical value; for example: count(), avg(), max(), min()
        Map If query has a grouping
        Collection For all other SELECT, DELETE, UPDATE statements
        null If the query returns no results or for create/delete index or drop/create cache, or backup/restore
        Parameters:
        sStatement - a Coherence Query Language statement
        context - the ExecutionContext to use
        Returns:
        the query results
        Throws:
        RuntimeException - if an invalid query is provided