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