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.Product;
7 import com.atlassian.marketplace.client.model.ProductVersion;
8
9 /**
10 * Starting point for all resources that return product information. Use
11 * {@link MarketplaceClient#products()} to access this API.
12 * <p>
13 * A "product", in this context, is an Atlassian software package that can be either purchased separately
14 * or installed into a platform instance, such as JIRA Service Desk. These are called "applications" in
15 * the user-facing UI, but that term is already used for a different purpose in the Marketplace model
16 * (see {@link Applications}).
17 *
18 * @since 2.0.0
19 */
20 public interface Products
21 {
22 /**
23 * Queries a single product.
24 * @param productKey the product's unique key
25 * @param query a {@link ProductQuery} which may contain criteria to limit the search, such as the
26 * compatible application version; use {@link ProductQuery#any()} if there are no additional criteria
27 * @return the product information, or {@link Option#none()} if there is no match
28 * @throws MpacException if the server was unavailable or returned an error
29 */
30 Option<Product> getByKey(String productKey, ProductQuery query) throws MpacException;
31
32 /**
33 * Queries a specific version of a product.
34 * @param productKey the product's unique key
35 * @param versionQuery search criteria for identifying a single version
36 * @return the product version information, or {@link Option#none()} if there is no match
37 * @throws MpacException if the server was unavailable or returned an error
38 */
39 Option<ProductVersion> getVersion(String productKey, ProductVersionSpecifier versionQuery) throws MpacException;
40
41 /**
42 * Returns a list of products.
43 * @param query a {@link ProductQuery}
44 * @return the available products
45 * @throws MpacException if the server was unavailable or returned an error
46 */
47 Page<Product> find(ProductQuery query) throws MpacException;
48 }