|
|||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
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 |
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.
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.
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.
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.
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
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.
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:
|
|||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |