org.musicontroller.service
Interface McService

All Known Implementing Classes:

McServiceImpl

public interface McService

Defines the service for managing the musicians that perform on songs.

Version:

$Id: McService.java,v 1.1 2010/03/16 18:55:42 varienaja Exp $

Author:

drexler

Method Summary

Band	addBand(java.lang.String bandName) Adds a band with the given name to the database.
void	addKeywordsToPlaylist(Playlist playlist, java.lang.String keywords, TrackList tracks) Adds the keywords in the comma separated list to the playlist.
void	addMusician(Playlist playlist, java.lang.String artistfirstname, java.lang.String artistlastname, java.lang.String instruments, java.lang.String tracks) Adds the artist as a performer to all songs in the playlist, playing the specified instruments.
void	addMusician(Song song, java.lang.String artistfirstname, java.lang.String artistlastname, java.lang.String instruments) Adds the artist as a performing artist in the song.
void	addSongToPlaylist(Song song, Playlist playlist, int songIndex) Adds the song to the playlist at the given song index.
java.io.File	attemptToDownloadCoverArt(long playlistid, int size) Test the existence of a cover art image with the required size.
java.util.List<PlaylistMergeBean>	constructMergeBeanList(Playlist playlist) Construct a list of PlaylistMergeBean objects.
java.util.List<SongBean>	constructSongBeanList(Playlist playlist) Construct a list with a SongBean object for each song in the playlist.
Playlist	createPlaylist(java.lang.String playlistname) Creates a playlist with the given name.
Song	createSong(java.lang.String songname, Band band, int length, java.util.Set<java.lang.String> keywords, java.lang.String destination) Creates a persistent song with the given name.
void	deleteMusician(Playlist playlist, java.lang.String artistfirstname, java.lang.String artistlastname, java.lang.String instruments, java.lang.String tracks) Removes the artist-instrument relations specified by the argument from every song in the playlist.
void	deleteMusician(Song song, java.lang.String artistfirstname, java.lang.String artistlastname, java.lang.String instruments) Deletes the artist as a performing artist in the song.
void	editSongsOfPlaylist(Playlist playlist, java.util.List<SongBean> songbeans) Edit song properties according to the new values stored in the songbeans in the supplied list.
java.util.List<Playlist>	findImportedPlaylist(MusicArchiveBean archive) Tries to find persistent playlists that matches the playlist name of 1 or more entries in the music archive.
Artist	getArtistById(long artistId) Return the artist with the given identifier
Band	getBandById(long bandid) Return the band with a given identifier.
java.util.List<Playlist>	getBandPlaylists(Band band) Returns a list of playlists containing at least one song by this band.
java.util.Collection<CoverArtSearchResult>	getCoverArtList(Playlist playlist) Returns a list of available cover art for the playlist.
java.util.Collection<CoverArtSearchResult>	getCoverArtList(java.lang.String bandName, java.lang.String playlistName) Returns a list of available cover art for the named playlist by the named band.
java.util.List<Keywordbag>	getKeywordBagsWithKeywords(java.util.List<java.lang.Long> selectedKeywordIds) Returns a list of all keyword bags containing all the keywords in the "selectedKeywordIds" parameter.
Keyword	getKeywordById(java.lang.Long selectedKeywordId) Returns the keyword with the id of the parameter.
Playlist	getPlaylistById(long playlistid) Retrieves the playlist with the specified id.
java.util.Set<Comment>	getReviews(Band band) Returns a (possibly empty) sorted set of reviews for a Band.
java.util.Set<Comment>	getReviews(Playlist playlist) Returns a (possibly empty) sorted set of reviews for a Playlist.
Song	getSongById(long songid) Return the song with a given identifier.
Playlist	getSongNeighbours(Song song, IUser user) Returns a playlist of songs that were played to a user close before or after a song.
java.util.List<Playlist>	getSongPlaylists(Song song) Returns a list of playlist containing the song.
Playlist	getSongsByBand(Band band) Returns a playlist with all songs played by the band.
Playlist	getUpcoming(long userid) Return a playlist with a prediction of the next 6 songs the DJ will play for the specified user.
java.lang.String	guessBandNameOfArchive(MusicArchiveBean archive) Return a guess about the band on the cover of a playlist.
java.util.Set<Playlist>	guessPlaylistsInArchive(MusicArchiveBean archive) Compile a set of persistent playlists that could be the same as the contents of the music archive.
java.util.List<java.lang.Object[]>	listBands(IUser user)
java.util.List<java.lang.Object[]>	listKeywords(IUser user, java.util.List<Keywordbag> bags)
void	mergePlaylist(Playlist playlist, IUser user, java.util.List<PlaylistMergeBean> mergeBeanList) Merge the playlist with the playlist in the list of beans that have the mergeIndicator set.
void	removeKeywordsFromPlaylist(Playlist playlist, java.lang.String keywords, TrackList tracks) Removes the keywords in the comma separated list from the playlist.
java.util.List<Playlist>	searchPlaylistByName(java.lang.String playlistName) Returns a list of playlists with the same name as the parameter.
void	setBandProperties(Band band, java.lang.String bandName) Sets the band name and comments string according to the specified parameters.
void	setPlaylistCoverArt(Playlist playlist, CoverArtSearchResult selected) Use the image in the CoverArtSearchResult to update the coverart for the playlist.
void	setPlaylistProperties(Playlist playlist, java.lang.String name, java.util.Date releaseDate) Edit basic playlist properties: name and releasedate.
void	setSongProperties(Song song, java.lang.String name, java.lang.String bandName, int msecs, java.lang.String keywords) Sets the song name, the song length in milliseconds and the song keywords according to the parameters specified.
Playlist	songsByKeywordbags(java.util.List<Keywordbag> bags, User user, int i) Generates a Playlist containing songs that belong to the specified Keywordbags.

