1 package com.atlassian.marketplace.client.api;
2
3 import com.atlassian.fugue.Option;
4 import com.atlassian.marketplace.client.MarketplaceClient;
5 import com.atlassian.marketplace.client.MpacException;
6 import com.atlassian.marketplace.client.model.Application;
7 import com.atlassian.marketplace.client.model.ApplicationVersion;
8
9 /**
10 * Starting point for all resources that return application information. Use
11 * {@link MarketplaceClient#applications()} to access this API.
12 * <p>
13 * An "application", in this context, is a top-level Atlassian software platform such as JIRA or Confluence;
14 * software packages like JIRA Service Desk, which are called "applications" in the UI, are instead accessed
15 * through the {@link Products} API.
16 *
17 * @since 2.0.0
18 */
19 public interface Applications
20 {
21 /**
22 * Queries a single application.
23 * @param applicationKey the application's unique key
24 * @return the application information, or {@link Option#none()} if there is no match
25 * @throws MpacException if the server was unavailable or returned an error
26 */
27 Option<Application> getByKey(ApplicationKey applicationKey) throws MpacException;
28
29 /**
30 * Queries a specific version of an application.
31 * @param applicationKey the application's unique key
32 * @param versionQuery search criteria for identifying a single version
33 * @return the application version information, or {@link Option#none()} if there is no match
34 * @throws MpacException if the server was unavailable or returned an error
35 */
36 Option<ApplicationVersion> getVersion(ApplicationKey applicationKey, ApplicationVersionSpecifier versionQuery) throws MpacException;
37
38 /**
39 * Gets a list of versions for an application.
40 * @param applicationKey the application's unique key
41 * @param versionsQuery an {@link ApplicationVersionsQuery} which may contain criteria to limit the
42 * search; use {@link ApplicationVersionsQuery#any()} if there are no additional criteria
43 * @return the application versions
44 * @throws MpacException if the server was unavailable or returned an error
45 */
46 Page<ApplicationVersion> getVersions(ApplicationKey applicationKey, ApplicationVersionsQuery versionsQuery) throws MpacException;
47
48 /**
49 * Creates a new version for an existing application. Only Marketplace administrators can perform
50 * this operation.
51 * <p>
52 * Use {@link com.atlassian.marketplace.client.model.ModelBuilders#applicationVersion} to build a new
53 * {@link ApplicationVersion} object.
54 *
55 * @param applicationKey unique key of the existing application
56 * @param version the add-on version to create
57 * @return an {@link ApplicationVersion} representing the version in its initial state after being created
58 * @throws MpacException if the server was unavailable or returned an error
59 */
60 ApplicationVersion createVersion(ApplicationKey applicationKey, ApplicationVersion version) throws MpacException;
61
62 /**
63 * Attempts to modify an existing application version. Only Marketplace administrators can perform this
64 * operation. You must have already queried the current state of the version with
65 * {@link Applications#getVersion(ApplicationKey, ApplicationVersionSpecifier)};
66 * then, build another instance that includes any changes you want to make, using
67 * {@link com.atlassian.marketplace.client.model.ModelBuilders#applicationVersion(ApplicationVersion)}.
68 *
69 * @param original the existing application version
70 * @param updated a copy of the version that includes some changes
71 * @return the updated version (re-queried from the server) if successful
72 * @throws MpacException if the server was unavailable or returned an error
73 */
74 ApplicationVersion updateVersion(ApplicationVersion original, ApplicationVersion updated) throws MpacException;
75 }