Package com.ldodds.musicbrainz

Introduction

See:
          Description

Interface Summary
MusicBrainz MusicBrainz query interface.
 

Class Summary
Album Note: this class has a natural ordering that is inconsistent with equals.
AlbumTripleBuilder  
Artist Note: this class has a natural ordering that is inconsistent with equals.
BeanPopulator This class provides methods to interpret a Jena Model returned from a MusicBrainz query.
MM Vocabulary definitions for the MusicBrainz Metadata ontology.
MQ Vocabulary definitions for the MusicBrainz Query ontology.
MusicBrainzImpl  
ReleaseDate Describes a ReleaseDate Not sure why the MM schema models this separately from release type and status, surely they ought to belong to the same class?
Track Note: this class has a natural ordering that is inconsistent with equals.
TrackSummary Summary details for a given Track.
 

Exception Summary
MusicBrainzException Exception throw by query methods if: Server returns any of the following HTTP error codes: 204, 400, 403, 500, 503 An HTTP 200 status code was retrieved but the RDF model contains an mq:Response with an mq:error property
 

Package com.ldodds.musicbrainz Description

Introduction

This is a Java port of the MusicBrainz API, written by Leigh Dodds (leigh@ldodds.com, http://www.ldodds.com). For more information about the MusicBrainz project see: http://www.musicbrainz.org.

Getting Started

The MusicBrainz web service has two types of query: those that are accessible via an HTTP GET request -- these take a unique artist/album/track identifier in the URL path info -- and those that are accessible via an HTTP POST request. The latter involving posting an RDF document describing the query to a CGI application, which will then return an RDF document describing the results.

The details on constructing a MusicBrainz query, including constructing the RDF query documents, is totally encapsulated within the provided implementation (MusicBrainz, MusicBrainzImpl, Templates).

The responses from the web service are made available in two formats: as "raw" RDF (actually Jena 2 Model instances) or via some simple JavaBeans (Artist, Album, Track, TrackSummary). These JavaBeans are instantiated by a factory class (BeanPopulator) which is capable of navigating the RDF graph returned by different MusicBrainz queries and pulling out the required data.

This means that you can choose to ignore the RDF details if you'd prefer, or dig around in the results and perform operations on the RDF graph.

Most of the MusicBrainz queries have a "depth" parameter. This equates to setting the level of detail in the results. For example when querying about an Album, do you also want details of all tracks, the artist, and possibly other albums by the same artist? Increasing the depth parameter increases the level of detail. As a rough guide, 2 is a "shallow" query, 4 is a medium query and 6 is a "deep" query. Play with the level of detail to get a feel for what's returned in different cases. However you should try to carefully select the depth of your query to make sure that you only retrieve as much information as you really need.

The "Raw RDF" Interface

Accessing the RDF data directly is very straight-forward. Firstly create an implementation of the MusicBrainz interface:


MusicBrainz server = new MusicBrainzImpl();

There is only a single implementation provided in this API (com.ldodds.musicbrainz.MusicBrainImpl). The object has an alternate constructor that allows you to specify the host name of the MusicBrainz server, in case you need to connect to a mirror.

Next we perform a query:


//name of an album
String name = "Second Toughest In The Infants";
//medium query
int depth = 4;
//maximum number of items to return
int maxItems = 1;

Model results = server.findAlbumByName(name, depth, maxItems);

The maxItems parameter, which is accepted by several methods, indicates to the MusicBrainz server how many results it can return. E.g. if there are two albums with similar names, can it return both or just the first? There is no way to fetch all matches, other than setting maxItems to be an arbitrarily large value.

At present the MusicBrainz web service supports wildcarding (% = zero or more characters). However it is possible that this may change in the future, so use with care.

At this point you have a Jena Model containing the results. This will basically be an mq:Result which has an mq:trackList, mq:artistList, or mq:albumList property. Examine MM and MQ to see what RDF classes and properties the MusicBrainz service can return.

The Bean Interface

Using the Bean interface involves exactly the same steps as using the RDF server above, with the addition of one extra line of code:


List albums = BeanPopulator.getAlbums(model);

This invokes a method on the BeanPopulator factory class, asking it to extract the metadata (in this example, an mm:Album) from the graph. The factory will create instances of the Album, Artist and Track beans and populate them with the results. With "deep" queries you'll find that an Artists and Tracks will be associated with their Albums, so you can do the following:


Album album = albums.get(0);
Artist artist = album.getArtist();
List tracks = album.getTracks();
//process the results...

This alternate interface means that the details of the underlying RDF data is totally hidden.

Note that at present the unique identifiers stored in the beans are the raw identifiers, and not URIs.

For more examples of how to use the bean interface, see the unit tests. There is one test for each MusicBrainz query.

Known Bugs and Limitations

The initial version of this API only supports a subset of the MusicBrainz API. Specifically it does not yet support the Authenticate and Submit requests required to actually submit new entries into the database. It also does not yet support the FileInfoLookup function. Later versions of this API will support all functionality. At present the API is read-only, but is complete enough to develop Java based applications.

The MusicBrainz#findDistinctTRMId implementation is untested as there appears to be a bug in the MusicBrainz server code that makes this result always return no results. See IRC logs.

The MusicBrainz#getTrackInfoFromTRMId implementation works, but has not had adequate testing as there appears to be some data errors in the MusicBrainz database: specifically the same trmid associated with the same track more than once. See IRC logs

Bug Reporting

If you encounter bugs in this code then please report them to leigh@ldodds.com. Please include the following information:

If you encounter problems with the data being returned then contact the MusicBrainz project directly. I DO NOT have access to the source database so cannot fix up data errors or server-side bugs.

General contact details for MusicBrainz can be found at: http://www.musicbrainz.org/support/contact.html.

Related Information

For information on the original C API see the following documents:

See the MusicBrainz website, IRC channel or mailing lists for more information on the MusicBrainz project and applications built using their data and code: