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