sk.baka.ambient.playlist
Interface IPlaylistStrategy

All Known Implementing Classes:

DynamicPlaylistStrategy, PlaylistPlayer, StaticPlaylistStrategy

public interface IPlaylistStrategy

An interface for a playlist. There are two playlist implementations - StaticPlaylistStrategy which holds a static playlist and supports random/repeat playmodes, and DynamicPlaylistStrategy which dynamically polls its datasource and modifies itself as the player propagates through the playlist.

All implementations should be serializable. Thread-unsafe - it is recommended that all methods are invoked in the Handler thread.

Author:

Martin Vysny

Method Summary

void	add(int index, List<TrackMetadataBean> tracks) Inserts given tracks before track with given index.
void	clearQueue() Clears queue from queued.
void	dequeue(int track) Dequeues given track if it was queued previously.
int	getCurrentlyPlaying() Returns currently playing track.
List<PlaylistItem>	getPlayItems() Returns list of playlist items.
List<Integer>	getQueue() Returns currently queued tracks.
Random	getRandom() Returns current random mode.
Interval	move(Interval interval, int targetIndex) Moves selected tracks before track with given index.
Interval	moveBy(Interval interval, int delta) Moves selected tracks up or down at least delta tracks, depending on the 'delta' value.
int	next() Moves to next track to be played.
int	peekNext() Peeks at the next track without actually changing the current track.
int	play(int track) Plays given track.
int	previous() Returns previous track to be played.
void	queue(Interval tracks) Queue this track for playing, after all other queued tracks.
void	reinit() Reinitializes the playlist - recomputes new random track ordering etc.
void	remove(Interval interval) Removes tracks with given index from the playlist.
void	replaceLocations(Map<String,String> locationMap) Modifies the playlist by changing all PlaylistItem locations.
void	setRandom(Random random) Sets the random mode.
void	shuffle() Randomize the playlist.
int	size() Returns the playlist length.
void	sortByAlbumOrder() Sorts the playlist with album order ordering.

Method Detail

setRandom

void setRandom(Random random)

Sets the random mode. Currently played track must be preserved.

Parameters:

random - the random mode, never null.

getRandom

Random getRandom()

Returns current random mode.

Returns:

the random mode, never null.

sortByAlbumOrder

void sortByAlbumOrder()

Sorts the playlist with album order ordering.

shuffle

void shuffle()

Randomize the playlist.

getCurrentlyPlaying

int getCurrentlyPlaying()

Returns currently playing track. Note that the playlist is not connected to the player and the player itself may be paused or stopped.

Returns:

currently playing track or -1 if nothing is being played. Index to the getPlayItems() list.

next

int next()

Moves to next track to be played. Returns -1 if no more tracks are to be played - this also causes the getCurrentlyPlaying() method to return -1. Calling this method while not playing anything will start to play first track.

Returns:

play item to play next or -1 if no more items are to be played. Index to the getPlayItems() list.

play

int play(int track)

Plays given track. The playback continues from this track forward, unless random play is activated.

Parameters:

track - the track to play. Index to the getPlayItems() list. If -1 then the current track pointer is moved before first track and the playback is stopped.

Returns:

the track that is being played.

previous

int previous()

Returns previous track to be played. Returns -1 if we are at the beginning of the playing track sequence. Calling this method while not playing anything will start to play last track.

Returns:

which item was played prior current track or -1 if we are at the beginning of the playing track sequence.

queue

void queue(Interval tracks)

Queue this track for playing, after all other queued tracks. Does nothing if the track is already queued.

Parameters:

tracks - the tracks to queue, index to the getPlayItems() list.

dequeue

void dequeue(int track)

Dequeues given track if it was queued previously. Does nothing if the track is not present in the queue anymore.

Parameters:

track - the track to dequeue.

clearQueue

void clearQueue()

Clears queue from queued.

getQueue

List<Integer> getQueue()

Returns currently queued tracks.

Returns:

queued tracks, never null.

size

int size()

Returns the playlist length.

Returns:

the playlist length.

getPlayItems

List<PlaylistItem> getPlayItems()

Returns list of playlist items. The operation must be quick - it should for example provide immutable view on an internal playlist structure, it should not recompute the list anew on each call.

Each PlaylistItem in the list must be an unique instance.

Returns:

list of playlist items, will not be modified.

reinit

void reinit()

Reinitializes the playlist - recomputes new random track ordering etc. Removes all queued tracks and stops the playback (getCurrentlyPlaying() will return -1).

add

void add(int index,
         List<TrackMetadataBean> tracks)

Inserts given tracks before track with given index.

Parameters:

index - the index, must not be negative.

tracks - the tracks meta, must not be null.

remove

void remove(Interval interval)

Removes tracks with given index from the playlist. If currently played track is removed then the current song must be set to -1.

Parameters:

interval - the interval to remove

move

Interval move(Interval interval,
              int targetIndex)

Moves selected tracks before track with given index. Correctly updates queue indices. Currently played track will not be changed, although the track index may change.

Parameters:

interval - the interval to move

targetIndex - move tracks before track with this index. If this index is contained in the interval then nothing is done.

Returns:

a new interval which contains all moved tracks.

Throws:

IllegalArgumentException - if the interval exceeds the playlist.

moveBy

Interval moveBy(Interval interval,
                int delta)

Moves selected tracks up or down at least delta tracks, depending on the 'delta' value. The playlist may decide to move tracks by more tracks than requested - for example, the dynamic playlist will skip the currently playing/queued tracks. If the move is not possible (for example there are not enough tracks) then move the tracks to the beginning (or end) of the playlist.

Currently played track will not be changed, although the queue indices. Currently played track will not be changed, although the track index may change.

Parameters:

interval - the interval to move

delta - move tracks up 'delta' tracks (if delta is negative), or down 'delta' tracks (if delta is positive). Do nothing if delta is zero.

Returns:

a new interval which contains all moved tracks.

Throws:

IllegalArgumentException - if the interval exceeds the playlist.

peekNext

int peekNext()

Peeks at the next track without actually changing the current track.

Returns:

next track index. Returns -1 when there's no track left. Dynamic playlist may return -1 when there are no upcoming tracks and the queue is empty.

replaceLocations

void replaceLocations(Map<String,String> locationMap)

Modifies the playlist by changing all PlaylistItem locations.

Parameters:

locationMap - maps old locations to new locations.