public class

AudioBoxClient

extends Object
java.lang.Object
   ↳ fm.audiobox.core.AudioBoxClient

Class Overview

AudioBoxClient is the main object of this library and allows you to perform requests and operations on AudioBox.

AudioBox let developers access to API in order to build any kind of modern applications, libraries and integrations on top of the platform.
AudioBox exposes basic and special API endpoints aimed at fast iteration of code and easiness.

All the HTTP/HTTPS are performed using the JSON data format and content type.

This library supports the OAuth2 Resource Owner Password Credentials Grant Type, thus, in order to work with it, you first need to register your application here (you need a valid AudioBox account):

https://audiobox.fm/oauth2/applications

Once you registered your application you have to properly configure the client as follows: 

 Configuration config = new Configuration()
   .setApiKey( "[Your Consumer Key]" )
   .setApiSecret( "[Your Consumer Secret]" );
Through the Configuration object you can configure many aspects of the library behaviors; some are trivial such as application name, version, etc. and other are more complex such as HttpTransport or JSON parser.

This library does not offer a data store for credentials storage out of the box. You should provide an implementation of the CredentialDataStore.
This data store should be used to store credentials so you should be really carefully with it.

To set it use the configuration: 

  config.setCredentialDataStore( new MyCredentialDataStore() );
To comply with OAuth standard you also have to provide a com.google.api.client.auth.oauth2.CredentialRefreshListener in order to keep tokens up to date. 
   config.setCredentialRefreshListener( new MyCredentialRefreshListener() );
Since this library wants to be as much agnostic as possible regarding the HTTP client and the JSON parser libraries you should set them at this moment by choosing amongst:

  • NetHttpTransport: based on HttpURLConnection that is found in all Java SDKs, and thus usually the simplest choice.
  • ApacheHttpTransport: based on the popular Apache HttpClient that allows for more customization.
  • UrlFetchTransport: based on URL Fetch Java API in the Google App Engine SDK

as HTTP transport, and:

  • JacksonFactory: based on the popular Jackson library which is considered the fastest in terms of parsing/serialization speed
  • GsonFactory: based on the Google GSON library which is a lighter-weight option (small size) that is pretty fast also (though not quite as fast as Jackson)
  • AndroidJsonFactory: based on the JSON library built-in to Android Honeycomb (SDK 3.0) or higher that is identical to the Google GSON library

as JSON parser library.

There are no defaults that's why you must provide them through the configuration: 

  config
    .setHttpTransport( new NetHttpTransport() )
    .setJsonFactory( new JacksonFactory() );

This is the basic configuration and once the setup is completed you can create your Client, authorize the application and start performing any kind of operation supported by AudioBox API through it: 

   Client client = new Client( config );
   client.authorize( "username", "password" );
   List<Playlist> playlists = client.getPlaylists();
   ...

NOTE: authorize(String, String) is only needed once to get and store the OAuth2 grant token; password is never (and it never should be) stored.

NOTE: grant tokens may expires at any time. A request against AudioBox with an expired token will result in an AuthorizationException. Your application should be ready to trap it in order to present a new login form.

NOTE: most of the methods of this library performs requests against AudioBox services. In order to avoid too many requests is highly recommended to implement some sort of caching system (memory or persisted).

For a complete list of API endpoints you can consult the AudioBox API handbook at this address:

http://audiobox.fm/apidocs

Summary

Constants
String ACCOUNT_TOKENS The key under which tokens are stored in the DataStore
Public Constructors
AudioBoxClient(Configuration conf)
Instantiates a new Client.
Public Methods
synchronized TokenResponse authorize(String username, String password, boolean relaunchExceptions)
Starts the authorization flow.
TokenResponse authorize(String username, String password)
Starts the authorization flow.
HttpResponse doDELETE(String path)
Performs signed DELETE requests to the given path.
HttpResponse doDELETE(String path, JsonObjectParser parser, HttpHeaders headers)
Performs signed DELETE requests to the given path.
HttpResponse doGET(String path)
Performs signed GET requests and returns the response.
HttpResponse doGET(String path, JsonObjectParser parser, HttpHeaders headers)
Performs signed GET requests and returns the response.
HttpResponse doPOST(String path, HttpContent data)
Performs signed POST requests and returns the response.
HttpResponse doPOST(String path)
Performs signed POST requests and returns the response.
HttpResponse doPOST(String path, HttpContent data, JsonObjectParser parser, HttpHeaders headers)
Performs signed POST requests and returns the response.
HttpResponse doPUT(String path, HttpContent data, JsonObjectParser parser, HttpHeaders headers)
Performs signed PUT requests and returns the response.
HttpResponse doPUT(String path, HttpContent data)
Performs signed PUT requests and returns the response.
HttpResponse doRequest(String method, String path, HttpContent data, JsonObjectParser parser, HttpHeaders headers)
Executes the configured request by calling AudioBox API services.
synchronized HttpResponse doRequestToChannel(String method, String path, HttpContent data, JsonObjectParser parser, Configuration.Channels channel, HttpHeaders headers)
Executes the configured request by calling AudioBox API services.
Configuration getConf()
Gets the global client configuration.
HttpHeaders getDefaultHeaders()
Gets global request headers
Notifications getNotifications()
Gets user's notifications.
Playlist getPlaylist(String token)
Gets the token-specified playlist.
List<Playlist> getPlaylists()
Gets user's playlists.
User getUser()
Returns information about the authorized user.
boolean isDaemonRunning()
This method returns true if AudioBox Desktop application is active on any computer.
Upload newUpload(File file, NetworkProgressListener listener)
Builds a new Upload ready to start.
Upload newUpload(File file)
Builds a new Upload ready to start.
String remoteDaemonIp()
This methods returns the remote ip address of AudioBox Desktop application
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACCOUNT_TOKENS

The key under which tokens are stored in the DataStore

Constant Value: "_audiobox_account_tokens"

Public Constructors

public AudioBoxClient (Configuration conf)

Instantiates a new Client.

Parameters
conf the conf
Throws
ConfigurationException the configuration exception
IOException if any problem occurs with the configured data store factory

Public Methods

public synchronized TokenResponse authorize (String username, String password, boolean relaunchExceptions)

Starts the authorization flow.

Given a username and a password if the request succeed this method will store the grant token for future requests and return the response.

Parameters
username the username
password the password
relaunchExceptions whether or not relaunch possible exceptions.
Returns
  • the token response, may be null
Throws
AuthorizationException in case the authorization fails.
IOException if any connection or configured data store problems occurs.

public TokenResponse authorize (String username, String password)

Starts the authorization flow.

Given a username and a password if the request succeed this method will store the grant token for future requests and return the response.

Parameters
username the username
password the password
Returns
  • the token response, may be null
Throws
AuthorizationException in case the authorization fails.
IOException if any connection or configured data store problems occurs.

public HttpResponse doDELETE (String path)

Performs signed DELETE requests to the given path.

Parameters
path the AudioBox API path where to make the request to.
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public HttpResponse doDELETE (String path, JsonObjectParser parser, HttpHeaders headers)

Performs signed DELETE requests to the given path.

Parameters
path the AudioBox API path where to make the request to.
parser the com.google.api.client.json.JsonObjectParser to use to parse the response.
headers additional request headers
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public HttpResponse doGET (String path)

Performs signed GET requests and returns the response.

Parameters
path the AudioBox API path where to make the request to.
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public HttpResponse doGET (String path, JsonObjectParser parser, HttpHeaders headers)

Performs signed GET requests and returns the response.

Parameters
path the AudioBox API path where to make the request to.
parser the com.google.api.client.json.JsonObjectParser to use to parse the response.
headers additional request headers
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public HttpResponse doPOST (String path, HttpContent data)

Performs signed POST requests and returns the response.

Parameters
path the AudioBox API path where to make the request to.
data the data to send with the request
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public HttpResponse doPOST (String path)

Performs signed POST requests and returns the response.

Parameters
path the AudioBox API path where to make the request to.
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public HttpResponse doPOST (String path, HttpContent data, JsonObjectParser parser, HttpHeaders headers)

Performs signed POST requests and returns the response.

Parameters
path the AudioBox API path where to make the request to.
data the data to send with the request
parser the com.google.api.client.json.JsonObjectParser to use to parse the response.
headers additional request headers
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public HttpResponse doPUT (String path, HttpContent data, JsonObjectParser parser, HttpHeaders headers)

Performs signed PUT requests and returns the response.

Parameters
path the AudioBox API path where to make the request to.
data the data to send with the request
parser the com.google.api.client.json.JsonObjectParser to use to parse the response.
headers additional request headers
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public HttpResponse doPUT (String path, HttpContent data)

Performs signed PUT requests and returns the response.

Parameters
path the AudioBox API path where to make the request to.
data the data to send with the request
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public HttpResponse doRequest (String method, String path, HttpContent data, JsonObjectParser parser, HttpHeaders headers)

Executes the configured request by calling AudioBox API services.

Parameters
method the method to use
path the AudioBox API path where to make the request to.
data the data to send with the request
parser the parser to use for the resulting object
headers additional request headers
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public synchronized HttpResponse doRequestToChannel (String method, String path, HttpContent data, JsonObjectParser parser, Configuration.Channels channel, HttpHeaders headers)

Executes the configured request by calling AudioBox API services.

Parameters
method the method to use
path the AudioBox API path where to make the request to.
data the data to send with the request
parser the parser to use for the resulting object
channel the Channel to query
headers additional request headers
Returns
  • the http response, may be null if any error occurs during the request.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public Configuration getConf ()

Gets the global client configuration.

Returns
  • the configuration

public HttpHeaders getDefaultHeaders ()

Gets global request headers

Returns
  • the default headers

public Notifications getNotifications ()

Gets user's notifications.

Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public Playlist getPlaylist (String token)

Gets the token-specified playlist. Triggers Smart Playlist compilation if the requested playlist is a SmartPlaylist.
NOTE: this method will always perform a request against AudioBox servers, for this reason be smart and try to apply some sort of cache strategy.

Parameters
token the token of the playlist to get.
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public List<Playlist> getPlaylists ()

Gets user's playlists.

Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public User getUser ()

Returns information about the authorized user.
NOTE: this method always performs a request, use it wisely

Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public boolean isDaemonRunning ()

This method returns true if AudioBox Desktop application is active on any computer.

Returns
  • true if AudioBox Desktop application is active on any computer. false if not
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public Upload newUpload (File file, NetworkProgressListener listener)

Builds a new Upload ready to start.

Parameters
file the file to upload on AudioBox
listener the NetworkProgressListener for progress monitoring
Returns

public Upload newUpload (File file)

Builds a new Upload ready to start.

You can still set a listener with setListener(fm.audiobox.core.net.NetworkProgressListener)

Parameters
file the file to upload on AudioBox
Returns

public String remoteDaemonIp ()

This methods returns the remote ip address of AudioBox Desktop application

Returns
  • the remote ip address
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also