Class MusicCollection

Object
  extended by MusicCollection

public class MusicCollection
extends Object

A MusicCollection object represents a collection of Songs. It differs from a Playlist in two major ways:

  1. it does not impose an order on the Songs it contains
  2. it allows itself to be queried to retrieve information about the Songs it contains, or to retrieve all Songs that it contains and that also meet certain conditions.

Unlike a Playlist, a MusicCollection does not support the inclusion of the same Song multiple times. The primary key used to uniquely identify Songs in a MusicCollection is the full (absolute) path of the file associated with each Song. If an attempt is made to add a Song to a MusicCollection, and the path of this Song is the same as the path of a Song already included in the MusicCollection, the MusicCollection should not change as a result.

Also, the MusicCollection class does NOT support the addition of null elements to a MusicCollection object. If an attempt is made to add a null element to a MusicCollection, the latter should not change as a result.

A MusicCollection MUST be able to store and manage an arbitrary number of Songs, limited only by the memory available to the Java Virtual Machine. In other words, the implementation of the MusicCollection class MUST NOT not impose an artificial limit to the number of Songs a MusicCollection can store and manage.


Constructor Summary
MusicCollection()
          Creates a new empty MusicCollection.
 
Method Summary
 void add(Song song)
           Adds the specified Song to this MusicCollection.
 void addAll(java.util.ArrayList<Song> songList)
          Adds the Songs contained in the specified ArrayList into this MusicCollection.
 void addAll(Song[] songArray)
          Adds the Song objects contained in the specified array of Songs into this MusicCollection.
 void clear()
           Makes this MusicCollection empty, so that it contains no Songs.
 java.util.ArrayList<String> getAllAlbums()
           Returns an ArrayList of Strings containing the titles of all albums represented by Songs in this MusicCollection.
 java.util.ArrayList<String> getAllArtists()
           Returns an ArrayList of Strings containing the names of the all artists who have produced at least one of the Songs currently stored in this MusicCollection, as given by the values of the artist attribute of the Songs stored in this MusicCollection.
 java.util.ArrayList<String> getContributedAlbums(String artistName)
           Returns an ArrayList of Strings containing the titles of all albums to which the specified artist has contributed at least one of the Songs stored in this MusicCollection, as given by the values of the artist and album attributes of the Songs stored in this MusicCollection.
 Song getSong(java.io.File path)
           Returns the Song contained in this MusicCollection whose path attribute is equal to the specified File, as defined by the equals() method of the File class, if such a Song exists within the MusicCollection.
 Playlist getSongs(SongFilter filter)
           Returns a Playlist containing all the Songs stored in this MusicCollection that are accepted by the specified SongFilter.
 Playlist getSongs(String albumTitle)
           Returns a Playlist containing all the Songs stored in this MusicCollection whose album attributes are equal to the specified album title.
 Playlist getSongs(String artistName, String albumTitle)
           Returns a Playlist containing all the Songs stored in this MusicCollection whose artist attributes are equal to the specified artist name, and whose album attributes are equal to the specified album title.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MusicCollection

public MusicCollection()
Creates a new empty MusicCollection.

Method Detail

clear

public void clear()

Makes this MusicCollection empty, so that it contains no Songs.


getAllArtists

public java.util.ArrayList<String> getAllArtists()

Returns an ArrayList of Strings containing the names of the all artists who have produced at least one of the Songs currently stored in this MusicCollection, as given by the values of the artist attribute of the Songs stored in this MusicCollection.

The name of each artist is included ONLY once in the returned ArrayList, regardless of how many Songs stored in this MusicCollection this artist has produced. Also, equality is determined by comparing the artist attributes of Songs. Finally, equality is determined in a case-INsensitive manner.

For example, artist names "Joe Bleau" and "JOE BLEAU" are considered to be the same for the purposes of determining the uniqueness of an artist's name, and only one of them should be included in the ArrayList of artist names returned by this method.

