1 /*
2 * Copyright (C) 2011 Atlassian
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package com.atlassian.jira.rest.client;
18
19 import com.atlassian.jira.rest.client.domain.SearchResult;
20
21 import javax.annotation.Nullable;
22
23 /**
24 * The client handling search REST resource
25 *
26 * @since 0.2 client, 4.3 server
27 */
28 public interface SearchRestClient {
29 /**
30 * Performs a JQL search and returns issues matching the query
31 *
32 * @param jql a valid JQL query (will be properly encoded by JIRA client). Restricted JQL characters (like '/') must be properly escaped.
33 * @param progressMonitor progress monitor
34 * @return issues matching given JQL query
35 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid JQL query, etc.)
36 */
37 SearchResult searchJql(@Nullable String jql, ProgressMonitor progressMonitor);
38
39 /**
40 * Performs a JQL search and returns issues matching the query using default maxResults (as configured in JIRA - usually 50) and startAt=0
41 *
42 * @param jql a valid JQL query (will be properly encoded by JIRA client). Restricted JQL characters (like '/') must be properly escaped.
43 * @param maxResults maximum results (page/window size) for this search. The page will contain issues from
44 * <code>startAt div maxResults</code> (no remnant) and will include at most <code>maxResults</code> matching issues.
45 * @param startAt starting index (0-based) defining the page/window for the results. It will be aligned by the server to the beginning
46 * on the page (startAt = startAt div maxResults). For example for startAt=5 and maxResults=3 the results will include matching issues
47 * with index 3, 4 and 5. For startAt = 6 and maxResults=3 the issues returned are from position 6, 7 and 8.
48 * @param progressMonitor progress monitor
49 * @return issues matching given JQL query
50 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid JQL query, etc.)
51 */
52 SearchResult searchJql(@Nullable String jql, int maxResults, int startAt, ProgressMonitor progressMonitor);
53 }