Class Playlist

Object
  extended by Playlist

public class Playlist
extends Object

A Playlist is an ordered sequence of Songs. Its main use is as input to a music player; a player will play all the Songs in a Playlist in the order in which they appear within the Playlist. Because of this, a Playlist can contain the same Song more than once, at different positions within the Playlist.

PlayLists do NOT support the addition of null elements. If an attempt is made to add a null element to a Playlist, the latter should not change as a result.

Like most of the Java container classes, Playlists are indexed from 0 to the number of elements (that is, Songs) they contain, minus 1. That list, if the Playlist contains 6 Songs, the first Song will be at index 0, the second Song will be at index 1, and so on, while the last Song will be at index (6 - 1) (that is, 5).

A Playlist 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 Playlist class MUST NOT not impose an artificial limit to the number of Songs a Playlist can store and manage.


Constructor Summary
Playlist()
          Creates a new empty Playlist.
Playlist(Playlist playlist)
           Creates a new Playlist containing the same Songs as those contained in the specified Playlist, in the same order.
 
Method Summary
 void add(int index, Song song)
           Inserts the specified Song at the specified position in this list, and shifts the Song currently at that position (if any) and any subsequent elements to the right (in other words, it adds one to their indices).
 boolean add(Song song)
           Adds the specified Song to the end of this Playlist object.
 boolean addAll(java.util.ArrayList<Song> songList)
           Adds all Songs contained in the specified ArrayList to the end of this Playlist, in the order in which they appear in the specified ArrayList.
 boolean addAll(Playlist playList)
           Adds all Songs contained in the specified Playlist to the end of this Playlist, in the order in which they appear in the specified Playlist.
 boolean addAll(Song[] songArray)
           Adds all Songs contained in the specified array of Songs to the end of this Playlist, in the order in which they appear in the specified array.
 void clear()
           Makes this Playlist object empty, so that it contains no Songs.
 Song get(int index)
           Returns the Song at the specified position in this Playlist.
 int getSize()
           Returns the number of Songs in this Playlist.
 boolean isEmpty()
           Returns true if this Playlist is empty, that is, it contains no Songs.
 java.util.ArrayList<String> load(java.io.File path, MusicCollection collection)
           Loads the Songs whose paths are stored in the file given by the specified File (the playlist file) into the Playlist.
 void moveDown(int index, int numberPositions)
           Moves the Song at the specified position in the Playlist a specified number of positions towards the end of the Playlist.
 void moveUp(int index, int numberPositions)
           Moves the Song at the specified position in the Playlist a specified number of positions towards the beginning of the Playlist.
 Song remove(int index)
           Removes the Song element at the specified position in this list, and shifts any subsequent Song (if any) to the left (that is, it subtracts one from their indices).
 void save(java.io.File path)
           Writes the full (absolute) path of each Song contained in this Playlist to the file whose path is given by the specified File (the playlist file).
 void sort(SongComparator comparator)
           Sorts the Songs in this Playlist so that they appear in the order implemented by the specified SongComparator object.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Playlist

public Playlist()
Creates a new empty Playlist.


Playlist

public Playlist(Playlist playlist)

Creates a new Playlist containing the same Songs as those contained in the specified Playlist, in the same order.

Subsequent changes to the newly created Playlist MUST NOT affect the specified Playlist, and subsequent changes to the specified Playlist MUST NOT affect the newly-created Playlist either.

Parameters:
playlist - A Playlist which contains the Songs to be stored in the newly-created Playlist.
Method Detail

clear

public void clear()

Makes this Playlist object empty, so that it contains no Songs. After calling this method on a Playlist, calling isEmpty() on the same Playlist MUST return true, and calling getSize() on the same PlayList MUST return 0.


add

public boolean add(Song song)

Adds the specified Song to the end of this Playlist object. If the specified Song is null, it MUST NOT be added to the Playlist and, therefore, the Playlist MUST NOT change.

This method returns true if this Playlist object has changed as a result of calling this method, false otherwise. Because a Playlist supports duplicate elements and its size is limited only by the memory available to the Java Virtual Machine, the only way a Playlist cannot change when this method is called is if the specified Song is null.

Parameters:
song - The Song to be added to the end of this Playlist.
Returns:
true if this Playlist object has changed as a result of calling this method, false otherwise.

addAll

public boolean addAll(Playlist playList)

Adds all Songs contained in the specified Playlist to the end of this Playlist, in the order in which they appear in the specified Playlist.

This method returns true if this Playlist object has changed as a result of calling this method, false otherwise. Because a Playlist cannot contain null elements, supports duplicate elements, and its size is limited only by the memory available to the Java Virtual Machine, the only way a Playlist cannot change when this method is called is if the specified Playlist contains no Songs (that is, calling isEmpty() on the specified Playlist returns true).

Subsequent changes to this Playlist MUST NOT affect the specified Playlist, and subsequent changes to the specified Playlist MUST NOT affect this Playlist either.

Parameters:
playList - The Playlist containing the Songs to be added to this Playlist.
Returns:
true if this Playlist object has changed as a result of calling this method, false otherwise.

addAll

public boolean addAll(java.util.ArrayList<Song> songList)

Adds all Songs contained in the specified ArrayList to the end of this Playlist, in the order in which they appear in the specified ArrayList. null elements contained in the specified ArrayList MUST NOT be added to this Playlist.

This method returns true if this Playlist object has changed as a result of calling this method, false otherwise. Because a Playlist cannot contain null elements, supports duplicate elements, and its size is limited only by the memory available to the Java Virtual Machine, the only way a Playlist cannot change when this method is called is if the specified ArrayList contains no Songs (that is, calling the size() method on it returns 0), or all the Songs it contains are in fact null elements.

Subsequent changes to this Playlist MUST NOT affect the specified ArrayList, and subsequent changes to the specified ArrayList MUST NOT affect this Playlist either.

Parameters:
songList - The ArrayList containing the Songs to be added to this Playlist.
Returns:
true if this Playlist object has changed as a result of calling this method, false otherwise.

addAll

public boolean addAll(Song[] songArray)

Adds all Songs contained in the specified array of Songs to the end of this Playlist, in the order in which they appear in the specified array. null elements contained in the specified array MUST NOT be added to this Playlist.

This method returns true if this Playlist object has changed as a result of calling this method, false otherwise. Because a Playlist cannot contain null elements, supports duplicate elements, and its size is limited only by the memory available to the Java Virtual Machine, the only way a Playlist cannot change when this method is called is if the specified array is null, contains no Songs (that is, its length is 0, or all the Songs it contains are in fact null elements.

Subsequent changes to this Playlist MUST NOT affect the specified array of Songs, and subsequent changes to the specified array of Songs MUST NOT affect this Playlist either.

Parameters:
songArray - The array of Songs containing the Songs to be added to this Playlist.
Returns:
true if this Playlist object has changed as a result of calling this method, false otherwise.

add

public void add(int index,
                Song song)

Inserts the specified Song at the specified position in this list, and shifts the Song currently at that position (if any) and any subsequent elements to the right (in other words, it adds one to their indices). If the specified Song is null, this method does nothing and Playlist does not change.

For example, if a Song is inserted at position 3 of a Playlist containing 6 Songs, the Song currently at position 3 is moved to position 4, the Song currently at position 4 is moved to position 5, and a new position 6 is created to store the Song currently at position 5.

Note that valid positions for this method include the position equal to the size of the Playlist. In this case, the specified Song is added at the end of the Playlist; this particular case is equivalent to calling the add(Song song) method.

Parameters:
index - The position in the Playlist in which the specified Song is to be added.
song - The Song to be added to the Playlist.
Throws:
IndexOutOfBoundsException - if index is out of range (less than 0 or greater than the size of this Playlist)

isEmpty

public boolean isEmpty()

Returns true if this Playlist is empty, that is, it contains no Songs.

Returns:
true if this Playlist is empty, false otherwise.

get

public Song get(int index)

Returns the Song at the specified position in this Playlist.

Parameters:
index - The position in the Playlist of the Song to return.
Returns:
The Song at the position specified by index in this Playlist.
Throws:
IndexOutOfBoundsException - if index is out of range (less than 0 or greater than or equal to the size of this Playlist).

remove

public Song remove(int index)

Removes the Song element at the specified position in this list, and shifts any subsequent Song (if any) to the left (that is, it subtracts one from their indices).

For example, if a Song is removed from position 3 of a Playlist containing 6 Songs, the Song currently at position 4 is moved to position 3, and the Song currently at position 5 is moved to position 4.

Parameters:
index - The position in this Playlist containing the Song to be removed.
Returns:
The Song that was removed from the list.
Throws:
IndexOutOfBoundsException - if index is out of range (less than 0 or greater than or equal to the size of this Playlist).

moveUp

public void moveUp(int index,
                   int numberPositions)

Moves the Song at the specified position in the Playlist a specified number of positions towards the beginning of the Playlist. Any Songs occurring in positions between the specified position and the position to which the Song at the specified position is to be moved will be shifted one position towards the end of the Playlist.

For example, if the Song at position 4 of a Playlist containing 6 Songs is moved 2 positions towards the beginning of the Playlist, the Song at position 4 is moved into position 2, the Song formerly in position 2 is moved into position 3, and the Song formerly into position 3 is moved into position 4.

Parameters:
index - The position in the Playlist of the Song to be moved.
numberPositions - The number of positions the Song at index should be moved.
Throws:
IndexOutOfBoundsException - if either index or the position to which the Song should move is out of range (less than 0 or greater than or equal to the size of this Playlist).
IllegalArgumentException - if numberPositions is 0 or negative.

moveDown

public void moveDown(int index,
                     int numberPositions)

Moves the Song at the specified position in the Playlist a specified number of positions towards the end of the Playlist. Any Songs occurring in positions between the specified position and the position to which the Song at the specified position is to be moved will be shifted one position towards the beginning of the Playlist.

For example, if the Song at position 2 of a Playlist containing 6 Songs is moved 2 positions towards the end of the Playlist, the Song at position 2 is moved into position 4, the Song formerly in position 4 is moved into position 3, and the Song formerly into position 3 is moved into position 2.

Parameters:
index - The position in the Playlist of the Song to be moved.
numberPositions - The number of positions the Song at index should be moved.
Throws:
IndexOutOfBoundsException - if either index or the position the Song should move is out of range (less than 0 or greater than or equal to the size of this Playlist).
IllegalArgumentException - if numberPositions is 0 or negative.

load

public java.util.ArrayList<String> load(java.io.File path,
                                        MusicCollection collection)
                                 throws java.io.IOException

Loads the Songs whose paths are stored in the file given by the specified File (the playlist file) into the Playlist.

This method works as follows:

  1. First, this Playlist is cleared (that is, made empty).
  2. Then, the playlist file is read, line by line. Each non-empty line in the playlist file represents the full (absolute) path of a file containing a digital audio track (empty lines are ignored). The specified MusicCollection is queried to see if it contains a Song associated to the file whose path was read from the playlist file.
    • If the specified MusicCollection does contain such a Song, the latter is added to the end of this Playlist.
    • If the specified MusicCollection does not contain such a Song, an attempt is made to create a Song object associated to the file whose path was read from the playlist file by calling the createSong() method on a SongFactory object.
    • If the attempt is successful, the Song object is added to the specified MusicCollection, as well as to the end of this Playlist. Otherwise, the path of the file is added to an ArrayList of String objects containing all paths present in the playlist file for which a Song object could not be obtained.
  3. When all the lines have been read from the playlist file, the latter is closed.

Note that after the paths have been read from the playlist file, the Songs MUST appear in the Playlist in the same order as their paths appear in the playlist file.

Parameters:
path - The path of a playlist file
collection - A MusicCollection from which Songs are to be retrieved, and to which Songs are to be added.
Returns:
The list of all the paths for which a corresponding Song object could not be obtained. The list is empty if a Song object was successfully obtained for all paths in the playlist file.
Throws:
java.io.IOException - if there is an error reading the playlist file (for example, it does not exist).

save

public void save(java.io.File path)
          throws java.io.IOException

Writes the full (absolute) path of each Song contained in this Playlist to the file whose path is given by the specified File (the playlist file). If the playlist file already exists, it is overwritten.

In the playlist file, the path of each Song is written on a separate line. The paths of the Songs MUST be written to the file in the order that they appear in this Playlist. It is acceptable to write empty lines to the file.

Also note that this Playlist MUST NOT change as a result of calling this method. The playlist file MUST be closed once the paths of all the Songs in this Playlist have been written.

Parameters:
path - The path of the playlist file to which the paths of the Songs contained in this Playlist will be saved.
Throws:
java.io.IOException - if there is an error writing to the playlist file.

getSize

public int getSize()

Returns the number of Songs in this Playlist.

Returns:
the number of Songs in this Playlist.

sort

public void sort(SongComparator comparator)

Sorts the Songs in this Playlist so that they appear in the order implemented by the specified SongComparator object.

For example, if the specified SongComparator object implements an order based on the album in which each Song appears (lexicographically increasing, lexicographically decreasing, or any other order), then after the method is called, the Songs in this Playlist will appear in that order.

Parameters:
comparator - The SongComparator performing the comparisons according to which the Songs contained in this Playlist will be sorted.