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