MusicBrainz API Client

A Java 8+ wrapper library for MusicBrainz web service API (version 2).

API Reference

Usage

First you need to create an instance of a MusicBrainzClient. The following will create a new musicbrainz client with a Jersey backend:

MusicBrainzClient client = MusicBrainzJerseyClient.createWithDefaults();

Lookup requests

Synchronous request:

Artist artist = client.artist()
        .withId(UUID.fromString("8e66ea2b-b57b-47d9-8df0-df4630aeb8e5"))
        .lookup()
        .get(); 
System.out.println(artist);

Asynchronous request with callback:

client.artist()
        .withId(UUID.fromString("1127ddc2-eab3-4662-8718-6adbdeea3b10"))
        .lookupAsync(new MusicBrainzRequestCallbackAdapter<Artist>() {
            @Override
            public void onSuccess(@NotNull Artist artist) {
                System.out.println(artist);
            }
        });

Asynchronous request with CompletableFuture:

client.artist()
        .withId(UUID.fromString("1127ddc2-eab3-4662-8718-6adbdeea3b10"))
        .lookupAsync()
        .thenApply(MusicBrainzResponse::get)
        .thenAccept(System.out::println);

Browse requests

Synchronous request:

List<Artist> artists = client.artist()
        .withAreaId(UUID.fromString("1127ddc2-eab3-4662-8718-6adbdeea3b10"))
        .browse()
        .get(); 
System.out.println(artists.size());

Asynchronous request with callback:

client.artist()
        .withAreaId(UUID.fromString("1127ddc2-eab3-4662-8718-6adbdeea3b10"))
        .browseAsync(new MusicBrainzRequestCallbackAdapter<List<Artist>>() {
            @Override
            public void onSuccess(@NotNull List<Artist> artists) {
                System.out.println(artists.size());
            }
        });

Asynchronous chunked requests with callback:

Chunked requests periodically fetch chunks of data until all data that's available have been fetched. The callback is invoked one or more times.

client.artist()
        .withAreaId(UUID.fromString("1127ddc2-eab3-4662-8718-6adbdeea3b10"))
        .browseChunksAsync(new MusicBrainzRequestCallbackAdapter<List<Artist>>() {
            @Override
            public void onSuccess(@NotNull List<Artist> artists) {
                System.out.println(artists.size());
            }
        });

Asynchronous request with CompletableFuture:

client.artist()
        .withAreaId(UUID.fromString("1127ddc2-eab3-4662-8718-6adbdeea3b10"))
        .browseAsync()
        .thenApply(MusicBrainzResponse::get)
        .thenApply(List::size)
        .thenAccept(System.out::println);

Search requests

Not yet implemented

Response entities

All response entities are auto-generated from musicbrainz source. There is no guarantee any of the entities properties will be present, therefore make sure to check the results or handle nulls.

Installation

Using Gradle, add this to your build script:

repositories {
    mavenCentral()
}
dependencies {
    compile 'io.aesy.musicbrainz:musicbrainz-api-jersey-client:1.0.0'
}

Using Maven, add this to your list of dependencies in pom.xml:

<dependency>
  <groupId>io.aesy.musicbrainz</groupId>
  <artifactId>musicbrainz-api-jersey-client</artifactId>
  <version>1.0.0</version>
</dependency>

Development

Prerequisites

• A Java 8+ Runtime
• Maven 3.6+

Build

To compile and package the application, simply issue the following command:

$ mvn package -DskipTests

This will create a jar located in jersey-client/target/.

Test

This project uses checkstyle for linting. Run it by using:

$ mvn checkstyle:check

All code that goes into master must pass all tests, including the lint checks.

To run unit tests, simply run:

$ mvn test

It's also possible to run these very same tests in integration test mode towards an existing musicbrainz server by providing an url as an environment variable. The following command will run the tests towards the musicbrainz test server:

$ MUSICBRAINZ_URL=https://test.musicbrainz.org/ws/2 mvn test

These integration tests are slow because they use rate limiting as to not overload the server.

Contribute

Use the issue tracker to report bugs or make feature requests. Pull requests are welcome, but it may be a good idea to create an issue to discuss any changes beforehand.

License

MIT, see LICENSE file.