org.eclipse.smila.search.api.helper
Class QueryBuilder

java.lang.Object
  org.eclipse.smila.search.api.helper.QueryBuilder

public class QueryBuilder
extends java.lang.Object

Builder for Query objects to send to a search service. Most methods just return the QueryBuilder they were called on to make it easy to chain several methods call in a single code line.

Author:

jschumacher

Constructor Summary

QueryBuilder(java.lang.String workflowName)
init request for given pipeline.

QueryBuilder(java.lang.String workflowName, Record query)
init request for given record.

QueryBuilder(java.lang.String workflowName, RecordFactory factory)
init request for given pipeline, use non-default RecordFactory.

Method Summary

QueryBuilder	addAnnotationNamedValue(java.lang.String attributeName, java.lang.String[] pathElements, java.lang.String valueName, java.lang.String value) Deprecated. Use setAnnotationNamedValue(String,String[],String,String) instead
QueryBuilder	addEnumFilter(java.lang.String attributeName, SearchAnnotations.FilterMode mode, java.lang.Iterable<? extends java.lang.Object> filterValues) add an enumeration filter to an attribute.
QueryBuilder	addFacetFilter(Facets facetList, int index) Deprecated. Use addFacetFilterToQuery(Facets,int) instead
QueryBuilder	addFacetFilterToQuery(Facets facetList, int index) copy filter from a facet to the attribute of this facet.
QueryBuilder	addLiteral(java.lang.String attributeName, Literal literal) add a ready built literal to an attribute.
QueryBuilder	addLiteral(java.lang.String attributeName, java.lang.Object value) add a literal value to an attribute.
QueryBuilder	addOrderBy(java.lang.String attribute, SearchParameters.OrderMode mode) add an orderby specification.
QueryBuilder	addParameter(java.lang.String name, java.lang.String value) adds an anonymous value to a service runtime parameter annotation.
QueryBuilder	addRangeFilter(java.lang.String attributeName, SearchAnnotations.FilterMode mode, java.lang.Object lowerBound, java.lang.Object upperBound) add a range filter to an attribute.
ResultAccessor	executeRequest(SearchService searchService) execute query on given search service and wrap result in high level result helper.
org.w3c.dom.Document	executeRequestXml(SearchService searchService) execute query on given search service and return search result as XML DOM document.
java.lang.String	executeRequestXmlString(SearchService searchService) execute query on given search service and return search result as XML string.
ParameterAnnotation	getParameters() access service runtime parameters of query object.
Record	getQuery() access underlying query record for advanced manipulation.
Annotation	getRankingAnnotation(java.lang.String attributeName) ensure and return ranking annotation for current record or given attribute.
java.lang.String	getWorkflowName() the name of the search pipeline to use.
QueryBuilder	setAnnotationNamedValue(java.lang.String attributeName, java.lang.String[] pathElements, java.lang.String valueName, java.lang.String value) sets a named value of an attribute's (sub) annotation. if any of the given elements do not exist they will be created along the way.
QueryBuilder	setAttachment(java.lang.String name, byte[] attachment) add attachment to query.
QueryBuilder	setBoostFactor(java.lang.String attributeName, double boost) set boost factor for attribute.
QueryBuilder	setId(Id id) set the ID of the query record.
QueryBuilder	setIndexName(java.lang.String indexName) set the index name for the query.
QueryBuilder	setLanguage(java.lang.String language) set the language parameter for the query.
QueryBuilder	setParameter(java.lang.String name, java.lang.String value) sets a named value in the service runtime parameter annotation.
QueryBuilder	setQuery(java.lang.String queryString) set the textual query string for the query.
QueryBuilder	setRankingName(java.lang.String attributeName, java.lang.String rankingName) set ranking name for record or attribute.
QueryBuilder	setResultOffset(int offset) set the search result offset for the query, i.e. the number of most relevant result objects to skip in the result list.
QueryBuilder	setResultSize(int size) set the maximum search result size for the query.
QueryBuilder	setThreshold(double threshold) set the threshold for the relevance value of search results, i.e. only results having a relevance of at least the threshold value, should be returned to the client.

Methods inherited from class java.lang.Object

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

Constructor Detail

QueryBuilder

public QueryBuilder(java.lang.String workflowName)

init request for given pipeline.

Parameters:

workflowName - pipeline name.

QueryBuilder

public QueryBuilder(java.lang.String workflowName,
                    RecordFactory factory)

init request for given pipeline, use non-default RecordFactory.

Parameters:

workflowName - pipeline name

factory - record factory to use.

QueryBuilder

public QueryBuilder(java.lang.String workflowName,
                    Record query)

init request for given record.

Parameters:

workflowName - pipeline name

query - query record to use.

Method Detail

setId

public QueryBuilder setId(Id id)

