org.deepsymmetry.beatlink.data

Class MenuLoader

java.lang.Object

org.deepsymmetry.beatlink.data.MenuLoader

public class MenuLoader
extends Object

Provides support for navigating the menu hierarchy offered by the dbserver on a player for a particular media slot. Note that for historical reasons, loading track metadata, playlists, and the full track list are performed by the MetadataFinder, even though those are technically menu operations.

Since:

0.4.0

Author:

James Elliott

Method Summary

Modifier and Type	Method and Description
static MenuLoader	getInstance() Get the singleton instance of this class.
List<Message>	requestAlbumMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for an Album menu.
List<Message>	requestAlbumTrackMenuFrom(SlotReference slotReference, int sortOrder, int albumId) Ask the specified player for an Album Track menu.
List<Message>	requestArtistAlbumMenuFrom(SlotReference slotReference, int sortOrder, int artistId) Ask the specified player for an Artist Album menu.
List<Message>	requestArtistAlbumTrackMenuFrom(SlotReference slotReference, int sortOrder, int artistId, int albumId) Ask the specified player for an Artist Album Tracks menu.
List<Message>	requestArtistMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for an Artist menu.
List<Message>	requestBpmMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for a BPM menu.
List<Message>	requestBpmRangeMenuFrom(SlotReference slotReference, int sortOrder, int bpm) Ask the specified player for a tempo range menu for a given BPM.
List<Message>	requestFolderMenuFrom(SlotReference slotReference, int sortOrder, int folderId) Ask the specified player for a Folder menu for exploring its raw filesystem.
List<Message>	requestGenreArtistAlbumMenuFrom(SlotReference slotReference, int sortOrder, int genreId, int artistId) Ask the specified player for a Genre Artist Albums menu.
List<Message>	requestGenreArtistAlbumTrackMenuFrom(SlotReference slotReference, int sortOrder, int genreId, int artistId, int albumId) Ask the specified player for a Genre Artist Album Tracks menu.
List<Message>	requestGenreArtistMenuFrom(SlotReference slotReference, int sortOrder, int genreId) Ask the specified player for a Genre Artists menu.
List<Message>	requestGenreMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for a Genre menu.
List<Message>	requestHistoryMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for a History menu.
List<Message>	requestHistoryPlaylistFrom(SlotReference slotReference, int sortOrder, int historyId) Ask the specified player a History playlist.
List<Message>	requestKeyMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for a Key menu.
List<Message>	requestKeyNeighborMenuFrom(SlotReference slotReference, int sortOrder, int keyId) Ask the specified player for a key neighbor menu for a given key.
List<Message>	requestMoreSearchResultsFrom(int player, CdjStatus.TrackSourceSlot slot, int sortOrder, String text, int offset, int count) Ask the specified player for more database records whose names contain text.
List<Message>	requestPlaylistMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for a Playlist menu.
List<Message>	requestRatingMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for a Rating menu.
List<Message>	requestRootMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for its top-level menu of menus.
List<Message>	requestSearchResultsFrom(int player, CdjStatus.TrackSourceSlot slot, int sortOrder, String text, AtomicInteger count) Ask the specified player for database records whose names contain text.
List<Message>	requestTrackMenuFrom(SlotReference slotReference, int sortOrder) Ask the specified player for a Track menu.
List<Message>	requestTracksByBpmRangeFrom(SlotReference slotReference, int sortOrder, int bpm, int range) Ask the specified player for tracks whose tempo falls within a specific percentage of a given BPM.
List<Message>	requestTracksByKeyAndDistanceFrom(SlotReference slotReference, int sortOrder, int keyId, int distance) Ask the specified player for a track menu for an allowed distance from a given key.
List<Message>	requestTracksByRatingFrom(SlotReference slotReference, int sortOrder, int rating) Ask the specified player for a track menu for a given rating.

Methods inherited from class java.lang.Object

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

Method Detail

requestRootMenuFrom

public List<Message> requestRootMenuFrom(SlotReference slotReference,
                                         int sortOrder)
                                  throws Exception

Ask the specified player for its top-level menu of menus. The MetadataFinder must be running for us to know the right kind of message to send, because it depends on whether the slot holds a rekordbox database or not. If we can't tell (because it's not running), we will just guess that there is one, and perhaps get back nothing.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details, although it does not seem to have an effect on the root menu

Returns:

the entries in the top level menu

Throws:

Exception - if there is a problem obtaining the menu

requestPlaylistMenuFrom

public List<Message> requestPlaylistMenuFrom(SlotReference slotReference,
                                             int sortOrder)
                                      throws Exception

Ask the specified player for a Playlist menu. This boils down to a call to MetadataFinder.requestPlaylistItemsFrom(int, CdjStatus.TrackSourceSlot, int, int, boolean) asking for the playlist folder with ID 0, but it is also made available here since this is likely where people will be looking for the capability. To get the contents of individual playlists or sub-folders, pass the playlist or folder ID obtained by calling this to that function.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the playlists and folders in the playlist menu

Throws:

Exception - if there is a problem obtaining the menu

See Also:

MetadataFinder.requestPlaylistItemsFrom(int, CdjStatus.TrackSourceSlot, int, int, boolean)

requestHistoryMenuFrom

public List<Message> requestHistoryMenuFrom(SlotReference slotReference,
                                            int sortOrder)
                                     throws Exception

Ask the specified player for a History menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details, although it does not seem to have an effect on the history menu

Returns:

the entries in the history menu

Throws:

Exception - if there is a problem obtaining the menu

requestHistoryPlaylistFrom

public List<Message> requestHistoryPlaylistFrom(SlotReference slotReference,
                                                int sortOrder,
                                                int historyId)
                                         throws Exception

Ask the specified player a History playlist.

Parameters:

slotReference - the player and slot for which the playlist is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

historyId - identifies which history session's playlist is desired

Returns:

the entries in the history playlist

Throws:

Exception - if there is a problem obtaining the playlist

requestTrackMenuFrom

public List<Message> requestTrackMenuFrom(SlotReference slotReference,
                                          int sortOrder)
                                   throws Exception

Ask the specified player for a Track menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the entries in the track menu

Throws:

Exception - if there is a problem obtaining the menu

requestArtistMenuFrom

public List<Message> requestArtistMenuFrom(SlotReference slotReference,
                                           int sortOrder)
                                    throws Exception

Ask the specified player for an Artist menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the entries in the artist menu

Throws:

Exception - if there is a problem obtaining the menu

requestArtistAlbumMenuFrom

public List<Message> requestArtistAlbumMenuFrom(SlotReference slotReference,
                                                int sortOrder,
                                                int artistId)
                                         throws Exception

Ask the specified player for an Artist Album menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

artistId - the artist whose album menu is desired

Returns:

the entries in the artist album menu

Throws:

Exception - if there is a problem obtaining the menu

requestArtistAlbumTrackMenuFrom

public List<Message> requestArtistAlbumTrackMenuFrom(SlotReference slotReference,
                                                     int sortOrder,
                                                     int artistId,
                                                     int albumId)
                                              throws Exception

Ask the specified player for an Artist Album Tracks menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

artistId - the artist whose album track menu is desired

albumId - the album whose track menu is desired, or -1 for all albums

Returns:

the entries in the artist albums menu

Throws:

Exception - if there is a problem obtaining the menu

requestAlbumTrackMenuFrom

public List<Message> requestAlbumTrackMenuFrom(SlotReference slotReference,
                                               int sortOrder,
                                               int albumId)
                                        throws Exception

Ask the specified player for an Album Track menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

albumId - the album whose track menu is desired

Returns:

the entries in the album track menu

Throws:

Exception - if there is a problem obtaining the menu

requestGenreMenuFrom

public List<Message> requestGenreMenuFrom(SlotReference slotReference,
                                          int sortOrder)
                                   throws Exception

Ask the specified player for a Genre menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the entries in the genre menu

Throws:

Exception - if there is a problem obtaining the menu

requestGenreArtistMenuFrom

public List<Message> requestGenreArtistMenuFrom(SlotReference slotReference,
                                                int sortOrder,
                                                int genreId)
                                         throws Exception

Ask the specified player for a Genre Artists menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

genreId - the genre whose artist menu is desired

Returns:

the entries in the genre artists menu

Throws:

Exception - if there is a problem obtaining the menu

requestGenreArtistAlbumMenuFrom

public List<Message> requestGenreArtistAlbumMenuFrom(SlotReference slotReference,
                                                     int sortOrder,
                                                     int genreId,
                                                     int artistId)
                                              throws Exception

Ask the specified player for a Genre Artist Albums menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

genreId - the genre whose artist album menu is desired

artistId - the artist whose album menu is desired, or -1 for all artists

Returns:

the entries in the genre artist albums menu

Throws:

Exception - if there is a problem obtaining the menu

requestGenreArtistAlbumTrackMenuFrom

public List<Message> requestGenreArtistAlbumTrackMenuFrom(SlotReference slotReference,
                                                          int sortOrder,
                                                          int genreId,
                                                          int artistId,
                                                          int albumId)
                                                   throws Exception

Ask the specified player for a Genre Artist Album Tracks menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

genreId - the genre whose artist album track menu is desired

artistId - the artist whose album track menu is desired, or -1 for all artists

albumId - the album whose track menu is desired, or -1 for all albums

Returns:

the entries in the genre artist albums menu

Throws:

Exception - if there is a problem obtaining the menu

requestAlbumMenuFrom

public List<Message> requestAlbumMenuFrom(SlotReference slotReference,
                                          int sortOrder)
                                   throws Exception

Ask the specified player for an Album menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the entries in the album menu

Throws:

Exception - if there is a problem obtaining the menu

requestKeyMenuFrom

public List<Message> requestKeyMenuFrom(SlotReference slotReference,
                                        int sortOrder)
                                 throws Exception

Ask the specified player for a Key menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the entries in the key menu

Throws:

Exception - if there is a problem obtaining the menu

requestKeyNeighborMenuFrom

public List<Message> requestKeyNeighborMenuFrom(SlotReference slotReference,
                                                int sortOrder,
                                                int keyId)
                                         throws Exception

Ask the specified player for a key neighbor menu for a given key.

Parameters:

slotReference - the player and slot for which the menu is desired

keyId - the key whose available compatible keys are desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the entries in the key neighbor menu

Throws:

Exception - if there is a problem obtaining the menu

requestTracksByKeyAndDistanceFrom

public List<Message> requestTracksByKeyAndDistanceFrom(SlotReference slotReference,
                                                       int sortOrder,
                                                       int keyId,
                                                       int distance)
                                                throws Exception

Ask the specified player for a track menu for an allowed distance from a given key.

Parameters:

slotReference - the player and slot for which the menu is desired

keyId - the key whose compatible tracks are desired

distance - how far along the circle of fifths are the tracks allowed to be from the specified key

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the matching tracks

Throws:

Exception - if there is a problem obtaining the menu

requestBpmMenuFrom

public List<Message> requestBpmMenuFrom(SlotReference slotReference,
                                        int sortOrder)
                                 throws Exception

Ask the specified player for a BPM menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the entries in the BPM menu

Throws:

Exception - if there is a problem obtaining the menu

requestBpmRangeMenuFrom

public List<Message> requestBpmRangeMenuFrom(SlotReference slotReference,
                                             int sortOrder,
                                             int bpm)
                                      throws Exception

Ask the specified player for a tempo range menu for a given BPM.

Parameters:

slotReference - the player and slot for which the menu is desired

bpm - the tempo whose nearby ranges are desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the entries in the tempo range menu

Throws:

Exception - if there is a problem obtaining the menu

requestTracksByBpmRangeFrom

public List<Message> requestTracksByBpmRangeFrom(SlotReference slotReference,
                                                 int sortOrder,
                                                 int bpm,
                                                 int range)
                                          throws Exception

Ask the specified player for tracks whose tempo falls within a specific percentage of a given BPM.

Parameters:

slotReference - the player and slot for which the menu is desired

bpm - the tempo that tracks must be close to

range - the percentage by which the actual tempo may differ for a track to still be returned

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the tracks whose tempo falls within the specified range

Throws:

Exception - if there is a problem obtaining the menu

requestRatingMenuFrom

public List<Message> requestRatingMenuFrom(SlotReference slotReference,
                                           int sortOrder)
                                    throws Exception

Ask the specified player for a Rating menu.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the entries in the rating menu

Throws:

Exception - if there is a problem obtaining the menu

requestTracksByRatingFrom

public List<Message> requestTracksByRatingFrom(SlotReference slotReference,
                                               int sortOrder,
                                               int rating)
                                        throws Exception

Ask the specified player for a track menu for a given rating.

Parameters:

slotReference - the player and slot for which the menu is desired

rating - the desired rating for tracks to be returned

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

Returns:

the matching tracks

Throws:

Exception - if there is a problem obtaining the menu

requestFolderMenuFrom

public List<Message> requestFolderMenuFrom(SlotReference slotReference,
                                           int sortOrder,
                                           int folderId)
                                    throws Exception

Ask the specified player for a Folder menu for exploring its raw filesystem. This is a request for unanalyzed items, so we do a typed menu request.

Parameters:

slotReference - the player and slot for which the menu is desired

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details

folderId - identifies the folder whose contents should be listed, use -1 to get the root folder

Returns:

the entries in the folder menu

Throws:

Exception - if there is a problem obtaining the menu

requestSearchResultsFrom

public List<Message> requestSearchResultsFrom(int player,
                                              CdjStatus.TrackSourceSlot slot,
                                              int sortOrder,
                                              String text,
                                              AtomicInteger count)
                                       throws Exception

Ask the specified player for database records whose names contain text. If count is not null, no more than that many results will be returned, and the value will be set to the total number of results that were available. Otherwise all results will be returned.

Parameters:

player - the player number whose database is to be searched

slot - the slot in which the database can be found

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details, although it does not seem to have an effect on searches.

text - the search text used to filter the results

count - if present, sets an upper limit on the number of results to return, and will get set to the actual number that were available

Returns:

the items that the specified search string; they may be a variety of different types

Throws:

Exception - if there is a problem performing the search

requestMoreSearchResultsFrom

public List<Message> requestMoreSearchResultsFrom(int player,
                                                  CdjStatus.TrackSourceSlot slot,
                                                  int sortOrder,
                                                  String text,
                                                  int offset,
                                                  int count)
                                           throws Exception

Ask the specified player for more database records whose names contain text. This can be used after calling requestSearchResultsFrom(int, CdjStatus.TrackSourceSlot, int, String, AtomicInteger) to obtain a partial result and the total count available, to gradually expand the search under direction from the user.

Parameters:

player - the player number whose database is to be searched

slot - the slot in which the database can be found

sortOrder - the order in which responses should be sorted, 0 for default, see Section 6.11.1 of the Packet Analysis document for details, although it does not seem to have an effect on searches.

text - the search text used to filter the results

offset - the first result desired (the first available result has offset 0)

count - the number of results to return (if more than the number available, fewer will simply be returned)

Returns:

the items that the specified search string; they may be a variety of different types

Throws:

Exception - if there is a problem performing the search

getInstance

public static MenuLoader getInstance()

Get the singleton instance of this class.

Returns:

the only instance of this class which exists.