1 package org.musicontroller.service;
2
3 import java.io.File;
4 import java.io.IOException;
5 import java.util.Collection;
6 import java.util.Date;
7 import java.util.List;
8 import java.util.Set;
9
10 import org.musicontroller.core.Artist;
11 import org.musicontroller.core.Band;
12 import org.musicontroller.core.Keyword;
13 import org.musicontroller.core.Keywordbag;
14 import org.musicontroller.core.Playlist;
15 import org.musicontroller.core.Song;
16 import org.musicontroller.gui.edit.PlaylistMergeBean;
17 import org.musicontroller.gui.edit.SongBean;
18 import org.musicontroller.gui.edit.TrackList;
19 import org.musicontroller.importer.MusicArchiveBean;
20 import org.musicontroller.security.IUser;
21 import org.musicontroller.security.User;
22 import org.varienaja.comments.Comment;
23 import org.varienaja.util.coverart.CoverArtSearchResult;
24
25 /**
26 * Defines the service for managing the musicians that
27 * perform on songs.
28 *
29 * @author drexler
30 * @version $Id: McService.java,v 1.1 2010/03/16 18:55:42 varienaja Exp $
31 */
32 public interface McService {
33
34 /**
35 * Adds a band with the given name to the database. If the database already contains a
36 * band with the same name, no new band is created. Returns the created band or the
37 * already existing band as its result.
38 * Band names are compared case insensitive. Band names consisting only of white space
39 * are ignored. Also, NULL values as band names are ignored. In these cases, the result is null.
40 * However, white space in band names is significant. Band names will not be trimmed.
41 *
42 * @param bandName The name of the new band.
43 * @return The band created or retrieved, with the sought band name.
44 */
45 public Band addBand(String bandName);
46
47 /**
48 * Adds the artist as a performer to all songs in the playlist, playing the specified
49 * instruments. Adds the artist if necessary. Removes previous instruments
50 * if the Artist is already present in the database. Relations of other
51 * artists are not affected. This method never removes a relation.
52 * If the user specifies a list of track numbers then this method adds the relation
53 * to the specified tracks only. The track list should be a comma separated list of
54 * track numbers. Invalid track numbers are ignored.
55 * @param playlist The playlist to add the defined Musician-Instrument relation to. Nothing
56 * happens if this is null.
57 * @param artistfirstname The first name of the artis to create/edit.
58 * @param artistlastname The last name of the artis to create/edit. Nothing happens if this
59 * is null.
60 * @param instruments The Instruments the artists plays on this playlist. This is
61 * a comma separated list of instrument names.
62 * @param tracks The tracklist. If the tracklist is null the artist will be added to
63 * all tracks of the playlist.
64 */
65 public void addMusician(Playlist playlist, String artistfirstname, String artistlastname, String instruments, String tracks);
66
67 /**
68 * Return the artist with the given identifier
69 * @param artistId The identifier of the artist sought
70 * @return The artist to find.
71 */
72 public Artist getArtistById(long artistId);
73
74 /**
75 * Adds the artist as a performing artist in the song.
76 * @param song The song to add a performer to. Nothing happens if this is null.
77 * @param artistfirstname The first name of the artis to create/edit.
78 * @param artistlastname The last name of the artis to create/edit.
79 * @param instruments The Instruments the artists plays on this playlist. This is
80 * a comma separated list of instrument names.
81 */
82 public void addMusician(Song song, String artistfirstname, String artistlastname, String instruments);
83
84 /**
85 * Removes the artist-instrument relations specified by the argument from every song in the playlist.
86 * This method will not create an artist with the given first/last name if it doesn't exist already.
87 * In that case, nothing happens.
88 * @param playlist The playlist to remove the artist instrument relation from. Nothing happens if this
89 * is null.
90 * @param artistfirstname The first name of the artist.
91 * @param artistlastname The last name of the artist. Nothing happens if this is null.
92 * @param instruments The instruments (a comma separated string). Nothing happens if this is null.
93 * @param tracks Indicates which tracks should be affected.
94 */
95 public void deleteMusician(Playlist playlist, String artistfirstname, String artistlastname, String instruments, String tracks);
96
97 /**
98 * Deletes the artist as a performing artist in the song. This method will not create an
99 * artist with the given first/last name if it doesn't exist already. In that case, nothing
100 * happens.
101 * @param song The song to remove a performer from. Nothing happens if this is null.
102 * @param artistfirstname The first name of the artis to create/edit.
103 * @param artistlastname The last name of the artis to create/edit. Nothing happens if this is null.
104 * @param instruments The Instruments the artists plays on this playlist. This is
105 * a comma separated list of instrument names. Nothing happens if this is null.
106 */
107 public void deleteMusician(Song song, String artistfirstname, String artistlastname, String instruments);
108
109 /**
110 * Adds the song to the playlist at the given song index.
111 *
112 * @param song The song to add. This parameter must be a persistent song object. If this parameter is null
113 * then nothing happens.
114 * @param playlist The playlist to add the song to. This parameter must be a persistent playlist object.
115 * If this parameter is null then nothing happens.
116 * @param songIndex The song index within the playlist. If the playlist already has a song at this
117 * index, the song index will be set to 0.
118 */
119 public void addSongToPlaylist(Song song, Playlist playlist, int songIndex);
120
121 /**
122 * Edit song properties according to the new values stored in
123 * the songbeans in the supplied list.
124 * @param playlist Specifies the playlist of the songs. Used for
125 * storing the track index numbers of the songs
126 * in this playlist. This parameter may be NULL,
127 * in which case no track index numbers will be set.
128 * @param songbeans The list of songbeans containing the new
129 * song properties.
130 */
131 public void editSongsOfPlaylist(Playlist playlist, List<SongBean> songbeans);
132
133 /**
134 * Edit basic playlist properties: name and releasedate.
135 * @param playlist The playlist to alter.
136 * @param name The playlist name to set. The playlist name is not changed if the
137 * parameter is null or "".
138 * @param releaseDate The release date to set. The releasedate is not changed if
139 * this parameter is null.
140 */
141 public void setPlaylistProperties(Playlist playlist, String name, Date releaseDate);
142
143 /**
144 * Creates a playlist with the given name. There can be more than 1 playlists with
145 * the same name. This method will always create a new persistent playlist. The
146 * release date of the playlist will be set to the system date.
147 * Returns the created playlist.
148 *
149 * @param playlistname The name of the new playlist. Empty names, names consisting only
150 * of whitespaces and null valued playlistnames are invalid and
151 * ignored. The result is NULL in those cases. Trailing and leading
152 * whitespace will be trimmed.
153 * @return The created playlist object.
154 */
155 public Playlist createPlaylist(String playlistname);
156
157 /**
158 * Retrieves the playlist with the specified id. Returns
159 * null if there is no playlist with the specified id.
160 */
161 public Playlist getPlaylistById(long playlistid);
162
163 /**
164 * Merge the playlist with the playlist in the list of beans that have
165 * the mergeIndicator set. The playlists in the bean will be merged into
166 * the playlist in the playlist parameter and deleted.
167 *
168 * @param playlist The playlist to merge.
169 * @param user The user doing the merging.
170 * @param mergeBeanList A list of beans containing possible merge candidates.
171 */
172 public void mergePlaylist(Playlist playlist, IUser user, List<PlaylistMergeBean> mergeBeanList);
173
174 /**
175 * Construct a list with a SongBean object for each song in the playlist. Returns
176 * an empty list if playlist is null.
177 * @param playlist The playlist.
178 * @return The constructed list of song beans.
179 */
180 public List<SongBean> constructSongBeanList(Playlist playlist);
181
182 /**
183 * Construct a list of PlaylistMergeBean objects. The list will contain a
184 * bean for every playlist in the database with the same playlist name as
185 * the playlist in the playlist parameter. Returns an empty list if the playlist
186 * parameter is null or if there are no other playlists with the same name.
187 * @param playlist The playslist
188 * @return A list of PlaylistMergeBean objects.
189 */
190 public List<PlaylistMergeBean> constructMergeBeanList(Playlist playlist);
191
192 /**
193 * Returns a list of available cover art for the playlist. This method will try to
194 * determine the band performing on the playlist. If the playlist contains songs by different
195 * bands then the band name used will be 'various'. The playlist mut have a name.
196 *
197 * @param playlist The playlist.
198 * @return A list of available cover art for this playlist.
199 */
200 public Collection<CoverArtSearchResult> getCoverArtList(Playlist playlist);
201
202 /**
203 * Returns a list of available cover art for the named playlist by the named band. Both bandName
204 * and playlist name must be specified, or this returns an empty list.
205 * @param bandName The band name.
206 * @param playlistName The playlist name.
207 * @return A list of available playlist cover art.
208 */
209 public Collection<CoverArtSearchResult> getCoverArtList(String bandName, String playlistName);
210
211 /**
212 * Creates a persistent song with the given name.
213 * @param songname The name of the song to create. The name must not be null and must
214 * contain a non whitespace character. Otherwise, no song is created and the
215 * result is null. Leading and trailing whitespace is removed.
216 * @param band The band of the new song. This parameter must contain a persistent band.
217 * Otherwise, no song is created and the result is null.
218 * @param length The lenght of the song in milliseconds.
219 * @param keywords The set of keywords of the song.
220 * @param destination The file name of the media file containg the song.
221 */
222 public Song createSong(String songname, Band band, int length, Set<String> keywords, String destination);
223
224 /**
225 * Return the song with a given identifier.
226 * @param songid The idenitfier.
227 * @return The song with the specified identifier.
228 */
229 public Song getSongById(long songid);
230
231 /**
232 * Return a playlist with a prediction of the next 6 songs the
233 * DJ will play for the specified user.
234 * @param userid The user.
235 * @return A Playlist containing the 6 upcoming songs that the DJ will
236 * play if no new requests/unrequests are made.
237 */
238 public Playlist getUpcoming(long userid);
239
240 /**
241 * Sets the song name, the song length in milliseconds and the song keywords
242 * according to the parameters specified.
243 * @param song The song to change.
244 * @param name The new song name. White space will be trimmed. The name will
245 * not change if the new name is null or empty after trimming.
246 * @param bandName The name of the band performing the song. The song will be
247 * moved to the band with this name. A new band will be made
248 * if it does not exist. If the bandname is null or empty after
249 * stripping white space, the band will not change.
250 * @param msecs The new song length in milliseconds. Zero or negative values
251 * will have no effect.
252 * @param keywords The new comma separated list of keywords.
253 */
254 public void setSongProperties(Song song,String name,String bandName,int msecs,String keywords);
255
256 /**
257 * Returns a list of playlist containing the song.
258 * @param song The song to look for.
259 * @return A list of playlists containing the song.
260 */
261 public List<Playlist> getSongPlaylists(Song song);
262
263 /**
264 * Returns a playlist of songs that were played to a user
265 * close before or after a song.
266 * @param song The song whose neighbours must be found.
267 * @param user The user.
268 * @return A Playlist containing the neighbours.
269 */
270 public Playlist getSongNeighbours(Song song, IUser user);
271
272 /**
273 * Returns a playlist with all songs played by the band.
274 * @param band The band.
275 * @return A playlist with all songs played by the band.
276 */
277 public Playlist getSongsByBand(Band band);
278
279 /**
280 * Return the band with a given identifier.
281 * @param bandid The idenitfier.
282 * @return The band with the specified identifier.
283 */
284 public Band getBandById(long bandid);
285
286 /**
287 * Returns a list of playlists containing at least one song by this band.
288 * @param band The band to look for.
289 * @return A list of playlists containing a song by the band.
290 */
291 public List<Playlist> getBandPlaylists(Band band);
292
293 /**
294 * Sets the band name and comments string according to the specified parameters.
295 * @param band The band to modify.
296 * @param bandName The new band name. If a band with this name already exists,
297 * then the 2 bands will be merged. If the trimmed band name is null or
298 * empty, no change occurs.
299 */
300 public void setBandProperties(Band band, String bandName);
301
302 /**
303 * @return Returns a list of Object-arrays. The first element of the array is the bandId (Long).
304 * The second element is the bandname (String), the third element is the amount of play-events
305 * for that band for the given User during the last year (Long).
306 * @param user The User to get this list for.
307 */
308 public List<Object[]> listBands(IUser user);
309
310 /**
311 * Returns the keyword with the id of the parameter.
312 * @param selectedKeywordId The id of the wanted keyword.
313 * @return The keyword with the given id.
314 */
315 public Keyword getKeywordById(Long selectedKeywordId);
316
317 /**
318 * Returns a list of all keyword bags containing all the keywords in the "selectedKeywordIds"
319 * parameter. If the parameter is null, then the result is null.
320 * @param selectedKeywordIds The list of keyword ids of the keywords that have to be present in
321 * all keyword bags in the result.
322 * @return a list of keyword bags containing all keywords in the selectedKeywordIds parameter.
323 */
324 public List<Keywordbag> getKeywordBagsWithKeywords(List<Long> selectedKeywordIds);
325
326 /**
327 * @return Returns a list of String-arrays. The first element of the array is the keywordId.
328 * The second element is the keywordname, the third element is the amount of play-events
329 * for that keyword for the given User during the last year. If the bags parameter is non-null,
330 * then only keywords occurring in the ketword bags in bags are included.
331 * @param user The User to get this list for.
332 * @param bags The Keywordbags to show Keywords of (or null to show all keywords)
333 */
334 public List<Object[]> listKeywords(IUser user, List<Keywordbag> bags);
335
336 /**
337 * Generates a Playlist containing songs that belong to the specified
338 * Keywordbags. The songs in the Playlist are ordered by the amount
339 * of play-events of the specified User during the last year.
340 * @param bags The Keywordbag(s) the Song could be in. If this parameter is null,
341 * an empty Playlist is returned.
342 * @param user The User-object (Used for sorting according to listening-habits). If
343 * this parameter is null, anonymous sorting is used.
344 * @param i Specifiec the maximum amount of records to return. Pass a
345 * value >0 to show all matches.
346 * @return A Playlist consisting of Songs that matched any of the given Keywordbags.
347 */
348 public Playlist songsByKeywordbags(List<Keywordbag> bags, User user, int i);
349
350 /**
351 * Adds the keywords in the comma separated list to the playlist.
352 * @param playlist The playlist. If this is null, nothing happens.
353 * @param keywords The comma separated list of keywords to add.
354 * @param tracks If not null, add the keywords only to the tracks in the track list.
355 */
356 public void addKeywordsToPlaylist(Playlist playlist, String keywords, TrackList tracks);
357
358 /**
359 * Removes the keywords in the comma separated list from the playlist.
360 * @param playlist The playlist. If this is null, nothing happens.
361 * @param keywords The comma separated list of keywords to remove.
362 * @param tracks If not null, remove the keywords only from the tracks in the track list.
363 */
364 public void removeKeywordsFromPlaylist(Playlist playlist, String keywords, TrackList tracks);
365
366 /**
367 * Use the image in the CoverArtSearchResult to update the coverart
368 * for the playlist. The CoverArtSearchResult contains an URL that points to the cover
369 * art image. All existing cover images for this playlist are deleted.
370 * @param playlist The playlist to set the cover art for. If null, the request is ignored.
371 * @param selected The selected cover art. If null, the request is ignored. If the URL inside
372 * this is NULL, the request is ignored. If the URI is non absolute, MusiController
373 * adds the "file:" protocol to it.
374 * @throws IOException Something went wrong when downloading the image or storing the image on disk.
375 */
376 public void setPlaylistCoverArt(Playlist playlist, CoverArtSearchResult selected) throws IOException;
377
378 /**
379 * Test the existence of a cover art image with the required size.
380 * @param playlistid The id of the playlist for which the cover art is requested.
381 * @param size The requested image size.
382 * @param return A file with the requested cover art image.
383 */
384 public File attemptToDownloadCoverArt(long playlistid, int size);
385
386 /**
387 * Tries to find persistent playlists that matches the playlist name of 1 or more entries in the music archive.
388 * @param archive The music archive.
389 * @return The playlists that could be the playlist in the music archive.
390 */
391 public List<Playlist> findImportedPlaylist(MusicArchiveBean archive);
392
393 /**
394 * Return a guess about the band on the cover of a playlist. Iterates through the
395 * songs. If all songs are performed by the same band, then it returns that band name.
396 * If there are more than 1 names, then it returns "Various". If there are no songs or
397 * if all songs have empty band names, then the result is "Unknown".
398 * @return A Guessed band name that could be on the cover of the playlist.
399 */
400 public String guessBandNameOfArchive(MusicArchiveBean archive);
401
402 /**
403 * Returns a (possibly empty) sorted set of reviews for a Playlist.
404 * @param playlist The playlist tot get the reviews for
405 * @return A list of Reviews.
406 */
407 public Set<Comment> getReviews(Playlist playlist);
408
409 /**
410 * Returns a (possibly empty) sorted set of reviews for a Band.
411 * @param band The Band tot get the reviews for
412 * @return A list of Reviews.
413 */
414 public Set<Comment> getReviews(Band band);
415
416 /**
417 * Compile a set of persistent playlists that could be the same as the contents of the music archive.
418 * @param archive The music archive.
419 * @return A set of playlists that could be contained in the music archive.
420 */
421 public Set<Playlist> guessPlaylistsInArchive(MusicArchiveBean archive);
422
423 /**
424 * Returns a list of playlists with the same name as the parameter.
425 * @param playlistName The name of the playlist.
426 * @return
427 */
428 public List<Playlist> searchPlaylistByName(String playlistName);
429 }