1 /***
2 * Ambient - A music player for the Android platform
3 Copyright (C) 2007 Martin Vysny
4
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18 package sk.baka.ambient.collection;
19
20 import java.io.Closeable;
21 import java.io.Serializable;
22 import java.util.Iterator;
23
24 import sk.baka.ambient.playlist.DynamicPlaylistStrategy;
25 import sk.baka.ambient.playlist.Random;
26
27 /***
28 * <p>
29 * Provides tracks on demand for the {@link DynamicPlaylistStrategy} playlist.
30 * The provider must maintain a history of provided tracks so that no tracks are
31 * provided two times (unless this functionality is explicitly required - for
32 * example when a playlist with same tracks is provided).
33 * </p>
34 * <p>
35 * When there are no more items to play, the provider should clean up after
36 * itself and wait to be garbage-collected.
37 * </p>
38 * <p>
39 * All providers must be serializable.
40 * </p>
41 *
42 * @author Martin Vysny
43 */
44 public interface IDynamicPlaylistTrackProvider extends
45 Iterator<TrackMetadataBean>, Serializable, Closeable {
46 /***
47 * Removes given amount of oldest tracks from the history.
48 *
49 * @param trackCount
50 * how many tracks to remove. If {@link Integer#MAX_VALUE} then
51 * entire history should be cleaned up.
52 */
53 void removeFromHistory(final int trackCount);
54
55 /***
56 * Sets the random mode of tracks provided next by the provider. By default
57 * the {@link Random#TRACK} is set.
58 *
59 * @param random
60 * the random mode, never <code>null</code>.
61 * @param currentTrack
62 * optional current track. When {@link Random#ALBUM}, the
63 * provider should start providing an album starting with this
64 * track.
65 */
66 void setRandom(final Random random, final TrackMetadataBean currentTrack);
67
68 /***
69 * Reinitializes itself - polls tracks from the DB etc.
70 */
71 void reset();
72 }