com.plumtree.server.search
Interface IPTSQueryRequest

public interface IPTSQueryRequest

A single request for the Plumtree search system to perform a search query and return results.

At minimum, for a successful search query, these calls must be made:

• setQuery to specify the search constraints (like the WHERE clause in SQL)
• restrictTo to specify the part of the index to search, or skip this step to search the whole index (like the FROM clause in SQL)
• setFieldsToReturn to specify the information you want for each result (like the SELECT clause in SQL)
• execute to perform the query

The execute method returns an IPTSQueryResponse containing info on the items that matched the query.

Method Summary

IPTSQueryResponse	execute() Runs the search and returns results in an IPTSQueryResponse object.
IPTSField[]	getFieldsToReturn() Returns fields that will be included as part of each IPTSResult when the search query is executed; counterpart of setFieldsToReturn.
int	getFirstResultIndex() Returns the current first result index.
java.lang.String	getLanguage() Returns the 2-character locale code, such as "en", for the language that will be used to parse text queries.
int	getMaxGroupCount() Get the maximum number of result groups (clusters) that can be returned, if setResultsGroupBy has been called.
IPTSQuery	getQuery() Get the current search query for this request; counterpart of setQuery.
int	getQueryTimeout() Returns the search server's query processing timeout for this request.
int	getRequiredAccessLevel() Get the access level that the current user must have for items returned by the query request.
IPTSField	getResultsGroupByField() Returns the field that will be used for clustering (grouping) results (counterpart of setResultsGroupBy).
boolean	getResultsOrderByAscending() Returns whether results will be in ascending or descending order of the order-by field (see getResultsOrderByField).
IPTSField	getResultsOrderByField() Returns the field that will be used for ordering results; counterpart of setResultsOrderBy.
int	getReturnedCount() Returns the currently requested number of returned results.
boolean	getReturnMatchingExcerpts() Returns whether the search server will return excerpts from fields that matched the query.
boolean	getUseShortConnectionTimeout() Returns true if the search server will use a short (30 second) timeout when waiting for a connection to the search server.
void	restrictTo(IPTSQuery restriction) Restrict this query request to a subsection of the search index.
void	restrictToAnyOf(IPTSQuery[] restrictions) Restrict this query request to specified subsections of the search index.
void	setFieldsToReturn(IPTSField[] fields) Specify fields to return along with each result.
void	setLanguage(java.lang.String language) Set the language in which all text queries associated with this request will be parsed.
void	setQuery(IPTFilter propertyFilter) Use the provided IPTFilter as the search query for this request.
void	setQuery(IPTSQuery query) Set the search query for this request.
void	setQuery(java.lang.String textQuery) Use the provided String as the search query for this request.
void	setQuery(java.lang.String textQuery, boolean useBestBets, boolean useSpellCorrection, boolean useThesaurus) Use the provided String as the search query for this request.
void	setQueryTimeout(int timeoutInSecs) Set the search server's query processing timeout for this request.
void	setRequiredAccessLevel(int accessLevel) Set the access level that the current user must have for items returned by the query request.
void	setResultsCount(int firstResult, int maxResults) Set the desired number of results and number to skip.
void	setResultsGroupBy(IPTSField field) Set field for results clustering (grouping).
void	setResultsGroupBy(IPTSField field, int maxGroupCount) Set field for results clustering (grouping) and specify the maximum number of desired groups.
void	setResultsOrderBy(IPTSField field, boolean isAscending) Set the field that will determine the order of results.
void	setReturnMatchingExcerpts(boolean returnMatchingExcerpts) Set whether to return excerpts from fields that matched the query.
void	setSearchServerLogInfo(com.plumtree.openfoundation.util.IXPDictionary logInfo) Set information to be logged as part of the search server's on-disk logs during the query request.
void	setTextQueryDefaultFields(IPTSWeightedFieldList fieldList) Set the list of fields that text queries search, by default.
void	setUseShortConnectionTimeout(boolean shortConnectionTimeout) Set whether to use a short or long timeout when waiting for a connection to the search server.
void	useIndexServerForQueries() Tells this IPTSQueryRequest to run all subsequent queries against the index search server, rather than the query search server.

Method Detail

setQuery

void setQuery(java.lang.String textQuery)

Use the provided String as the search query for this request. The default search fields are searched (see IPTSSearchableCollection.TextQueryDefault); these are usually the title, description, and full-text content fields. An admin can edit this list of fields via the UI, or the default may be changed on-the-fly by calling setTextQueryDefaultFields. The thesaurus, spell correction, and Best Bets are not used.

This call replaces any previous queries set by any call to setQuery.

Parameters:

textQuery - the full-text search query.

Throws:

PTSEmptyQueryException - if textQuery is empty

setQuery

void setQuery(java.lang.String textQuery,
              boolean useBestBets,
              boolean useSpellCorrection,
              boolean useThesaurus)
              throws PTSEmptyQueryException

Use the provided String as the search query for this request. The default search fields are searched (see IPTSSearchableCollection.TextQueryDefault); these are usually the title, description, and full-text content fields. An admin can edit this list of fields via the UI, or the default may be changed on-the-fly by calling setTextQueryDefaultFields.

This call replaces any previous queries set by any call to setQuery.

Parameters:

textQuery - the full-text search query.

useBestBets - whether any Best Bets for textQuery should be the highest-ranked results

useSpellCorrection - whether to apply spelling correction to textQuery.

useThesaurus - whether to expand textQuery using the thesaurus.

Throws:

PTSEmptyQueryException - if textQuery is empty

setQuery

void setQuery(IPTFilter propertyFilter)

Use the provided IPTFilter as the search query for this request. This call replaces any previous queries set by any call to setQuery. Calling this method is equivalent to creating a PropertyFilterQuery to wrap the IPTFilter, and passing it to setQuery(IPTSQuery).

Parameters:

propertyFilter - tree of property constraints, possibly including a full-text search query.

setQuery

void setQuery(IPTSQuery query)

Set the search query for this request. This call replaces any previous queries set by a call to any version of setQuery.

Parameters:

query - the search query.

getQuery

IPTSQuery getQuery()

Get the current search query for this request; counterpart of setQuery. Does not include any restrictions added by calling restrictTo or restrictToAnyOf.

Returns:

the current search query for this request

restrictTo

void restrictTo(IPTSQuery restriction)

Restrict this query request to a subsection of the search index. Results must satisfy the specified IPTSQuery restriction, in addition to the original query passed to setQuery.

restriction is usually a container within one of the Plumtree applications. See the factory methods in IPTSPortalCollection, IPTSCollabCollection, and IPTSContentCollection).

However, any other IPTSQuery may also be used as the restriction in this call. The restriction is ANDed with the query passed to setQuery when the query request is executed. Alternatively, advanced users may ignore this method, and simply include these restrictions as part of an IPTSQuery tree that is passed to setQuery.

Calls to this method override any previous call to restrictTo.

restrictToAnyOf

void restrictToAnyOf(IPTSQuery[] restrictions)

Restrict this query request to specified subsections of the search index. Results must satisfy at least one of the restrictions specified here, as well as the original query passed to setQuery.

restrictions are usually containers within the Plumtree applications. See the factory methods in IPTSPortalCollection, IPTSCollabCollection, and IPTSContentCollection).

However, any other IPTSQuery may also be used as a restriction in this call. The restrictions passed to this method are ORed together, and then the composite is ANDed with the query passed to setQuery when the query request is executed. Alternatively, advanced users may ignore this method, and simply include these restrictions as part of an IPTSQuery tree that is passed to setQuery.

Calls to this method override any previous call to restrictTo.

setFieldsToReturn

void setFieldsToReturn(IPTSField[] fields)

Specify fields to return along with each result. By default, no fields are guaranteed to be returned, so it is important to call this method before calling execute

This call overrides any previous calls to setFieldsToReturn, i.e. it replaces, instead of adding to, the set specified by a previous call.

getFieldsToReturn

IPTSField[] getFieldsToReturn()

Returns fields that will be included as part of each IPTSResult when the search query is executed; counterpart of setFieldsToReturn.

Returns:

fields that will be returned.

execute

IPTSQueryResponse execute()
                          throws PTSAdjacentOperatorsException,
                                 PTSEmptyQueryException,
                                 PTSEndsInOperatorException,
                                 PTSInappropriateOperatorException,
                                 PTSIncompatibleRestrictionException,
                                 PTSInvalidSearchException,
                                 PTSSearchServerConnectionException,
                                 PTSSyntaxException,
                                 PTSUnbalancedParenthesesException,
                                 PTSUnsupportedWildcardException

Runs the search and returns results in an IPTSQueryResponse object. This call does not return until the request has finished or timed out.

See the documentation for the individual exception types for more information about each possible error condition.

If the request times out, a partial result set may be returned. Call IPTSQueryResponse.queryTimedOut to find out whether this is the case.

