Package com.tagtraum.ubermusic.lastfm

Class LastFM

java.lang.Object

com.tagtraum.core.WebService

com.tagtraum.ubermusic.lastfm.LastFM

All Implemented Interfaces:

TagProvider, UberMusic

public class LastFM
extends WebService
implements UberMusic, TagProvider

LastFM.

Author:

Hendrik Schreiber

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	LastFM.Session

Field Summary

Fields inherited from class com.tagtraum.core.WebService

HTTP_METHOD_GET, HTTP_METHOD_POST, HTTP_METHOD_PUT

Constructor Summary

Constructors

Constructor	Description
LastFM()

Method Summary

Modifier and Type	Method	Description
AudioArtist	artistInfo(String artist, String mbid)	Fetch artists for the given artist from Last.fm.
List<Similarity<AudioArtist>>	artistSimilar(String artist, String mbid)	Fetch similar artists for the given artist from Last.fm.
LastFM.Session	authGetSession(String token)	Gets a session key for the token.
String	authGetToken()	Obtains token necessary for authorization.
protected boolean	cacheResource(URL url, byte[] content)	Allows turning caching for a specific resource and its content on and off.
Session	createSession(LastFM.Session session)
Session	createSession(String sessionKey, String username)
static Mood	deriveMood(List<Tag> tags)	Attempt to derive a mood from the given tags.
List<AudioArtist>	getArtists(AudioSong song)	Lookup artists for a song.
URL	getAuthorizationURL(String token)	Needed to authorize this application for a given user.
protected org.json.simple.JSONObject	getJSONObject(String request, Charset responseCharset, long maximumAge, TimeUnit timeUnit)	Utility method to get a JSON dictionary from a webservice.
protected org.json.simple.JSONObject	getJSONObject(String request, Charset responseCharset, Map<String,String> parameters)
List<Similarity<AudioArtist>>	getSimilarArtists(AudioSong song)	Try to find similar artists for the given song.
List<Tag>	getTags(AudioSong song)	Fetch the top tags for the given song from Last.fm.
URL	getURL(AudioSong song)	Obtain a Last.fm-URL for the given song.
protected void	handleStatusCode(HttpURLConnection httpURLConnection, int statusCode)	Handles standard responses to status codes.
void	libraryAddTrack(AudioSong song, String sessionKey)	Adds a song to the user's library.
void	libraryAddTrack(String name, String artist, String sessionKey)	Adds a song to the user's library.
List<AudioSong>	lookup(AudioSong song)	Looks up metadata for a song.
List<AudioSong>	lookup(String name, String artist, String mbid)
List<AudioSong>	tagGetTopTracks(String tag, int page)	Get the top tracks for a given tag.
boolean	trackScrobble(AudioSong song, long startedPlaying, String sessionKey)	A track should only be scrobbled when the following conditions have been met: The track must be longer than 30 seconds. And the track has been played for at least half its duration, or for 4 minutes (whichever occurs earlier.) As soon as these conditions have been met, the scrobble request may be sent at any time.
boolean	trackScrobble(String name, String artist, String album, String albumArtist, int trackNumber, String mbid, int totalTime, long startedPlaying, String sessionKey)
List<Tag>	trackTopTags(String name, String artist, String mbid)	Fetch the top tags for the given track from Last.fm.
void	trackUpdateNowPlaying(AudioSong song, String sessionKey)	Update "now playing".
void	trackUpdateNowPlaying(String name, String artist, String album, String albumArtist, int trackNumber, String mbid, int totalTime, String sessionKey)	Update "now playing".

Methods inherited from class com.tagtraum.core.WebService

clearCache, getCache, getConnectTimeOut, getDomFactory, getJSONArray, getJSONArray, getJSONObject, getJSONObjectWithPayload, getMaxAge, getReadTimeOut, getRequestDelay, getSSLSocketFactory, getUserAgent, getXmlDocument, getXmlObject, isAcceptGzipContentEncoding, openConnection, openConnection, openInputStream, readURL, setAcceptGzipContentEncoding, setCache, setConnectTimeOut, setDomFactory, setMaxAge, setNextAllowedConnection, setReadTimeOut, setRequestDelay, setSSLSocketFactory, setUserAgent, toParameterString, useCacheOnly, waitForTurn

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.tagtraum.ubermusic.UberMusic

lookup, lookup

Constructor Detail

LastFM

public LastFM()

Method Detail

deriveMood

public static Mood deriveMood(List<Tag> tags)

Attempt to derive a mood from the given tags.

Parameters:

tags - tags

Returns:

derived mood or null, if we were unable to derive one

createSession

public Session createSession(LastFM.Session session)

createSession

public Session createSession(String sessionKey,
                             String username)

authGetToken

public String authGetToken()
                    throws IOException

Obtains token necessary for authorization.

Returns:

token

Throws:

IOException - if we cannot get a token

See Also:

getAuthorizationURL(String)

authGetSession

public LastFM.Session authGetSession(String token)
                              throws IOException

Gets a session key for the token. This is only possible after the user authorized the app via getAuthorizationURL(String).
Session keys have an infinite lifetime by default. You are recommended to store the key securely. Users are able to revoke privileges for your application on their Last.fm settings screen, rendering session keys invalid.

Parameters:

token - token

Returns:

session

Throws:

IOException - if we cannot get a session

See Also:

authGetToken(), getAuthorizationURL(String)

getAuthorizationURL

public URL getAuthorizationURL(String token)
                        throws IOException

Needed to authorize this application for a given user.

Parameters:

token - token

Returns:

url

Throws:

IOException - should the request for a token, necessary to build the URL, fail

See Also:

authGetToken(), http://www.last.fm/api/authspec

tagGetTopTracks

public List<AudioSong> tagGetTopTracks(String tag,
                                       int page)
                                throws IOException

Get the top tracks for a given tag.

Parameters:

tag - tag

Returns:

list of tracks

Throws:

IOException - if something goes wrong

libraryAddTrack

public void libraryAddTrack(AudioSong song,
                            String sessionKey)
                     throws IOException

Adds a song to the user's library.

Parameters:

song - song

sessionKey - (required) session key

Throws:

IOException - if we cannot add the track

libraryAddTrack

public void libraryAddTrack(String name,
                            String artist,
                            String sessionKey)
                     throws IOException

Adds a song to the user's library.

Parameters:

name - (required) title

artist - (required) artist

sessionKey - (required) session key

Throws:

IOException - if we cannot add the track

See Also:

libraryAddTrack(com.tagtraum.audiokern.AudioSong, String)

trackUpdateNowPlaying

public void trackUpdateNowPlaying(AudioSong song,
                                  String sessionKey)
                           throws IOException

Update "now playing".

Parameters:

song - song

sessionKey - key

Throws:

IOException - if "now playing" fails

trackUpdateNowPlaying

public void trackUpdateNowPlaying(String name,
                                  String artist,
                                  String album,
                                  String albumArtist,
                                  int trackNumber,
                                  String mbid,
                                  int totalTime,
                                  String sessionKey)
                           throws IOException

Update "now playing".

Parameters:

name - name

artist - artist

album - album

albumArtist - albumArtist

trackNumber - trackNumber

mbid - mbid

totalTime - totalTime

sessionKey - session key

Throws:

IOException - if we cannot update "now playing"

trackScrobble

public boolean trackScrobble(AudioSong song,
                             long startedPlaying,
                             String sessionKey)
                      throws IOException

A track should only be scrobbled when the following conditions have been met:

• The track must be longer than 30 seconds.
• And the track has been played for at least half its duration, or for 4 minutes (whichever occurs earlier.)

As soon as these conditions have been met, the scrobble request may be sent at any time. It is often most convenient to send a scrobble request when a track has finished playing. *

Parameters:

song - song

startedPlaying - (required) time in seconds since 1970

sessionKey - (required) session key

Returns:

true, if the scrobble was accepted

Throws:

IOException - if scroblle fails

See Also:

trackScrobble(String, String, String, String, int, String, int, long, String), trackUpdateNowPlaying(com.tagtraum.audiokern.AudioSong, String)

trackScrobble

public boolean trackScrobble(String name,
                             String artist,
                             String album,
                             String albumArtist,
                             int trackNumber,
                             String mbid,
                             int totalTime,
                             long startedPlaying,
                             String sessionKey)
                      throws IOException

Parameters:

name - (required)

artist - (required)

album - album

albumArtist - albumArtist

trackNumber - trackNumber

mbid - mbid

totalTime - totalTime

startedPlaying - (required)

sessionKey - (required)

Returns:

true, if the scrobble was accepted

Throws:

IOException - if scroblle fails

See Also:

trackScrobble(com.tagtraum.audiokern.AudioSong, long, String)

lookup

public List<AudioSong> lookup(AudioSong song)
                       throws IOException