However, "Joe Bleau" and "Joe Bleau and Jane Doe" are considered to be different artists for the purpose of determining the uniqueness of an artist's name, and both should be included in the ArrayList of artist names returned by this method.

The artist names MUST appear within the returned ArrayList in case-INsensitive lexicographical order. Subsequent changes to the returned ArrayList MUST NOT affect the state of this MusicCollection. Likewise, subsequent changes to the state of this MusicCollection MUST NOT have any impact on the returned ArrayList.

Returns:
An ArrayList of Strings containing the names of all artists who have produced at least one song currently stored in this MusicCollection.

getAllAlbums

public java.util.ArrayList<String> getAllAlbums()

Returns an ArrayList of Strings containing the titles of all albums represented by Songs in this MusicCollection. In other words, for an album title t to be included in the returned ArrayList, there must be at least one Song in this MusicCollection whose album attribute is equal to this album title t.

The title of each album is included ONLY once in the returned ArrayList, regardless of how many Songs stored in this MusicCollection have a given album title as their album title attribute. Also, equality is determined in a case-INsensitive manner. For example, album names "Joe Bleau: Greatest Hits" and "JOE BLEAU: GREATEST HITS" are considered to be the same for the purposes of determining the uniqueness of an album's title, and only one of them should be included in the ArrayList returned by this method.

The album titles MUST appear within the returned ArrayList in case-INsensitive lexicographical order. Subsequent changes to the returned ArrayList MUST NOT affect the state of this MusicCollection. Likewise, subsequent changes to the state of this MusicCollection MUST NOT have any impact on the returned ArrayList.

Returns:
An ArrayList of Strings containing the titles of all albums which include at least one song currently stored in this MusicCollection.

getContributedAlbums

public java.util.ArrayList<String> getContributedAlbums(String artistName)

Returns an ArrayList of Strings containing the titles of all albums to which the specified artist has contributed at least one of the Songs stored in this MusicCollection, as given by the values of the artist and album attributes of the Songs stored in this MusicCollection.

For example, if artist "Joe Bleau" has contributed 2 songs to the album titled Tribute to Jane Doe (assuming that a least one of these songs is stored as a Song object in this MusicCollection) and 10 songs to the album Joe Bleau: Greatest Hits (again assuming that at least one of these songs is stored as a Song object in this MusicCollection), then the returned ArrayList should contain "Tribute to Jane Doe" and "Joe Bleau: Greatest Hits".

The title of each album is included ONLY once in the returned ArrayList, regardless of how many Songs stored in this MusicCollection this album contains. Also, equality is determined in a case-INsensitive manner. For example, album names "Joe Bleau: Greatest Hits" and "JOE BLEAU: GREATEST HITS" are considered to be the same for the purposes of determining the uniqueness of an artist's name, and only one of them should be included in the ArrayList returned by this method.

The album titles MUST appear within the returned ArrayList in case-INsensitive lexicographical order. Subsequent changes to the returned ArrayList MUST NOT affect the state of this MusicCollection. Likewise, subsequent changes to the state of this MusicCollection MUST NOT have any impact on the returned ArrayList.

Parameters:
artistName - The artist whose whose album titles should be returned.
Returns:
An ArrayList of String containing the titles of all albums to which the specified artist has contributed at least one of the Songs currently stored in this MusicCollection.

getSongs

public Playlist getSongs(String albumTitle)

Returns a Playlist containing all the Songs stored in this MusicCollection whose album attributes are equal to the specified album title.

The comparison is performed in a case-INsensitive manner. The Songs in the returned Playlist MUST be sorted in increasing order by disc number. If two Songs have the same disc number, the song with the smaller track number MUST occur before the other in the returned Playlist.

Subsequent changes to the returned Playlist MUST NOT affect the state of this MusicCollection. Likewise, subsequent changes to the state of this MusicCollection MUST NOT have any impact on the returned Playlist.

Parameters:
albumTitle - The title of the album.
Returns:
A Playlist containing all the Songs stored in this MusicCollection whose album attributes are equal to albumTitle.

getSongs

public Playlist getSongs(String artistName,
                         String albumTitle)

Returns a Playlist containing all the Songs stored in this MusicCollection whose artist attributes are equal to the specified artist name, and whose album attributes are equal to the specified album title.

The comparison is performed in a case-INsensitive manner. The Songs in the returned Playlist MUST be sorted in increasing order by disc number. If two Songs have the same disc number, the song with the smaller track number MUST occur before the other in the Playlist.

Subsequent changes to the returned Playlist MUST NOT affect the state of this MusicCollection. Likewise, subsequent changes to the state of this MusicCollection MUST NOT have any impact on the returned Playlist.

Parameters:
artistName - The name of the artist.
albumTitle - The title of the album.
Returns:
A Playlist containing all the Songs stored in this MusicCollection whose artist attributes are equal to artistName, and whose album attributes are equal to albumTitle.

getSongs

public Playlist getSongs(SongFilter filter)

Returns a Playlist containing all the Songs stored in this MusicCollection that are accepted by the specified SongFilter. In other words, this method returns a Playlist containing all the Songs currently stored in this MusicCollection for which the accept() method defined in the SongFilter class returns true when invoked on the specified SongFilter object.

The order in which the Songs appear in the returned Playlist is undefined (that is, the Songs can appear in any order).

Subsequent changes to the returned Playlist MUST NOT affect the state of this MusicCollection. Likewise, subsequent changes to the state of this MusicCollection MUST NOT have any impact on the returned Playlist.

Parameters:
filter - A SongFilter object; Songs accepted by this SongFilter are included in the returned PlayList.
Returns:
A Playlist containing all Songs currently stored in this MusicCollection that are accepted by filter.

getSong

public Song getSong(java.io.File path)

Returns the Song contained in this MusicCollection whose path attribute is equal to the specified File, as defined by the equals() method of the File class, if such a Song exists within the MusicCollection. If this MusicCollection contains no such object, this method returns null.

Parameters:
path - The path of a Song potentially stored in this MusicCollection.
Returns:
The Song object contained in this MusicCollection whose path attribute is equal to path if one exists, null otherwise.

add

public void add(Song song)

Adds the specified Song to this MusicCollection.

If the specified Song is null, or if this MusicCollection contains a Song whose path attribute is equal to the path attribute of the specified Song, then this Song MUST NOT be added to this MusicCollection, and the latter therefore does not change.

Parameters:
song - The Song to be added to this MusicCollection.

addAll

public void addAll(java.util.ArrayList<Song> songList)
Adds the Songs contained in the specified ArrayList into this MusicCollection.

If the specified ArrayList contains null elements, these null elements MUST NOT be added to this MusicCollection. Likewise, if the specified ArrayList contains Songs whose path attributes are equal to the path attribute of Songs contained this MusicCollection, these Songs MUST NOT be added to this MusicCollection. However, non-null Songs contained in the specified ArrayList whose path attributes are not equal to the path attributes of Songs currently stored in this MusicCollection MUST be added to the latter.

Parameters:
songList - An ArrayList of Songs to be added to this MusicCollection.

addAll

public void addAll(Song[] songArray)
Adds the Song objects contained in the specified array of Songs into this MusicCollection.

If the specified array contains null elements, these null elements MUST NOT be added to this MusicCollection. Likewise, if the specified array contains Songs whose path attributes are equal to the path attribute of Songs contained this MusicCollection, these Songs MUST NOT be added to this MusicCollection. However, non-null Songs contained in the specified array whose path attributes are not equal to the path attributes of Songs currently stored in this MusicCollection MUST be added to the latter.

Parameters:
songArray - An array of Songs to be added to this MusicCollection.