org.eclipse.ecf.protocol.bittorrent
Class Torrent

java.lang.Object
  org.eclipse.ecf.protocol.bittorrent.Torrent

public class Torrent
extends java.lang.Object

The Torrent class is used for hooking onto a TorrentFile so that pieces can be exchanged with peers.

Method Summary

void	addHashCheckListener(IHashCheckListener listener) Adds the specified listener to the collection of listeners for this torrent if it is not already contained.
void	addPieceProgressListener(IPieceProgressListener listener) Adds the specified listener to the collection of listeners for this torrent if it is not already contained.
void	addTorrentErrorListener(ITorrentErrorListener listener) Adds the specified listener to the collection of listeners for this torrent if it is not already contained.
void	addTorrentProgressListener(ITorrentProgressListener listener) Adds the specified listener to the collection of listeners for this torrent if it is not already contained.
void	addTorrentStateListener(ITorrentStateListener listener) Adds the specified listener to the collection of listeners for this torrent if it is not already contained.
boolean	delete() Removes all information pertaining to the opened torrent in addition to removing the target that has been set for downloading or seeding.
int	getConnectedPeers() Retrieves the number of peers that connections have been created for thus far.
long	getDiscarded() Retrieves the amount of data that has been discarded thus far.
long	getDownloaded() Retrieves the amount that has been downloaded thus far since the original call to start().
long	getDownSpeed() Gets the downloading speed as calculated over a twenty second rolling average.
int	getPeers() Returns the total number of peers that are attempting to download this torrent.
long	getRemaining() Retreives the number of bytes that are required to complete the download.
int	getSeeds() Returns the number of seeds that are currently assisting with the distribution.
int	getState() Retrieves the current state in which this torrent is currently in.
long	getTimeRemaining() Retrieves the time in seconds that are remaining for this download to complete.
TorrentFile	getTorrentFile() Retrieves the torrent file that was used to create this torrent.
long	getUploaded() Returns the number of bytes that has been uploaded to peers thus far since calling start().
long	getUpSpeed() Retrieves the uploading speed per calculations over a twenty second rolling average.
boolean	performHashCheck() Performs a hash check on all pieces for this torrnet in a separate thread.
void	remove() Removes all previously saved status and configuration information regarding the opened torrent.
boolean	removeHashCheckListener(IHashCheckListener listener) Removes the specified listener so that it will no longer be notified of pieces have completed the hash checking process.
boolean	removePieceProgressListener(IPieceProgressListener listener) Removes the specified listener so that it will no longer be notified of a piece having downloaded some additional bytes.
boolean	removeTorrentErrorListener(ITorrentErrorListener listener) Removes the specified listener so that it will no longer be notified of errors.
boolean	removeTorrentProgressListener(ITorrentProgressListener listener) Removes the specified listener so that it will no longer be notified when pieces has been completed.
boolean	removeTorrentStateListener(ITorrentStateListener listener) Removes the specified listener so that it will no longer be notified of state updates.
void	setFilesToDownload(int[] downloadChoices) Setup file download priority levels and whether a file should even be downloaded at all.
void	setMaxConnections(int maxConnections) Sets the maximum number of connections that this torrent should attempt to connect to.
void	setMaxDownloadSpeed(long maximum) Sets the maximum number of bytes to download per second from peers.
void	setMaxUploadSpeed(long maximum) Sets the maximum number of bytes to upload per second to peers.
void	start() Contacts the tracker to begin exchanging pieces with any peers that are found.
void	stop() Stops downloading, seeding, or the hash checking process for this torrent.

Methods inherited from class java.lang.Object

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

Method Detail

start

public void start()
           throws java.io.IOException

Contacts the tracker to begin exchanging pieces with any peers that are found.

Throws:

java.io.IOException - If an error occurs while querying the tracker or connecting to one of the provided peers

stop

public void stop()
          throws java.io.IOException

Stops downloading, seeding, or the hash checking process for this torrent. It is crucial that this method be called for termination as it will perform clean-up on lingering threads that are performing background operations.

Throws:

java.io.IOException - If an IOException occurred while informing the tracker that the client is stopping

remove

public void remove()

Removes all previously saved status and configuration information regarding the opened torrent. This will call stop() prior to the deletion of the files.

delete

public boolean delete()

Removes all information pertaining to the opened torrent in addition to removing the target that has been set for downloading or seeding.

Returns:

true if the target file or directory has been deleted successfully, false otherwise

performHashCheck

public boolean performHashCheck()

Performs a hash check on all pieces for this torrnet in a separate thread. This may not necessarily run if the torrent is currently performing other actions. The returned value will indicate whether the hash check is being performed or not.

Returns:

true if the torrent will begin performing hash check on its pieces on a separate thread or is already running a hash check, false if the torrent is currently performing other operations and is unable to run a hash check

addTorrentStateListener

public void addTorrentStateListener(ITorrentStateListener listener)
                             throws java.lang.IllegalArgumentException

Adds the specified listener to the collection of listeners for this torrent if it is not already contained. The listener will be notified of the changes of the current state of the torrent's activity. The event's state will correspond to the value returned from getState().

Parameters:

listener - the listener to notify

Throws:

java.lang.IllegalArgumentException - If listener is null

addTorrentProgressListener

public void addTorrentProgressListener(ITorrentProgressListener listener)
                                throws java.lang.IllegalArgumentException

Adds the specified listener to the collection of listeners for this torrent if it is not already contained. The listener will be notified when another piece has been completed by verifying it against a hash sum.

Parameters:

listener - the listener to notify

Throws:

java.lang.IllegalArgumentException - If listener is null

addPieceProgressListener

public void addPieceProgressListener(IPieceProgressListener listener)
                              throws java.lang.IllegalArgumentException

Adds the specified listener to the collection of listeners for this torrent if it is not already contained. The listener will be notified when a piece has downloaded some amount of additional bytes.

Parameters:

listener - the listener to notify

Throws:

java.lang.IllegalArgumentException - If listener is null

addHashCheckListener

public void addHashCheckListener(IHashCheckListener listener)

Adds the specified listener to the collection of listeners for this torrent if it is not already contained. The listener will be notified when a piece has successfully completed its hash check.

Parameters:

listener - the listener to notify

Throws:

java.lang.IllegalArgumentException - If listener is null

addTorrentErrorListener

public void addTorrentErrorListener(ITorrentErrorListener listener)
                             throws java.lang.IllegalArgumentException

Adds the specified listener to the collection of listeners for this torrent if it is not already contained. The listener will be notified when errors such as tracker failures or hash check failures occurs.

Parameters:

listener - the listener to notify

Throws:

java.lang.IllegalArgumentException - If listener is null

removeTorrentStateListener

public boolean removeTorrentStateListener(ITorrentStateListener listener)

Removes the specified listener so that it will no longer be notified of state updates.

Parameters:

listener - the listener to remove

Returns:

true if one such listener was removed, false otherwise

removeTorrentProgressListener

public boolean removeTorrentProgressListener(ITorrentProgressListener listener)

Removes the specified listener so that it will no longer be notified when pieces has been completed.

Parameters:

listener - the listener to remove

Returns:

true if one such listener was removed, false otherwise

removePieceProgressListener

public boolean removePieceProgressListener(IPieceProgressListener listener)

Removes the specified listener so that it will no longer be notified of a piece having downloaded some additional bytes.

Parameters:

listener - the listener to remove

Returns:

true if one such listener was removed, false otherwise

removeHashCheckListener

public boolean removeHashCheckListener(IHashCheckListener listener)

Removes the specified listener so that it will no longer be notified of pieces have completed the hash checking process.

Parameters:

listener - the listener to remove

Returns:

true if one such listener was removed, false otherwise

removeTorrentErrorListener

public boolean removeTorrentErrorListener(ITorrentErrorListener listener)

Removes the specified listener so that it will no longer be notified of errors.

Parameters:

listener - the listener to remove

Returns:

