com.google.gerrit.index.query

Class QueryBuilder<T,Q extends QueryBuilder<T,Q>>

java.lang.Object

com.google.gerrit.index.query.QueryBuilder<T,Q>

Type Parameters:

T - type of object the predicates can evaluate in memory.

Direct Known Subclasses:

AccountQueryBuilder, ChangeQueryBuilder, GroupQueryBuilder, ProjectQueryBuilder

public abstract class QueryBuilder<T,Q extends QueryBuilder<T,Q>>
extends Object

Base class to support writing parsers for query languages.

Subclasses may document their supported query operators by declaring public methods that perform the query conversion into a Predicate. For example, to support "is:starred", "is:unread", and nothing else, a subclass may write:

 @Operator
 public Predicate is(String value) {
   if ("starred".equals(value)) {
     return new StarredPredicate();
   }
   if ("unread".equals(value)) {
     return new UnreadPredicate();
   }
   throw new IllegalArgumentException();
 }
 

The available operator methods are discovered at runtime via reflection. Method names (after being converted to lowercase), correspond to operators in the query language, method string values correspond to the operator argument. Methods must be declared public, returning Predicate, accepting one String, and annotated with the QueryBuilder.Operator annotation.

Subclasses may also declare a handler for values which appear without operator by overriding defaultField(String).

Instances are non-singletons and should only be used once, in order to rescan the DynamicMap of plugin-provided operators on each query invocation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	QueryBuilder.Definition<T,Q extends QueryBuilder<T,Q>> Defines the operators known by a QueryBuilder.
protected static interface	QueryBuilder.Operator Denotes a method which is a query operator.
static interface	QueryBuilder.OperatorFactory<T,Q extends QueryBuilder<T,Q>> Converts a value string passed to an operator into a Predicate.

Field Summary

Fields

Modifier and Type	Field and Description
protected QueryBuilder.Definition<T,Q>	builderDef

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	QueryBuilder(QueryBuilder.Definition<T,Q> def, DynamicMap<? extends QueryBuilder.OperatorFactory<T,Q>> dynamicOpFactories)

Method Summary

Modifier and Type	Method and Description
protected Predicate<T>	defaultField(String value) Handle a value present outside of an operator.
protected static QueryParseException	error(String msg)
protected static QueryParseException	error(String msg, Throwable why)
static <T,P extends Predicate<T>> P	find(Predicate<T> p, Class<P> clazz) Locate a predicate in the predicate tree.
static <T,P extends OperatorPredicate<T>> P	find(Predicate<T> p, Class<P> clazz, String name) Locate a predicate in the predicate tree.
List<Predicate<T>>	parse(List<String> queries) Parse multiple user-supplied query strings into a list of predicates.
Predicate<T>	parse(String query) Parse a user-supplied query string into a predicate.

Methods inherited from class java.lang.Object

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

Field Detail

builderDef

protected final QueryBuilder.Definition<T,Q extends QueryBuilder<T,Q>> builderDef

Constructor Detail

QueryBuilder

protected QueryBuilder(QueryBuilder.Definition<T,Q> def,
                       DynamicMap<? extends QueryBuilder.OperatorFactory<T,Q>> dynamicOpFactories)

Method Detail

find

public static <T,P extends Predicate<T>> P find(Predicate<T> p,
                                                Class<P> clazz)

Locate a predicate in the predicate tree.

Parameters:

p - the predicate to find.

clazz - type of the predicate instance.

Returns:

the predicate, null if not found.

find

public static <T,P extends OperatorPredicate<T>> P find(Predicate<T> p,
                                                        Class<P> clazz,
                                                        String name)

Locate a predicate in the predicate tree.

Parameters:

p - the predicate to find.

clazz - type of the predicate instance.

name - name of the operator.

Returns:

the first instance of a predicate having the given type, as found by a depth-first search.

parse

public Predicate<T> parse(String query)
                   throws QueryParseException

Parse a user-supplied query string into a predicate.

Parameters:

query - the query string.

Returns:

predicate representing the user query.

Throws:

QueryParseException - the query string is invalid and cannot be parsed by this parser. This may be due to a syntax error, may be due to an operator not being supported, or due to an invalid value being passed to a recognized operator.

parse

public List<Predicate<T>> parse(List<String> queries)
                         throws QueryParseException

Parse multiple user-supplied query strings into a list of predicates.

Parameters:

queries - the query strings.

Returns:

predicates representing the user query, in the same order as the input.

Throws:

QueryParseException - one of the query strings is invalid and cannot be parsed by this parser. This may be due to a syntax error, may be due to an operator not being supported, or due to an invalid value being passed to a recognized operator.

defaultField

protected Predicate<T> defaultField(String value)
                             throws QueryParseException

Handle a value present outside of an operator.

This default implementation always throws an "Unsupported query: " message containing the input text. Subclasses may override this method to perform do-what-i-mean guesses based on the input string.

Parameters:

value - the value supplied by itself in the query.

Returns:

predicate representing this value.

Throws:

QueryParseException - the parser does not recognize this value.

error

protected static QueryParseException error(String msg)

error

protected static QueryParseException error(String msg,
                                           Throwable why)