Description copied from interface: UberMusic

Looks up metadata for a song.

Specified by:

lookup in interface UberMusic

Parameters:

song - song (query by example)

Returns:

reference songs, empty list, if the metadata is unavailable

Throws:

IOException - IOException

lookup

public List<AudioSong> lookup(String name,
                              String artist,
                              String mbid)
                       throws IOException

Throws:

IOException

getURL

public URL getURL(AudioSong song)
           throws IOException

Obtain a Last.fm-URL for the given song. If no URL can be found, the site-search URL is returned.

Parameters:

song - song

Returns:

url

Throws:

IOException - if we cannot get the URL

getTags

public List<Tag> getTags(AudioSong song)
                  throws IOException

Fetch the top tags for the given song from Last.fm.

Specified by:

getTags in interface TagProvider

Parameters:

song - song

Returns:

list of tags

Throws:

IOException - if top tags fails

See Also:

track.getTopTags, trackTopTags(String, String, String)

trackTopTags

public List<Tag> trackTopTags(String name,
                              String artist,
                              String mbid)
                       throws IOException

Fetch the top tags for the given track from Last.fm.

Parameters:

name - track name

artist - artist name

mbid - musicbrainz track id, if available, otherwise null

Returns:

list of tags

Throws:

IOException - if top tags fails

See Also:

track.getTopTags

getArtists

public List<AudioArtist> getArtists(AudioSong song)
                             throws IOException

Description copied from interface: UberMusic

Lookup artists for a song. The default implementation returns an empty list.

Specified by:

getArtists in interface UberMusic

Parameters:

song - song

Returns:

list of similar artists that seem to match the given song

Throws:

IOException - IOException

getSimilarArtists

public List<Similarity<AudioArtist>> getSimilarArtists(AudioSong song)
                                                throws IOException

Description copied from interface: UberMusic

Try to find similar artists for the given song. The default implementation returns an empty list.

Specified by:

getSimilarArtists in interface UberMusic

Parameters:

song - song

Returns:

list of similar artists

Throws:

IOException - IOException

artistSimilar

public List<Similarity<AudioArtist>> artistSimilar(String artist,
                                                   String mbid)
                                            throws IOException

Fetch similar artists for the given artist from Last.fm.

Parameters:

artist - artist name

mbid - artist musicbrainz id, if available

Returns:

list of artists

Throws:

IOException - if similar artists cannot be retrieved

See Also:

artist.getSimilar

artistInfo

public AudioArtist artistInfo(String artist,
                              String mbid)
                       throws IOException

Fetch artists for the given artist from Last.fm.

Parameters:

artist - artist name

mbid - artist musicbrainz id, if available

Returns:

artist

Throws:

IOException - if similar artists cannot be retrieved

See Also:

artist.getSimilar

handleStatusCode

protected void handleStatusCode(HttpURLConnection httpURLConnection,
                                int statusCode)
                         throws IOException

Description copied from class: WebService

Handles standard responses to status codes.

Overrides:

handleStatusCode in class WebService

Parameters:

httpURLConnection - http url connection

statusCode - status code

Throws:

IOException

getJSONObject

protected org.json.simple.JSONObject getJSONObject(String request,
                                                   Charset responseCharset,
                                                   long maximumAge,
                                                   TimeUnit timeUnit)
                                            throws IOException,
                                                   org.json.simple.parser.ParseException

Description copied from class: WebService

Utility method to get a JSON dictionary from a webservice.

Overrides:

getJSONObject in class WebService

Parameters:

request - request URL

responseCharset - character set to use when decoding the response, i.e. the character set communicated in the corresponding HTTP header is ignored

maximumAge - up to this age the cache is consulted

timeUnit - max age time unit

Returns:

JSON dictionary

Throws:

IOException - if something goes wrong

org.json.simple.parser.ParseException - if the JSON is malformed

getJSONObject

protected org.json.simple.JSONObject getJSONObject(String request,
                                                   Charset responseCharset,
                                                   Map<String,String> parameters)
                                            throws IOException,
                                                   org.json.simple.parser.ParseException

Throws:

IOException

org.json.simple.parser.ParseException

cacheResource

protected boolean cacheResource(URL url,
                                byte[] content)

Description copied from class: WebService

Allows turning caching for a specific resource and its content on and off.

Overrides:

cacheResource in class WebService

Parameters:

url - url

content - resource content

Returns:

by default this method returns true