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