Class CmsSearchParameters

    • Field Summary

      Fields 
      Modifier and Type Field Description
      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).
      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

      Constructors 
      Constructor Description
      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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      void addFieldQuery​(CmsSearchParameters.CmsSearchFieldQuery query)
      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 maximum creation date a resource must have to be included in the search result.
      long getMaxDateLastModified()
      Returns the maximum last modification date a resource must have to be included in the search result.
      long getMinDateCreated()
      Returns the minimum creation date a resource must have to be included in the search result.
      long getMinDateLastModified()
      Returns the minimum last modification date a resource must have to be included in the search result.
      java.lang.String getParsedQuery()
      Returns the parsed query.
      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.
      boolean isIgnoreQuery()
      Returns true if the query part should be ignored so that only filters are used for searching.
      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 excerptOnlySearchedFields)
      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 setIgnoreQuery​(boolean isIgnoreQuery)
      Sets the flag to indicate if the query part should be ignored so that only filters are used for searching.
      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 maxDateCreated)
      Sets the maximum creation date a resource must have to be included in the search result.
      void setMaxDateLastModified​(long maxDateLastModified)
      Sets the maximum last modification date a resource must have to be included in the search result.
      void setMinDateCreated​(long minDateCreated)
      Sets the minimum creation date a resource must have to be included in the search result.
      void setMinDateLastModified​(long minDateLastModified)
      Sets the minimum last modification date a resource must have to be included in the search result.
      void setParsedQuery​(java.lang.String parsedQuery)
      Sets the parsed query.
      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).
      • 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​(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
      • 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 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 java.lang.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 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
      • 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
      • 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​(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 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:
        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
      • 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​(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 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​(java.lang.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​(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
      • 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()