This library is not yet ready for production. It is actually under heavy development and still requires some refactor. It does not work on the actual API specifications, if you need a java library that works with the actual API please use the old AudioBox.fm-JavaLib.

audiobox-jlib is a simple library to control AudioBox account through its powerful API.

• Java 1.8
• Android Build Tools 19+ (for android projects)

• You can choose amongst 3 HTTP Transport out of the box and if you are not happy you can implement your own.
• You can choose amongst 3 JSON parser (Jackson, Guava, AndroidJsonFactory)
• Transparent OAuth2 authorization flow
• Easy to use

• SLF4J 1.7 (logging)
• Typesafe Config 1.3.0 (configuration)
• Google HTTP Java Client 1.21 (HTTP layer)
• Google OAuth Java Client 1.21 (OAuth2 layer)
• Apache Common Validator 1.5 (Utils)
• Apache Commons Lang 3.4 (Utils)
• Java Object Diff 0.93.2 (Utils)

If your project is under maven add this under the dependency management section:

<dependency>
  <groupId>fm.audiobox</groupId>
  <artifactId>audiobox-jlib</artifactId>
  <version>1.0.5</version>
</dependency>

If your project uses gradle add this line in your dependency clojure:

dependencies {
  ...
  compile 'fm.audiobox:audiobox-jlib:1.0.5'
  ...
}

Alternatively add this jar to your project classpath.

1. Subscribe an AudioBox account here.
2. Register your application here.
3. Take note of the API Consumer Key and Consumer Secret.

Now that you have all needed pieces you have to configure your client before making any operation:

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 is 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() );

We just gone through the basic configuration and once the setup is completed you can create your AudioBoxClient, but we still need to authorize the application to start performing any kind of operation supported by AudioBox API:

AudioBoxClient client = new AudioBoxClient( config );
client.authorize( "username", "password" );
...

When the application is successfully authorized a grant token is stored in the configured data store. Keep in mind that 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.

Now that the client is configured and authorized we can browse and perform any API-supported operation on AudioBox:

Get user information:

client.getUser();

Get user's playlists:

client.getPlaylists();

Or some other MediaFile operation:

// Load playlists
List<Playlist> playlists = client.getPlaylists();
Playlist p = playlists.get(0);

// Load media files
List<MediaFile> mfs = p.getMediaFiles(client);
MediaFile m = mfs.get(0);

// Edit some label
m.setTitle("foo");
m.setArtist("bar");

// Save modifications
m.update(client);

To know more about this library checkout the JavaDoc.

• AudioBox for Android

• Get familiar with the philosophy of the library design.
• Check for open issues or open a new issue to fill a bug or a feature request.
• Fork the audiobox-jlib on Github and make your changes.
• Write some tests which show that the bug was fixed or that the feature works as expected.
• Send a pull request to get changes merged and published.

To generate test coverage report run

gradle test jacocoTestReport

To generate JDoc run

gradle generateDoclava