Method Detail

addBand

Band addBand(java.lang.String bandName)

Adds a band with the given name to the database. If the database already contains a band with the same name, no new band is created. Returns the created band or the already existing band as its result. Band names are compared case insensitive. Band names consisting only of white space are ignored. Also, NULL values as band names are ignored. In these cases, the result is null. However, white space in band names is significant. Band names will not be trimmed.

Parameters:

bandName - The name of the new band.

Returns:

The band created or retrieved, with the sought band name.

addMusician

void addMusician(Playlist playlist,
                 java.lang.String artistfirstname,
                 java.lang.String artistlastname,
                 java.lang.String instruments,
                 java.lang.String tracks)

Adds the artist as a performer to all songs in the playlist, playing the specified instruments. Adds the artist if necessary. Removes previous instruments if the Artist is already present in the database. Relations of other artists are not affected. This method never removes a relation. If the user specifies a list of track numbers then this method adds the relation to the specified tracks only. The track list should be a comma separated list of track numbers. Invalid track numbers are ignored.

Parameters:

playlist - The playlist to add the defined Musician-Instrument relation to. Nothing happens if this is null.

artistfirstname - The first name of the artis to create/edit.

artistlastname - The last name of the artis to create/edit. Nothing happens if this is null.

instruments - The Instruments the artists plays on this playlist. This is a comma separated list of instrument names.

tracks - The tracklist. If the tracklist is null the artist will be added to all tracks of the playlist.

getArtistById

Artist getArtistById(long artistId)

Return the artist with the given identifier

Parameters:

artistId - The identifier of the artist sought

Returns:

The artist to find.

addMusician

void addMusician(Song song,
                 java.lang.String artistfirstname,
                 java.lang.String artistlastname,
                 java.lang.String instruments)

Adds the artist as a performing artist in the song.

Parameters:

song - The song to add a performer to. Nothing happens if this is null.

artistfirstname - The first name of the artis to create/edit.

artistlastname - The last name of the artis to create/edit.

instruments - The Instruments the artists plays on this playlist. This is a comma separated list of instrument names.

deleteMusician

void deleteMusician(Playlist playlist,
                    java.lang.String artistfirstname,
                    java.lang.String artistlastname,
                    java.lang.String instruments,
                    java.lang.String tracks)

Removes the artist-instrument relations specified by the argument from every song in the playlist. This method will not create an artist with the given first/last name if it doesn't exist already. In that case, nothing happens.

Parameters:

playlist - The playlist to remove the artist instrument relation from. Nothing happens if this is null.

artistfirstname - The first name of the artist.

artistlastname - The last name of the artist. Nothing happens if this is null.

instruments - The instruments (a comma separated string). Nothing happens if this is null.

tracks - Indicates which tracks should be affected.

deleteMusician