set the ID of the query record. If the ID is not set by the client, the builder will create an Id just before the request is executed, using the local IP address as source and a random UUID as key.

Parameters:

id - Id

Returns:

"this"

setQuery

public QueryBuilder setQuery(java.lang.String queryString)

set the textual query string for the query. The syntax of this string depends on the requirements of the retrieval service used in the pipeline, so every string is accepted here and no syntax checking is done.

Parameters:

queryString - textual query string.

Returns:

"this"

setResultSize

public QueryBuilder setResultSize(int size)

set the maximum search result size for the query.

Parameters:

size - maximum result size.

Returns:

"this"

setResultOffset

public QueryBuilder setResultOffset(int offset)

set the search result offset for the query, i.e. the number of most relevant result objects to skip in the result list. Use this to implement paging on the result set.

Parameters:

offset - result offset

Returns:

"this"

setThreshold

public QueryBuilder setThreshold(double threshold)

set the threshold for the relevance value of search results, i.e. only results having a relevance of at least the threshold value, should be returned to the client. Relevances are usually number betwenn 0.0 (completely irrelevant to the query) and 1.0 (perfect match), so the threshold value should be from the same range. However, as the search API does not know about details of the used search engine, no checking is done and all double values are accepted.

Parameters:

threshold - relevance threshold value.

Returns:

"this"

setLanguage

public QueryBuilder setLanguage(java.lang.String language)

set the language parameter for the query. This is used by services/pipelets that have a language specific functionality (e.g. stemming, spellchecking, recognition of currency values ...) to configure the language of the query string. Usually the possible values are the standard locale codes like "en", "de".

Parameters:

language - a language code.

Returns:

"this"

setIndexName

public QueryBuilder setIndexName(java.lang.String indexName)

set the index name for the query. Some search engine integrations may be capable of managing multiple seperated indexes and use this parameter to select the index to search in.

Parameters:

indexName - index name

Returns:

"this"

addLiteral

public QueryBuilder addLiteral(java.lang.String attributeName,
                               java.lang.Object value)
                        throws InvalidTypeException

add a literal value to an attribute. Valid value types are

• String
• Number
• Boolean
• Date

Parameters:

attributeName - name of attribute

value - value

Returns:

"this"

Throws:

InvalidTypeException - object type cannot be used as a literal value.

addLiteral

public QueryBuilder addLiteral(java.lang.String attributeName,
                               Literal literal)

add a ready built literal to an attribute.

Parameters:

attributeName - attribute name.

literal - a literal to add

Returns:

"this"

addEnumFilter

public QueryBuilder addEnumFilter(java.lang.String attributeName,
                                  SearchAnnotations.FilterMode mode,
                                  java.lang.Iterable<? extends java.lang.Object> filterValues)
                           throws InvalidTypeException

add an enumeration filter to an attribute. An enumeration filter describes a list of allowed or forbidden values for this attribute. The search result must contain only objects that contain matching values in this attribute. The SearchAnnotations.FilterMode specifies what "matching" means:

• ANY: valid results must have at least one of the listed attribute values and can have additional values.
• ALL: valid results must have all of the listed attribute values and can have additional values.
• ONLY: valid results must have only values listed in the filter, but do not need to have all (or even one) value.
• NONE: valid results must have none of the listed attribute values (no value at all is fine, too).

Parameters:

attributeName - name of attribute.

mode - filter mode

filterValues - filter values.

Returns:

"this"

Throws:

InvalidTypeException - at least one filter values is of an invalid class

addRangeFilter

public QueryBuilder addRangeFilter(java.lang.String attributeName,
                                   SearchAnnotations.FilterMode mode,
                                   java.lang.Object lowerBound,
                                   java.lang.Object upperBound)
                            throws InvalidTypeException

add a range filter to an attribute. A range filter describes a range of allowed or forbidden values by specifying a lower and/or an upper bound. This usually makes sense only for numeric or chronologic (date/time) attributes, but this is not enforced by the builder. Either bound can be left unspecified (null) to describe a filter range with only a minimum or maximum value.

Parameters:

attributeName - name of attribute.

mode - filter mode

lowerBound - lower bound of filter range. can be null

upperBound - upper bound of filter range. can be null.

Returns:

"this"

Throws:

InvalidTypeException - at least one filter values is of an invalid class

addFacetFilter

public QueryBuilder addFacetFilter(Facets facetList,
                                   int index)

Deprecated. Use addFacetFilterToQuery(Facets,int) instead

copy filter from a facet to the attribute of this facet. If the facet contains an object filter, this one is added to the appropriate attribute. If it does not contain an object filter, but a text filter, this string is appended immediately to the current query string. It is required that the pipeline returns a text filter valid for immediate appending to the input query string.

