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.Addon;
7 import com.atlassian.marketplace.client.model.AddonPricing;
8 import com.atlassian.marketplace.client.model.AddonReference;
9 import com.atlassian.marketplace.client.model.AddonSummary;
10 import com.atlassian.marketplace.client.model.AddonVersion;
11 import com.atlassian.marketplace.client.model.AddonVersionSummary;
12
13 /**
14 * Starting point for all resources that return add-on information. Use {@link MarketplaceClient#addons()}
15 * to access this API.
16 * @since 2.0.0
17 */
18 public interface Addons
19 {
20 /**
21 * Queries detail information for a single add-on.
22 * @param addonKey the add-on's unique key
23 * @param query an {@link AddonQuery} which may contain criteria to limit the search, such as the
24 * compatible application version; use {@link AddonQuery#any()} if there are no additional criteria
25 * @return the add-on information, or {@link Option#none()} if there is no match
26 * @throws MpacException if the server was unavailable or returned an error
27 */
28 Option<Addon> getByKey(String addonKey, AddonQuery query) throws MpacException;
29
30 /**
31 * Returns a list of add-ons.
32 * @param query an {@link AddonQuery}
33 * @return summary information for the available add-ons
34 * @throws MpacException if the server was unavailable or returned an error
35 */
36 Page<AddonSummary> find(AddonQuery query) throws MpacException;
37
38 /**
39 * Creates a new add-on listing. Assuming all properties are valid, if the add-on is private
40 * it will be created in a private state immediately; if it is public, it will be created in a "submitted"
41 * state and will not be visible until it has been approved by Atlassian.
42 * <p>
43 * Use {@link com.atlassian.marketplace.client.model.ModelBuilders#addon} to build a new
44 * {@link Addon} object. The add-on must include an initial version; to set this, use
45 * {@link com.atlassian.marketplace.client.model.ModelBuilders.AddonBuilder#version(Option)}.
46 *
47 * @param addon the add-on to create
48 * @return an {@link Addon} representing the add-on in its initial state after being created
49 * @throws MpacException if the server was unavailable or returned an error
50 */
51 Addon createAddon(Addon addon) throws MpacException;
52
53 /**
54 * Attempts to modify an existing add-on. You must have already queried the current state
55 * of the add-on with {@link Addons#getByKey(String, com.atlassian.marketplace.client.api.AddonQuery)};
56 * then, build another instance that includes any changes you want to make, using
57 * {@link com.atlassian.marketplace.client.model.ModelBuilders#addon(Addon)}.
58 *
59 * @param original the existing add-on
60 * @param updated a copy of the add-on that includes some changes
61 * @return the updated add-on (re-queried from the server) if successful
62 * @throws MpacException if the server was unavailable or returned an error
63 */
64 Addon updateAddon(Addon original, Addon updated) throws MpacException;
65
66 /**
67 * Queries one version of an add-on.
68 * @param addonKey the add-on's unique key
69 * @param version an {@link AddonVersionSpecifier} which designates either a specific
70 * version or the latest version
71 * @param query an {@link AddonVersionsQuery} which may contain criteria to limit the search, such as the
72 * compatible application version; use {@link AddonVersionsQuery#any()} if there are no additional criteria
73 * @return the add-on version information, or {@link Option#none()} if there is no match
74 * @throws MpacException if the server was unavailable or returned an error
75 */
76 Option<AddonVersion> getVersion(String addonKey, AddonVersionSpecifier version, AddonVersionsQuery query) throws MpacException;
77
78 /**
79 * Gets a list of versions for an add-on.
80 * @param addonKey the add-on's unique key
81 * @param versionsQuery an {@link AddonVersionsQuery} which may contain criteria to limit the search, such as the
82 * compatible application version; use {@link AddonVersionsQuery#any()} if there are no additional criteria
83 * @return the add-on versions
84 * @throws MpacException if the server was unavailable or returned an error
85 */
86 Page<AddonVersionSummary> getVersions(String addonKey, AddonVersionsQuery versionsQuery) throws MpacException;
87
88 /**
89 * Creates a new version for an existing add-on. Assuming all properties are valid,
90 * if the version requires approval for any reason (such as being the first paid-via-Atlassian version of
91 * a formerly free add-on, or the first Cloud version of a Server add-on) it will be created in a
92 * "submitted" state pending Atlassian approval; otherwise it will be public or private as you specified.
93 * <p>
94 * Use {@link com.atlassian.marketplace.client.model.ModelBuilders#addonVersion} to build a new
95 * {@link AddonVersion} object.
96 *
97 * @param addonKey unique key of the existing add-on
98 * @param version the add-on version to create
99 * @return an {@link AddonVersion} representing the version in its initial state after being created
100 * @throws MpacException if the server was unavailable or returned an error
101 */
102 AddonVersion createVersion(String addonKey, AddonVersion version) throws MpacException;
103
104 /**
105 * Attempts to modify an existing add-on version. You must have already queried the current state
106 * of the version with {@link Addons#getVersion(String, AddonVersionSpecifier, AddonVersionsQuery)};
107 * then, build another instance that includes any changes you want to make, using
108 * {@link com.atlassian.marketplace.client.model.ModelBuilders#addonVersion(AddonVersion)}.
109 *
110 * @param original the existing add-on version
111 * @param updated a copy of the version that includes some changes
112 * @return the updated version (re-queried from the server) if successful
113 * @throws MpacException if the server was unavailable or returned an error
114 */
115 AddonVersion updateVersion(AddonVersion original, AddonVersion updated) throws MpacException;
116
117 /**
118 * Queries the current pricing (the prices that are publicly visible on the Marketplace site) for
119 * an add-on. Returns {@code none()} if the add-on is not paid via Atlassian, is not available
120 * for the given hosting model, or has not yet been approved.
121 * @param addonKey unique key of the add-on
122 * @param pricingType specifies pricing for Cloud or Server
123 * @return the pricing, if available
124 * @throws MpacException
125 */
126 Option<AddonPricing> getPricing(String addonKey, PricingType pricingType) throws MpacException;
127
128 /**
129 * Similar to {@link #find}, but further restricts the query to add-ons that have a banner image,
130 * and returns minimal {@link AddonReference} results, whose {@link AddonReference#getImage()} method
131 * will return the banner image.
132 * @param query an {@link AddonQuery}
133 * @return a list of matching add-ons
134 * @throws MpacException if the server was unavailable or returned an error
135 */
136 Page<AddonReference> findBanners(AddonQuery query) throws MpacException;
137
138 /**
139 * Returns add-ons that Marketplace considers similar to the specified add-on in some way,
140 * optionally constrained by compatibility or other {@link AddonQuery} properties.
141 * @param addonKey the add-on's unique key
142 * @param query an {@link AddonQuery} which may contain criteria to limit the search, such as the
143 * compatible application version; use {@link AddonQuery#any()} if there are no additional criteria
144 * @return a list of recommended add-ons
145 * @throws MpacException if the server was unavailable or returned an error
146 */
147 Page<AddonReference> findRecommendations(String addonKey, AddonQuery query) throws MpacException;
148
149 /**
150 * Checks if the access token for the given add-on is valid for this application instance to use,
151 * and if so, marks it as claimed by this instance (based on the current hostname).
152 * @param addonKey the add-on's unique key
153 * @param token the license token to check
154 * @return true if the token is valid for this add-on and can be used by this instance; false otherwise
155 * @throws MpacException if the server was unavailable or returned an error
156 */
157 boolean claimAccessToken(String addonKey, String token) throws MpacException;
158 }