christophedelory.playlist.xspf
Class Playlist

java.lang.Object
  christophedelory.playlist.xspf.Playlist

All Implemented Interfaces:

SpecificPlaylist

public class Playlist
extends Object
implements SpecificPlaylist

XSPF, an XML format designed to enable playlist sharing.

Version:

$Revision: 91 $

Author:

Christophe Delory

Constructor Summary

Playlist()

Method Summary

void	addExtension(Object extension) Adds an extension to this playlist.
void	addLink(Link link) Adds a link to this playlist.
void	addMeta(Meta meta) Adds a metadata to this playlist.
void	addTrack(Track track) Adds a track to this playlist.
String	getAnnotation() Returns a human-readable comment on the playlist.
Attribution	getAttribution() Returns the playlist's attribution.
String	getCreator() Returns a human-readable name of the entity (author, authors, group, company, etc) that authored the playlist.
Date	getDate() Returns a creation date (not last-modified date) of the playlist.
List<AnyNode>	getExtensions() Returns a list of playlist extensions.
String	getIdentifier() Returns a canonical ID for this playlist.
String	getImage() Returns an URI of an image to display in the absence of a //playlist/trackList/image element.
String	getInfo() Returns an URI of a web page to find out more about this playlist.
String	getLicense() Returns an URI of a resource that describes the license under which this playlist was released.
List<Link>	getLinks() Returns the list of links defined in this playlist.
String	getLocation() Returns a source URI for this playlist.
List<Meta>	getMetas() Returns the list of metadata defined in this playlist.
SpecificPlaylistProvider	getProvider() Returns the provider of this specific playlist.
String	getTitle() Returns a human-readable title for the playlist.
List<Track>	getTracks() Returns an ordered list of xspf:track elements to be rendered.
Integer	getVersion() Returns the version number.
void	setAnnotation(String annotation) Initializes a human-readable comment on the playlist.
void	setAttribution(Attribution attribution) Initializes this playlist's attribution.
void	setCreator(String creator) Initializes a human-readable name of the entity (author, authors, group, company, etc) that authored the playlist.
void	setDate(Date date) Initializes a creation date (not last-modified date) of the playlist.
void	setIdentifier(String identifier) Initializes a canonical ID for this playlist.
void	setImage(String image) Initializes an URI of an image to display in the absence of a //playlist/trackList/image element.
void	setInfo(String info) Initializes an URI of a web page to find out more about this playlist.
void	setLicense(String license) Initializes an URI of a resource that describes the license under which this playlist was released.
void	setLocation(String location) Initializes a source URI for this playlist.
void	setProvider(SpecificPlaylistProvider provider) Initializes the provider of this specific playlist.
void	setTitle(String title) Initializes a human-readable title for the playlist.
void	setVersion(Integer version) Initializes the version number.
Playlist	toPlaylist() Builds a generic representation from this specific playlist.
void	writeTo(OutputStream out, String encoding) Writes this specific playlist to the specified output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Playlist

public Playlist()

Method Detail

setProvider

public void setProvider(SpecificPlaylistProvider provider)

Description copied from interface: SpecificPlaylist

Initializes the provider of this specific playlist.

Specified by:

setProvider in interface SpecificPlaylist

Parameters:

provider - the provider of this playlist. Shall not be null.

See Also:

SpecificPlaylist.getProvider()

getProvider

public SpecificPlaylistProvider getProvider()

Description copied from interface: SpecificPlaylist

Returns the provider of this specific playlist.

Specified by:

getProvider in interface SpecificPlaylist

Returns:

the provider of this playlist. May be null.

See Also:

SpecificPlaylist.setProvider(christophedelory.playlist.SpecificPlaylistProvider)

writeTo

public void writeTo(OutputStream out,
                    String encoding)
             throws Exception

Description copied from interface: SpecificPlaylist

Writes this specific playlist to the specified output stream. When done, the stream may be flushed, but not closed.

Specified by:

writeTo in interface SpecificPlaylist

Parameters:

out - an output stream. Shall not be null.

encoding - the content encoding of the output resource, or null if not known.

Throws:

NullPointerException - if out is null.

Exception - if any error occurs during the marshalling process.

See Also:

SpecificPlaylistFactory.readFrom(java.net.URL), SpecificPlaylistProvider.readFrom(java.io.InputStream, java.lang.String, org.apache.commons.logging.Log)

toPlaylist

public Playlist toPlaylist()

Description copied from interface: SpecificPlaylist

Builds a generic representation from this specific playlist.

Specified by:

toPlaylist in interface SpecificPlaylist

Returns:

a generic playlist. Shall not be null.

See Also:

SpecificPlaylistProvider.toSpecificPlaylist(christophedelory.playlist.Playlist)

getVersion

public Integer getVersion()

Returns the version number. Default value is 1. Notice that the namespace is 0 but the version is 1. This is because version 1 playlists are backwards compatible with version 0 parsers.

Returns:

a version number. Shall not be null.

See Also:

setVersion(java.lang.Integer)

setVersion

public void setVersion(Integer version)

Initializes the version number.

Parameters:

version - a version number. Shall not be null.

Throws:

NullPointerException - if version is null.

See Also:

getVersion()

getTitle

public String getTitle()

Returns a human-readable title for the playlist.

Returns:

a title. May be null.

See Also:

setTitle(java.lang.String)

setTitle

public void setTitle(String title)

Initializes a human-readable title for the playlist.

Parameters:

title - a title. May be null.

See Also:

getTitle()

getCreator

public String getCreator()

Returns a human-readable name of the entity (author, authors, group, company, etc) that authored the playlist.

Returns:

a creator. May be null.

See Also:

setCreator(java.lang.String)

setCreator

public void setCreator(String creator)

Initializes a human-readable name of the entity (author, authors, group, company, etc) that authored the playlist.

Parameters:

creator - a creator. May be null.

See Also:

getCreator()

getAnnotation

public String getAnnotation()

Returns a human-readable comment on the playlist. This is character data, not HTML, and it may not contain markup.

Returns:

an annotation. May be null.

See Also:

setAnnotation(java.lang.String)

setAnnotation

public void setAnnotation(String annotation)

Initializes a human-readable comment on the playlist.

Parameters:

annotation - an annotation. May be null.

See Also:

getAnnotation()

getInfo

public String getInfo()

Returns an URI of a web page to find out more about this playlist. Likely to be homepage of the author, and would be used to find out more about the author and to find more playlists by the author.

Returns:

an information. May be null.

See Also:

setInfo(java.lang.String)

setInfo

public void setInfo(String info)

Initializes an URI of a web page to find out more about this playlist.

Parameters:

info - an information. May be null.

See Also:

getInfo()

getLocation

public String getLocation()

Returns a source URI for this playlist.

Returns:

a location. May be null.

See Also:

setLocation(java.lang.String)

setLocation

public void setLocation(String location)

Initializes a source URI for this playlist.

Parameters:

location - a location. May be null.

See Also:

getLocation()

getIdentifier

public String getIdentifier()

Returns a canonical ID for this playlist.

Returns:

an identifier. May be null.

See Also:

setIdentifier(java.lang.String)

setIdentifier

public void setIdentifier(String identifier)

Initializes a canonical ID for this playlist.

Parameters:

identifier - an identifier. May be null.

See Also:

getIdentifier()

getImage

public String getImage()

Returns an URI of an image to display in the absence of a //playlist/trackList/image element.

Returns:

an image. May be null.

See Also:

setImage(java.lang.String)

setImage

public void setImage(String image)

Initializes an URI of an image to display in the absence of a //playlist/trackList/image element.

Parameters:

image - an image. May be null.

See Also:

getImage()

getDate

public Date getDate()

Returns a creation date (not last-modified date) of the playlist. The underlying string is formatted as a XML schema dateTime. A sample date is "2005-01-08T17:10:47-05:00". In the absence of a timezone, the element MAY be assumed to use Coordinated Universal Time (UTC, sometimes called "Greenwich Mean Time").
Note: in version 0 of XSPF, this was specified as an ISO 8601 date. xsd:dateTime is the same thing (with better documentation) for almost every date in history, and there are no playlist creation dates that might be different.

Returns:

a date. May be null.

See Also:

setDate(java.util.Date)

setDate

public void setDate(Date date)

Initializes a creation date (not last-modified date) of the playlist.

Parameters:

date - a date. May be null.

See Also:

getDate()

getLicense

public String getLicense()

Returns an URI of a resource that describes the license under which this playlist was released.

Returns:

a license. May be null.

See Also:

setLicense(java.lang.String)

setLicense

public void setLicense(String license)

Initializes an URI of a resource that describes the license under which this playlist was released.

Parameters:

license - a license. May be null.

See Also:

getLicense()

getAttribution

public Attribution getAttribution()

Returns the playlist's attribution.

Returns:

an attribution. May be null.

See Also:

setAttribution(christophedelory.playlist.xspf.Attribution)

setAttribution

public void setAttribution(Attribution attribution)

Initializes this playlist's attribution.

Parameters:

attribution - an attribution. May be null.

See Also:

getAttribution()

getExtensions

public List<AnyNode> getExtensions()

Returns a list of playlist extensions. This element allows non-XSPF XML to be included in XSPF documents. The purpose is to allow nested XML, which the meta and link elements do not.

Returns:

a list of extensions. May be empty but not null.

See Also:

addExtension(java.lang.Object)

addExtension

public void addExtension(Object extension)

Adds an extension to this playlist.
The extension element must have an "application" attribute. It's the URI of a resource defining the structure and purpose of the nested XML.
The input type is an Object just because it's what the Castor framework expects.

Parameters:

extension - an extension. Shall not be null.

Throws:

NullPointerException - if extension is null.

IllegalArgumentException - if extension is not an AnyNode instance.

IllegalArgumentException - if no "application" attribute can be found in the specified extension element.

See Also:

getExtensions()

addLink

public void addLink(Link link)

Adds a link to this playlist.

Parameters:

link - a link. Shall not be null

Throws:

NullPointerException - if link is null.

See Also:

getLinks()

getLinks

public List<Link> getLinks()

Returns the list of links defined in this playlist. The link element allows XSPF to be extended without the use of XML namespaces.

Returns:

a list of links. May be empty but not null.

See Also:

addLink(christophedelory.playlist.xspf.Link)

addMeta

public void addMeta(Meta meta)

Adds a metadata to this playlist.

Parameters:

meta - a metadata. Shall not be null

Throws:

NullPointerException - if meta is null.

See Also:

getMetas()

getMetas

public List<Meta> getMetas()

Returns the list of metadata defined in this playlist. The meta element allows metadata fields to be added to XSPF.

Returns:

a list of metadata. May be empty but not null.

See Also:

addMeta(christophedelory.playlist.xspf.Meta)

addTrack

public void addTrack(Track track)

Adds a track to this playlist.

Parameters:

track - a track. Shall not be null

Throws:

NullPointerException - if track is null.

See Also:

getTracks()

getTracks

public List<Track> getTracks()

Returns an ordered list of xspf:track elements to be rendered. The sequence is a hint, not a requirement; renderers are advised to play tracks from top to bottom unless there is an indication otherwise. If an xspf:track element cannot be rendered, a user-agent MUST skip to the next xspf:track element and MUST NOT interrupt the sequence.

Returns:

a list of tracks. May be empty but not null.

See Also:

addTrack(christophedelory.playlist.xspf.Track)