com.cutunes.client
Class ClientCommunicator

java.lang.Object
  com.cutunes.client.ClientCommunicator

public class ClientCommunicator

extends java.lang.Object

Client communicator defines the main point of communication between the client (through either a Java app or web-based applet) and the server. This class:

Initializes communication with the server

Verifies the users login information

Discovers the user's last sync date

Attempts to discover the location of the user's iTunes XML file

Initializes an ItunesXMLParser (SAX parser) which extracts song information

Queues songs until a batch is ready to be send to the server over XML-RPC

Sends all songs as required

Records the user's last sync date

Provides methods for getting information for the playlist generation application The standard XML SAX parser is extended as ItunesXMLParser to extract the song information. XML-RPC is used for all server communication using a very simple API.

Author:

blake, hal2001

Method Summary

void	addPlaylistToQueue(java.util.Hashtable playlistHash) Adds a single playlistHash object to a Vector of playlistHashes.
void	addSongToQueue(java.util.Hashtable songHash) Adds a single songHash object to a Vector of songHashes.
int	countForArtist(java.lang.String query) Returns the number of playcounts for all users for a given artist.
java.util.Vector	getArtistsLike(java.lang.String artist) For playlist Generation.
java.util.Vector	getArtistsOfUser(int userID, int myUserID, int limit) Get the top N artists of a user that the current user also has.
static ClientCommunicator	getInstance() Java singleton getInstance() method insures only a single instance of the ClientCommunicator is ever instantiated.
java.sql.Timestamp	getLastSync(int userID) Queries server to the get the Timestamp of a given user's last sync.
java.util.Vector	getSongsForArtist(java.lang.String artist, int userID, int numItems) Get a N songs that a user has of a given artist.
int	getUserID(java.lang.String username, java.lang.String password) Queries the server to get the userID integer based on that users username/password pair.
java.util.Vector	getUserIDFor(java.lang.String query)
void	logPlaylist(java.lang.String query, int userID) Logs a user creating a playlist from a query
static void	main(java.lang.String[] args) Simple main method will parse and sync current user's information based on command line parameters.
static boolean	parseAndSyncData(java.lang.String username, java.lang.String password, boolean usingApplet) Instanitates ItunesXMLParser and parses the current user's iTunes XML file.
void	sendPlaylistGroup(int userID, java.lang.String user, java.util.Vector playlists) Sends the current group of SongHashes in songs Vector to the server using XML-RPC.
void	sendPlaylistQueueNow() Sends all playlistHash objects queued in playlistGroup Vector to the server immediately using XML-RPC.
void	sendSongGroup(int userID, java.lang.String user, java.util.Vector songs) Sends the current group of SongHashes in songs Vector to the server using XML-RPC.
void	sendSongQueueNow() Sends any songHash objects queued in songGroup Vector to the server immediately using XML-RPC.
void	setLastSync(int userID) Queries the server to set the last sync time for the giving user to the current time.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static ClientCommunicator getInstance()

Java singleton getInstance() method insures only a single instance of the ClientCommunicator is ever instantiated.

Returns:

Returns a reference to the singleton object

getUserID

public int getUserID(java.lang.String username,
                     java.lang.String password)

Queries the server to get the userID integer based on that users username/password pair. If username/password are incorrect or do not exist, the server will return a negative value.

Parameters:

username - String username

password - String password

Returns:

UserID or negative value if incorrect password.

getLastSync

public java.sql.Timestamp getLastSync(int userID)

Queries server to the get the Timestamp of a given user's last sync.

Parameters:

userID - UserID to get last sync for

Returns:

Timestamp of last sync

setLastSync

public void setLastSync(int userID)

Queries the server to set the last sync time for the giving user to the current time.

Parameters:

userID - UserID to set last sync time for

addSongToQueue

public void addSongToQueue(java.util.Hashtable songHash)

Adds a single songHash object to a Vector of songHashes. When the Vector grows larger than SONG_GROUP_SIZE, that songGroup is sent to the server with sendSongGroup() and a new Vector is created.

Parameters:

songHash - SongHash object to add the queue

sendSongQueueNow

public void sendSongQueueNow()

Sends any songHash objects queued in songGroup Vector to the server immediately using XML-RPC.

addPlaylistToQueue

public void addPlaylistToQueue(java.util.Hashtable playlistHash)

Adds a single playlistHash object to a Vector of playlistHashes.

Parameters:

playlistHash - playlistHash object to add the queue

sendPlaylistQueueNow

public void sendPlaylistQueueNow()

Sends all playlistHash objects queued in playlistGroup Vector to the server immediately using XML-RPC.

sendPlaylistGroup

public void sendPlaylistGroup(int userID,
                              java.lang.String user,
                              java.util.Vector playlists)

Sends the current group of SongHashes in songs Vector to the server using XML-RPC. Adds necessary information like userIB, lastSync, VERSION, etc to the XML-RPC message.

Parameters:

userID - UserID of current user

user - Username of current user

sendSongGroup

public void sendSongGroup(int userID,
                          java.lang.String user,
                          java.util.Vector songs)

Sends the current group of SongHashes in songs Vector to the server using XML-RPC. Adds necessary information like userIB, lastSync, VERSION, etc to the XML-RPC message.

Parameters:

userID - UserID of current user

user - Username of current user

songs - Vector of songHash objects to send

parseAndSyncData

public static boolean parseAndSyncData(java.lang.String username,
                                       java.lang.String password,
                                       boolean usingApplet)

Instanitates ItunesXMLParser and parses the current user's iTunes XML file. Determines correct location of iTunes XML file based on user's home directory and operating system. Currently only supports Mac OS X and Windows XP with iTunes file in standard user directory location.

If the user has never synced before, all songs will be sent to the server. Otherwise, only songs that have been played since the last sync will be sent. At the end of parsing/sending songs, the users last sync time will be updated to the current time.

If an applet is used to run this method (the usingApplet boolean is true) the applet status box will be updated.

Parameters:

username - Username of current user

password - Password of current user

usingApplet - Whether an applet is called this method or not

Returns:

True if parse/sync successful, false otherwise

getArtistsLike

public java.util.Vector getArtistsLike(java.lang.String artist)

For playlist Generation. Return a vector of artists that are similar to a specified artist.

Parameters:

artist - the specified artist

Returns:

A vector containing similar artists

getSongsForArtist

public java.util.Vector getSongsForArtist(java.lang.String artist,
                                          int userID,
                                          int numItems)

Get a N songs that a user has of a given artist. The method returns a vector of song vectors. Each song vector is a vector with 4 elements (song name, album, artist, score)

Parameters:

artist - the artist

userID - current user ID

numItems - number of songs to retrieve

Returns:

a vector of song vectors

getArtistsOfUser

public java.util.Vector getArtistsOfUser(int userID,
                                         int myUserID,
                                         int limit)

Get the top N artists of a user that the current user also has. The method returns a vector artist vectors, each of which contains and artist name, and a score.

Parameters:

userID - the other user

myUserID - the current user

limit - the number of artists to retrieve

Returns:

a vector of artist vectors

getUserIDFor

public java.util.Vector getUserIDFor(java.lang.String query)

countForArtist

public int countForArtist(java.lang.String query)

Returns the number of playcounts for all users for a given artist. Used to check if an artist exists. 0 if not found.

Parameters:

query - the possible artist

Returns:

number of playcounts

logPlaylist

public void logPlaylist(java.lang.String query,
                        int userID)

Logs a user creating a playlist from a query

Parameters:

query -

userID -

main

public static void main(java.lang.String[] args)

Simple main method will parse and sync current user's information based on command line parameters.

Parameters:

args - Requires USERNAME PASSWORD parameters