Package com.tangosol.util

Class QueryHelper

java.lang.Object
com.tangosol.util.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

  • Field Details

  • Method Details

    • 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

    • createExecutionContext

      public static ExecutionContext createExecutionContext(ConfigurableCacheFactory factory)
      Create a new ExecutionContext. The following properties will be set on the returned context:
      • silent mode is enabled
      • sanity checking is enabled
      • cache factory based on provided argument
      Parameters:
      factory - the ConfigurableCacheFactory the ExecutionContext should use
      Returns:
      a new ExecutionContext
      Throws:
      IllegalArgumentException - if factory is null
      Since:
      21.06

    • createExecutionContext

      public static ExecutionContext createExecutionContext(Session session)
      Create a new ExecutionContext. The following properties will be set on the returned context:
      • silent mode is enabled
      • sanity checking is enabled
      • session based on provided argument
      • extended language support enabled
      Parameters:
      session - the Session the ExecutionContext should use
      Returns:
      a new ExecutionContext
      Throws:
      IllegalArgumentException - if session is null
      Since:
      21.06

    • 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

    • createStatement

      public static Statement createStatement(String sStatement, ExecutionContext context)
      Creates a new Coherence Query Language Statement from the provided query string.
      Parameters:
      sStatement - a Coherence Query Language statement
      context - the ExecutionContext to use
      Returns:
      the parsed Coherence Query Language statement ready for execution
      Throws:
      RuntimeException - if an invalid query is provided
      Since:
      21.06
      See Also:

    • createStatement

      public static Statement createStatement(String sStatement, ExecutionContext context, Object[] oaPositionalParams)
      Creates a new Coherence Query Language Statement from the provided query string. This query string may contain zero or more parameters in the format of ?{n} where {n} is a numeric value indicating the position of the parameter in the provided argument array.
      Parameters:
      sStatement - a Coherence Query Language statement
      context - the ExecutionContext to use
      oaPositionalParams - the positional parameter values
      Returns:
      the parsed Coherence Query Language statement ready for execution
      Throws:
      RuntimeException - if an invalid query is provided
      Since:
      21.06
      See Also:

    • createStatement

      public static Statement createStatement(String sStatement, ExecutionContext context, Map<String,Object> mapBindingParams)
      Creates a new Coherence Query Language Statement from the provided query string. This query string may contain zero or more parameters in the format of :{key} where {key} is maps to a key in the provided binding parameters.
      Parameters:
      sStatement - a Coherence Query Language statement
      context - the ExecutionContext to use
      mapBindingParams - a Map keyed by the parameter name within the query string mapped to the binding value
      Returns:
      the parsed Coherence Query Language statement ready for execution
      Throws:
      RuntimeException - if an invalid query is provided
      Since:
      21.06
      See Also:

    • createStatement

      protected static Statement createStatement(String sStatement, ExecutionContext context, Object[] aoPositionalParams, Map<String,Object> mapBindingParams)
      Creates a new Coherence Query Language Statement from the provided query string.
      Parameters:
      sStatement - a Coherence Query Language statement
      context - the ExecutionContext to use
      aoPositionalParams - parameters, in order, to be applied to query
      mapBindingParams - parameters, mapped to binding names
      Returns:
      the parsed Coherence Query Language statement ready for execution
      Throws:
      RuntimeException - if an invalid query is provided
      Since:
      21.06
      See Also: