net.roarsoftware.lastfm.scrobble
Class Scrobbler

java.lang.Object
  extended by net.roarsoftware.lastfm.scrobble.Scrobbler

public class Scrobbler
extends java.lang.Object

This class manages communication with the server for scrobbling songs. You can retrieve an instance of this class by calling newScrobbler.
It contains methods to perform the handshake, notify Last.fm about a now playing song and submitting songs to a musical profile, aka scrobbling songs.
See http://www.last.fm/api/submissions for a deeper explanation of the protocol and various guidelines on how to use the scrobbling service, since this class does not cover error handling or caching.
All methods in this class, which are communicating with the server, return an instance of ResponseStatus which contains information if the operation was successful or not.
This class respects the proxy property in the Caller class in all its HTTP calls. If you need the Scrobbler to use a Proxy server, set it with Caller.setProxy(java.net.Proxy).

Author:
Janni Kovacs

Method Summary
 ResponseStatus handshake(Session session)
          Performs a web-service handshake.
 ResponseStatus handshake(java.lang.String password)
          Performs a standard handshake with the user's password.
static Scrobbler newScrobbler(java.lang.String clientId, java.lang.String clientVersion, java.lang.String user)
          Creates a new Scrobbler instance bound to the specified user.
 ResponseStatus nowPlaying(java.lang.String artist, java.lang.String track)
          Submits 'now playing' information.
 ResponseStatus nowPlaying(java.lang.String artist, java.lang.String track, java.lang.String album, int length, int tracknumber)
          Submits 'now playing' information.
 ResponseStatus submit(java.util.Collection<SubmissionData> data)
          Scrobbles up to 50 songs at once.
 ResponseStatus submit(java.lang.String artist, java.lang.String track, java.lang.String album, int length, int tracknumber, Source source, long startTime)
          Scrobbles a song.
 ResponseStatus submit(SubmissionData data)
          Scrobbles a song.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

newScrobbler

public static Scrobbler newScrobbler(java.lang.String clientId,
                                     java.lang.String clientVersion,
                                     java.lang.String user)
Creates a new Scrobbler instance bound to the specified user.

Parameters:
clientId - The client id (or "tst")
clientVersion - The client version (or "1.0")
user - The last.fm user
Returns:
a new Scrobbler instance

handshake

public ResponseStatus handshake(java.lang.String password)
                         throws java.io.IOException
Performs a standard handshake with the user's password.

Parameters:
password - The user's password
Returns:
the status of the operation
Throws:
java.io.IOException - on I/O errors

handshake

public ResponseStatus handshake(Session session)
                         throws java.io.IOException
Performs a web-service handshake.

Parameters:
session - An authenticated Session.
Returns:
the status of the operation
Throws:
java.io.IOException - on I/O errors
See Also:
Authenticator

nowPlaying

public ResponseStatus nowPlaying(java.lang.String artist,
                                 java.lang.String track)
                          throws java.io.IOException
Submits 'now playing' information. This does not affect the musical profile of the user.

Parameters:
artist - The artist's name
track - The track's title
Returns:
the status of the operation
Throws:
java.io.IOException - on I/O errors

nowPlaying

public ResponseStatus nowPlaying(java.lang.String artist,
                                 java.lang.String track,
                                 java.lang.String album,
                                 int length,
                                 int tracknumber)
                          throws java.io.IOException
Submits 'now playing' information. This does not affect the musical profile of the user.

Parameters:
artist - The artist's name
track - The track's title
album - The album or null
length - The length of the track in seconds
tracknumber - The position of the track in the album or -1
Returns:
the status of the operation
Throws:
java.io.IOException - on I/O errors

submit

public ResponseStatus submit(java.lang.String artist,
                             java.lang.String track,
                             java.lang.String album,
                             int length,
                             int tracknumber,
                             Source source,
                             long startTime)
                      throws java.io.IOException
Scrobbles a song.

Parameters:
artist - The artist's name
track - The track's title
album - The album or null
length - The length of the track in seconds
tracknumber - The position of the track in the album or -1
source - The source of the track
startTime - The time the track started playing in UNIX timestamp format and UTC time zone
Returns:
the status of the operation
Throws:
java.io.IOException - on I/O errors

submit

public ResponseStatus submit(SubmissionData data)
                      throws java.io.IOException
Scrobbles a song.

Parameters:
data - Contains song information
Returns:
the status of the operation
Throws:
java.io.IOException - on I/O errors

submit

public ResponseStatus submit(java.util.Collection<SubmissionData> data)
                      throws java.io.IOException
Scrobbles up to 50 songs at once. Song info is contained in the Collection passed. Songs must be in chronological order of their play, that means the track first in the list has been played before the track second in the list and so on.

Parameters:
data - A list of song infos
Returns:
the status of the operation
Throws:
java.io.IOException - on I/O errors
java.lang.IllegalArgumentException - if data contains more than 50 entries