org.deepsymmetry.beatlink.data

Class ArtFinder

java.lang.Object

org.deepsymmetry.beatlink.LifecycleParticipant

org.deepsymmetry.beatlink.data.ArtFinder

public class ArtFinder
extends LifecycleParticipant

Watches for new metadata to become available for tracks loaded on players, and queries the appropriate player for the album art when that happens.

Maintains a hot cache of art for any track currently loaded in a player, either on the main playback deck, or as a hot cue, since those tracks could start playing instantly. Also maintains a second-level in-memory cache of artwork, discarding the least-recently-used art when the cache fills, because tracks can share artwork, so the DJ may load another track with the same album art.

Implicitly honors the active/passive setting of the MetadataFinder (see MetadataFinder.setPassive(boolean)), because art is loaded in response to metadata updates.

Author:

James Elliott

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_ART_CACHE_SIZE The maximum number of artwork images we will retain in our cache.

Method Summary

Modifier and Type	Method and Description
void	addAlbumArtListener(AlbumArtListener listener) Adds the specified album art listener to receive updates when the album art for a player changes.
Set<AlbumArtListener>	getAlbumArtListeners() Get the set of currently-registered album art listeners.
long	getArtCacheSize() Check how many album art images can be kept in the in-memory second-level cache.
AlbumArt	getCachedArtwork(ZipFile cache, DataReference artReference) Look up artwork from a cache file.
static ArtFinder	getInstance() Get the singleton instance of this class.
AlbumArt	getLatestArtFor(DeviceUpdate update) Look up the album art we have for a given player, identified by a status update received from that player.
AlbumArt	getLatestArtFor(int player) Look up the album art we have for the track loaded in the main deck of a given player number.
Map<DeckReference,AlbumArt>	getLoadedArt() Get the art available for all tracks currently loaded in any player, either on the play deck, or in a hot cue.
boolean	isRunning() Check whether we are currently running.
void	removeAlbumArtListener(AlbumArtListener listener) Removes the specified album art listener so that it no longer receives updates when the album art for a player changes.
AlbumArt	requestArtworkFrom(DataReference artReference) Ask the specified player for the specified artwork from the specified media slot, first checking if we have a cached copy.
void	setArtCacheSize(int size) Set how many album art images can be kept in the in-memory second-level cache.
void	start() Start finding album art for all active players.
void	stop() Stop finding album art for all active players.
String	toString()

Methods inherited from class org.deepsymmetry.beatlink.LifecycleParticipant

addLifecycleListener, deliverLifecycleAnnouncement, ensureRunning, getLifecycleListeners, removeLifecycleListener

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ART_CACHE_SIZE

public static final int DEFAULT_ART_CACHE_SIZE

The maximum number of artwork images we will retain in our cache.

See Also:

Constant Field Values

Method Detail

isRunning

public boolean isRunning()

Check whether we are currently running. Unless the MetadataFinder is in passive mode, we will automatically request album art from the appropriate player when a new track is loaded that is not found in the hot cache, second-level memory cache, or an attached metadata cache file.

Specified by:

isRunning in class LifecycleParticipant

Returns:

true if album art is being kept track of for all active players

See Also:

MetadataFinder.isPassive()

getLoadedArt

public Map<DeckReference,AlbumArt> getLoadedArt()

Get the art available for all tracks currently loaded in any player, either on the play deck, or in a hot cue.

Returns:

the album art associated with all current players, including for any tracks loaded in their hot cue slots

Throws:

IllegalStateException - if the ArtFinder is not running

getLatestArtFor

public AlbumArt getLatestArtFor(int player)

Look up the album art we have for the track loaded in the main deck of a given player number.

Parameters:

player - the device number whose album art for the playing track is desired

Returns:

the album art for the track loaded on that player, if available

Throws:

IllegalStateException - if the ArtFinder is not running

getLatestArtFor

public AlbumArt getLatestArtFor(DeviceUpdate update)

Look up the album art we have for a given player, identified by a status update received from that player.

Parameters:

update - a status update from the player for which album art is desired

Returns:

the album art for the track loaded on that player, if available

Throws:

IllegalStateException - if the ArtFinder is not running

getArtCacheSize

public long getArtCacheSize()

Check how many album art images can be kept in the in-memory second-level cache.

Returns:

the maximum number of distinct album art images that will automatically be kept for reuse in the in-memory art cache.

setArtCacheSize

public void setArtCacheSize(int size)

Set how many album art images can be kept in the in-memory second-level cache.

Parameters:

size - the maximum number of distinct album art images that will automatically be kept for reuse in the in-memory art cache; if you set this to a smaller number than are currently present in the cache, some of the older images will be immediately discarded so that only the number you specified remain

Throws:

IllegalArgumentException - if size is less than 1

requestArtworkFrom

public AlbumArt requestArtworkFrom(DataReference artReference)

Ask the specified player for the specified artwork from the specified media slot, first checking if we have a cached copy.

Parameters:

artReference - uniquely identifies the desired artwork

Returns:

the artwork, if it was found, or null

Throws:

IllegalStateException - if the ArtFinder is not running

getCachedArtwork

public AlbumArt getCachedArtwork(ZipFile cache,
                                 DataReference artReference)

Look up artwork from a cache file.

Parameters:

cache - the appropriate metadata cache file

artReference - the unique database specification of the desired artwork

Returns:

the cached album art (if available), or null

Throws:

IllegalStateException - if the ArtFinder is not running

addAlbumArtListener

public void addAlbumArtListener(AlbumArtListener listener)

Adds the specified album art listener to receive updates when the album art for a player changes. If listener is null or already present in the set of registered listeners, no exception is thrown and no action is performed.

To reduce latency, updates are delivered to listeners directly on the thread that is receiving packets from the network, so if you want to interact with user interface objects in listener methods, you need to use javax.swing.SwingUtilities.invokeLater(Runnable) to do so on the Event Dispatch Thread. Even if you are not interacting with user interface objects, any code in the listener method must finish quickly, or it will add latency for other listeners, and updates will back up. If you want to perform lengthy processing of any sort, do so on another thread.

Parameters:

listener - the album art update listener to add

removeAlbumArtListener

public void removeAlbumArtListener(AlbumArtListener listener)

Removes the specified album art listener so that it no longer receives updates when the album art for a player changes. If listener is null or not present in the set of registered listeners, no exception is thrown and no action is performed.

Parameters:

listener - the album art update listener to remove

getAlbumArtListeners

public Set<AlbumArtListener> getAlbumArtListeners()

Get the set of currently-registered album art listeners.

Returns:

the listeners that are currently registered for album art updates

start

public void start()
           throws Exception

Start finding album art for all active players. Starts the MetadataFinder if it is not already running, because we need it to send us metadata updates to notice when new tracks are loaded. This in turn starts the DeviceFinder, so we can keep track of the comings and goings of players themselves. We also start the ConnectionManager in order to make queries to obtain art.

Throws:

Exception - if there is a problem starting the required components

stop

public void stop()

Stop finding album art for all active players.

getInstance

public static ArtFinder getInstance()

Get the singleton instance of this class.

Returns:

the only instance of this class which exists.

toString

public String toString()

Overrides:

toString in class Object