Package org.opencms.search

Class CmsSearchParameters

java.lang.Object
org.opencms.search.CmsSearchParameters
public class CmsSearchParameters extends 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

  • Field Details

    • 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).

    • SORT_NAMES

      public static final 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 Details

    • 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(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(String query, List<String> fields, List<String> roots, List<String> categories, List<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 Details

    • 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(String fieldName, 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 List<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 List<CmsSearchParameters.CmsSearchFieldQuery> getFieldQueries()
      Returns the list of individual field queries.

      Returns:
      the list of individual field queries
      Since:
      7.5.1

    • getFields

      public List<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 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 maximum creation date a resource must have to be included in the search result.

      Returns:
      the maximum creation date a resource must have to be included in the search result

    • getMaxDateLastModified

      public long getMaxDateLastModified()
      Returns the maximum last modification date a resource must have to be included in the search result.

      Returns:
      the maximum last modification date a resource must have to be included in the search result

    • getMinDateCreated

      public long getMinDateCreated()
      Returns the minimum creation date a resource must have to be included in the search result.

      Returns:
      the minimum creation date a resource must have to be included in the search result

    • getMinDateLastModified

      public long getMinDateLastModified()
      Returns the minimum last modification date a resource must have to be included in the search result.

      Returns:
      the minimum last modification date a resource must have to be included in the search result

    • getParsedQuery

      public String getParsedQuery()
      Returns the parsed query.

      The parsed query is automatically set by the OpenCms search index when a query is created with either setQuery(String) or addFieldQuery(CmsSearchFieldQuery). The Lucene query build from the parameters is stored here and can be later used for paging through the results.

      Please note that this returns only to the query part, not the filter part of the search.

      Returns:
      the parsed query

    • getQuery

      public 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 List<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 List<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 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 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:

    • 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 String getSortName()
      Returns the name of the sort option being used.

      Returns:
      the name of the sort option being used
      See Also:

    • 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

    • isIgnoreQuery

      public boolean isIgnoreQuery()
      Returns true if the query part should be ignored so that only filters are used for searching.

      Returns:
      true if the query part should be ignored so that only filters are used for searching
      Since:
      8.0.0

    • 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(List<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 excerptOnlySearchedFields)
      Controls if the excerpt from a field is generated only for searched fields, or for all fields (the default).

      Parameters:
      excerptOnlySearchedFields - if true, the excerpt is generated only from the fields actually searched in
      See Also:

    • setFields

      public void setFields(List<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

    • setIgnoreQuery

      public void setIgnoreQuery(boolean isIgnoreQuery)
      Sets the flag to indicate if the query part should be ignored so that only filters are used for searching.

      Parameters:
      isIgnoreQuery - the flag to indicate if the query part should be ignored
      Since:
      8.0.0

    • setIndex

      public void setIndex(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 maxDateCreated)
      Sets the maximum creation date a resource must have to be included in the search result.

      Parameters:
      maxDateCreated - the maximum creation date to set

    • setMaxDateLastModified

      public void setMaxDateLastModified(long maxDateLastModified)
      Sets the maximum last modification date a resource must have to be included in the search result.

      Parameters:
      maxDateLastModified - the maximum last modification date to set

    • setMinDateCreated

      public void setMinDateCreated(long minDateCreated)
      Sets the minimum creation date a resource must have to be included in the search result.

      Parameters:
      minDateCreated - the minimum creation date to set

    • setMinDateLastModified

      public void setMinDateLastModified(long minDateLastModified)
      Sets the minimum last modification date a resource must have to be included in the search result.

      Parameters:
      minDateLastModified - he minimum last modification date to set

    • setParsedQuery

      public void setParsedQuery(String parsedQuery)
      Sets the parsed query.

      The parsed query is automatically set by the OpenCms search index when a query is created with either setQuery(String) or addFieldQuery(CmsSearchFieldQuery). The Lucene query build from the parameters is stored here and can be later used for paging through the results.

      Please note that this applies only to the query part, not the filter part of the search.

      Parameters:
      parsedQuery - the parsed query to set

    • setQuery

      public void setQuery(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(List<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(List<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(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(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(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:

    • toQueryString

      public 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 String toString()
      Overrides:
      toString in class Object
      See Also: