fm.audiobox.core

Class AudioBoxClient

java.lang.Object

fm.audiobox.core.AudioBoxClient

public class AudioBoxClient
extends java.lang.Object

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 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

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ACCOUNT_TOKENS The key under which tokens are stored in the DataStore

Constructor Summary

Constructors

Constructor and Description
AudioBoxClient(Configuration conf) Instantiates a new Client.

Method Summary

Methods

Modifier and Type	Method and Description
com.google.api.client.auth.oauth2.TokenResponse	authorize(java.lang.String username, java.lang.String password) Starts the authorization flow.
com.google.api.client.auth.oauth2.TokenResponse	authorize(java.lang.String username, java.lang.String password, boolean relaunchExceptions) Starts the authorization flow.
com.google.api.client.http.HttpResponse	doDELETE(java.lang.String path) Performs signed DELETE requests to the given path.
com.google.api.client.http.HttpResponse	doDELETE(java.lang.String path, com.google.api.client.json.JsonObjectParser parser, com.google.api.client.http.HttpHeaders headers) Performs signed DELETE requests to the given path.
com.google.api.client.http.HttpResponse	doGET(java.lang.String path) Performs signed GET requests and returns the response.
com.google.api.client.http.HttpResponse	doGET(java.lang.String path, com.google.api.client.json.JsonObjectParser parser, com.google.api.client.http.HttpHeaders headers) Performs signed GET requests and returns the response.
com.google.api.client.http.HttpResponse	doPOST(java.lang.String path) Performs signed POST requests and returns the response.
com.google.api.client.http.HttpResponse	doPOST(java.lang.String path, com.google.api.client.http.HttpContent data) Performs signed POST requests and returns the response.
com.google.api.client.http.HttpResponse	doPOST(java.lang.String path, com.google.api.client.http.HttpContent data, com.google.api.client.json.JsonObjectParser parser, com.google.api.client.http.HttpHeaders headers) Performs signed POST requests and returns the response.
com.google.api.client.http.HttpResponse	doPUT(java.lang.String path, com.google.api.client.http.HttpContent data) Performs signed PUT requests and returns the response.
com.google.api.client.http.HttpResponse	doPUT(java.lang.String path, com.google.api.client.http.HttpContent data, com.google.api.client.json.JsonObjectParser parser, com.google.api.client.http.HttpHeaders headers) Performs signed PUT requests and returns the response.
com.google.api.client.http.HttpResponse	doRequest(java.lang.String method, java.lang.String path, com.google.api.client.http.HttpContent data, com.google.api.client.json.JsonObjectParser parser, com.google.api.client.http.HttpHeaders headers) Executes the configured request by calling AudioBox API services.
com.google.api.client.http.HttpResponse	doRequestToChannel(java.lang.String method, java.lang.String path, com.google.api.client.http.HttpContent data, com.google.api.client.json.JsonObjectParser parser, Configuration.Channels channel, com.google.api.client.http.HttpHeaders headers) Executes the configured request by calling AudioBox API services.
Configuration	getConf() Gets the global client configuration.
com.google.api.client.http.HttpHeaders	getDefaultHeaders() Gets global request headers
Notifications	getNotifications() Gets user's notifications.
Playlist	getPlaylist(java.lang.String token) Gets the token-specified playlist.
java.util.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(java.io.File file) Builds a new Upload ready to start.
Upload	newUpload(java.io.File file, NetworkProgressListener listener) Builds a new Upload ready to start.
java.lang.String	remoteDaemonIp() This methods returns the remote ip address of AudioBox Desktop application

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ACCOUNT_TOKENS

public static final java.lang.String ACCOUNT_TOKENS

The key under which tokens are stored in the DataStore

See Also:

Constant Field Values

Constructor Detail

AudioBoxClient

public AudioBoxClient(Configuration conf)
               throws ConfigurationException,
                      java.io.IOException

Instantiates a new Client.

Parameters:

conf - the conf

Throws:

ConfigurationException - the configuration exception

java.io.IOException - if any problem occurs with the configured data store factory

Method Detail

getConf

public Configuration getConf()

Gets the global client configuration.

Returns:

the configuration

getDefaultHeaders

public com.google.api.client.http.HttpHeaders getDefaultHeaders()

Gets global request headers

Returns:

the default headers

authorize

public com.google.api.client.auth.oauth2.TokenResponse authorize(java.lang.String username,
                                                        java.lang.String password)
                                                          throws java.io.IOException

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.

java.io.IOException - if any connection or configured data store problems occurs.

authorize

public com.google.api.client.auth.oauth2.TokenResponse authorize(java.lang.String username,
                                                        java.lang.String password,
                                                        boolean relaunchExceptions)
                                                          throws java.io.IOException

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.

java.io.IOException - if any connection or configured data store problems occurs.

isDaemonRunning

public boolean isDaemonRunning()
                        throws java.io.IOException

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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

remoteDaemonIp

public java.lang.String remoteDaemonIp()
                                throws java.io.IOException

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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

getUser

public User getUser()
             throws java.io.IOException

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

Returns:

the user

Throws:

AudioBoxException - if any of the remote error exception is detected.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

getPlaylists

public java.util.List<Playlist> getPlaylists()
                                      throws java.io.IOException

Gets user's playlists.

Returns:

a List of playlists

Throws:

AudioBoxException - if any of the remote error exception is detected.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

getPlaylist

public Playlist getPlaylist(java.lang.String token)
                     throws java.io.IOException

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:

the specified playlist

Throws:

AudioBoxException - if any of the remote error exception is detected.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

getNotifications

public Notifications getNotifications()
                               throws java.io.IOException

Gets user's notifications.

Returns:

the notifications

Throws:

AudioBoxException - if any of the remote error exception is detected.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

newUpload

public Upload newUpload(java.io.File file)

Builds a new Upload ready to start.

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

Parameters:

file - the file to upload on AudioBox

Returns:

a Upload ready to Upload.start()

newUpload

public Upload newUpload(java.io.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:

a Upload ready to Upload.start()

doGET

public com.google.api.client.http.HttpResponse doGET(java.lang.String path)
                                              throws java.io.IOException

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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doGET

public com.google.api.client.http.HttpResponse doGET(java.lang.String path,
                                            com.google.api.client.json.JsonObjectParser parser,
                                            com.google.api.client.http.HttpHeaders headers)
                                              throws java.io.IOException

Performs signed GET requests and returns the response.

Parameters:

path - the AudioBox API path where to make the request to.

parser - the 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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doPUT

public com.google.api.client.http.HttpResponse doPUT(java.lang.String path,
                                            com.google.api.client.http.HttpContent data)
                                              throws java.io.IOException

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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doPUT

public com.google.api.client.http.HttpResponse doPUT(java.lang.String path,
                                            com.google.api.client.http.HttpContent data,
                                            com.google.api.client.json.JsonObjectParser parser,
                                            com.google.api.client.http.HttpHeaders headers)
                                              throws java.io.IOException

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 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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doDELETE

public com.google.api.client.http.HttpResponse doDELETE(java.lang.String path)
                                                 throws java.io.IOException

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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doDELETE

public com.google.api.client.http.HttpResponse doDELETE(java.lang.String path,
                                               com.google.api.client.json.JsonObjectParser parser,
                                               com.google.api.client.http.HttpHeaders headers)
                                                 throws java.io.IOException

Performs signed DELETE requests to the given path.

Parameters:

path - the AudioBox API path where to make the request to.

parser - the 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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doPOST

public com.google.api.client.http.HttpResponse doPOST(java.lang.String path)
                                               throws java.io.IOException

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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doPOST

public com.google.api.client.http.HttpResponse doPOST(java.lang.String path,
                                             com.google.api.client.http.HttpContent data)
                                               throws java.io.IOException

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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doPOST

public com.google.api.client.http.HttpResponse doPOST(java.lang.String path,
                                             com.google.api.client.http.HttpContent data,
                                             com.google.api.client.json.JsonObjectParser parser,
                                             com.google.api.client.http.HttpHeaders headers)
                                               throws java.io.IOException

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 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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doRequest

public com.google.api.client.http.HttpResponse doRequest(java.lang.String method,
                                                java.lang.String path,
                                                com.google.api.client.http.HttpContent data,
                                                com.google.api.client.json.JsonObjectParser parser,
                                                com.google.api.client.http.HttpHeaders headers)
                                                  throws java.io.IOException

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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException

doRequestToChannel

public com.google.api.client.http.HttpResponse doRequestToChannel(java.lang.String method,
                                                         java.lang.String path,
                                                         com.google.api.client.http.HttpContent data,
                                                         com.google.api.client.json.JsonObjectParser parser,
                                                         Configuration.Channels channel,
                                                         com.google.api.client.http.HttpHeaders headers)
                                                           throws java.io.IOException

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.

java.io.IOException - if any connection problem occurs.

See Also:

AudioBoxException