net.roarsoftware.lastfm
Class Track

java.lang.Object
  extended by net.roarsoftware.lastfm.ImageHolder
      extended by net.roarsoftware.lastfm.MusicEntry
          extended by net.roarsoftware.lastfm.Track

public class Track
extends MusicEntry

Bean that contains information related to Tracks and provides bindings to methods in the track. namespace.

Author:
Janni Kovacs

Field Summary
protected  java.lang.String album
           
static java.lang.String ALBUM_PAGE
           
protected  java.lang.String albumMbid
           
protected  java.lang.String artist
           
static java.lang.String ARTIST_PAGE
           
protected  java.lang.String artistMbid
           
protected  int duration
           
protected  boolean fullTrackAvailable
           
protected  java.util.Map<java.lang.String,java.lang.String> lastFmExtensionInfos
           
protected  java.lang.String location
           
protected  boolean nowPlaying
           
protected  java.util.Date playedWhen
           
protected  int position
           
static java.lang.String TRACK_PAGE
           
 
Fields inherited from class net.roarsoftware.lastfm.MusicEntry
listeners, mbid, name, playcount, streamable, tags, url
 
Fields inherited from class net.roarsoftware.lastfm.ImageHolder
imageUrls
 
Constructor Summary
protected Track(java.lang.String name, java.lang.String url, java.lang.String artist)
           
protected Track(java.lang.String name, java.lang.String url, java.lang.String mbid, int playcount, int listeners, boolean streamable, java.lang.String artist, java.lang.String artistMbid, boolean fullTrackAvailable, boolean nowPlaying)
           
 
Method Summary
static Result addTags(java.lang.String artist, java.lang.String track, java.lang.String tags, Session session)
          Tag an album using a list of user supplied tags.
static Result ban(java.lang.String artist, java.lang.String track, Session session)
          Ban a track for a given user profile.
 java.lang.String getAlbum()
           
 java.lang.String getAlbumMbid()
           
 java.lang.String getArtist()
           
 java.lang.String getArtistMbid()
           
 int getDuration()
          Returns the duration of the song, if available, in seconds.
