net.sf.mmm.search.engine.api

Interface SearchQueryBuilder

All Superinterfaces:

Refreshable

All Known Implementing Classes:

AbstractSearchQueryBuilder, LuceneSearchQueryBuilder

public interface SearchQueryBuilder
extends Refreshable

This is the interface used to build search-queries.
You can either specify the query as string and parse it or create your query constructively.
Here is an example:

 SearchQueryBuilder queryBuilder = mySearchEngine.getQueryBuilder();
 ComplexSearchQuery query = queryBuilder.createComplexQuery();
 SearchQuery subQuery1 = queryBuilder.createTermQuery(SearchEntry.PROPERTY_TEXT, "Multimedia*");
 query.addRequiredQuery(subQuery1);
 SearchQuery subQuery2 = queryBuilder.createTermQuery(SearchEntry.PROPERTY_TEXT, "PHP");
 query.addExcludingQuery(subQuery2);
 SearchQuery subQuery3 = queryBuilder.createPhraseQuery(SearchEntry.PROPERTY_TITLE, "Enterprise Content Management");
 query.addOptionalQuery(subQuery3);
 

The resulting query will be the same as if parseStandardQuery(String) was called with "+text:Multimedia* -text:PHP title:\"Enterprise Content Management\"". A SearchQueryBuilder has to be stateless and thread-safe.

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
ComplexSearchQuery	createComplexQuery() This method creates a complex query.
SearchQuery	createPhraseQuery(String field, String phrase) This method creates a new query for the given phrase and property.
SearchQuery	createRangeQuery(String field, String minimum, String maximum, boolean minimumInclusive, boolean maximumInclusive) This method creates a SearchQuery for a range of values.
SearchQuery	createWordQuery(String field, String word) This method creates a new query for the given word and field.
SearchQuery	parseStandardQuery(String query) This method parses the given query string in the standard query language of this specification.
SearchQuery	parseStandardQuery(String query, SearchQueryBuilderOptions options) This method parses the given query string in the standard query language of this specification.
boolean	refresh() This method refreshes the given object.

Method Detail

parseStandardQuery

SearchQuery parseStandardQuery(String query)
                        throws SearchException

This method parses the given query string in the standard query language of this specification.

Parameters:

query - is the query to parse as string.

Returns:

the parsed query.

Throws:

SearchException - if the given query string is illegal and can NOT be parsed. Implementations should be tolerant and try to avoid this situation.

See Also:

parseStandardQuery(String, SearchQueryBuilderOptions)

parseStandardQuery

SearchQuery parseStandardQuery(String query,
                               SearchQueryBuilderOptions options)
                        throws SearchException

This method parses the given query string in the standard query language of this specification.
The standard query language is defined by the following EBNF grammar:

 <WHITESPACE> = (' '|'\t'|'\n'|'\r')
 <WHITESPACES> = (<WHITESPACE>)+
 <START_CHAR> = ^(<WHITESPACE>|'+'|'-'|'('|')'|'"'|'\'')
 <CHAR> = (<START_CHAR>|'+'|'-')
 <WORD> = <START_CHAR> (<CHAR>)*
 <PHRASE> = '"' (^('"'))* '"'
 <TO> = ("TO" | "to" | "-")
 <MIN> = <WORD>
 <MAX> = <WORD>
 <RANGE> = ('{' | '[') <MIN> ' ' <TO> ' ' <MAX> (']' | '}')
 <MATCH> = (<PHRASE> | <WORD> | <RANGE>)
 <FIELD> = ('a'-'z'|'A'-'Z')+
 <CLAUSE> = ['+'|'-'] [<FIELD> ':'] ( <MATCH> | '(' <QUERY> ')' )
 <QUERY> = <CLAUSE> | <CLAUSE> (<WHITESPACES> <QUERY>)* ) 
 

Parameters:

query - is the query to parse as string.

options - are the SearchQueryBuilderOptions.

Returns:

the parsed query.

Throws:

SearchException - if the given query string is illegal and can NOT be parsed. Implementations should be tolerant and try to avoid this situation.

createPhraseQuery

SearchQuery createPhraseQuery(String field,
                              String phrase)

This method creates a new query for the given phrase and property.

Parameters:

field - is the name of the field to search.

phrase - is the exact phrase to search for.

Returns:

the created query.

createWordQuery

SearchQuery createWordQuery(String field,
                            String word)

This method creates a new query for the given word and field.

Parameters:

field - is the name of the field where to search.

word - is the single term or glob pattern (e.g. "moon?i*" to match "moonlight" or "moonride") to search for.

Returns:

the created query.

createRangeQuery

SearchQuery createRangeQuery(String field,
                             String minimum,
                             String maximum,
                             boolean minimumInclusive,
                             boolean maximumInclusive)

This method creates a SearchQuery for a range of values.

Parameters:

field - is the name of the field(s) to match.

minimum - is the minimum or infimum value.

maximum - is the maximum or supremum value.

minimumInclusive - - true if the minimum is included and matches, false if the minimum is treated as infimum and only higher values will match.

maximumInclusive - - true if the maximum is included and matches, false if the maximum is treated as supremum and only lower values will match.

Returns:

the created range SearchQuery.

createComplexQuery

ComplexSearchQuery createComplexQuery()

This method creates a complex query. You can then add sub-queries to this query with logical operations.

Returns:

the created query.

refresh

boolean refresh()

This method refreshes the given object. This can be anything from reloading configuration to rebuilding the internal state. An invocation of this method may be expensive and should only be invoked as needed. The implementation of this method should be thread-safe if the object itself is to be used by separate consumers at all.

Specified by:

refresh in interface Refreshable

Returns:

true if something has changed, false otherwise. If the implementation can not determine the change it should return true.