1 /*
2 * Copyright (C) 2010 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.*;
20 import com.atlassian.jira.rest.client.api.domain.input.*;
21 import com.atlassian.util.concurrent.Promise;
22 import com.google.common.annotations.Beta;
23
24 import javax.annotation.Nullable;
25 import java.io.File;
26 import java.io.InputStream;
27 import java.net.URI;
28 import java.util.Collection;
29
30 /**
31 * The com.atlassian.jira.rest.client.api handling issue resources.
32 *
33 * @since 0.1
34 */
35 public interface IssueRestClient {
36
37 /**
38 * Creates new issue.
39 *
40 * @param issue populated with data to create new issue
41 * @return basicIssue with generated <code>issueKey</code>
42 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
43 * @since com.atlassian.jira.rest.client.api 1.0, server 5.0
44 */
45 Promise<BasicIssue> createIssue(IssueInput issue);
46
47 /**
48 * Retrieves CreateIssueMetadata with specified filters.
49 *
50 * @param options optional request configuration like filters and expandos. You may use {@link GetCreateIssueMetadataOptionsBuilder} to build them. Pass <code>null</code> if you don't want to set any option.
51 * @return List of {@link CimProject} describing projects, issue types and fields.
52 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
53 * @since com.atlassian.jira.rest.client.api 1.0, server 5.0
54 */
55 Promise<Iterable<CimProject>> getCreateIssueMetadata(@Nullable GetCreateIssueMetadataOptions options);
56
57 /**
58 * Creates new issues in batch.
59 *
60 * @param issues populated with data to create new issue
61 * @return BulkOperationResult<BasicIssues> with generated <code>issueKey</code> and errors for failed issues
62 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
63 * @since com.atlassian.jira.rest.client.api 2.0, server 6.0
64 */
65
66 Promise<BulkOperationResult<BasicIssue>> createIssues(Collection<IssueInput> issues);
67
68 /**
69 * Retrieves issue with selected issue key.
70 *
71 * @param issueKey issue key (like TST-1, or JRA-9)
72 * @return issue with given <code>issueKey</code>
73 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
74 */
75 Promise<Issue> getIssue(String issueKey);
76
77 /**
78 * Retrieves issue with selected issue key, with specified additional expandos.
79 *
80 * @param issueKey issue key (like TST-1, or JRA-9)
81 * @param expand additional expands. Currently CHANGELOG is the only supported expand that is not expanded by default.
82 * @return issue with given <code>issueKey</code>
83 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
84 * @since 0.6
85 */
86 Promise<Issue> getIssue(String issueKey, Iterable<Expandos> expand);
87
88 /**
89 * Retrieves complete information (if the caller has permission) about watchers for selected issue.
90 *
91 * @param watchersUri URI of watchers resource for selected issue. Usually obtained by calling <code>Issue.getWatchers().getSelf()</code>
92 * @return detailed information about watchers watching selected issue.
93 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
94 * @see com.atlassian.jira.rest.client.api.domain.Issue#getWatchers()
95 */
96 Promise<Watchers> getWatchers(URI watchersUri);
97
98 /**
99 * Retrieves complete information (if the caller has permission) about voters for selected issue.
100 *
101 * @param votesUri URI of voters resource for selected issue. Usually obtained by calling <code>Issue.getVotesUri()</code>
102 * @return detailed information about voters of selected issue
103 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
104 * @see com.atlassian.jira.rest.client.api.domain.Issue#getVotesUri()
105 */
106 Promise<Votes> getVotes(URI votesUri);
107
108 /**
109 * Retrieves complete information (if the caller has permission) about transitions available for the selected issue in its current state.
110 *
111 * @param transitionsUri URI of transitions resource of selected issue. Usually obtained by calling <code>Issue.getTransitionsUri()</code>
112 * @return transitions about transitions available for the selected issue in its current state.
113 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
114 */
115 Promise<Iterable<Transition>> getTransitions(URI transitionsUri);
116
117 /**
118 * Retrieves complete information (if the caller has permission) about transitions available for the selected issue in its current state.
119 *
120 * @param issue issue
121 * @return transitions about transitions available for the selected issue in its current state.
122 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
123 * @since v0.5
124 */
125 Promise<Iterable<Transition>> getTransitions(Issue issue);
126
127 /**
128 * Performs selected transition on selected issue.
129 *
130 * @param transitionsUri URI of transitions resource of selected issue. Usually obtained by calling <code>Issue.getTransitionsUri()</code>
131 * @param transitionInput data for this transition (fields modified, the comment, etc.)
132 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
133 */
134 Promise<Void> transition(URI transitionsUri, TransitionInput transitionInput);
135
136 /**
137 * Performs selected transition on selected issue.
138 *
139 * @param issue selected issue
140 * @param transitionInput data for this transition (fields modified, the comment, etc.)
141 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
142 * @since v0.5
143 */
144 Promise<Void> transition(Issue issue, TransitionInput transitionInput);
145
146 /**
147 * Casts your vote on the selected issue. Casting a vote on already votes issue by the caller, causes the exception.
148 *
149 * @param votesUri URI of votes resource for selected issue. Usually obtained by calling <code>Issue.getVotesUri()</code>
150 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
151 */
152 Promise<Void> vote(URI votesUri);
153
154 /**
155 * Removes your vote from the selected issue. Removing a vote from the issue without your vote causes the exception.
156 *
157 * @param votesUri URI of votes resource for selected issue. Usually obtained by calling <code>Issue.getVotesUri()</code>
158 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
159 */
160 Promise<Void> unvote(URI votesUri);
161
162 /**
163 * Starts watching selected issue
164 *
165 * @param watchersUri URI of watchers resource for selected issue. Usually obtained by calling <code>Issue.getWatchers().getSelf()</code>
166 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
167 */
168 Promise<Void> watch(URI watchersUri);
169
170 /**
171 * Stops watching selected issue
172 *
173 * @param watchersUri URI of watchers resource for selected issue. Usually obtained by calling <code>Issue.getWatchers().getSelf()</code>
174 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
175 */
176 Promise<Void> unwatch(URI watchersUri);
177
178 /**
179 * Adds selected person as a watcher for selected issue. You need to have permissions to do that (otherwise
180 * the exception is thrown).
181 *
182 * @param watchersUri URI of watchers resource for selected issue. Usually obtained by calling <code>Issue.getWatchers().getSelf()</code>
183 * @param username user to add as a watcher
184 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
185 */
186 Promise<Void> addWatcher(final URI watchersUri, final String username);
187
188 /**
189 * Removes selected person from the watchers list for selected issue. You need to have permissions to do that (otherwise
190 * the exception is thrown).
191 *
192 * @param watchersUri URI of watchers resource for selected issue. Usually obtained by calling <code>Issue.getWatchers().getSelf()</code>
193 * @param username user to remove from the watcher list
194 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
195 */
196 Promise<Void> removeWatcher(final URI watchersUri, final String username);
197
198 /**
199 * Creates link between two issues and adds a comment (optional) to the source issues.
200 *
201 * @param linkIssuesInput details for the link and the comment (optional) to be created
202 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, permissions, etc.)
203 * @since com.atlassian.jira.rest.client.api 0.2, server 4.3
204 */
205 Promise<Void> linkIssue(LinkIssuesInput linkIssuesInput);
206
207 /**
208 * Uploads attachments to JIRA (adding it to selected issue)
209 *
210 * @param attachmentsUri where to upload the attachment. You can get this URI by examining issue resource first
211 * @param in stream from which to read data to upload
212 * @param filename file name to use for the uploaded attachment
213 * @since com.atlassian.jira.rest.client.api 0.2, server 4.3
214 */
215 Promise<Void> addAttachment(URI attachmentsUri, InputStream in, String filename);
216
217 /**
218 * Uploads attachments to JIRA (adding it to selected issue)
219 *
220 * @param attachmentsUri where to upload the attachments. You can get this URI by examining issue resource first
221 * @param attachments attachments to upload
222 * @since com.atlassian.jira.rest.client.api 0.2, server 4.3
223 */
224 Promise<Void> addAttachments(URI attachmentsUri, AttachmentInput... attachments);
225
226 /**
227 * Uploads attachments to JIRA (adding it to selected issue)
228 *
229 * @param attachmentsUri where to upload the attachments. You can get this URI by examining issue resource first
230 * @param files files to upload
231 * @since com.atlassian.jira.rest.client.api 0.2, server 4.3
232 */
233 Promise<Void> addAttachments(URI attachmentsUri, File... files);
234
235 /**
236 * Adds a comment to JIRA (adding it to selected issue)
237 *
238 * @param commentsUri where to add comment
239 * @param comment the {@link Comment} to add
240 * @since com.atlassian.jira.rest.client.api 1.0, server 5.0
241 */
242 Promise<Void> addComment(URI commentsUri, Comment comment);
243
244 /**
245 * Retrieves the content of given attachment.
246 *
247 * @param attachmentUri URI for the attachment to retrieve
248 * @return stream from which the caller may read the attachment content (bytes). The caller is responsible for closing the stream.
249 */
250 @Beta
251 Promise<InputStream> getAttachment(URI attachmentUri);
252
253 /**
254 * Adds new worklog entry to issue.
255 *
256 * @param worklogUri URI for worklog in issue
257 * @param worklogInput worklog input object to create
258 */
259 Promise<Void> addWorklog(URI worklogUri, WorklogInput worklogInput);
260
261 /**
262 * Expandos supported by {@link IssueRestClient#getIssue(String, Iterable)}
263 */
264 public enum Expandos {
265 CHANGELOG("changelog"), SCHEMA("schema"), NAMES("names"), TRANSITIONS("transitions");
266
267 private final String value;
268
269 private Expandos(String value) {
270 this.value = value;
271 }
272
273 public String getValue() {
274 return value;
275 }
276 }
277 }