Welcome to the Java SDK

About

The Quantone Java SDK makes it simple to query the Quantone API and deal with the results returned.

Calls to the Quantone API are made through query objects, which take care of all the logic involved in running a REST query, including deserializing the results to handy result objects. These can then be used to easily integrate Quantone data into your own application

Download

Please note: The Java SDK is currently in beta release. Content and functionality are likely to change significantly and without warning.

Download

The latest binaries and source code for the Quantone Java SDK are avalible from GitHub

Installation

  • Add the downloaded or compiled QuantoneSDK.jar file to your project. Refer to the documentation of your chosen IDE for more details on how to do this
  • Add the following imports to the top of any file that will use the Quantone Java SDK

import QuantoneSDK.*;
import QuantoneSDK.QuantoneObjectModel.*;
import QuantoneSDK.QuantoneQuery.*;

Querying the API

Before you can query the Quantone API, you first need to create a new Quantone object. This will be used to run all your queries. The Quantone class has a constructor that takes two arguments, your app ID and app Key. These are provided on registration.

Quantone myQuantone = new Quantone("YOUR_APP_ID", "YOUR_APP_KEY");

Each query topic has its own Query class. A full list of topics can be found in our API Reference. Lookup query classes, eg AlbumsByIdQuery, return one result and are used to find items by Quantone ID. Query classes, eg QueryAlbums, return many results and are used to search the API by parameters such as title, main artists, release date etc.

Querying works the same for all topics. First, a new instance of the class must be created. The parameters should then be filled in with the values you require. The Quantone Java SDK is code completion compatible. A full list of parameters can also be found online in our API Reference. Please note: not all parameters are currently supported by the SDK

Single Query

The following code demonstrates how to create a new AlbumsByIdQuery query to find the album with a given Quantone ID.

AlbumsByIdQuery qo = new AlbumsByIdQuery();
qo.setDepth(Arrays.asList(new AlbumRetrievalDepth[]{AlbumRetrievalDepth.ARTISTDETAILS}));
qo.setId("156dda6c-358f-e311-be87-ac220b82800d");

Search Query

The following code demonstrates how to create a new QueryAlbums query, searching for albums with the title 'Rumours' that were released in 1977.

AlbumsQuery qo = new AlbumsQuery();
qo.setTitle("Rumours");
qo.setDateReleased("1977");

Running The Query

Once the parameters you wish to search on have been set, use the Quantone.Execute(qo) method to run the query. The result object returned will correspond to the query type

AlbumsQueryResult qr = myQuantone.Execute(qo);

Dealing With Results

The result of the query is saved to the Result object in your Query object. The structure of this differs slightly for single and search queries.

Checking for Errors

Any errors that occur are thrown as a QuantoneException. It is therefore recommend to implement some form of error handling to catch these exceptions

try {
    AlbumsQueryResult qr = myQuantone.Execute(qo);
}
catch (QuantoneException ex) {
    System.out.println(ex.getMessage());
}

Single Query Result

Lookup query topics return a 'by id' query result object, e.g. a AlbumsByIdQuery would return an AlbumsByIdQueryResult. This query result object contains a single result entity. The type of this entity corresponds to the query topic, so a AlbumsByIdQuery would return an Album. The properties of this entity can then be accessed and used within your own application.

AlbumsQueryResult qr = myQuantone.Execute(qo);
Album album = qr.Result;
// Display the details of the album
System.out.println("Id: " + album.getId());
System.out.println("Title: " + album.getTitle());
System.out.println("ArtistsLiteral: " + album.getArtistsLiteral());
System.out.println("Artists: " + album.getArtists());
System.out.println("OriginalReleaseDate: " + album.getOriginalReleaseDate());
System.out.println("Format: " + album.getFormat());
System.out.println("IsLive: " + album.getIsLive());
System.out.println("IsUnofficial: " + album.getIsUnofficial());
System.out.println("Genres: " + album.getGenres());
System.out.println("ImageId: " + album.getImageId());
System.out.println("Participations: " + album.getParticipations());
System.out.println("Identifiers: " + album.getIdentifiers());
System.out.println("Recordings: " + album.getRecordings());
System.out.println("Releases: " + album.getReleases());

Search Query Result

Search queries return a query result object, e.g. a AlbumsQuery would return an AlbumsQueryResult. This query object contains an array of result entities. The type of this again corresponds to the topic, so a AlbumsQuery would return a Album[].

AlbumsByIdQueryResult qr = myQuantone.Execute(qo);
Album[] albums = qr.Result;
for (Album album : albums){ 
    // Display the details of the album
    System.out.println("Id: " + album.getId());
    System.out.println("Title: " + album.getTitle());
    System.out.println("ArtistsLiteral: " + album.getArtistsLiteral());
    System.out.println("Artists: " + album.getArtists());
    System.out.println("OriginalReleaseDate: " + album.getOriginalReleaseDate());
    System.out.println("Format: " + album.getFormat());
    System.out.println("IsLive: " + album.getIsLive());
    System.out.println("IsUnofficial: " + album.getIsUnofficial());
    System.out.println("Genres: " + album.getGenres());
    System.out.println("ImageId: " + album.getImageId());
    System.out.println("Participations: " + album.getParticipations());
    System.out.println("Identifiers: " + album.getIdentifiers());
    System.out.println("Recordings: " + album.getRecordings());
    System.out.println("Releases: " + album.getReleases());
}

Version History

Version 0.1.0

  • Supports query building and result handling for Album, Artist and Recording topics
  • Compatability with Quantone API v3

Planned Changes

Below is a list of planned changes for future releases that will likely effect the way you use the Quantone Java SDK. This list is not comprehensive and is subject to change at any time whilst the SDK is in beta release.

  • The underlying object model is currently being re-written, which may result in changes to some Query and Result objects. Expected v0.2 and upwards

Upcoming Features

Below is a list of features planned for future releases of the SDK. This list is not comprehensive. Features and estimated release versions are subject to change at any time.

  • Error codes will be added to the Error object that will be thrown to make identifying errors easier and more reliable. Estimated v0.2 - v0.3
  • Utilties for dealing with paged results. Will include functions for navigating between pages, to a specific page and returning all pages in a single object. Estimated v0.3
  • Support for Image queries and image handling helpers Estimated v0.4
  • Support for Disc Tag queries Estimated v0.4 - v0.5

Terms of Use

©Quantone Limited, 2015. May be used freely in unaltered form.

Use of the Quantone API is subject to the following end user license agreement & terms and conditions