1 package com.atlassian.marketplace.client.api;
2
3 import java.io.File;
4
5 import com.atlassian.marketplace.client.MarketplaceClient;
6 import com.atlassian.marketplace.client.MarketplaceClientFactory;
7 import com.atlassian.marketplace.client.MpacException;
8 import com.atlassian.marketplace.client.http.HttpConfiguration;
9 import com.atlassian.marketplace.client.model.ModelBuilders;
10
11 /**
12 * Allows you to manage file-like data that can be attached to resources, such as a logo
13 * for an add-on or vendor, or an artifact for an installable add-on. Use
14 * {@link MarketplaceClient#assets()} to access this API.
15 * <p>
16 * Asset uploads are managed as follows:
17 * <ul>
18 * <li> To upload an asset, you must be authenticated as a Marketplace user (that is, when
19 * you created your client instance with {@link MarketplaceClientFactory}, you provided
20 * an {@link HttpConfiguration} with {@link HttpConfiguration.Credentials}).
21 * <li> The Marketplace server may reject uploads if you submit many of them in rapid
22 * succession.
23 * <li> If an uploaded asset is not used in any model object (for instance, if you upload
24 * a logo image, but then do not set it as the logo for an add-on or a vendor), the
25 * server will delete it after about a day.
26 * </ul>
27 * @since 2.0.0
28 */
29 public interface Assets
30 {
31 /**
32 * Uploads an add-on artifact (.jar or .obr) to the Marketplace server, which can then
33 * be used for an add-on version that you are planning to create.
34 * <p>
35 * If successful, you will receive an {@link ArtifactId}, which you can pass to
36 * {@link ModelBuilders.AddonVersionBuilder#artifact}.
37 * <p>
38 * Note that if the artifact is available online (for instance, an Atlassian Connect
39 * descriptor), you can instead use {@link ArtifactId#fromUri(java.net.URI)} to
40 * tell Marketplace where to get the artifact.
41 *
42 * @param artifactFile a local file containing the artifact
43 * @return an {@link ArtifactId} that uniquely identifies the new asset resource
44 * @throws MpacException if the server was unavailable or returned an error
45 */
46 ArtifactId uploadAddonArtifact(File artifactFile) throws MpacException;
47
48 /**
49 * Uploads an image file to the Marketplace server, which can then be used for an image
50 * property of a model object that you are planning to create or update.
51 * <p>
52 * If successful, you will receive an {@link ImageId}, which you can pass to one of the
53 * {@link ModelBuilders} methods such as {@link ModelBuilders.AddonBuilder#logo(com.atlassian.fugue.Option)}
54 * or {@link ModelBuilders.ScreenshotBuilder#image(ImageId)}.
55 * <p>
56 * Note that if the image is available online, you do not have to upload it, but can
57 * instead use {@link ImageId#fromUri(java.net.URI)} to tell Marketplace where
58 * to get the image.
59 *
60 * @param imageFile a local file containing the image data
61 * @param imageType specifies what kind of property the image will be used for; this
62 * determines how it will be scaled
63 * @return an {@link ImageId} that uniquely identifies the new asset resource
64 * @throws MpacException if the server was unavailable or returned an error
65 */
66 ImageId uploadImage(File imageFile, ImagePurpose imageType) throws MpacException;
67 }