|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
ObjectPlaylist
public class Playlist
A Playlist
is an ordered sequence of Song
s.
Its main use is as input to a music player; a player will play all the
Song
s 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
.
PlayList
s 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, Playlist
s are
indexed from 0
to the number of elements (that is,
Song
s) they contain, minus 1
. That list, if
the Playlist
contains 6 Song
s, 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 Song
s, 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 Song
s a Playlist
can
store and manage.
Constructor Summary | |
---|---|
Playlist()
Creates a new empty Playlist . |
|
Playlist(Playlist playlist)
Creates a new Playlist containing the same
Song s as those contained in the specified
Playlist , in the same order. |
Method Summary | |
---|---|
void |
add(int index,
Song song)
Inserts the specified 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 Song s 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 Song s 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 Song s contained in the specified array of
Song s 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
Song s. |
Song |
get(int index)
Returns the Song at the specified position in this
Playlist . |
int |
getSize()
Returns the number of Song s in this Playlist . |
boolean |
isEmpty()
Returns true if this Playlist is empty,
that is, it contains no Song s. |
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 Song s 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 |
---|
public Playlist()
Playlist
.
public Playlist(Playlist playlist)
Creates a new Playlist
containing the same
Song
s 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.
playlist
- A Playlist
which contains the Song
s
to be stored in the newly-created Playlist
.Method Detail |
---|
public void clear()
Makes this Playlist
object empty, so that it contains no
Song
s. 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
.
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
.
song
- The Song
to be added to the end of this
Playlist
.
true
if this Playlist
object has
changed as a result of calling this method, false
otherwise.public boolean addAll(Playlist playList)
Adds all Song
s 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
Song
s (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.
playList
- The Playlist
containing the Song
s
to be added to this Playlist
.
true
if this Playlist
object has
changed as a result of calling this method, false
otherwise.public boolean addAll(java.util.ArrayList<Song> songList)
Adds all Song
s 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
Song
s (that is, calling the size()
method
on it returns 0
), or all the Song
s 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.
songList
- The ArrayList
containing the Song
s
to be added to this Playlist
.
true
if this Playlist
object has
changed as a result of calling this method, false
otherwise.public boolean addAll(Song[] songArray)
Adds all Song
s contained in the specified array of
Song
s 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
Song
s (that is, its length
is
0
, or all the Song
s it contains are in
fact null
elements.
Subsequent changes to this Playlist
MUST NOT
affect the specified array of Song
s, and subsequent
changes to the specified array of Song
s MUST NOT
affect this Playlist
either.
songArray
- The array of Song
s containing the
Song
s to be added to this
Playlist
.
true
if this Playlist
object has
changed as a result of calling this method, false
otherwise.public void add(int index, Song song)
Inserts the specified 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 Song
s, 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.
index
- The position in the Playlist
in which the
specified Song
is to be added.song
- The Song
to be added to the Playlist
.
IndexOutOfBoundsException
- if index
is out of range (less than 0
or greater than the size of this Playlist
)public boolean isEmpty()
Returns true
if this Playlist
is empty,
that is, it contains no Song
s.
true
if this Playlist
is empty,
false
otherwise.public Song get(int index)
Returns the Song
at the specified position in this
Playlist
.
index
- The position in the Playlist
of the
Song
to return.
Song
at the position specified by
index
in this Playlist
.
IndexOutOfBoundsException
- if index
is out of range (less than
0
or greater than or equal to the size of this
Playlist
).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
Song
s, the Song
currently at position
4
is moved to position 3
, and the
Song
currently at position 5
is moved to
position 4
.
index
- The position in this Playlist
containing the
Song
to be removed.
Song
that was removed from the list.
IndexOutOfBoundsException
- if index
is out of range (less than
0
or greater than or equal to the size of this
Playlist
).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 Song
s
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
.
index
- The position in the Playlist
of the
Song
to be moved.numberPositions
- The number of positions the Song
at
index
should be moved.
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.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 Song
s 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
.
index
- The position in the Playlist
of the
Song
to be moved.numberPositions
- The number of positions the Song
at
index
should be moved.
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.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:
Playlist
is cleared (that is, made
empty).MusicCollection
is queried to see if it contains a
Song
associated to the file whose path was read from the
playlist file.
MusicCollection
does contain such a
Song
, the latter is added to the end of this
Playlist
.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.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.
Note that after the paths have been read from the playlist file, the
Song
s MUST appear in the Playlist
in the same order as their paths appear in the playlist file.
path
- The path of a playlist filecollection
- A MusicCollection
from which Song
s
are to be retrieved, and to which Song
s are to
be added.
Song
object could not be obtained. The list is
empty if a Song
object was successfully obtained
for all paths in the playlist file.
java.io.IOException
- if there is an error reading the playlist file (for example,
it does not exist).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 Song
s 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 Song
s in this
Playlist
have been written.
path
- The path of the playlist file to which the paths of the
Song
s contained in this Playlist
will be saved.
java.io.IOException
- if there is an error writing to the playlist file.public int getSize()
Returns the number of Song
s in this Playlist
.
Song
s in this Playlist
.public void sort(SongComparator comparator)
Sorts the Song
s 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 Song
s
in this Playlist
will appear in that order.
comparator
- The SongComparator
performing the comparisons
according to which the Song
s contained in this
Playlist
will be sorted.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |