com.tangosol.util

Class QueryHelper

java.lang.Object

com.tangosol.util.QueryHelper

public 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 Summary

Fields

Modifier and Type	Field and Description
protected static CoherenceQueryLanguage	f_language The default CoherenceQueryLanguage used by this QueryHelper when no language is provided to methods.

Constructor Summary

Constructors

Constructor and Description
QueryHelper()

Method Summary

Modifier and Type	Method and Description
static ValueExtractor	createExtractor(String s) Make a new ValueExtractor from the given String.
static ValueExtractor	createExtractor(String sQuery, CoherenceQueryLanguage language) Make a new ValueExtractor from the given String.
static Filter	createFilter(String sWhereClause) Make a new Filter from the given String.
static Filter	createFilter(String sWhereClause, Map mapBindings) Make a new Filter from the given String.
static Filter	createFilter(String sWhereClause, Object[] aBindings) Make a new Filter from the given String.
static Filter	createFilter(String sWhereClause, Object[] aBindings, Map mapBindings) Make a new Filter from the given String.
static Filter	createFilter(String sWhereClause, Object[] aBindings, Map mapBindings, CoherenceQueryLanguage language) Make a new Filter from the given String.
static Object	executeStatement(String sStatement) Execute a CohQL statement.
static Object	executeStatement(String sStatement, ExecutionContext context) Execute a CohQL statement.
protected static Term	parse(String sQuery) Return the Term representing the AST produced by parsing the specified CohQL query String.
protected static Term	parse(String sQuery, CoherenceQueryLanguage language) Return the Term representing the AST produced by parsing the specified CohQL query String.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

f_language

protected static final CoherenceQueryLanguage f_language

The default CoherenceQueryLanguage used by this QueryHelper when no language is provided to methods.

Constructor Detail

QueryHelper

public QueryHelper()

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[] aBindings)

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

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:

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

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:

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