1 package com.atlassian.marketplace.client;
2
3 import java.io.Closeable;
4
5 import com.atlassian.marketplace.client.api.AddonCategories;
6 import com.atlassian.marketplace.client.api.Addons;
7 import com.atlassian.marketplace.client.api.Applications;
8 import com.atlassian.marketplace.client.api.Assets;
9 import com.atlassian.marketplace.client.api.LicenseTypes;
10 import com.atlassian.marketplace.client.api.Page;
11 import com.atlassian.marketplace.client.api.PageReference;
12 import com.atlassian.marketplace.client.api.Products;
13 import com.atlassian.marketplace.client.api.Vendors;
14 import com.atlassian.marketplace.client.http.HttpTransport;
15 import com.atlassian.marketplace.client.model.Links;
16
17 /**
18 * Client interface for the Atlassian Marketplace 2.0 API.
19 * <p>
20 * Construct a concrete implementation of the client ({@link com.atlassian.marketplace.client.impl.DefaultMarketplaceClient})
21 * and use that instance for all API requests.
22 */
23 public interface MarketplaceClient extends Closeable
24 {
25 /**
26 * Checks whether the MPAC service is available, by attempting to get the root resource.
27 *
28 * @return true if the request was successful; false if it failed for any reason
29 */
30 public boolean isReachable();
31
32 /**
33 * Returns an API object that provides access to add-on listings.
34 */
35 public Addons addons() throws MpacException;
36
37 /**
38 * Returns an API object that provides access to add-on categories.
39 */
40 public AddonCategories addonCategories() throws MpacException;
41
42 /**
43 * Returns an API object that provides access to application listings.
44 */
45 public Applications applications() throws MpacException;
46
47 /**
48 * Returns an API object that provides file uploading capabilities.
49 */
50 public Assets assets() throws MpacException;
51
52 /**
53 * Returns an API object that provides access to software license types.
54 */
55 public LicenseTypes licenseTypes() throws MpacException;
56
57 /**
58 * Returns an API object that provides access to product listings (which are called "applications" in the administrative UI).
59 */
60 public Products products() throws MpacException;
61
62 /**
63 * Returns an API object that provides access to vendors.
64 */
65 public Vendors vendors() throws MpacException;
66
67 /**
68 * Queries a page of a result set from a previous query, for any resource that provides paginated
69 * results (such as {@link Addons#find}). The {@link PageReference} is obtained by calling
70 * {@link Page#getPrevious()}, {@link Page#getNext()}, or {@link Page#getReference()} on an existing
71 * {@link Page} of results.
72 * @return a {@link Page} containing the results
73 * @throws MpacException if the server was unavailable or returned an error
74 */
75 public <T> Page<T> getMore(PageReference<T> ref) throws MpacException;
76
77 /**
78 * Returns the top-level API resource links, such as "addons". <tt>MarketplaceClient</tt>
79 * normally traverses these links automatically; you should only need to use this method if
80 * you are passing a URL outside of Java code, for instance to a front-end script.
81 * @return a {@link Links} object
82 * @throws MpacException if the server was unavailable or returned an error
83 */
84 public Links getRootLinks() throws MpacException;
85
86 /**
87 * Provides access to the underlying HTTP transport mechanism. This allows for
88 * implementation of extension modules for Marketplace APIs that are not supported
89 * by the base library.
90 */
91 public HttpTransport getHttp();
92
93 /**
94 * Attempts to convert the specified model object to a JSON string. This should be used only for
95 * testing purposes; normally, JSON serialization is done automatically within client methods.
96 * @param entity a model object
97 * @return a JSON string
98 * @throws MpacException if the object could not be serialized as JSON (for instance, because it
99 * is not an instance of any of this library's model classes)
100 */
101 public <T> String toJson(T entity) throws MpacException;
102
103 /**
104 * Should be called when finished with client to release resources.
105 */
106 void close();
107 }