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