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 * Performs selected transition on selected issue.
83 * @param transitionsUri URI of transitions resource of selected issue. Usually obtained by calling <code>Issue.getTransitionsUri()</code>
84 * @param transitionInput data for this transition (fields modified, the comment, etc.)
85 * @param progressMonitor progress monitor
86 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
87
88 */
89 void transition(URI transitionsUri, TransitionInput transitionInput, ProgressMonitor progressMonitor);
90
91 /**
92 * Casts your vote on the selected issue. Casting a vote on already votes issue by the caller, causes the exception.
93 * @param votesUri URI of votes resource for selected issue. Usually obtained by calling <code>Issue.getVotesUri()</code>
94 * @param progressMonitor progress monitor
95 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
96 */
97 void vote(URI votesUri, ProgressMonitor progressMonitor);
98
99 /**
100 * Removes your vote from the selected issue. Removing a vote from the issue without your vote causes the exception.
101 * @param votesUri URI of votes resource for selected issue. Usually obtained by calling <code>Issue.getVotesUri()</code>
102 * @param progressMonitor progress monitor
103 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
104 */
105 void unvote(URI votesUri, ProgressMonitor progressMonitor);
106
107 /**
108 * Starts watching selected issue
109 * @param watchersUri
110 * @param progressMonitor progress monitor
111 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
112 */
113 void watch(URI watchersUri, ProgressMonitor progressMonitor);
114
115 /**
116 * Stops watching selected issue
117 * @param watchersUri
118 * @param progressMonitor progress monitor
119 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
120 */
121 void unwatch(URI watchersUri, ProgressMonitor progressMonitor);
122
123 /**
124 * Adds selected person as a watcher for selected issue. You need to have permissions to do that (otherwise
125 * the exception is thrown).
126 *
127 * @param watchersUri
128 * @param username user to add as a watcher
129 * @param progressMonitor progress monitor
130 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
131 */
132 void addWatcher(final URI watchersUri, final String username, ProgressMonitor progressMonitor);
133
134 /**
135 * Removes selected person from the watchers list for selected issue. You need to have permissions to do that (otherwise
136 * the exception is thrown).
137 *
138 * @param watchersUri
139 * @param username user to remove from the watcher list
140 * @param progressMonitor progress monitor
141 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, etc.)
142 */
143 void removeWatcher(final URI watchersUri, final String username, ProgressMonitor progressMonitor);
144
145 /**
146 * Creates link between two issues and adds a comment (optional) to the source issues.
147 *
148 * @param linkIssuesInput details for the link and the comment (optional) to be created
149 * @param progressMonitor progress monitor
150 * @throws RestClientException in case of problems (connectivity, malformed messages, invalid argument, permissions, etc.)
151 * @since client 0.2, server 4.3
152 */
153 void linkIssue(LinkIssuesInput linkIssuesInput, ProgressMonitor progressMonitor);
154
155 /**
156 * Uploads attachments to JIRA (adding it to selected issue)
157 *
158 * @param progressMonitor progress monitor
159 * @param attachmentsUri where to upload the attachment. You can get this URI by examining issue resource first
160 * @param in stream from which to read data to upload
161 * @param filename file name to use for the uploaded attachment
162 * @since client 0.2, server 4.3
163 */
164 void addAttachment(ProgressMonitor progressMonitor, URI attachmentsUri, InputStream in, String filename);
165
166 /**
167 * Uploads attachments to JIRA (adding it to selected issue)
168 *
169 * @param progressMonitor progress monitor
170 * @param attachmentsUri where to upload the attachments. You can get this URI by examining issue resource first
171 * @param attachments attachments to upload
172 * @since client 0.2, server 4.3
173 */
174 void addAttachments(ProgressMonitor progressMonitor, URI attachmentsUri, AttachmentInput ... attachments);
175
176 /**
177 * Uploads attachments to JIRA (adding it to selected issue)
178 * @param progressMonitor progress monitor
179 * @param attachmentsUri where to upload the attachments. You can get this URI by examining issue resource first
180 * @param files files to upload
181 * @since client 0.2, server 4.3
182 */
183 void addAttachments(ProgressMonitor progressMonitor, URI attachmentsUri, File... files);
184
185 /**
186 * Retrieves the content of given attachment.
187 *
188 *
189 * @param pm progress monitor
190 * @param attachmentUri URI for the attachment to retrieve
191 * @return stream from which the caller may read the attachment content (bytes). The caller is responsible for closing the stream.
192 */
193 @Beta
194 public InputStream getAttachment(ProgressMonitor pm, URI attachmentUri);
195
196 }