org.opencms.search
Class CmsSearchParameters

java.lang.Object
  org.opencms.search.CmsSearchParameters

public class CmsSearchParameters
extends java.lang.Object

Contains the search parameters for a call to CmsSearchIndex.search(org.opencms.file.CmsObject, CmsSearchParameters).

Primary purpose is translation of search arguments to response parameters and from request parameters as well as support for creation of restrictions of several search query parameter sets.

Since:

6.0.0

Version:

$Revision: 1.17 $

Author:

Alexander Kandzior

Nested Class Summary

class

CmsSearchParameters.CmsSearchFieldQuery Describes a specific search field query.

Field Summary

protected int	m_displayPages The number of displayed pages returned by getPageLinks().
protected int	m_matchesPerPage The number of matches per page.
static org.apache.lucene.search.Sort	SORT_DATE_CREATED Sort result documents by date of creation, then score.
static org.apache.lucene.search.Sort	SORT_DATE_LASTMODIFIED Sort result documents by date of last modification, then score.
static org.apache.lucene.search.Sort	SORT_DEFAULT Default sort order (by document score - for this null gave best performance).
static java.lang.String[]	SORT_NAMES Names of the default sort options.
static org.apache.lucene.search.Sort	SORT_TITLE Sort result documents by title, then score.

Constructor Summary

CmsSearchParameters()
Creates a new search parameter instance with no search query and default values for the remaining parameters.

CmsSearchParameters(java.lang.String query)
Creates a new search parameter instance with the provided search query and default values for the remaining parameters.

CmsSearchParameters(java.lang.String query, java.util.List<java.lang.String> fields, java.util.List<java.lang.String> roots, java.util.List<java.lang.String> categories, java.util.List<java.lang.String> resourceTypes, boolean calculateCategories, org.apache.lucene.search.Sort sort)
Creates a new search parameter instance with the provided parameter values.

Method Summary

void	addFieldQuery(CmsSearchParameters.CmsSearchFieldQuery query) Adds an individual query for a search field.
void	addFieldQuery(java.lang.String fieldName, java.lang.String searchQuery, org.apache.lucene.search.BooleanClause.Occur occur) Adds an individual query for a search field.
boolean	getCalculateCategories() Returns whether category counts are calculated for search results or not.
java.util.List<java.lang.String>	getCategories() Returns the list of categories to limit the search to.
int	getDisplayPages() Returns the maximum number of pages which should be shown.
java.util.List<CmsSearchParameters.CmsSearchFieldQuery>	getFieldQueries() Returns the list of individual field queries.
java.util.List<java.lang.String>	getFields() Returns the list of search index field names (Strings) to search in.
java.lang.String	getIndex() Get the name of the index for the search.
int	getMatchesPerPage() Gets the number of matches displayed on each page.
long	getMaxDateCreated() Returns the creation date the resources have to have as maximum.
long	getMaxDateLastModified() Returns the last modification date the resources have to have as maximum.
long	getMinDateCreated() Returns the creation date the resources have to have as minimum.
long	getMinDateLastModified() Returns the last modification date the resources have to have as minimum.
java.lang.String	getQuery() Returns the search query to use.
int	getQueryLength() Gets the minimum search query length.
java.util.List<java.lang.String>	getResourceTypes() Returns the list of resource types to limit the search to.
java.util.List<java.lang.String>	getRoots() Returns the list of strings of search roots to use.
java.lang.String	getSearchCategories() Returns the list of categories to limit the search to.
CmsSearchIndex	getSearchIndex() Returns the search index to search in or null if not set before (setSearchIndex(CmsSearchIndex)).
int	getSearchPage() Returns the search page to display.
java.lang.String	getSearchRoots() Returns the comma separated lists of root folder names to restrict search to.
org.apache.lucene.search.Sort	getSort() Returns the instance that defines the sort order for the results.
java.lang.String	getSortName() Returns the name of the sort option being used.
boolean	isCalculateCategories() Returns true if the category count is calculated for all search results.
boolean	isExcerptOnlySearchedFields() Returns true if fields configured for the excerpt should be used for generating the excerpt only if they have been actually searched in.
CmsSearchParameters	restrict(CmsSearchParameters restriction) Creates a merged parameter set from this parameters, restricted by the given other parameters.
void	setCalculateCategories(boolean flag) Set whether category counts shall be calculated for the corresponding search results or not.
void	setCategories(java.util.List<java.lang.String> categories) Set the list of categories (strings) to this parameters.
void	setDisplayPages(int value) Sets the maximum number of pages which should be shown.
void	setExcerptOnlySearchedFields(boolean excerptAllFields) Controls if the excerpt from a field is generated only for searched fields, or for all fields (the default).
void	setFields(java.util.List<java.lang.String> fields) Sets the list of strings of names of fields to search in.
void	setIndex(java.lang.String indexName) Set the name of the index to search.
void	setMatchesPerPage(int matches) Sets the number of matches per page.
void	setMaxDateCreated(long dateCreatedTo) Sets the creation date the resources have to have as maximum.
void	setMaxDateLastModified(long dateLastModifiedTo) Sets the last modification date the resources have to have as maximum.
void	setMinDateCreated(long dateCreatedFrom) Sets the creation date the resources have to have as minimum.
void	setMinDateLastModified(long dateLastModifiedFrom) Sets the last modification date the resources have to have as minimum.
void	setQuery(java.lang.String query) Sets the query to search for.
void	setQueryLength(int length) Sets the minimum length of the search query.
void	setResourceTypes(java.util.List<java.lang.String> resourceTypes) Set the list of resource types (strings) to limit the search to.
void	setRoots(java.util.List<java.lang.String> roots) Sets the list of strings of roots to search under for the search.
void	setSearchCategories(java.lang.String categories) Set the comma separated search root names to restrict search to.
void	setSearchIndex(CmsSearchIndex index) Sets the search index to use for the search.
void	setSearchPage(int page) Set the search page to display.
void	setSearchRoots(java.lang.String rootNameList) Set the comma separated search root names to restrict search to.
void	setSort(org.apache.lucene.search.Sort sortOrder) Set the instance that defines the sort order for search results.
void	setSortName(java.lang.String sortName) Sets the internal member of type Sort according to the given sort name.
java.lang.String	toQueryString() Creates a query String build from this search parameters for HTML links.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

SORT_DATE_CREATED

public static final org.apache.lucene.search.Sort SORT_DATE_CREATED

Sort result documents by date of creation, then score.

SORT_DATE_LASTMODIFIED

public static final org.apache.lucene.search.Sort SORT_DATE_LASTMODIFIED

Sort result documents by date of last modification, then score.

SORT_DEFAULT

public static final org.apache.lucene.search.Sort SORT_DEFAULT

Default sort order (by document score - for this null gave best performance).

SORT_NAMES

public static final java.lang.String[] SORT_NAMES

Names of the default sort options.

SORT_TITLE

public static final org.apache.lucene.search.Sort SORT_TITLE

Sort result documents by title, then score.

m_displayPages

protected int m_displayPages

The number of displayed pages returned by getPageLinks().

m_matchesPerPage

protected int m_matchesPerPage

The number of matches per page.

Constructor Detail

CmsSearchParameters

public CmsSearchParameters()

Creates a new search parameter instance with no search query and default values for the remaining parameters.

Before using this search parameters for a search method setQuery(String) has to be invoked.

CmsSearchParameters

public CmsSearchParameters(java.lang.String query)

Creates a new search parameter instance with the provided search query and default values for the remaining parameters.

Only the "meta" field (combination of content and title) will be used for search. No search root restriction is chosen. No category restriction is used. No category counts are calculated for the result. Sorting is turned off. This is a simple but fast setup.

Parameters:

query - the query to search for

CmsSearchParameters

public CmsSearchParameters(java.lang.String query,
                           java.util.List<java.lang.String> fields,
                           java.util.List<java.lang.String> roots,
                           java.util.List<java.lang.String> categories,
                           java.util.List<java.lang.String> resourceTypes,
                           boolean calculateCategories,
                           org.apache.lucene.search.Sort sort)

Creates a new search parameter instance with the provided parameter values.

Parameters:

query - the search term to search the index

fields - the list of fields to search

roots - only resource that are sub-resource of one of the search roots are included in the search result

categories - the list of categories to limit the search to

resourceTypes - the list of resource types to limit the search to

calculateCategories - if true, the category count is calculated for all search results (use with caution, this option uses much performance)

sort - the sort order for the search

Method Detail

addFieldQuery

public void addFieldQuery(CmsSearchParameters.CmsSearchFieldQuery query)

Adds an individual query for a search field.

If this is used, any setting made with setQuery(String) and setFields(List) will be ignored and only the individual field search settings will be used.

Parameters:

query - the query to add

Since:

7.5.1

addFieldQuery

public void addFieldQuery(java.lang.String fieldName,
                          java.lang.String searchQuery,
                          org.apache.lucene.search.BooleanClause.Occur occur)

Adds an individual query for a search field.

If this is used, any setting made with setQuery(String) and setFields(List) will be ignored and only the individual field search settings will be used.

Parameters:

fieldName - the field name

searchQuery - the search query

occur - the occur parameter for the query in the field

Since:

7.5.1

getCalculateCategories

public boolean getCalculateCategories()