Parameters:

facetList - list of facets for a single attribute

index - position of used facet.

Returns:

"this"

addFacetFilterToQuery

public QueryBuilder addFacetFilterToQuery(Facets facetList,
                                          int index)

copy filter from a facet to the attribute of this facet. If the facet contains an object filter, this one is added to the appropriate attribute. If it does not contain an object filter, but a text filter, this string is appended to the current query string. For this to work the Facets.getStringFilter(int) must be set in the pipeline that returns a text filter valid for immediate appending to the input query string.

Parameters:

facetList - list of facets for a single attribute

index - position of used facet.

Returns:

"this"

addOrderBy

public QueryBuilder addOrderBy(java.lang.String attribute,
                               SearchParameters.OrderMode mode)

add an orderby specification.

Parameters:

attribute - an attribute to order by

mode - the order direction (ascending or descending)

Returns:

"this"

getRankingAnnotation

public Annotation getRankingAnnotation(java.lang.String attributeName)

ensure and return ranking annotation for current record or given attribute.

Parameters:

attributeName - name of attribute, or null for top-level ranking annotation.

Returns:

ranking annotation

setBoostFactor

public QueryBuilder setBoostFactor(java.lang.String attributeName,
                                   double boost)

set boost factor for attribute.

Parameters:

attributeName - name of attribute

boost - boost factor

Returns:

"this"

setRankingName

public QueryBuilder setRankingName(java.lang.String attributeName,
                                   java.lang.String rankingName)

set ranking name for record or attribute.

Parameters:

attributeName - name of attribute, or null for top-level ranking annotation.

rankingName - name of ranking.

Returns:

"this"

setParameter

public QueryBuilder setParameter(java.lang.String name,
                                 java.lang.String value)

sets a named value in the service runtime parameter annotation.

Parameters:

name - parameter name

value - parameter value

Returns:

"this"

addParameter

public QueryBuilder addParameter(java.lang.String name,
                                 java.lang.String value)

adds an anonymous value to a service runtime parameter annotation.

Parameters:

name - parameter name

value - parameter value

Returns:

"this"

setAttachment

public QueryBuilder setAttachment(java.lang.String name,
                                  byte[] attachment)

add attachment to query. Keep in mind that attachments are kept in memory in search processig, so you should care about not adding large attachments.

Parameters:

name - attachment name

attachment - attachment content

Returns:

"this"

executeRequest

public ResultAccessor executeRequest(SearchService searchService)
                              throws ProcessingException

execute query on given search service and wrap result in high level result helper.

Parameters:

searchService - search service instance.

Returns:

search result.

Throws:

ProcessingException - any error while processing the search

executeRequestXml

public org.w3c.dom.Document executeRequestXml(SearchService searchService)
                                       throws javax.xml.parsers.ParserConfigurationException

execute query on given search service and return search result as XML DOM document.

Parameters:

searchService - search service instance.

Returns:

search result, or XML description of error that occurred in searcuh

Throws:

javax.xml.parsers.ParserConfigurationException - error creating the XML result

executeRequestXmlString

public java.lang.String executeRequestXmlString(SearchService searchService)
                                         throws javax.xml.parsers.ParserConfigurationException

execute query on given search service and return search result as XML string.

Parameters:

searchService - search service instance.

Returns:

search result, or XML description of error that occurred in searcuh

Throws:

javax.xml.parsers.ParserConfigurationException - error creating the XML result

getQuery

public Record getQuery()

access underlying query record for advanced manipulation.

Returns:

query record.

getWorkflowName

public java.lang.String getWorkflowName()

the name of the search pipeline to use.

Returns:

pipeline name.

getParameters

public ParameterAnnotation getParameters()

access service runtime parameters of query object.

Returns:

parameter annotation accessor.

addAnnotationNamedValue

public QueryBuilder addAnnotationNamedValue(java.lang.String attributeName,
                                            java.lang.String[] pathElements,
                                            java.lang.String valueName,
                                            java.lang.String value)

Deprecated. Use setAnnotationNamedValue(String,String[],String,String) instead

add a named value to a attribute (sub) annotation.

Parameters:

attributeName - attribute name

pathElements - path of annotation names

valueName - name of named value

value - value

Returns:

"this"

Throws:

InvalidTypeException - should not happen

setAnnotationNamedValue

public QueryBuilder setAnnotationNamedValue(java.lang.String attributeName,
                                            java.lang.String[] pathElements,
                                            java.lang.String valueName,
                                            java.lang.String value)

sets a named value of an attribute's (sub) annotation. if any of the given elements do not exist they will be created along the way.

Parameters:

attributeName - attribute name

pathElements - path of annotation names

valueName - name of named value

value - value

Returns:

"this"

Throws:

InvalidTypeException - should not happen