void deleteMusician(Song song,
                    java.lang.String artistfirstname,
                    java.lang.String artistlastname,
                    java.lang.String instruments)

Deletes the artist as a performing artist in the song. This method will not create an artist with the given first/last name if it doesn't exist already. In that case, nothing happens.

Parameters:

song - The song to remove a performer from. Nothing happens if this is null.

artistfirstname - The first name of the artis to create/edit.

artistlastname - The last name of the artis to create/edit. Nothing happens if this is null.

instruments - The Instruments the artists plays on this playlist. This is a comma separated list of instrument names. Nothing happens if this is null.

addSongToPlaylist

void addSongToPlaylist(Song song,
                       Playlist playlist,
                       int songIndex)

Adds the song to the playlist at the given song index.

Parameters:

song - The song to add. This parameter must be a persistent song object. If this parameter is null then nothing happens.

playlist - The playlist to add the song to. This parameter must be a persistent playlist object. If this parameter is null then nothing happens.

songIndex - The song index within the playlist. If the playlist already has a song at this index, the song index will be set to 0.

editSongsOfPlaylist

void editSongsOfPlaylist(Playlist playlist,
                         java.util.List<SongBean> songbeans)

Edit song properties according to the new values stored in the songbeans in the supplied list.

Parameters:

playlist - Specifies the playlist of the songs. Used for storing the track index numbers of the songs in this playlist. This parameter may be NULL, in which case no track index numbers will be set.

songbeans - The list of songbeans containing the new song properties.

setPlaylistProperties

void setPlaylistProperties(Playlist playlist,
                           java.lang.String name,
                           java.util.Date releaseDate)

Edit basic playlist properties: name and releasedate.

Parameters:

playlist - The playlist to alter.

name - The playlist name to set. The playlist name is not changed if the parameter is null or "".

releaseDate - The release date to set. The releasedate is not changed if this parameter is null.

createPlaylist

Playlist createPlaylist(java.lang.String playlistname)

Creates a playlist with the given name. There can be more than 1 playlists with the same name. This method will always create a new persistent playlist. The release date of the playlist will be set to the system date. Returns the created playlist.

Parameters:

playlistname - The name of the new playlist. Empty names, names consisting only of whitespaces and null valued playlistnames are invalid and ignored. The result is NULL in those cases. Trailing and leading whitespace will be trimmed.

Returns:

The created playlist object.

getPlaylistById

Playlist getPlaylistById(long playlistid)

Retrieves the playlist with the specified id. Returns null if there is no playlist with the specified id.

mergePlaylist

void mergePlaylist(Playlist playlist,
                   IUser user,
                   java.util.List<PlaylistMergeBean> mergeBeanList)

Merge the playlist with the playlist in the list of beans that have the mergeIndicator set. The playlists in the bean will be merged into the playlist in the playlist parameter and deleted.

Parameters:

playlist - The playlist to merge.

user - The user doing the merging.

mergeBeanList - A list of beans containing possible merge candidates.

constructSongBeanList

java.util.List<SongBean> constructSongBeanList(Playlist playlist)

Construct a list with a SongBean object for each song in the playlist. Returns an empty list if playlist is null.

Parameters:

playlist - The playlist.

Returns:

The constructed list of song beans.

constructMergeBeanList

java.util.List<PlaylistMergeBean> constructMergeBeanList(Playlist playlist)

Construct a list of PlaylistMergeBean objects. The list will contain a bean for every playlist in the database with the same playlist name as the playlist in the playlist parameter. Returns an empty list if the playlist parameter is null or if there are no other playlists with the same name.

Parameters:

playlist - The playslist

Returns:

A list of PlaylistMergeBean objects.

getCoverArtList

java.util.Collection<CoverArtSearchResult> getCoverArtList(Playlist playlist)

Returns a list of available cover art for the playlist. This method will try to determine the band performing on the playlist. If the playlist contains songs by different bands then the band name used will be 'various'. The playlist mut have a name.

Parameters:

playlist - The playlist.

Returns:

A list of available cover art for this playlist.

getCoverArtList

java.util.Collection<CoverArtSearchResult> getCoverArtList(java.lang.String bandName,
                                                           java.lang.String playlistName)

Returns a list of available cover art for the named playlist by the named band. Both bandName and playlist name must be specified, or this returns an empty list.

Parameters:

bandName - The band name.

playlistName - The playlist name.

Returns:

A list of available playlist cover art.

createSong

Song createSong(java.lang.String songname,
                Band band,
                int length,
                java.util.Set<java.lang.String> keywords,
                java.lang.String destination)

Creates a persistent song with the given name.

Parameters:

songname - The name of the song to create. The name must not be null and must contain a non whitespace character. Otherwise, no song is created and the result is null. Leading and trailing whitespace is removed.

band - The band of the new song. This parameter must contain a persistent band. Otherwise, no song is created and the result is null.

length - The lenght of the song in milliseconds.

keywords - The set of keywords of the song.

destination - The file name of the media file containg the song.

getSongById

Song getSongById(long songid)

Return the song with a given identifier.

Parameters:

songid - The idenitfier.

Returns:

The song with the specified identifier.

getUpcoming

Playlist getUpcoming(long userid)

Return a playlist with a prediction of the next 6 songs the DJ will play for the specified user.

Parameters:

userid - The user.

Returns:

A Playlist containing the 6 upcoming songs that the DJ will play if no new requests/unrequests are made.

setSongProperties

void setSongProperties(Song song,
                       java.lang.String name,
                       java.lang.String bandName,
                       int msecs,
                       java.lang.String keywords)

Sets the song name, the song length in milliseconds and the song keywords according to the parameters specified.

Parameters:

song - The song to change.

name - The new song name. White space will be trimmed. The name will not change if the new name is null or empty after trimming.

bandName - The name of the band performing the song. The song will be moved to the band with this name. A new band will be made if it does not exist. If the bandname is null or empty after stripping white space, the band will not change.

msecs - The new song length in milliseconds. Zero or negative values will have no effect.

keywords - The new comma separated list of keywords.

getSongPlaylists

java.util.List<Playlist> getSongPlaylists(Song song)

Returns a list of playlist containing the song.

Parameters:

song - The song to look for.

Returns:

A list of playlists containing the song.

getSongNeighbours

Playlist getSongNeighbours(Song song,
                           IUser user)

Returns a playlist of songs that were played to a user close before or after a song.

Parameters:

song - The song whose neighbours must be found.

user - The user.

Returns:

A Playlist containing the neighbours.

getSongsByBand

Playlist getSongsByBand(Band band)

Returns a playlist with all songs played by the band.

Parameters:

band - The band.

Returns:

A playlist with all songs played by the band.

getBandById

Band getBandById(long bandid)

Return the band with a given identifier.

Parameters:

bandid - The idenitfier.

Returns:

The band with the specified identifier.

getBandPlaylists

java.util.List<Playlist> getBandPlaylists(Band band)

Returns a list of playlists containing at least one song by this band.

Parameters:

band - The band to look for.

Returns:

A list of playlists containing a song by the band.

setBandProperties

void setBandProperties(Band band,
                       java.lang.String bandName)

Sets the band name and comments string according to the specified parameters.

Parameters:

band - The band to modify.

bandName - The new band name. If a band with this name already exists, then the 2 bands will be merged. If the trimmed band name is null or empty, no change occurs.

listBands

java.util.List<java.lang.Object[]> listBands(IUser user)

Parameters:

user - The User to get this list for.

Returns:

Returns a list of Object-arrays. The first element of the array is the bandId (Long). The second element is the bandname (String), the third element is the amount of play-events for that band for the given User during the last year (Long).

getKeywordById

Keyword getKeywordById(java.lang.Long selectedKeywordId)

Returns the keyword with the id of the parameter.

Parameters:

selectedKeywordId - The id of the wanted keyword.

Returns:

The keyword with the given id.

getKeywordBagsWithKeywords

java.util.List<Keywordbag> getKeywordBagsWithKeywords(java.util.List<java.lang.Long> selectedKeywordIds)

Returns a list of all keyword bags containing all the keywords in the "selectedKeywordIds" parameter. If the parameter is null, then the result is null.

Parameters:

selectedKeywordIds - The list of keyword ids of the keywords that have to be present in all keyword bags in the result.

Returns:

a list of keyword bags containing all keywords in the selectedKeywordIds parameter.

listKeywords

java.util.List<java.lang.Object[]> listKeywords(IUser user,
                                                java.util.List<Keywordbag> bags)

Parameters:

user - The User to get this list for.

bags - The Keywordbags to show Keywords of (or null to show all keywords)

