1 /*
2 * Copyright (C) 2011 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.Version;
20 import com.atlassian.jira.rest.client.domain.VersionRelatedIssuesCount;
21 import com.atlassian.jira.rest.client.domain.input.VersionInput;
22 import com.atlassian.jira.rest.client.domain.input.VersionPosition;
23
24 import javax.annotation.Nullable;
25 import java.net.URI;
26
27 /**
28 * The client responsible for Project version(s) related operations
29 *
30 * @since 0.3 client, 4.4 server
31 */
32 public interface VersionRestClient {
33
34 /**
35 * Retrieves full information about selected project version
36 *
37 * @param versionUri URI of the version to retrieve. You can get it for example from Project or it can be
38 * referenced from an issue.
39 * @param progressMonitor progress monitor
40 * @return full information about selected project version
41 * @throws RestClientException in case of problems (connectivity, malformed messages, etc.)
42 */
43 Version getVersion(URI versionUri, ProgressMonitor progressMonitor);
44
45 /**
46 * Creates a new version (which logically belongs to a project)
47 *
48 * @param version details about version to create
49 * @param progressMonitor progress monitor
50 * @return newly created version
51 * @throws RestClientException in case of problems (connectivity, malformed messages, etc.)
52 */
53 Version createVersion(VersionInput version, ProgressMonitor progressMonitor);
54
55 /**
56 * Updates selected version with a new details.
57 *
58 * @param versionUri full URI to the version to update
59 * @param versionInput new details of the version. <code>null</code> fields will be ignored
60 * @param progressMonitor progress monitor
61 * @return newly updated version
62 * @throws RestClientException in case of problems (connectivity, malformed messages, etc.)
63 */
64 Version updateVersion(URI versionUri, VersionInput versionInput, ProgressMonitor progressMonitor);
65
66 /**
67 * Removes selected version optionally changing Fix Version(s) and/or Affects Version(s) fields of related issues.
68 *
69 * @param versionUri full URI to the version to remove
70 * @param moveFixIssuesToVersionUri URI of the version to which issues should have now set their Fix Version(s)
71 * field instead of the just removed version. Use <code>null</code> to simply clear Fix Version(s) in all those issues
72 * where the version removed was referenced.
73 * @param moveAffectedIssuesToVersionUri URI of the version to which issues should have now set their Affects Version(s)
74 * field instead of the just removed version. Use <code>null</code> to simply clear Affects Version(s) in all those issues
75 * where the version removed was referenced.
76 * @param progressMonitor progress monitor
77 * @throws RestClientException in case of problems (connectivity, malformed messages, etc.)
78 */
79 void removeVersion(URI versionUri, @Nullable URI moveFixIssuesToVersionUri,
80 @Nullable URI moveAffectedIssuesToVersionUri, ProgressMonitor progressMonitor);
81
82 /**
83 * Retrieves basic statistics about issues which have their Fix Version(s) or Affects Version(s) field
84 * pointing to given version.
85 *
86 * @param versionUri full URI to the version you want to get related issues count for
87 * @param progressMonitor progress monitor
88 * @throws RestClientException in case of problems (connectivity, malformed messages, etc.)
89 * @return basic stats about issues related to given version
90 */
91 VersionRelatedIssuesCount getVersionRelatedIssuesCount(URI versionUri, ProgressMonitor progressMonitor);
92
93 /**
94 * Retrieves number of unresolved issues which have their Fix Version(s) field
95 * pointing to given version.
96 *
97 * @param versionUri full URI to the version you want to get the number of unresolved issues for
98 * @param progressMonitor progress monitor
99 * @throws RestClientException in case of problems (connectivity, malformed messages, etc.)
100 * @return number of unresolved issues having this version included in their Fix Version(s) field.
101 */
102 int getNumUnresolvedIssues(URI versionUri, ProgressMonitor progressMonitor);
103
104 /**
105 * Moves selected version after another version. Ordering of versions is important on various reports and whenever
106 * input version fields are rendered by JIRA.
107 * If version is already immediately after the other version (defined by <code>afterVersionUri</code>) then
108 * such call has no visual effect.
109 *
110 * @param versionUri full URI to the version to move
111 * @param afterVersionUri URI of the version to move selected version after
112 * @param progressMonitor progress monitor
113 * @throws RestClientException in case of problems (connectivity, malformed messages, etc.)
114 * @return just moved version
115 */
116 Version moveVersionAfter(URI versionUri, URI afterVersionUri, ProgressMonitor progressMonitor);
117
118 /**
119 * Moves selected version to another position.
120 * If version already occupies given position (e.g. is the last version and we want to move to a later position or to the last position)
121 * then such call does not change anything.
122 *
123 * @param versionUri full URI to the version to move
124 * @param versionPosition defines a new position of selected version
125 * @param progressMonitor progress monitor
126 * @throws RestClientException in case of problems (connectivity, malformed messages, etc.)
127 * @return just moved version
128 */
129 Version moveVersion(URI versionUri, VersionPosition versionPosition, ProgressMonitor progressMonitor);
130
131 }