1 package org.musicontroller.songselection;
2
3 import java.util.List;
4
5 import org.musicontroller.core.Song;
6
7 /**
8 * Randomly selects a preset number of songs from the song pool.
9 * The Candidate selector does not know the user for which the
10 * candidates are selected.
11 */
12 public interface CandidateSelector {
13
14 /**
15 * Selects candidate-Songs from the pool.
16 * If requests were made, all those requests are returned, even if there
17 * are more than candidatecount of them.
18 * @param requests An optional list of requested songs.
19 * @return A list of candidate Songs
20 */
21 public List<Song> selectCandidates(List<Long> requests);
22
23 /**
24 * Selects a selection of candidate-Songs from the pool.
25 * @param count The amount of candidates to select. When this value is
26 * bigger than the amount of songs available in the pool, a
27 * as much Songs as possible are returned.
28 * @return A list of candidate Songs, in which no Song appears more than
29 * once.
30 */
31 public List<Song> selectCandidates(int count);
32
33 /**
34 * Adds a Song to the pool.
35 * @param song The Song to add.
36 */
37 public void addToCandidates(Song song);
38
39 /**
40 * Removes a Song from the pool.
41 * @param song The Song to remove.
42 */
43 public void removeFromCandidates(Song song);
44
45 /**
46 * Returns true if the requests will be played at random
47 * or false otherwise.
48 * @return True if the requests will be played at random.
49 */
50 public boolean requestsPlayedAtRandom();
51
52 /**
53 * Returns true if the requests will be played in order
54 * of entry or false otherwise.
55 * @return True if the requests will be played in the order
56 * of entry.
57 */
58 public boolean requestsPlayedInOrder();
59
60 /**
61 * Instructs the selector to select requested songs in the
62 * order of entry.
63 * TODO if this setting changes, the DJ must revise its predictions
64 */
65 public void playRequestsInOrder();
66
67 /**
68 * Instructs the selector to play the requested songs in
69 * random order.
70 * TODO if this setting changes, the DJ must revise its predictions
71 */
72 public void playRequestsAtRandom();
73
74 /**
75 * Getter for the number of candidates that will be returned in a list of
76 * candidate Songs.
77 * @return The size of the candidate list.
78 */
79 public int getCandidateCount();
80 }