Returns:

Returns a list of String-arrays. The first element of the array is the keywordId. The second element is the keywordname, the third element is the amount of play-events for that keyword for the given User during the last year. If the bags parameter is non-null, then only keywords occurring in the ketword bags in bags are included.

songsByKeywordbags

Playlist songsByKeywordbags(java.util.List<Keywordbag> bags,
                            User user,
                            int i)

Generates a Playlist containing songs that belong to the specified Keywordbags. The songs in the Playlist are ordered by the amount of play-events of the specified User during the last year.

Parameters:

bags - The Keywordbag(s) the Song could be in. If this parameter is null, an empty Playlist is returned.

user - The User-object (Used for sorting according to listening-habits). If this parameter is null, anonymous sorting is used.

i - Specifiec the maximum amount of records to return. Pass a value >0 to show all matches.

Returns:

A Playlist consisting of Songs that matched any of the given Keywordbags.

addKeywordsToPlaylist

void addKeywordsToPlaylist(Playlist playlist,
                           java.lang.String keywords,
                           TrackList tracks)

Adds the keywords in the comma separated list to the playlist.

Parameters:

playlist - The playlist. If this is null, nothing happens.

keywords - The comma separated list of keywords to add.

tracks - If not null, add the keywords only to the tracks in the track list.

removeKeywordsFromPlaylist

void removeKeywordsFromPlaylist(Playlist playlist,
                                java.lang.String keywords,
                                TrackList tracks)

Removes the keywords in the comma separated list from the playlist.

Parameters:

playlist - The playlist. If this is null, nothing happens.

keywords - The comma separated list of keywords to remove.

tracks - If not null, remove the keywords only from the tracks in the track list.

setPlaylistCoverArt

void setPlaylistCoverArt(Playlist playlist,
                         CoverArtSearchResult selected)
                         throws java.io.IOException

Use the image in the CoverArtSearchResult to update the coverart for the playlist. The CoverArtSearchResult contains an URL that points to the cover art image. All existing cover images for this playlist are deleted.

Parameters:

playlist - The playlist to set the cover art for. If null, the request is ignored.

selected - The selected cover art. If null, the request is ignored. If the URL inside this is NULL, the request is ignored. If the URI is non absolute, MusiController adds the "file:" protocol to it.

Throws:

java.io.IOException - Something went wrong when downloading the image or storing the image on disk.

attemptToDownloadCoverArt

java.io.File attemptToDownloadCoverArt(long playlistid,
                                       int size)

Test the existence of a cover art image with the required size.

Parameters:

playlistid - The id of the playlist for which the cover art is requested.

size - The requested image size.

return - A file with the requested cover art image.

findImportedPlaylist

java.util.List<Playlist> findImportedPlaylist(MusicArchiveBean archive)

Tries to find persistent playlists that matches the playlist name of 1 or more entries in the music archive.

Parameters:

archive - The music archive.

Returns:

The playlists that could be the playlist in the music archive.

guessBandNameOfArchive

java.lang.String guessBandNameOfArchive(MusicArchiveBean archive)

Return a guess about the band on the cover of a playlist. Iterates through the songs. If all songs are performed by the same band, then it returns that band name. If there are more than 1 names, then it returns "Various". If there are no songs or if all songs have empty band names, then the result is "Unknown".

Returns:

A Guessed band name that could be on the cover of the playlist.

getReviews

java.util.Set<Comment> getReviews(Playlist playlist)

Returns a (possibly empty) sorted set of reviews for a Playlist.

Parameters:

playlist - The playlist tot get the reviews for

Returns:

A list of Reviews.

getReviews

java.util.Set<Comment> getReviews(Band band)

Returns a (possibly empty) sorted set of reviews for a Band.

Parameters:

band - The Band tot get the reviews for

Returns:

A list of Reviews.

guessPlaylistsInArchive

java.util.Set<Playlist> guessPlaylistsInArchive(MusicArchiveBean archive)

Compile a set of persistent playlists that could be the same as the contents of the music archive.

Parameters:

archive - The music archive.

Returns:

A set of playlists that could be contained in the music archive.

searchPlaylistByName

java.util.List<Playlist> searchPlaylistByName(java.lang.String playlistName)

Returns a list of playlists with the same name as the parameter.

Parameters:

playlistName - The name of the playlist.

Returns: