de.umass.lastfm
Class Artist

java.lang.Object
  extended by de.umass.lastfm.ImageHolder
      extended by de.umass.lastfm.MusicEntry
          extended by de.umass.lastfm.Artist

public class Artist
extends MusicEntry

Bean that contains artist information.
This class contains static methods that executes API methods relating to artists.
Method names are equivalent to the last.fm API method names.

Author:
Janni Kovacs

Field Summary
 
Fields inherited from class de.umass.lastfm.MusicEntry
id, listeners, mbid, name, percentageChange, playcount, streamable, tags, url, userPlaycount
 
Fields inherited from class de.umass.lastfm.ImageHolder
imageUrls
 
Constructor Summary
protected Artist(String name, String url)
           
protected Artist(String name, String url, String mbid, int playcount, int listeners, boolean streamable)
           
 
Method Summary
static Result addTags(String artist, String tags, Session session)
          Tag an artist with one or more user supplied tags.
static Artist getCorrection(String artist, String apiKey)
          Use the last.fm corrections data to check whether the supplied artist has a correction to a canonical artist.
static Collection<Event> getEvents(String artist, String apiKey)
          Returns a list of upcoming events for an artist.
static PaginatedResult<Image> getImages(String artist, int page, int limit, String apiKey)
          Get Images for this artist in a variety of sizes.
static PaginatedResult<Image> getImages(String artist, String apiKey)
          Get Images for this artist in a variety of sizes.
static Artist getInfo(String artistOrMbid, Locale locale, String username, String apiKey)
          Retrieves detailed artist info for the given artist or mbid entry.
static Artist getInfo(String artistOrMbid, String apiKey)
          Retrieves detailed artist info for the given artist or mbid entry.
static Artist getInfo(String artistOrMbid, String username, String apiKey)
          Retrieves detailed artist info for the given artist or mbid entry.
static PaginatedResult<Event> getPastEvents(String artist, int page, int limit, String apiKey)
          Get a paginated list of all the events this artist has played at in the past.
static PaginatedResult<Event> getPastEvents(String artist, String apiKey)
          Get a paginated list of all the events this artist has played at in the past.
 Collection<Artist> getSimilar()
          Returns a list of similar Artists.
static Collection<Artist> getSimilar(String artist, int limit, String apiKey)
          Returns limit similar artists to the given one.
static Collection<Artist> getSimilar(String artist, String apiKey)
          Calls getSimilar(String, int, String) with the default limit of 100.
 float getSimilarityMatch()
           
static Collection<String> getTags(String artist, Session session)
          Get the tags applied by an individual user to an artist on Last.fm.
static Collection<Album> getTopAlbums(String artist, String apiKey)
          Returns a list of the given artist's top albums.
static Collection<User> getTopFans(String artist, String apiKey)
          Retrieves a list of the top fans of the given artist.
static Collection<Tag> getTopTags(String artist, String apiKey)
          Retrieves the top tags for the given artist.
static Collection<Track> getTopTracks(String artist, String apiKey)
          Get the top tracks by an artist on Last.fm, ordered by popularity
static Result removeTag(String artist, String tag, Session session)
          Remove a user's tag from an artist.
static Collection<Artist> search(String name, String apiKey)
          Searches for an artist and returns a Collection of possible matches.
static Result share(String artist, String recipients, String message, Session session)
          Share an artist with one or more Last.fm users or other friends.
static Result shout(String artist, String message, Session session)
          Shout on this artist's shoutbox
 
Methods inherited from class de.umass.lastfm.MusicEntry
getId, getListeners, getMbid, getName, getPercentageChange, getPlaycount, getTags, getUrl, getUserPlaycount, getWikiLastChanged, getWikiSummary, getWikiText, isStreamable, loadStandardInfo
 
Methods inherited from class de.umass.lastfm.ImageHolder
availableSizes, getImageURL, loadImages
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Artist

protected Artist(String name,
                 String url)

Artist

protected Artist(String name,
                 String url,
                 String mbid,
                 int playcount,
                 int listeners,
                 boolean streamable)
Method Detail

getSimilarityMatch

public float getSimilarityMatch()

getSimilar

public Collection<Artist> getSimilar()
Returns a list of similar Artists. Note that this method does not retrieve this list from the server but instead returns the result of an artist.getInfo call.
If you need to retrieve similar artists to a specified artist use the getSimilar(String, String) method.

Returns:
list of similar artists
See Also:
getSimilar(String, String), getSimilar(String, int, String)

getInfo

public static Artist getInfo(String artistOrMbid,
                             String apiKey)
Retrieves detailed artist info for the given artist or mbid entry.

Parameters:
artistOrMbid - Name of the artist or an mbid
apiKey - The API key
Returns:
detailed artist info

getInfo

public static Artist getInfo(String artistOrMbid,
                             String username,
                             String apiKey)
Retrieves detailed artist info for the given artist or mbid entry.

Parameters:
artistOrMbid - Name of the artist or an mbid
username - The username for the context of the request, or null. If supplied, the user's playcount for this artist is included in the response
apiKey - The API key
Returns:
detailed artist info

getInfo

public static Artist getInfo(String artistOrMbid,
                             Locale locale,
                             String username,
                             String apiKey)
Retrieves detailed artist info for the given artist or mbid entry.

Parameters:
artistOrMbid - Name of the artist or an mbid
locale - The language to fetch info in, or null
username - The username for the context of the request, or null. If supplied, the user's playcount for this artist is included in the response
apiKey - The API key
Returns:
detailed artist info

getSimilar

public static Collection<Artist> getSimilar(String artist,
                                            String apiKey)
Calls getSimilar(String, int, String) with the default limit of 100.

Parameters:
artist - Artist's name
apiKey - The API key
Returns:
similar artists
See Also:
getSimilar(String, int, String)

getSimilar

public static Collection<Artist> getSimilar(String artist,
                                            int limit,
                                            String apiKey)
Returns limit similar artists to the given one.

Parameters:
artist - Artist's name
limit - Number of maximum results
apiKey - The API key
Returns:
similar artists

search

public static Collection<Artist> search(String name,
                                        String apiKey)
Searches for an artist and returns a Collection of possible matches.

Parameters:
name - The artist name to look up
apiKey - The API key
Returns:
a list of possible matches

getTopAlbums

public static Collection<Album> getTopAlbums(String artist,
                                             String apiKey)
Returns a list of the given artist's top albums.

Parameters:
artist - Artist's name
apiKey - The API key
Returns:
list of top albums

getTopFans

public static Collection<User> getTopFans(String artist,
                                          String apiKey)
Retrieves a list of the top fans of the given artist.

Parameters:
artist - Artist's name
apiKey - The API key
Returns:
list of top fans

getTopTags

public static Collection<Tag> getTopTags(String artist,
                                         String apiKey)
Retrieves the top tags for the given artist.

Parameters:
artist - Artist's name
apiKey - The API key
Returns:
list of top tags

getTopTracks

public static Collection<Track> getTopTracks(String artist,
                                             String apiKey)
Get the top tracks by an artist on Last.fm, ordered by popularity

Parameters:
artist - The artist name in question
apiKey - A Last.fm API key.
Returns:
list of top tracks

addTags

public static Result addTags(String artist,
                             String tags,
                             Session session)
Tag an artist with one or more user supplied tags.

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

removeTag

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

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

share

public static Result share(String artist,
                           String recipients,
                           String message,
                           Session session)
Share an artist with one or more Last.fm users or other friends.

Parameters:
artist - The artist to share.
recipients - A comma delimited list of email addresses or Last.fm usernames. Maximum is 10.
message - An optional message to send with the recommendation.
session - A Session instance
Returns:
the Result of the operation

getTags

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

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

getEvents

public static Collection<Event> getEvents(String artist,
                                          String apiKey)
Returns a list of upcoming events for an artist.

Parameters:
artist - The artist name in question
apiKey - A Last.fm API key.
Returns:
a list of events

getPastEvents

public static PaginatedResult<Event> getPastEvents(String artist,
                                                   String apiKey)
Get a paginated list of all the events this artist has played at in the past.

Parameters:
artist - The name of the artist you would like to fetch event listings for
apiKey - A Last.fm API key
Returns:
a list of past events

getPastEvents

public static PaginatedResult<Event> getPastEvents(String artist,
                                                   int page,
                                                   int limit,
                                                   String apiKey)
Get a paginated list of all the events this artist has played at in the past.

Parameters:
artist - The name of the artist you would like to fetch event listings for
page - The page of results to return
limit - The maximum number of results to return per page
apiKey - A Last.fm API key
Returns:
a list of past events

getImages

public static PaginatedResult<Image> getImages(String artist,
                                               String apiKey)
Get Images for this artist in a variety of sizes.

Parameters:
artist - The artist name in question
apiKey - A Last.fm API key
Returns:
a list of Images

getImages

public static PaginatedResult<Image> getImages(String artist,
                                               int page,
                                               int limit,
                                               String apiKey)
Get Images for this artist in a variety of sizes.

Parameters:
artist - The artist name in question
page - Which page of limit amount to display
limit - How many to return. Defaults and maxes out at 50
apiKey - A Last.fm API key
Returns:
a list of Images

shout

public static Result shout(String artist,
                           String message,
                           Session session)
Shout on this artist's shoutbox

Parameters:
artist - The name of the artist to shout on
message - The message to post to the shoutbox
session - A Session instance
Returns:
the result of the operation

getCorrection

public static Artist getCorrection(String artist,
                                   String apiKey)
Use the last.fm corrections data to check whether the supplied artist has a correction to a canonical artist. This method returns a new Artist object containing the corrected data, or null if the supplied Artist was not found.

Parameters:
artist - The artist name to correct
apiKey - A Last.fm API key
Returns:
a new Artist, or null