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