Returns whether category counts are calculated for search results or not.

Returns:

a boolean that tells whether category counts are calculated for search results or not

getCategories

public java.util.List<java.lang.String> getCategories()

Returns the list of categories to limit the search to.

Returns:

the list of categories to limit the search to

getDisplayPages

public int getDisplayPages()

Returns the maximum number of pages which should be shown.

Returns:

the maximum number of pages which should be shown

getFieldQueries

public java.util.List<CmsSearchParameters.CmsSearchFieldQuery> getFieldQueries()

Returns the list of individual field queries.

Returns:

the list of individual field queries

Since:

7.5.1

getFields

public java.util.List<java.lang.String> getFields()

Returns the list of search index field names (Strings) to search in.

Returns:

the list of search index field names (Strings) to search in

getIndex

public java.lang.String getIndex()

Get the name of the index for the search.

Returns:

the name of the index for the search

getMatchesPerPage

public int getMatchesPerPage()

Gets the number of matches displayed on each page.

Returns:

matches per result page

getMaxDateCreated

public long getMaxDateCreated()

Returns the creation date the resources have to have as maximum.

Returns:

the creation date the resources have to have as maximum

getMaxDateLastModified

public long getMaxDateLastModified()

Returns the last modification date the resources have to have as maximum.

Returns:

the last modification date the resources have to have as maximum

getMinDateCreated

public long getMinDateCreated()

Returns the creation date the resources have to have as minimum.

Returns:

the creation date the resources have to have as minimum

getMinDateLastModified

public long getMinDateLastModified()

Returns the last modification date the resources have to have as minimum.

Returns:

the last modification date the resources have to have as minimum

getQuery

public java.lang.String getQuery()

Returns the search query to use.

Returns:

the search query to use

getQueryLength

public int getQueryLength()

Gets the minimum search query length.

Returns:

the minimum search query length

getResourceTypes

public java.util.List<java.lang.String> getResourceTypes()

Returns the list of resource types to limit the search to.

Returns:

the list of resource types to limit the search to

Since:

7.5.1

getRoots

public java.util.List<java.lang.String> getRoots()

Returns the list of strings of search roots to use.

Only resource that are sub-resource of one of the search roots are included in the search result.

Returns:

the list of strings of search roots to use

getSearchCategories

public java.lang.String getSearchCategories()

Returns the list of categories to limit the search to.

Returns:

the list of categories to limit the search to

getSearchIndex

public CmsSearchIndex getSearchIndex()

Returns the search index to search in or null if not set before (setSearchIndex(CmsSearchIndex)).

Returns:

the search index to search in or null if not set before (setSearchIndex(CmsSearchIndex))

getSearchPage

public int getSearchPage()

Returns the search page to display.

Returns:

the search page to display

getSearchRoots

public java.lang.String getSearchRoots()

Returns the comma separated lists of root folder names to restrict search to.

This method is a "sibling" to method getRoots() but with the support of being usable with widget technology.

Returns:

the comma separated lists of field names to search in

See Also:

setSortName(String)

getSort

public org.apache.lucene.search.Sort getSort()

Returns the instance that defines the sort order for the results.

Returns:

the instance that defines the sort order for the results

getSortName

public java.lang.String getSortName()

Returns the name of the sort option being used.

Returns:

the name of the sort option being used

See Also:

SORT_NAMES, setSortName(String)

isCalculateCategories

public boolean isCalculateCategories()

Returns true if the category count is calculated for all search results.

Returns:

true if the category count is calculated for all search results

isExcerptOnlySearchedFields

public boolean isExcerptOnlySearchedFields()

Returns true if fields configured for the excerpt should be used for generating the excerpt only if they have been actually searched in.

The default setting is false, which means all text fields configured for the excerpt will be used to generate the excerpt, regardless if they have been searched in or not.

Please note: A field will only be included in the excerpt if it has been configured as excerpt="true" in opencms-search.xml. This method controls if so configured fields are used depending on the fields searched, see setFields(List).

Returns:

true if fields configured for the excerpt should be used for generating the excerpt only if they have been actually searched in

restrict

public CmsSearchParameters restrict(CmsSearchParameters restriction)

Creates a merged parameter set from this parameters, restricted by the given other parameters.

This is mainly intended for "search in search result" functions.

The restricted query is build of the queries of both parameters, appended with AND.

The lists in the restriction for getFields(), getRoots() and getCategories() are intersected with the lists of this search parameters. Only elements contained in both lists are included for the created search parameters. If a list in either the restriction or in this search parameters is null, the list from the other search parameters is used directly.

The values for isCalculateCategories() and getSort() of this parameters are used for the restricted parameters.

Parameters:

restriction - the parameters to restrict this parameters with

Returns:

the restricted parameters

setCalculateCategories

public void setCalculateCategories(boolean flag)

Set whether category counts shall be calculated for the corresponding search results or not.

Parameters:

flag - true if category counts shall be calculated for the corresponding search results or false if not

setCategories

public void setCategories(java.util.List<java.lang.String> categories)

Set the list of categories (strings) to this parameters.

Parameters:

categories - the list of categories (strings) of this parameters

setDisplayPages

public void setDisplayPages(int value)

Sets the maximum number of pages which should be shown.

Enter an odd value to achieve a nice, "symmetric" output.

Parameters:

value - the maximum number of pages which should be shown

setExcerptOnlySearchedFields

public void setExcerptOnlySearchedFields(boolean excerptAllFields)

Controls if the excerpt from a field is generated only for searched fields, or for all fields (the default).

Parameters:

excerptAllFields - if true, the excerpt is generated only from the fields actually searched in

See Also:

isExcerptOnlySearchedFields()

setFields

public void setFields(java.util.List<java.lang.String> fields)

Sets the list of strings of names of fields to search in.

Parameters:

fields - the list of strings of names of fields to search in to set

setIndex

public void setIndex(java.lang.String indexName)

Set the name of the index to search.

Parameters:

indexName - the name of the index

setMatchesPerPage

public void setMatchesPerPage(int matches)

Sets the number of matches per page.

Parameters:

matches - the number of matches per page

setMaxDateCreated

public void setMaxDateCreated(long dateCreatedTo)

Sets the creation date the resources have to have as maximum.

Parameters:

dateCreatedTo - the creation date the resources have to have as maximum to set

setMaxDateLastModified

public void setMaxDateLastModified(long dateLastModifiedTo)

Sets the last modification date the resources have to have as maximum.

Parameters:

dateLastModifiedTo - the last modification date the resources have to have as maximum to set

setMinDateCreated

public void setMinDateCreated(long dateCreatedFrom)

Sets the creation date the resources have to have as minimum.

Parameters:

dateCreatedFrom - the creation date the resources have to have as minimum to set

setMinDateLastModified

public void setMinDateLastModified(long dateLastModifiedFrom)

Sets the last modification date the resources have to have as minimum.

Parameters:

dateLastModifiedFrom - the the last modification date the resources have to have as minimum to set

setQuery

public void setQuery(java.lang.String query)

Sets the query to search for.

The decoding here is tailored for query strings that are additionally manually UTF-8 encoded at client side (javascript) to get around an issue with special chars in applications that use non- UTF-8 encoding (e.g. ISO-8859-1) OpenCms applications. It is not recommended to use this with front ends that don't encode manually as characters like sole "%" (without number suffix) will cause an Exception.

Parameters:

query - the query to search for to set

setQueryLength

public void setQueryLength(int length)

Sets the minimum length of the search query.

Parameters:

length - the minimum search query length

setResourceTypes

public void setResourceTypes(java.util.List<java.lang.String> resourceTypes)

Set the list of resource types (strings) to limit the search to.

Parameters:

resourceTypes - the list of resource types (strings) to limit the search to

Since:

7.5.1

setRoots

public void setRoots(java.util.List<java.lang.String> roots)

Sets the list of strings of roots to search under for the search.

Parameters:

roots - the list of strings of roots to search under for the search to set

setSearchCategories

public void setSearchCategories(java.lang.String categories)

Set the comma separated search root names to restrict search to.

Parameters:

categories - the comma separated category names to restrict search to

setSearchIndex

public void setSearchIndex(CmsSearchIndex index)
                    throws CmsIllegalArgumentException

Sets the search index to use for the search.

Parameters:

index - the search index to use for the search to set.

Throws:

CmsIllegalArgumentException - if null is given as argument

setSearchPage

public void setSearchPage(int page)

Set the search page to display.

Parameters:

page - the search page to display

setSearchRoots

public void setSearchRoots(java.lang.String rootNameList)

Set the comma separated search root names to restrict search to.

Parameters:

rootNameList - the comma separated search root names to restrict search to

setSort

public void setSort(org.apache.lucene.search.Sort sortOrder)

Set the instance that defines the sort order for search results.

Parameters:

sortOrder - the instance that defines the sort order for search results to set

setSortName

public void setSortName(java.lang.String sortName)

Sets the internal member of type Sort according to the given sort name.

For a list of valid sort names, please see SORT_NAMES.

Parameters:

sortName - the name of the sort to use

See Also:

SORT_NAMES

toQueryString

public java.lang.String toQueryString()

Creates a query String build from this search parameters for HTML links.

Returns:

a query String build from this search parameters for HTML links

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()