com.atlassian.jira.rest.v2.search
Class SearchResource

java.lang.Object
  com.atlassian.jira.rest.v2.search.SearchResource

public class SearchResource
extends Object

Resource for searches.

Since:

v4.3

Constructor Summary

SearchResource(SearchService searchService, JiraAuthenticationContext jiraAuthenticationContext, IssueSearchLimits searchLimits, BeanBuilderFactory beanBuilderFactory)

Method Summary

protected SearchResultsBean	asResultsBean(SearchResults results, PagerFilter filter, IncludedFields fields, StringList expand, Set<String> warningMessages) Creates a SearchResultsBean suitable for returning to the client.
protected PagerFilter	createFilter(Integer startAt, Integer maxResults) Creates a new PagerFilter for the given search request.
SearchResultsBean	search(String jql, Integer startAt, Integer maxResults, List<StringList> fields, StringList expand) Searches for issues using JQL.
SearchResultsBean	searchUsingSearchRequest(SearchRequestBean searchRequest) Performs a search using JQL.

Methods inherited from class java.lang.Object

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

Constructor Detail

SearchResource

public SearchResource(SearchService searchService,
                      JiraAuthenticationContext jiraAuthenticationContext,
                      IssueSearchLimits searchLimits,
                      BeanBuilderFactory beanBuilderFactory)

Method Detail

search

public SearchResultsBean search(String jql,
                                Integer startAt,
                                Integer maxResults,
                                List<StringList> fields,
                                StringList expand)
                         throws SearchException

Searches for issues using JQL.

Sorting the jql parameter is a full JQL expression, and includes an ORDER BY clause.

The fields param (which can be specified multiple times) gives a comma-separated list of fields to include in the response. This can be used to retrieve a subset of fields. A particular field can be excluded by prefixing it with a minus.

By default, only navigable (*navigable) fields are returned in this search resource. Note: the default is different in the get-issue resource -- the default there all fields (*all).

• *all - include all fields
• *navigable - include just navigable fields
• summary,comment - include just the summary and comments
• -description - include navigable fields except the description (the default is *navigable for search)
• *all,-comment - include everything except comments

GET vs POST: If the JQL query is too large to be encoded as a query param you should instead POST to this resource.

Expanding Issues in the Search Result: It is possible to expand the issues returned by directly specifying the expansion on the expand parameter passed in to this resources.

For instance, to expand the "changelog" for all the issues on the search result, it is neccesary to specify "changelog" as one of the values to expand.

Parameters:

jql - a JQL query string

startAt - the index of the first issue to return (0-based)

maxResults - the maximum number of issues to return (defaults to 50). The maximum allowable value is dictated by the JIRA property 'jira.search.views.default.max'. If you specify a value that is higher than this number, your search results will be truncated.

fields - the list of fields to return for each issue. By default, all navigable fields are returned.

expand - A comma-separated list of the parameters to expand.

Returns:

a SearchResultsBean

Throws:

SearchException - if there is a problem performing the search

searchUsingSearchRequest

public SearchResultsBean searchUsingSearchRequest(SearchRequestBean searchRequest)
                                           throws SearchException

Performs a search using JQL.

Parameters:

searchRequest - a JSON object containing the search request

Returns:

a SearchResultsBean

Throws:

SearchException - if there is a problem performing the search

asResultsBean

protected SearchResultsBean asResultsBean(SearchResults results,
                                          PagerFilter filter,
                                          IncludedFields fields,
                                          StringList expand,
                                          Set<String> warningMessages)

Creates a SearchResultsBean suitable for returning to the client.

Parameters:

results - a SearchResults

filter - a PagerFilter that was used for the search

fields - a List<StringList,>

expand - the parameters to expand

warningMessages -

Returns:

a SearchResultsBean

createFilter

protected PagerFilter createFilter(Integer startAt,
                                   Integer maxResults)

Creates a new PagerFilter for the given search request. If the maxResults specified in the search request is greater than the value returned by IssueSearchLimits.getMaxResults(), the value returned by this method will be used.

Parameters:

startAt - an Integer containing the start index

maxResults - an Integer containing the max results

Returns:

a PagerFilter