Package com.atlassian.jira.bc.issue.search

Interface SearchService

All Known Implementing Classes:
DefaultSearchService
@PublicApi public interface SearchService
Provides functionality (search, query string generation, parsing, validation, context generation, etc...) related to searching in JIRA. This deals with Query objects which contain the search criteria in JIRA.
Since:
v4.0

  • Method Details

    • search

      SearchResults<Issue> search(ApplicationUser searcher, Query query, PagerFilter pager) throws SearchException
      Search the index, and only return issues that are in the pager's range.

      Note: that this method returns read only Issue objects, and should not be used where you need the issue for update.

      Parameters:
      searcher - the user performing the search, which will be used to create a permission filter that filters out any of the results the user is not able to see and will be used to provide context for the search.
      query - contains the information required to perform the search.
      pager - the pager filter. To retrieve unlimited number of results, use streamSearch(com.atlassian.jira.user.ApplicationUser, com.atlassian.query.Query)
      Returns:
      A SearchResults containing the resulting issues.
      Throws:
      SearchException - thrown if there is a severe problem encountered with lucene when searching (wraps an IOException).
      Since:
      v7.0

    • search

      SearchResults<Issue> search(ApplicationUser searcher, Query query, @Nullable TrackHits trackHits, PagerFilter pager) throws SearchException
      Search the index, and only return issues that are in the pager's range.

      Note: that this method returns read only Issue objects, and should not be used where you need the issue for update.

      Parameters:
      searcher - the user performing the search, which will be used to create a permission filter that filters out any of the results the user is not able to see and will be used to provide context for the search.
      query - contains the information required to perform the search.
      trackHits - defines how the total hits count is calculated. Only applicable for SearchPlatform.OPENSEARCH. For SearchPlatform.LUCENE the total hits count is always tracked (equivalent to TrackHits.all()).
      pager - the pager filter. To retrieve unlimited number of results, use streamSearch(com.atlassian.jira.user.ApplicationUser, com.atlassian.query.Query)
      Returns:
      A SearchResults containing the resulting issues.
      Throws:
      SearchException - thrown if there is a severe problem encountered with lucene when searching (wraps an IOException).
      Since:
      11.0
      See Also:

    • search

      SearchResults<Issue> search(ApplicationUser searcher, Query jqlQuery, Query filterQuery, PagerFilter pager) throws SearchException
      Searches the index and returns issues within the pager's range. Allows adding a filter query (filterQuery) to merge with the JQL query (jqlQuery).

      Note that this method returns read only Issue objects, and should not be used where you need the issue for update.

      Parameters:
      searcher - the user performing the search, providing context for the search.
      jqlQuery - the JQL query to search with.
      filterQuery - an additional search query to combine with the generated query from the provided jqlQuery.
      pager - the pager filter. To retrieve unlimited number of results, use streamSearch(com.atlassian.jira.user.ApplicationUser, com.atlassian.query.Query)
      Returns:
      A SearchResults containing the resulting issues.
      Throws:
      SearchException - if a severe problem is encountered during the search (wraps an IOException).
      Since:
      10.4

    • search

      SearchResults<Issue> search(ApplicationUser searcher, Query jqlQuery, Query filterQuery, @Nullable TrackHits trackHits, PagerFilter pager) throws SearchException
      Searches the index and returns issues within the pager's range. Allows adding a filter query (filterQuery) to merge with the JQL query (jqlQuery).

      Note that this method returns read only Issue objects, and should not be used where you need the issue for update.

      Parameters:
      searcher - the user performing the search, providing context for the search.
      jqlQuery - the JQL query to search with.
      filterQuery - an additional search query to combine with the generated query from the provided jqlQuery.
      trackHits - defines how the total hits count is calculated. Only applicable for SearchPlatform.OPENSEARCH. For SearchPlatform.LUCENE the total hits count is always tracked (equivalent to TrackHits.all()).
      pager - the pager filter. To retrieve unlimited number of results, use streamSearch(com.atlassian.jira.user.ApplicationUser, com.atlassian.query.Query)
      Returns:
      A SearchResults containing the resulting issues.
      Throws:
      SearchException - if a severe problem is encountered during the search (wraps an IOException).
      Since:
      11.0
      See Also:

    • search

      SearchResults<Issue> search(DocumentSearchRequest searchRequest, PagerFilter pager) throws SearchException
      Searches the index and returns issues within the pager's range. Allows adding a filter query (filterQuery) to merge with the JQL query (jqlQuery).

      Note that this method returns read only Issue objects, and should not be used where you need the issue for update.

      Parameters:
      searchRequest - the set of parameters that define the search behaviour
      pager - the pager filter. To retrieve unlimited number of results, use streamSearch(com.atlassian.jira.user.ApplicationUser, com.atlassian.query.Query)
      Returns:
      A SearchResults containing the resulting issues.
      Throws:
      SearchException - if a severe problem is encountered during the search (wraps an IOException).
      Since:
      11.2
      See Also:

    • streamSearch

      SearchStreamResults<Issue> streamSearch(ApplicationUser searcher, Query query) throws SearchException
      Search the index, and only return the matched issues as a stream, which is memory efficient for a large number of issues.

      Note: that this method returns read only Issue objects, and should not be used where you need the issue for update.

      Parameters:
      searcher - the user performing the search, which will be used to create a permission filter that filters out any of the results the user is not able to see and will be used to provide context for the search.
      query - contains the information required to perform the search.
      Returns:
      A SearchStreamResults containing the stream of resulting issues.
      Throws:
      SearchException - thrown if there is a severe problem encountered when searching (wraps an IOException).
      Since:
      v10.6

    • searchOverrideSecurity

      SearchResults<Issue> searchOverrideSecurity(ApplicationUser searcher, Query query, PagerFilter pager) throws SearchException
      Search the index, and only return issues that are in the pager's range not taking into account any security constraints.

      As the method name implies, it bypasses the security restrictions that would normally be applied when performing a search. As such, it should only be used for administrative tasks where you really need to know about ALL affected issues.

      Note that this method returns read only Issue objects, and should not be used where you need the issue for update. Also note that if you are only after the number of search results use searchCount(ApplicationUser, Query) as it provides better performance.

      Parameters:
      searcher - the user performing the search which will be used to provide context for the search.
      query - contains the information required to perform the search.
      pager - the pager filter. To retrieve unlimited number of results, use streamSearch(com.atlassian.jira.user.ApplicationUser, com.atlassian.query.Query)
      Returns:
      A SearchResults containing the resulting issues.
      Throws:
      SearchException - thrown if there is a severe problem encountered with lucene when searching (wraps an IOException).
      ClauseTooComplexSearchException - if the query or part of the query produces lucene that is too complex to be processed.
      Since:
      v7.0

    • searchCount

      long searchCount(ApplicationUser searcher, Query query) throws SearchException
      Search the index, and return the count of the issues matching the query.
      Parameters:
      searcher - the user performing the search, which will be used to create a permission filter that filters out any of the results the user is not able to see and will be used to provide context for the search.
      query - contains the information required to perform the search.
      Returns:
      the number of issues matching the query
      Throws:
      SearchException - thrown if there is a severe problem encountered with lucene when searching (wraps an IOException).
      Since:
      v7.0

    • searchCount

      long searchCount(ApplicationUser searcher, Query query, Long timeout) throws SearchException
      Search the index, and return the count of the issues matching the query.
      Parameters:
      searcher - the user performing the search, which will be used to create a permission filter that filters out any of the results the user is not able to see and will be used to provide context for the search
      query - contains the information required to perform the search.
      timeout - timeout in milliseconds
      Returns:
      the number of issues matching the query
      Throws:
      SearchException - thrown if there is a severe problem encountered with lucene when searching (wraps an IOException).
      Since:
      v8.12

    • searchCountOverrideSecurity

      long searchCountOverrideSecurity(ApplicationUser searcher, Query query) throws SearchException
      Return the number of issues matching the provided search criteria, overridding any security constraints.

      As the method name implies, it bypasses the security restrictions that would normally be applied when performing a search. As such, it should only be used for administrative tasks where you really need to know about ALL affected issues.

      Note: Searching for the count avoids loading the issue data into memory, so this should be preferred when the count is all you need to know.

      Parameters:
      searcher - the user performing the search which will be used to provide context for the search.
      query - contains the information required to perform the search.
      Returns:
      number of matching results.
      Throws:
      SearchException - thrown if there is a severe problem encountered with lucene when searching (wraps an IOException).
      ClauseTooComplexSearchException - if the query or part of the query produces lucene that is too complex to be processed.
      Since:
      v7.0

    • getQueryString

      String getQueryString(ApplicationUser user, Query query)
      Deprecated.
      Since v7.1. Use getIssueSearchPath(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.issue.search.SearchService.IssueSearchParameters) instead.
      Returns the query string to represent the specified SearchQuery.

      The query string is prepended with "&jqlQuery=" so that it is ready for use in building a URL.

      Parameters:
      user - the user performing the search
      query - the SearchQuery to generate the query string of. Does not accept null.
      Returns:
      a String which represents the query string of a SearchQuery (ie no context/base applied). Never null.
      Since:
      v7.0 with ApplicationUser, previously with User

    • getIssueSearchPath

      @Nonnull String getIssueSearchPath(ApplicationUser user, @Nonnull SearchService.IssueSearchParameters params)
      Returns the URL relative to the app context to represent the specified issue search.

      The URL is composed by the issue search path and provided parameters (e.g. "&/issues/?jql=...invalid input: '&filter'=..."), but does NOT include the context path.

      Parameters:
      user - the user performing the search
      params - the parameters to generate the URL. Possible parameters are filter Id and query (JQL), both are optional but you cannot use both at the same time. Does not accept null.
      Returns:
      a String which represents the issue search URL and query string corresponding to the parameters (no context/base applied). Never null.
      Since:
      v7.1

    • parseQuery

      SearchService.ParseResult parseQuery(ApplicationUser searcher, String query)
      Parses the query string into a JQL Query.
      Parameters:
      searcher - the user in context
      query - the query to parse into a Query.
      Returns:
      a result set that contains the query and a message set of any errors or warnings that occured during the parse.
      Since:
      v7.0

    • validateQuery

      @Nonnull MessageSet validateQuery(ApplicationUser searcher, @Nonnull Query query)
      Validates the specified Query for passed user. The same as calling validateQuery(searcher, query, null);.
      Parameters:
      searcher - the user performing the search
      query - the search query to validate
      Returns:
      a message set containing any errors encountered; never null.
      Since:
      v7.0

    • validateQuery

      @Nonnull MessageSet validateQuery(ApplicationUser searcher, @Nonnull Query query, Long searchRequestId)
      Validates the specified Query for passed user and search request. This validates the the passed query as if it was run as the passed search request.
      Parameters:
      searcher - the user performing the search.
      query - the search query to validate.
      searchRequestId - validate in the context of this search request. Can be null to indicate the passed query is not currently a search request.
      Returns:
      a message set containing any errors encountered; never null.
      Since:
      v7.0

    • doesQueryFitFilterForm

      boolean doesQueryFitFilterForm(ApplicationUser user, Query query)
      Checks if a Query is capable of being shown on the simple (GUI-based) issue navigator edit screen.
      Parameters:
      user - the user who is executing the query.
      query - the Query which to check that is displayable on the simple (GUI-based) issue navigator edit screen. Does not accept null.
      Returns:
      true if the query is displayable on the simple (GUI-based) issue navigator edit screen, false otherwise.
      Since:
      v7.0

    • getQueryContext

      QueryContext getQueryContext(ApplicationUser searcher, Query query)
      Generates a full QueryContext for the specified Query for the searching user. The full QueryContext contains all explicit and implicitly specified projects and issue types from the Query.

      For a better explanation of the differences between the full and simple QueryContexts, see QueryContextVisitor in jira-core.

      Parameters:
      searcher - the user performing the search
      query - the search query to generate the context for
      Returns:
      a QueryContext that contains the implicit and explicit project / issue types implied by the included clauses in the query.
      Since:
      v7.0

    • getSimpleQueryContext

      QueryContext getSimpleQueryContext(ApplicationUser searcher, Query query)
      Generates a simple QueryContext for the specified Query for the searching user. The simple QueryContext contains only the explicit projects and issue types specified in the Query. If none were specified, it will be the Global context.

      For a better explanation of the differences between the full and simple QueryContexts, see QueryContextVisitor in jira-core.

      Parameters:
      searcher - the user performing the search
      query - the search query to generate the context for
      Returns:
      a QueryContext that contains only the explicit project / issue types from the included clauses in the query.
      Since:
      v7.0

    • getSearchContext

      SearchContext getSearchContext(ApplicationUser searcher, Query query)
      This produces an old-style SearchContext based on the passed in search query and the user that is performing the search.

      This will only make sense if the query returns true for doesQueryFitFilterForm(ApplicationUser, Query) since SearchContext is only relevant for simple queries.

      The more acurate context can be gotten by calling getQueryContext(ApplicationUser, Query).

      If the query will not fit in the simple issue navigator then the generated SearchContext will be empty. This method never returns a null SearchContext, even when passed a null SearchQuery.

      Parameters:
      searcher - the user performing the search, not always the SearchRequest's owner
      query - the query for which you want a context
      Returns:
      a SearchContext with the correct project/issue types if the query fits in the issue navigator, otherwise an empty SearchContext. Never null.
      Since:
      v7.0

    • getJqlString

      String getJqlString(Query query)
      Gets the JQL string representation for the passed query. Returns the string from Query.getQueryString() if it exists or generates one if it does not. Equilavent to: 
        if (query.getQueryString() != null)
    return query.getQueryString();
  else
    return getGeneratedJqlString(query);
      Parameters:
      query - the query. Cannot be null.
      Returns:
      the JQL string represenation of the passed query.

    • getGeneratedJqlString

      String getGeneratedJqlString(Query query)
      Generates a JQL string representation for the passed query. The JQL string is always generated, that is, Query.getQueryString() is completely ignored if it exists. The returned JQL is automatically escaped as necessary.
      Parameters:
      query - the query. Cannot be null.
      Returns:
      the generated JQL string representation of the passed query.

    • sanitiseSearchQuery

      Query sanitiseSearchQuery(ApplicationUser searcher, Query query)
      Returns an equivalent Query with all the potential "information leaks" removed, with regards to the specified user. For example, if the query contains the clause "project = Invisible", and the specified user does not have browse permission for project "Invisible", the sanitised query will replace this clause with "project = 12345" (where 12345 is the id of the project).
      Parameters:
      searcher - the user performing the search
      query - the query to sanitise; must not be null.
      Returns:
      the sanitised query; never null.
      Since:
      v7.0