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.api;
18
19 import com.atlassian.jira.rest.client.api.domain.Filter;
20 import com.atlassian.jira.rest.client.api.domain.SearchResult;
21 import com.atlassian.util.concurrent.Promise;
22
23 import javax.annotation.Nullable;
24 import java.net.URI;
25 import java.util.Set;
26
27 /**
28 * The client handling search REST resource
29 *
30 * @since 2.0 client, 4.3 server
31 */
32 public interface SearchRestClient {
33 /**
34 * Performs a JQL search and returns issues matching the query
35 *
36 * @param jql a valid JQL query (will be properly encoded by JIRA client). Restricted JQL characters (like '/') must be properly escaped.
37 * @return issues matching given JQL query
38 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid JQL query, etc.)
39 */
40 Promise<SearchResult> searchJql(@Nullable String jql);
41
42 /**
43 * Performs a JQL search and returns issues matching the query. The first startAt issues will be skipped and SearchResult will
44 * contain at most maxResults issues. List of issue fields which should be included in the result may be specified.
45 *
46 * @param jql a valid JQL query (will be properly encoded by JIRA client). Restricted JQL characters (like '/') must
47 * be properly escaped. All issues matches to the null or empty JQL.
48 * @param maxResults maximum results for this search. When null is given, the default maxResults configured in JIRA is
49 * used (usually 50).
50 * @param startAt starting index (0-based) defining how many issues should be skipped in the results. For example for
51 * startAt=5 and maxResults=3 the results will include matching issues with index 5, 6 and 7.
52 * For startAt = 0 and maxResults=3 the issues returned are from position 0, 1 and 2.
53 * When null is given, the default startAt is used (0).
54 * @param fields set of fields which should be retrieved. You can specify *all for all fields
55 * or *navigable (which is the default value, used when null is given) which will cause to include only
56 * navigable fields in the result. To ignore the specific field you can use "-" before the field's name.
57 * Note that the following fields: summary, issuetype, created, updated, project and status are
58 * required. These fields are included in *all and *navigable.
59 * @return issues matching given JQL query
60 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid JQL query, etc.)
61 */
62 Promise<SearchResult> searchJql(@Nullable String jql, @Nullable Integer maxResults, @Nullable Integer startAt, @Nullable Set<String> fields);
63
64 /**
65 * Retrieves list of your favourite filters.
66 *
67 * @return list of your favourite filters
68 * @since 2.0 client, 5.0 server
69 */
70 Promise<Iterable<Filter>> getFavouriteFilters();
71
72 /**
73 * Retrieves filter for given URI.
74 *
75 * @param filterUri URI to filter resource (usually get from <code>self</code> attribute describing component elsewhere)
76 * @return filter
77 * @since 2.0 client, 5.0 server
78 */
79 Promise<Filter> getFilter(URI filterUri);
80
81 /**
82 * Retrieves filter for given id.
83 *
84 * @param id ID of the filter
85 * @return filter
86 * @since 2.0 client, 5.0 server
87 */
88 Promise<Filter> getFilter(long id);
89 }