true if one such listener was removed, false otherwise

setMaxConnections

public void setMaxConnections(int maxConnections)
                       throws java.lang.IllegalArgumentException

Sets the maximum number of connections that this torrent should attempt to connect to. The default value is set to 50 although 30 peers should already be plenty. This value should not be heightened unless there is a good reason to do so as it will likely cause network congestions.

Parameters:

maxConnections - the maximum number of connections that should be used

Throws:

java.lang.IllegalArgumentException - If maxConnections is negative

setFilesToDownload

public void setFilesToDownload(int[] downloadChoices)

Setup file download priority levels and whether a file should even be downloaded at all.

Parameters:

downloadChoices - an integer array which stores a value greater than zero if the file should have a high priority, a value equal to zero if it should have a regular priority, or less than zero if it should not be downloaded at all, the values should correspond to the files returned from TorrentFile's TorrentFile.getFilenames() method

Throws:

java.lang.IllegalArgumentException - If downloadChoices is null or if the length of the array is not equal to the number of files for this torrent

getDownloaded

public long getDownloaded()

Retrieves the amount that has been downloaded thus far since the original call to start().

Returns:

the amount of bytes that has been downloaded from peers

getUploaded

public long getUploaded()

Returns the number of bytes that has been uploaded to peers thus far since calling start().

Returns:

the amount of bytes that has been uploaded to peers

getRemaining

public long getRemaining()

Retreives the number of bytes that are required to complete the download.

Returns:

the number of bytes left to complete the download

getDownSpeed

public long getDownSpeed()

Gets the downloading speed as calculated over a twenty second rolling average.

Returns:

the speed at which bytes are being downloaded from peers

getUpSpeed

public long getUpSpeed()

Retrieves the uploading speed per calculations over a twenty second rolling average.

Returns:

the speed at which bytes are being uploaded to peers

setMaxDownloadSpeed

public void setMaxDownloadSpeed(long maximum)

Sets the maximum number of bytes to download per second from peers. If maximum is zero or negative, the speed capping limit will be lifted.

Parameters:

maximum - the maximum number of bytes that should be downloaded from peers per second

setMaxUploadSpeed

public void setMaxUploadSpeed(long maximum)

Sets the maximum number of bytes to upload per second to peers. If maximum is zero or negative, the speed capping limit will be lifted.

Parameters:

maximum - the maximum number of bytes that should be uploaded to peers per second

getTimeRemaining

public long getTimeRemaining()

Retrieves the time in seconds that are remaining for this download to complete. If the returned value is -1, the time is unknown. This will be returned when the downloading speed is at 0.

Returns:

the time remaining in seconds for the download to complete or -1 if the value is not known

getDiscarded

public long getDiscarded()

Retrieves the amount of data that has been discarded thus far. This is caused by pieces that has failed the integrity hash check.

Returns:

the amount of bytes that has been discarded

getConnectedPeers

public int getConnectedPeers()

Retrieves the number of peers that connections have been created for thus far.

Returns:

the number of connected peers

getSeeds

public int getSeeds()

Returns the number of seeds that are currently assisting with the distribution.

Returns:

the number of connected seeds, if the value is -1, the tracker does not support the distribution of this information

See Also:

getPeers()

getPeers

public int getPeers()

Returns the total number of peers that are attempting to download this torrent.

Returns:

the total number of connected peers on the torrent, if the value is -1, the tracker does not support the distribution of this information

See Also:

getSeeds()

getTorrentFile

public TorrentFile getTorrentFile()

Retrieves the torrent file that was used to create this torrent.

Returns:

the TorrentFile that initialized this

getState

public int getState()

Retrieves the current state in which this torrent is currently in. This could be any one of the states provided by the ITorrentStateListener interface.

Returns:

the state that this torrent is currently in

See Also:

ITorrentStateListener.STARTED, ITorrentStateListener.EXCHANGING, ITorrentStateListener.STOPPED, ITorrentStateListener.FINISHED, ITorrentStateListener.HASH_CHECKING