Throws:

PTSAdjacentOperatorsException

PTSEmptyQueryException

PTSEndsInOperatorException

PTSInappropriateOperatorException

PTSIncompatibleRestrictionException

PTSInvalidSearchException

PTSSearchServerConnectionException

PTSSyntaxException

PTSUnbalancedParenthesesException

PTSUnsupportedWildcardException

setResultsCount

void setResultsCount(int firstResult,
                     int maxResults)

Set the desired number of results and number to skip. For example, to request results 11 through 20, call setResultsCount(11, 10). The default is to return the first ten results.

getReturnedCount

int getReturnedCount()

Returns the currently requested number of returned results. For example, if you have requested results 11 through 20, this value will be 10.

Returns:

the currently requested number of returned results, from a previous call to setResultsCount.

getFirstResultIndex

int getFirstResultIndex()

Returns the current first result index. For example, if you have requested results 11 through 20, this value will be 11.

Returns:

the currently set first result index, from a previous call to setResultsCount

setResultsOrderBy

void setResultsOrderBy(IPTSField field,
                       boolean isAscending)

Set the field that will determine the order of results. The default is to order by relevance (to explicitly request this behavior, pass null for the field Only integer, floating-point, and date-time fields may be used for order-by. The Search Server does not currently support ordering by string values.

Parameters:

field - the field to order by, or null to order by relevance.

isAscending - whether results should appear in ascending order of field, or descending; if relevance-ranked, this parameter is ignored.

getResultsOrderByField

IPTSField getResultsOrderByField()

Returns the field that will be used for ordering results; counterpart of setResultsOrderBy.

Returns:

the field that will be used for ordering results (from a previous call to setResultsOrderBy).

getResultsOrderByAscending

boolean getResultsOrderByAscending()

Returns whether results will be in ascending or descending order of the order-by field (see getResultsOrderByField).

Returns:

whether results will be in ascending or descending order

setResultsGroupBy

void setResultsGroupBy(IPTSField field)

Set field for results clustering (grouping). A maximum of 10 groups are returned, plus the "all others" group.

For the portal "object type" categorization, use field IPTSPlumtreeCollection.CategorizableObjectType. For the portal's "folder" categorization, use field IPTSPortalCollection.FolderPath.

Any other searchable and retrievable string field may also be used for clustering. In this case, the search server will find the most common terms (words) in the field (within your set of search results). Each group will correspond to one of these common terms, and will contain search results that have the term in the field. Note that a single search result may appear in multiple groups.

For a simple example, suppose that the Name field is used, and documents "Cats Dogs" and "Cats Mice" match the query. The first group will be "Cats" and contain both results. "Dogs" and "Mice" will be the other group, and will each contain one result.

Parameters:

field - field to use for results clustering.

setResultsGroupBy

void setResultsGroupBy(IPTSField field,
                       int maxGroupCount)

Set field for results clustering (grouping) and specify the maximum number of desired groups.

For the portal "object type" categorization, use field IPTSPlumtreeCollection.CategorizableObjectType. For the portal's "folder" categorization, use field IPTSPortalCollection.FolderPath.

Any other searchable and retrievable string field may also be used for clustering. In this case, the search server will find the most common terms (words) in the field (within your set of search results). Each group will correspond to one of these common terms, and will contain search results that have the term in the field. Note that a single search result may appear in multiple groups.

For a simple example, suppose that the Name field is used, and documents "Cats Dogs" and "Cats Mice" match the query. The first group will be "Cats" and contain both results. "Dogs" and "Mice" will be the other group, and will each contain one result.

Parameters:

field - field to use for results clustering.

maxGroupCount - maximum number of groups to return, not including the "all others" group. Must be between 2 and 20 (inclusive).

getResultsGroupByField

IPTSField getResultsGroupByField()

Returns the field that will be used for clustering (grouping) results (counterpart of setResultsGroupBy).

Returns:

the field that will be used for clustering (grouping) results, or null if results will not be grouped.

getMaxGroupCount

int getMaxGroupCount()

Get the maximum number of result groups (clusters) that can be returned, if setResultsGroupBy has been called. Does not include the "all others" group.

setTextQueryDefaultFields

void setTextQueryDefaultFields(IPTSWeightedFieldList fieldList)

Set the list of fields that text queries search, by default. See IPTSSearchableCollection.TextQueryDefault for more information. All fields within the list must be of type PTSFieldType.STRING.

setLanguage

void setLanguage(java.lang.String language)

Set the language in which all text queries associated with this request will be parsed. The default is the current user's language, or the portalwide default.

Parameters:

language - language in which to parse query. Use a two-character locale such as "en".

getLanguage

java.lang.String getLanguage()

Returns the 2-character locale code, such as "en", for the language that will be used to parse text queries.

Returns:

language that will be used to parse query.

useIndexServerForQueries

void useIndexServerForQueries()

Tells this IPTSQueryRequest to run all subsequent queries against the index search server, rather than the query search server. This is used for certain administration tasks where changes to the index should be reflected in search results immediately. Most users will not need to call this method.

In deployments with only one search server (used as both the query and index server) this method has no effect.

setReturnMatchingExcerpts

void setReturnMatchingExcerpts(boolean returnMatchingExcerpts)

Set whether to return excerpts from fields that matched the query. If this method is called with argument false, then IPTSResult.getFieldExcerpts will return no value, nor will field IPTSPlumtreeCollection.Excerpt. In some cases, this shortens search server query processing time.

Default is true, and usually does not need to be changed.

Parameters:

returnMatchingExcerpts - whether to return excerpts from fields that matched the query.

getReturnMatchingExcerpts

boolean getReturnMatchingExcerpts()

Returns whether the search server will return excerpts from fields that matched the query. See setReturnMatchingExcerpts for more details.

setQueryTimeout

void setQueryTimeout(int timeoutInSecs)

Set the search server's query processing timeout for this request. After the timeout elapses, the server will stop processing the query and return whatever results it has accumulated so far. This should be regarded as an execution time target, not as a strict upper bound.

Parameters:

timeoutInSecs - desired timeout in seconds (if positive), 0 to disable the timeout, or -1 to use the default from the search server configuration.

getQueryTimeout

int getQueryTimeout()

Returns the search server's query processing timeout for this request. See setQueryTimeout.

Returns:

the search server's query processing timeout for this request, 0 if the timeout is disabled, or -1 if the search server's default will be used.

setSearchServerLogInfo

void setSearchServerLogInfo(com.plumtree.openfoundation.util.IXPDictionary logInfo)

Set information to be logged as part of the search server's on-disk logs during the query request. (This information is not logged to PTSpy.)

When execute is called, the IXPDictionary is enumerated and XPConvert.ToString is called on each key and value. These string keys and values are logged in the search server log file in the form <key>value</key>.

The key must be a single alphanumeric token conforming to [A-Za-z][A-Za-z0-9_]*.

setUseShortConnectionTimeout

void setUseShortConnectionTimeout(boolean shortConnectionTimeout)

Set whether to use a short or long timeout when waiting for a connection to the search server. If shortConnectionTimeout is true, use a "short" 30-second timeout; otherwise use a "long" 10-minute timeout (the default). Note that setQueryTimeout sets the timeout for query processing within the search server itself, while setUseShortConnectionTimeout sets the timeout for establishing a connection to the search server.

Parameters:

shortConnectionTimeout - whether to use a short connection timeout.

getUseShortConnectionTimeout

boolean getUseShortConnectionTimeout()

Returns true if the search server will use a short (30 second) timeout when waiting for a connection to the search server. See setUseShortConnectionTimeout for more information.

Returns:

whether a short connection timeout will be used.

setRequiredAccessLevel

void setRequiredAccessLevel(int accessLevel)

Set the access level that the current user must have for items returned by the query request. By default, the user must have READ level access.

This access level does not apply to Collab items, since Collab uses a different security model. Any Collab item visible to the current user can be returned if it matches the query and restrictions, regardless of the access level set via this method.

Parameters:

accessLevel - one of PT_ACCESS_LEVELS.PT_ACCESS_LEVEL_READ, PT_ACCESS_LEVELS.PT_ACCESS_LEVEL_SELECT, PT_ACCESS_LEVELS.PT_ACCESS_LEVEL_EDIT, PT_ACCESS_LEVELS.PT_ACCESS_LEVEL_ADMIN.

getRequiredAccessLevel

int getRequiredAccessLevel()

Get the access level that the current user must have for items returned by the query request.

Returns:

one of PT_ACCESS_LEVELS.PT_ACCESS_LEVEL_READ, PT_ACCESS_LEVELS.PT_ACCESS_LEVEL_SELECT, PT_ACCESS_LEVELS.PT_ACCESS_LEVEL_EDIT, PT_ACCESS_LEVELS.PT_ACCESS_LEVEL_ADMIN.