static Track getInfo(java.lang.String artist, java.lang.String trackOrMbid, java.lang.String apiKey)
          Get the metadata for a track on Last.fm using the artist/track name or a musicbrainz id.
 java.lang.String getLastFmInfo(java.lang.String key)
          Returns last.fm specific information about this Track.
 java.lang.String getLocation()
          Returns the location (URL) of this Track.
 java.util.Date getPlayedWhen()
          Returns the time when the track was played, if this data is available (e.g.
 int getPosition()
          Returns the position of this track in its associated album, or -1 if not available.
static java.util.Collection<Track> getSimilar(java.lang.String artist, java.lang.String track, java.lang.String mbid, java.lang.String apiKey)
          Get the similar tracks for this track on Last.fm, based on listening data.
You have to provide either an artist and a track name or an mbid.
static java.util.Collection<java.lang.String> getTags(java.lang.String artist, java.lang.String track, Session session)
          Get the tags applied by an individual user to an track on Last.fm.
static java.util.Collection<User> getTopFans(java.lang.String artist, java.lang.String trackOrMbid, java.lang.String apiKey)
          Retrieves the top fans for the given track.
static java.util.List<Tag> getTopTags(java.lang.String artist, java.lang.String trackOrMbid, java.lang.String apiKey)
          Retrieves the top tags for the given track.
 boolean isFullTrackAvailable()
           
 boolean isNowPlaying()
           
static Result love(java.lang.String artist, java.lang.String track, Session session)
          Love a track for a user profile.
static Result removeTag(java.lang.String artist, java.lang.String track, java.lang.String tag, Session session)
          Remove a user's tag from a track.
static java.util.Collection<Track> search(java.lang.String track, java.lang.String apiKey)
          Searches for a track with the given name and returns a list of possible matches.
static java.util.Collection<Track> search(java.lang.String artist, java.lang.String track, int limit, java.lang.String apiKey)
          Searches for a track with the given name and returns a list of possible matches.
static Result share(java.lang.String artist, java.lang.String track, java.lang.String message, java.lang.String recipient, Session session)
          Share a track twith one or more Last.fm users or other friends.
static Track trackFromElement(DomElement e)
           
 
Methods inherited from class net.roarsoftware.lastfm.MusicEntry
getListeners, getMbid, getName, getPlaycount, getTags, getUrl, getWikiLastChanged, getWikiSummary, getWikiText, isStreamable, loadStandardInfo
 
Methods inherited from class net.roarsoftware.lastfm.ImageHolder
availableSizes, getImageURL, loadImages
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ARTIST_PAGE

public static final java.lang.String ARTIST_PAGE
See Also:
Constant Field Values

ALBUM_PAGE

public static final java.lang.String ALBUM_PAGE
See Also:
Constant Field Values

TRACK_PAGE

public static final java.lang.String TRACK_PAGE
See Also:
Constant Field Values

artist

protected java.lang.String artist

artistMbid

protected java.lang.String artistMbid

album

protected java.lang.String album

albumMbid

protected java.lang.String albumMbid

position

protected int position

fullTrackAvailable

protected boolean fullTrackAvailable

nowPlaying

protected boolean nowPlaying

playedWhen

protected java.util.Date playedWhen

duration

protected int duration

location

protected java.lang.String location

lastFmExtensionInfos

protected java.util.Map<java.lang.String,java.lang.String> lastFmExtensionInfos
Constructor Detail

Track

protected Track(java.lang.String name,
                java.lang.String url,
                java.lang.String artist)

Track

protected Track(java.lang.String name,
                java.lang.String url,
                java.lang.String mbid,
                int playcount,
                int listeners,
                boolean streamable,
                java.lang.String artist,
                java.lang.String artistMbid,
                boolean fullTrackAvailable,
                boolean nowPlaying)
Method Detail

getDuration

public int getDuration()
Returns the duration of the song, if available, in seconds. The duration attribute is only available for tracks retrieved by Playlist.fetch and Track.getInfo.

Returns:
duration in seconds

getArtist

public java.lang.String getArtist()

getArtistMbid

public java.lang.String getArtistMbid()

getAlbum

public java.lang.String getAlbum()

getAlbumMbid

public java.lang.String getAlbumMbid()

isFullTrackAvailable

public boolean isFullTrackAvailable()

isNowPlaying

public boolean isNowPlaying()

getLocation

public java.lang.String getLocation()
Returns the location (URL) of this Track. This information is only available with the Radio services.

Returns:
the location

getLastFmInfo

public java.lang.String getLastFmInfo(java.lang.String key)
Returns last.fm specific information about this Track. Only available in Tracks, fetched from radio-playlists. key can be one of the following: Or use the available constants in this class.
Note that the key string is case sensitive.

Parameters:
key - A key
Returns:
associated value
See Also:
ARTIST_PAGE, ALBUM_PAGE, TRACK_PAGE

getPlayedWhen

public java.util.Date getPlayedWhen()
Returns the time when the track was played, if this data is available (e.g. for recent tracks) or null, if this data is not available.

Returns:
the date when the track was played or null

getPosition

public int getPosition()
Returns the position of this track in its associated album, or -1 if not available.

Returns:
the album position

search

public static java.util.Collection<Track> search(java.lang.String track,
                                                 java.lang.String apiKey)
Searches for a track with the given name and returns a list of possible matches.

Parameters:
track - Track name
apiKey - The API key
Returns:
a list of possible matches
See Also:
search(String, String, int, String)

search

public static java.util.Collection<Track> search(java.lang.String artist,
                                                 java.lang.String track,
                                                 int limit,
                                                 java.lang.String apiKey)
Searches for a track with the given name and returns a list of possible matches. Specify an artist name or a limit to narrow down search results. Pass null for the artist parameter if you want to specify a limit but don't want to define an artist.

Parameters:
artist - Artist's name or null
track - Track name
limit - Number of maximum results
apiKey - The API key
Returns:
a list of possible matches

getTopTags

public static java.util.List<Tag> getTopTags(java.lang.String artist,
                                             java.lang.String trackOrMbid,
                                             java.lang.String apiKey)
Retrieves the top tags for the given track. You either have to specify a track and artist name or a mbid. If you specify an mbid you may pass null for the first parameter.

Parameters:
artist - Artist name or null if an MBID is specified
trackOrMbid - Track name or MBID
apiKey - The API key
Returns:
list of tags

getTopFans

public static java.util.Collection<User> getTopFans(java.lang.String artist,
                                                    java.lang.String trackOrMbid,
                                                    java.lang.String apiKey)
Retrieves the top fans for the given track. You either have to specify a track and artist name or a mbid. If you specify an mbid you may pass null for the first parameter.

Parameters:
artist - Artist name or null if an MBID is specified
trackOrMbid - Track name or MBID
apiKey - The API key
Returns:
list of fans

addTags

public static Result addTags(java.lang.String artist,
                             java.lang.String track,
                             java.lang.String tags,
                             Session session)
Tag an album using a list of user supplied tags.

Parameters:
artist - The artist name in question
track - The track name in question
tags - A comma delimited list of user supplied tags to apply to this track. Accepts a maximum of 10 tags.
session - A Session instance.
Returns:
the Result of the operation

removeTag

public static Result removeTag(java.lang.String artist,
                               java.lang.String track,
                               java.lang.String tag,
                               Session session)
Remove a user's tag from a track.

Parameters:
artist - The artist name in question
track - The track name in question
tag - A single user tag to remove from this track.
session - A Session instance.
Returns:
the Result of the operation

share

public static Result share(java.lang.String artist,
                           java.lang.String track,
                           java.lang.String message,
                           java.lang.String recipient,
                           Session session)
Share a track twith one or more Last.fm users or other friends.

Parameters:
artist - An artist name.
track - A track name.
message - A message to send with the recommendation or null. If not supplied a default message will be used.
recipient - A comma delimited list of email addresses or Last.fm usernames. Maximum is 10.
session - A Session instance
Returns:
the Result of the operation

love

public static Result love(java.lang.String artist,
                          java.lang.String track,
                          Session session)
Love a track for a user profile. This needs to be supplemented with a scrobbling submission containing the 'love' rating (see the audioscrobbler API).

Parameters:
artist - An artist name
track - A track name
session - A Session instance
Returns:
the Result of the operation

ban

public static Result ban(java.lang.String artist,
                         java.lang.String track,
                         Session session)
Ban a track for a given user profile. This needs to be supplemented with a scrobbling submission containing the 'ban' rating (see the audioscrobbler API). * @param artist An artist name

Parameters:
artist - An artist name
track - A track name
session - A Session instance
Returns:
the Result of the operation

getSimilar

public static java.util.Collection<Track> getSimilar(java.lang.String artist,
                                                     java.lang.String track,
                                                     java.lang.String mbid,
                                                     java.lang.String apiKey)
Get the similar tracks for this track on Last.fm, based on listening data.
You have to provide either an artist and a track name or an mbid. Pass null for parameters you don't need.

Parameters:
artist - The artist name in question
track - The track name in question
mbid - The musicbrainz id for the track
apiKey - A Last.fm API key.
Returns:
a list of similar Tracks

getTags

public static java.util.Collection<java.lang.String> getTags(java.lang.String artist,
                                                             java.lang.String track,
                                                             Session session)
Get the tags applied by an individual user to an track on Last.fm.

Parameters:
artist - The artist name in question
track - The track name in question
session - A Session instance
Returns:
a list of tags

getInfo

public static Track getInfo(java.lang.String artist,
                            java.lang.String trackOrMbid,
                            java.lang.String apiKey)
Get the metadata for a track on Last.fm using the artist/track name or a musicbrainz id.

Parameters:
artist - The artist name in question or null if an mbid is specified
trackOrMbid - The track name in question or the musicbrainz id for the track
apiKey - A Last.fm API key.
Returns:
Track information

trackFromElement

public static Track trackFromElement(DomElement e)