Searching for apps from Java

The Marketplace API Java client lets you query app listings through the Addons API.

For a stand-alone demo, see ListAddons.java in the Marketplace API Tutorials repository.

Prerequisites

You will need:

  • A Java project that uses the marketplace-client-java library
  • MarketplaceClient object. It does not require credentials, but you may wish to configure it with your Atlassian account credentials if you want your queries to include private apps or private app versions.

Step 1: Build an app query

The AddonQuery class contains all the optional properties for specifying which apps you are interested in. If you want all apps, use the special value AddonQuery.any(). Otherwise, use AddonQuery.builder() to construct a query. Below are some example queries:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// A query for all apps that are compatible with Jira
AddonQuery myQuery = AddonQuery.builder()
    .application(Option.some(ApplicationKey.JIRA))
    .build());

// A query for all apps that are compatible with Jira - will only return the first 5 results
AddonQuery myQuery = AddonQuery.builder()
    .application(Option.some(ApplicationKey.JIRA))
    .limit(Option.some(5))
    .build();

// A query for all paid via Atlassian apps that are compatible with Jira Server 7.1.0
AddonQuery myQuery = AddonQuery.builder()
    .application(Option.some(ApplicationKey.JIRA))
    .appBuildNumber(Option.some(71003))  // this is the build number for Jira 7.1.0
    .cost(Option.some(Cost.PAID_VIA_ATLASSIAN))
    .hosting(Option.some(HostingType.SERVER))
    .build();

For more details on all of the supported properties in AddonQuery, see the full API documentation.

Step 2: Perform the query

The find method in the Addons API sends the query to Marketplace, and returns a Page object that represents the result set:

1
Page<AddonSummary> results = client.addons().find(myQuery);

Step 3: Process results

Page implements Iterable, so you can easily loop through the items in it as you would with any Java collection. For instance, this example prints the name of each app to the console:

1
2
3
for (AddonSummary a: results) {
    System.out.println(a.getName());
}

Tthe individual items are instances of AddonSummary, which is like Addon but does not include every app property; if you want the full app details, you will need to do an app detail query.

Step 4: Handle multiple pages of results

As the name implies, a Page is not necessarily the full result set, but rather a single page of results. The default size of a page is 10, but you can specify a different number using limit as shown in Step 1 (up to a maximum of 50). If there are more results than will fit on one page, the size() method will tell you how many results are in the current page, and totalSize() will tell you how many results matched the query in general:

1
2
System.out.println("Total number of apps found: " + results.totalSize());
System.out.println("Number of apps on this page: " + results.size());

If you want to read through every app in the full result set one page at a time, then use the getNext() method. This returns an Option containing a PageReference value which you can pass to the getMore() method to get the next page (or none() if you are on the last page):

1
2
3
4
5
6
7
8
9
10
for (Option<PageReference<AddonSummary>> nextPage = results.getNext();
     nextPage.isDefined(); nextPage = results.getNext()) {
    // Since Option implements Iterable, we can use "for" to execute this code only if it has a value
    for (PageReference<AddonSummary> nextRef: nextPage) {
        results = client.getMore(nextRef);
        for (AddonSummary a: results) {
            System.out.println(a.getName());
        }
    }
}