org.deepsymmetry.beatlink.data

Class MetadataCache

java.lang.Object

org.deepsymmetry.beatlink.data.MetadataCache

All Implemented Interfaces:

MetadataProvider

public class MetadataCache
extends Object
implements MetadataProvider

A ZIP-file based cache of all the kinds of track metadata that we need, so we can operate with full functionality even when metadata requests are difficult or impossible because four CDJs are all using the same media. Although this class implements MetadataProvider, it should not be passed to MetadataFinder.addMetadataProvider(MetadataProvider) because there is all kinds of special handling needed to deal in a backwards-compatible way with older cache files that do not store media details. Instead, use the longstanding MetadataFinder.attachMetadataCache(SlotReference, File) and MetadataFinder.addAutoAttachCacheFile(File) methods to work with metadata cache files.

Since:

0.5.0

Field Summary

Fields

Modifier and Type	Field and Description
static String	CACHE_FORMAT_IDENTIFIER The comment string used to identify a ZIP file as one of our metadata caches.
MediaDetails	sourceMedia Holds information about the media from which this cache was created.
int	sourcePlaylist Holds the ID of the playlist that was used to create the cache, or 0 of it is an all-tracks cache.
int	trackCount Holds the number of tracks contained in the cache.

Constructor Summary

Constructors

Constructor and Description
MetadataCache(File file) Open the specified ZIP file and prepare to serve its contents as a cache.

Method Summary

Modifier and Type	Method and Description
void	close() Close the cache.
static void	createMetadataCache(SlotReference slot, int playlistId, File cache) Creates a metadata cache archive file of all tracks in the specified slot on the specified player.
static void	createMetadataCache(SlotReference slot, int playlistId, File cache, MetadataCacheCreationListener listener) Creates a metadata cache archive file of all tracks in the specified slot on the specified player.
AlbumArt	getAlbumArt(MediaDetails sourceMedia, DataReference art) Get a particular album art image, if it is available.
BeatGrid	getBeatGrid(MediaDetails sourceMedia, DataReference track) Get the beat grid for a particular track, if it is available.
static long	getCachePauseInterval() Check how long we pause between requesting metadata entries while building a cache to give the player a chance to perform its other tasks.
CueList	getCueList(MediaDetails sourceMedia, DataReference track) Get the cue list for a particular track, if it is available.
String	getName() Get the path name of the file containing the cache.
List<Integer>	getTrackIds() Returns a list of the rekordbox IDs of the tracks contained in the cache.
TrackMetadata	getTrackMetadata(MediaDetails sourceMedia, DataReference track) Get metadata for a particular track, if it is available.
WaveformDetail	getWaveformDetail(MediaDetails sourceMedia, DataReference track) Get the waveform detail for a particular track, if it is available.
WaveformPreview	getWaveformPreview(MediaDetails sourceMedia, DataReference track) Get the waveform preview for a particular track, if it is available.
static void	setCachePauseInterval(long milliseconds) Set how long to pause between requesting metadata entries while building a cache to give the player a chance to perform its other tasks.
List<MediaDetails>	supportedMedia() Get the list of media devices for which metadata can be offered by this provider.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

sourcePlaylist

public final int sourcePlaylist

Holds the ID of the playlist that was used to create the cache, or 0 of it is an all-tracks cache.

trackCount

public final int trackCount

Holds the number of tracks contained in the cache.

sourceMedia

public final MediaDetails sourceMedia

Holds information about the media from which this cache was created. Will be present in caches created by Beat Link version 0.4.1 or later; older caches will result in a null value.

CACHE_FORMAT_IDENTIFIER

public static final String CACHE_FORMAT_IDENTIFIER

The comment string used to identify a ZIP file as one of our metadata caches.

See Also:

Constant Field Values

Constructor Detail

MetadataCache

public MetadataCache(File file)
              throws IOException

Open the specified ZIP file and prepare to serve its contents as a cache. When you are finished with the cache, be sure to call its close() method to free up system resources.

Parameters:

file - the metadata cache file to be served.

Throws:

IOException - if there is a problem reading the file, or if it does not have the right content

Method Detail

close

public void close()
           throws IOException

Close the cache. This should be called when the cache will no longer be used, to free up file descriptors. Once this is called, trying to access any cached information will fail with an IOException.

Throws:

IOException - if there is a problem closing the cache

getName

public String getName()

Get the path name of the file containing the cache.

Returns:

the path name of the metadata cache file.

getTrackIds

public List<Integer> getTrackIds()

Returns a list of the rekordbox IDs of the tracks contained in the cache.

Returns:

a list containing the rekordbox ID for each track present in the cache, in the order they appear

supportedMedia

public List<MediaDetails> supportedMedia()

Description copied from interface: MetadataProvider

Get the list of media devices for which metadata can be offered by this provider. If the provider can offer metadata for all media, return an empty list, and it will always be consulted. Otherwise, it will only be consulted for media that were listed in response to this call when it was registered using MetadataFinder.addMetadataProvider(MetadataProvider).

Specified by:

supportedMedia in interface MetadataProvider

Returns:

the media device descriptors for which we have at least one available metadata item.

getTrackMetadata

public TrackMetadata getTrackMetadata(MediaDetails sourceMedia,
                                      DataReference track)

Description copied from interface: MetadataProvider

Get metadata for a particular track, if it is available.

Specified by:

getTrackMetadata in interface MetadataProvider

Parameters:

sourceMedia - the media to which the track belongs, for use by providers which store metadata from multiple sources

track - identifies the track whose metadata is desired; since track metadata always has a player and slot associated with it, those are needed as well as the rekordbox ID in order to create it

Returns:

the metadata corresponding to that track, or null if it is not a track for which we have metadata

getAlbumArt

public AlbumArt getAlbumArt(MediaDetails sourceMedia,
                            DataReference art)

Description copied from interface: MetadataProvider

Get a particular album art image, if it is available.

Specified by:

getAlbumArt in interface MetadataProvider

Parameters:

sourceMedia - the media to which the art belongs, for use by providers which store metadata from multiple sources

art - identifies the album art whose metadata is desired; since art always has a player and slot associated with it, those are needed as well as the rekordbox ID in order to create it

Returns:

the art with the specified id, or null if we don't have it to offer

getBeatGrid

public BeatGrid getBeatGrid(MediaDetails sourceMedia,
                            DataReference track)

Description copied from interface: MetadataProvider

Get the beat grid for a particular track, if it is available.

Specified by:

getBeatGrid in interface MetadataProvider

Parameters:

sourceMedia - the media to which the track belongs, for use by providers which store metadata from multiple sources

track - identifies the track whose beat grid is desired; since beat grids always have a player and slot associated with them, those are needed as well as the rekordbox ID in order to create one

Returns:

the beat grid corresponding to that track, or null if we don't have one to offer

getCueList

public CueList getCueList(MediaDetails sourceMedia,
                          DataReference track)

Description copied from interface: MetadataProvider

Get the cue list for a particular track, if it is available.

Specified by:

getCueList in interface MetadataProvider

Parameters:

sourceMedia - the media to which the track belongs, for use by providers which store metadata from multiple sources

track - identifies the track whose cue list is desired

Returns:

the cue list corresponding to that track, or null if we don't have one to offer

getWaveformPreview

public WaveformPreview getWaveformPreview(MediaDetails sourceMedia,
                                          DataReference track)

Description copied from interface: MetadataProvider

Get the waveform preview for a particular track, if it is available.

Specified by:

getWaveformPreview in interface MetadataProvider

Parameters:

sourceMedia - the media to which the track belongs, for use by providers which store metadata from multiple sources

track - identifies the track whose waveform preview is desired; since beat grids always have a player and slot associated with them, those are needed as well as the rekordbox ID in order to create one

Returns:

the waveform preview corresponding to that track, or null if we don't have one to offer

getWaveformDetail

public WaveformDetail getWaveformDetail(MediaDetails sourceMedia,
                                        DataReference track)

Description copied from interface: MetadataProvider

Get the waveform detail for a particular track, if it is available.

Specified by:

getWaveformDetail in interface MetadataProvider

Parameters:

sourceMedia - the media to which the track belongs, for use by providers which store metadata from multiple sources

track - identifies the track whose waveform detail is desired; since beat grids always have a player and slot associated with them, those are needed as well as the rekordbox ID in order to create one

Returns:

the waveform detail corresponding to that track, or null if we don't have one to offer

createMetadataCache

public static void createMetadataCache(SlotReference slot,
                                       int playlistId,
                                       File cache)
                                throws Exception

Creates a metadata cache archive file of all tracks in the specified slot on the specified player. Any previous contents of the specified file will be replaced.

Parameters:

slot - the slot in which the media to be cached can be found

playlistId - the id of playlist to be cached, or 0 of all tracks should be cached

cache - the file into which the metadata cache should be written

Throws:

Exception - if there is a problem communicating with the player or writing the cache file.

setCachePauseInterval

public static void setCachePauseInterval(long milliseconds)

Set how long to pause between requesting metadata entries while building a cache to give the player a chance to perform its other tasks.

Parameters:

milliseconds - the delay to add between each track that gets added to the metadata cache

getCachePauseInterval

public static long getCachePauseInterval()

Check how long we pause between requesting metadata entries while building a cache to give the player a chance to perform its other tasks.

Returns:

the delay to add between each track that gets added to the metadata cache

createMetadataCache

public static void createMetadataCache(SlotReference slot,
                                       int playlistId,
                                       File cache,
                                       MetadataCacheCreationListener listener)
                                throws Exception

Creates a metadata cache archive file of all tracks in the specified slot on the specified player. Any previous contents of the specified file will be replaced. If a non-null listener is supplied, its MetadataCacheCreationListener.cacheCreationContinuing(TrackMetadata, int, int) method will be called after each track is added to the cache, allowing it to display progress updates to the user, and to continue or cancel the process by returning true or false. Because this takes a huge amount of time relative to CDJ status updates, it can only be performed while the MetadataFinder is in passive mode.

Parameters:

slot - the slot in which the media to be cached can be found

playlistId - the id of playlist to be cached, or 0 of all tracks should be cached

cache - the file into which the metadata cache should be written

listener - will be informed after each track is added to the cache file being created and offered the opportunity to cancel the process

Throws:

Exception - if there is a problem communicating with the player or writing the cache file