1 package org.musicontroller.dao;
2
3 import java.util.Collection;
4 import java.util.List;
5 import java.util.Map;
6
7 import org.hibernate.SessionFactory;
8 import org.musicontroller.SongChangeListener;
9 import org.musicontroller.core.AIBag;
10 import org.musicontroller.core.Artist;
11 import org.musicontroller.core.Band;
12 import org.musicontroller.core.Instrument;
13 import org.musicontroller.core.Keyword;
14 import org.musicontroller.core.Keywordbag;
15 import org.musicontroller.core.Link;
16 import org.musicontroller.core.Playlist;
17 import org.musicontroller.core.Song;
18 import org.musicontroller.security.IUser;
19 import org.musicontroller.security.UserDao;
20 import org.springframework.orm.hibernate3.HibernateTemplate;
21
22 public interface Dao extends UserDao {
23 public List<Long> getSongIds();
24
25 /**
26 * Retrieves the song with the given id from the database.
27 * @param id The song id.
28 * @return The song with the given identifier.
29 */
30 public Song getSongById(long id);
31
32 /**
33 * Retrieves a number of songs from the database, corresponding
34 * with the given Ids.
35 * @param ids The ids to get. This must not be null.
36 * @return A List of Song-objects
37 */
38 public List<Song> getSongsById(Collection<Long> ids);
39
40
41 /**
42 * Retrieves the band with the given id from the database.
43 * @param id The band id.
44 * @return The band with the given identifier.
45 */
46 public Band getBandById(long id);
47
48 /**
49 * Retrieves the band with the given name from the database. If there ares
50 * more than one Band with this name, the result is the Band that has
51 * been in the Database longest.
52 * @param name The band name.
53 * @return The band with the given name.
54 */
55 public Band getBandByName(String name);
56
57 /**
58 * Retrieves the keyword with the given id from the database.
59 * @param id The keyword id.
60 * @return The keyword with the given identifier.
61 */
62 public Keyword getKeywordById(long id);
63
64 /**
65 * Retrieves the keyword bag with the given id from the database.
66 * @param id The keyword bag id.
67 * @return The keyword bagwith the given identifier.
68 */
69 public Keywordbag getKeywordBagById(long id);
70
71 /**
72 * Retrieves the artist with the given id from the database.
73 * @param id The artist id.
74 * @return The artist with the given identifier.
75 */
76 public Artist getArtistById(long id);
77
78 /**
79 * Retrieves the ai_bag with the given id from the database.
80 * @param id The ai_bag id.
81 * @return The ai_bag with the given identifier.
82 */
83 public AIBag getAIBagById(long id);
84
85 /**
86 * Retrieves the instrument with the given id from the database.
87 * @param id The instrument id.
88 * @return The instrument with the given identifier.
89 */
90 public Instrument getInstrumentById(long id);
91
92 /**
93 * Returns a specific Playlist
94 * @param playlistid The requested playlist id.
95 * @param user The user to use for retrieving "special" playlists.
96 * @return The Playlist, or null if a Playlist with the given id doesn't exist.
97 */
98 public Playlist getPlaylistById(long playlistid, IUser user);
99
100 /**
101 * Retrieves the Playlist with the given name from the database. If there are
102 * more than one Playlists with this name, the result is the Playlist that has
103 * been in the Database longest.
104 * @param name The playlist name.
105 * @return The Playlist with the given name.
106 */
107 public Playlist getPlaylistByName(String name);
108
109 public Playlist songsByBand(long bandid);
110 public Playlist songsByKeyword(long keywordid);
111
112 /**
113 * Generates a Playlist containing songs that belong to the specified
114 * Keywordbags. The songs in the Playlist are ordered by the amount
115 * of play-events of the specified User during the last year.
116 * @param bags The Keywordbag(s) the Song could be in. If this parameter is null,
117 * an empty Playlist is returned.
118 * @param user The User-object (Used for sorting according to listening-habits). If
119 * this parameter is null, anonymous sorting is used.
120 * @param maxResults Specifiec the maximum amount of records to return. Pass a
121 * value >0 to show all matches.
122 * @return A Playlist consisting of Songs that matched any of the given Keywordbags.
123 */
124 public Playlist songsByKeywordbags(List<Keywordbag> bags, IUser user, int maxResults);
125 public Playlist songsByKeywords(List<Keyword> keywords, IUser user);
126 public Playlist songsByKeywordIds(List<Long> keywordIds, IUser user);
127
128 /**
129 * Returns a Playlist containing Songs that are neighbours of the given Song
130 * and User. Neighbours are Songs that are played or requested at least five
131 * times 10 minutes before or after this song was played or requested. The
132 * resulting Playlist is sorted by the amount of 'together-played'-hits.
133 * @param songid The Song to get the neighbours for.
134 * @param user The User for whom to inspect the played and requested-Events
135 * @return A Playlist, containing the Neighbouring Songs.
136 */
137 public Playlist getNeighbours(long songid, IUser user);
138
139 /**
140 * Searches the database for songs that are stored more than one time in
141 * the database.
142 * @return A List of Long-pairs with songIDs.
143 */
144 public List<Long[]> getDoubleSongs();
145
146 /**
147 * Merges two songs to one. All events, occurences on playlists, etc. will be merged.
148 * @param keep This song stays.
149 * @param remove This song will be removed.
150 */
151 public void mergeSongs(Song keep, Song remove);
152
153 /**
154 * Searches in the Database, and returns the objects that were selected.
155 * @param hql The HQL-query.
156 * @param params Query parameters as name,value pairs
157 * @param maxResults The maximum amount of objects to return. Use 0 for all results.
158 * @return The objects that fit to the search-query.
159 */
160 @SuppressWarnings("unchecked")
161 public List search(String hql, Map<String,Object> params, int maxResults);
162
163 /**
164 * Searches in the Database, and returns the objects that were selected.
165 * @param hql The HQL-query.
166 * @param params Query parameters as name,value pairs
167 * @param maxResults The maximum amount of objects to return. Use 0 for all results.
168 * @param offset The first <i>offset</i> objects will not be returned
169 * @return The objects that fit to the search-query.
170 */
171 @SuppressWarnings("unchecked")
172 public List search(String hql, Map<String,Object> params, int maxResults, int offset);
173
174 /**
175 * Locate and load the band with the given name. Returns NULL if
176 * there is no band with the given name. If there are more bands
177 * with this name this method returns one of them.
178 *
179 * @param bandname The band name.
180 * @return The band with the given name.
181 */
182 public Band searchBand(String bandname);
183
184 /**
185 * Merge two bands, moving all songs from one to the other. The artists
186 * relations of the removed band are lost.
187 * @param keep Keep this band. Add all songs of the other band to this band.
188 * @param remove The band to remove, moving all songs to the other band.
189 */
190 public void mergeBands(Band keep, Band remove);
191
192 /**
193 * Find a keyword matching the given keyword-string.
194 * @param keyworddesc The desired keyword string.
195 * @return A keyword with the desired text or null if it does not exist.
196 */
197 public Keyword searchKeyword(String keyworddesc);
198
199 /**
200 * Find a playlist matching the given name. The search is case sensitive. Returns
201 * an empty list if the playlist name parameter is null or if no playlist with
202 * that name exists.
203 * @param playlistname The desired playlist name.
204 * @return A playlist with the desired name or null if it does not exist.
205 */
206 public List<Playlist> searchPlaylist(String playlistname);
207
208 /**
209 * Find an artist matching the given first and last name.
210 * @param artistfirstname The desired artist name. May be null.
211 * @param artistlastname The desired artist last name. The result is null
212 * if this is null.
213 * @return An artist with the desired name or null if it does not exist.
214 */
215 public Artist searchArtist(String artistfirstname, String artistlastname);
216
217
218 /**
219 * Return a list of all appearances of an artist in songs.
220 * @param artistid The artist to search.
221 * @return
222 */
223 public AIBag getArtistAppearances(long artistid);
224
225 /**
226 * Persist the properties of this band.
227 * @param band The band to persist.
228 */
229 public void save(Band band);
230
231 /**
232 * Persist the properties of this keyword.
233 * @param keyword The keyword to persist.
234 */
235 public void save(Keyword keyword);
236
237 /**
238 * Persist a keyword bag.
239 * @param keywordbag The keyword bag to persist.
240 */
241 public void save(Keywordbag keywordbag);
242
243 /**
244 * Persist the properties of this playlist.
245 * @param playlist The playlist to persist.
246 */
247 public void save(Playlist playlist);
248
249 /**
250 * Persist the properties of this link.
251 * @param link The link to persist.
252 */
253 public void save(Link link);
254
255 /**
256 * Persist the properties of this song.
257 * @param song The song to persist.
258 */
259 public void save(Song song);
260
261 /**
262 * Persist the properties of this artist.
263 * @param artist The artist to persist.
264 */
265 public void save(Artist artist);
266
267 /**
268 * Persist the properties of this Instrument.
269 * @param instr The instrument to persist.
270 */
271 public void save(Instrument instr);
272
273 /**
274 * Persist the properties of this AIBag.
275 * @param aibag The AIBag to persist.
276 */
277 public void save(AIBag aibag);
278
279 /**
280 * Find a song with the given name performed by the specified band.
281 * If there is more than 1 song matching the name and band, this method returns
282 * one of them. Returns if a matching song does not exist.
283 * @param band The band
284 * @param songname The song name.
285 * @return A song matching the band and song name, or NULL if there is no such song.
286 */
287 public Song getSong(Band band, String songname);
288
289 /**
290 * Searches for a User, and returns if, if found.
291 * @param username The username to search for
292 * @return The User, or null if no User with a matching name could be found
293 */
294 public IUser findUserByName(String username);
295
296 /**
297 * Lists all playlists on which a band is present.
298 * @param band The Band to search Playlists for.
299 * @return A list of Playlists on which songs exist of the Band
300 */
301 public List<Playlist> listPlaylists(Band band);
302 public List<Playlist> listPlaylists(Song song);
303
304 /**
305 * Lists all Playlists.
306 * @return All Playlists.
307 */
308 public List<Playlist> listPlaylists();
309
310 /**
311 * Lists all Playlists that contain Podcasts.
312 * @return All Playlists that contain Podcasts.
313 */
314 public List<Playlist> listPodcasts();
315
316 public void evictSong(long songid);
317 public void evict(Object o);
318
319 /**
320 * @return Returns a list of String-arrays. The first element of the array is the bandId.
321 * The second element is the bandname, the third element is the amount of play-events
322 * for that band for the given User during the last year, the fourth element en the amount
323 * of skip-events for that band during the last year.
324 * @param user The User to get this list for.
325 */
326 public List<Object[]> listBands(IUser user);
327
328 /**
329 * Lists all known Keywords.
330 * @return All Keywords in no particular order.
331 */
332 public List<Keyword> listKeywords();
333
334 /**
335 * @return Returns a list of String-arrays. The first element of the array is the keywordId.
336 * The second element is the keywordname, the third element is the amount of play-events
337 * for that keyword for the given User during the last year, the fourth element is the amount
338 * of skip-events for that keyword during the last year. If the bags parameter is non-null,
339 * then only keywords occurring in the ketword bags in bags are included.
340 * @param user The User to get this list for.
341 * @param bags The Keywordbags to show Keywords of (or null to show all keywords)
342 */
343 public List<Object[]> listKeywords(IUser user, List<Keywordbag> bags);
344
345 /**
346 * Returns a list with all keyword bags that contain at least all keywords given in
347 * the "keywords" parameter.
348 * @param keywords The list of keywords that hava to be present in each keyword bag in
349 * the result. If this parameter is null or empty, the result is null.
350 * @return A list of Keywordbags containing all keywords given.
351 */
352 public List<Keywordbag> listKeywordsBags(List<Keyword> keywords);
353
354 /**
355 * @param keywords
356 * @return A list of Keywordbags containing exactly all keywords given, no more, no less.
357 */
358 public Keywordbag getKeywordsBag(Collection<Keyword> keywords);
359
360 /**
361 * @return Returns a list of String-arrays. The first element of the array is the
362 * month, the second element is the year and the third element is the amount of songs
363 * that were added to the database in that month.
364 */
365 public List<Object[]> listMonthlySongCounts();
366
367 /**
368 * Returns per-user play-statistics. This method queries the database, and
369 * returns a Map containing String -> Integer relations. These releations
370 * are constructed as follows:
371 * "yyyy,mm,k" -> x
372 *
373 * where mm is the month,
374 * yyyy is the year,
375 * k is the eventkind
376 * and x is the amount of such events
377 *
378 * @see org.musicontroller.core.Event
379 * @param user The user to gather these statistics for.
380 * @return The Map as stated above. The order of the keys in the returned map
381 * is guaranteed to be alphabetical.
382 */
383 public Map<String, Integer> listMonthlyStatistics(IUser user);
384
385 /**
386 * @return Returns a list of Object-arrays. The first element of the array is the
387 * name (String) of a namable item. The second is the id (Long).
388 * Namable items are all items in the database that both have a name and an id.
389 * (Bands, Artists, Playlists, Songs, Instruments, Keywords)
390 */
391 public List<Object[]> listNamableItems();
392
393 /**
394 * Returns a list of all Keyword bags.
395 * @return A list of all keyword bags.
396 */
397 public List<Keywordbag> listKeywordbags();
398
399 /**
400 * Returns the instrument with the given instrument name or NULL if
401 * there is no instrument with the given name.
402 * @param instrname The intsrument name.
403 * @return The instrument with the given name.
404 */
405 public Instrument searchInstrument(String instrname);
406
407 public int count(String hql, Map<String,Object> params) throws Exception;
408
409 /**
410 * Searches the database for the most used AIBag for this band.
411 * This comes in handy when a user needs to have a hint for which artists and
412 * instruments to choose for a new song.
413 * @param band The Band
414 * @return A suggestion for a AIBag for a new song of this band.
415 */
416 public AIBag getMostUsedAIBag(Band band);
417
418 /**
419 * Returns a list of all Artist-Instrument bags.
420 * @return A list of all Artist-Instrument bags.
421 */
422 public List<AIBag> listAIBags();
423
424 /**
425 * Merge the two playlists into one. There is no effect if one or both of the
426 * arguments are null.
427 * @param keep This playlist will receive all songs from the other playlist.
428 * @param delete This The songs of this playlist will be moved to the other playlist
429 * and this playlist will be deleted.
430 */
431 public void mergePlaylists(Playlist keep, Playlist delete);
432
433 /**
434 * Deletes an artist. Nothing happens if the 'delete' argument is null.
435 * @param delete The artist to delete.
436 */
437 public void deleteArtist(Artist delete);
438
439 /**
440 * Deletes an AIBag. Nothing happens if the 'delete' argument is null.
441 * @param delete The AIBag to delete.
442 */
443 public void deleteAiBag(AIBag delete);
444
445 /**
446 * Returns the SessionFactory.
447 * @return The SessionFactory.
448 */
449 public SessionFactory getSessionFactory2();
450
451 /**
452 * Adds a SongChangeListener to the internal list of listeners. The listener
453 * will be informed about all Song-changes that happen after registration.
454 * @param listener The SongChangeListener to register.
455 */
456 public void registerSongChangeListener(SongChangeListener listener);
457
458 public HibernateTemplate getSupport();
459 }