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