File Doc Category Size Date Package
Download.java API Doc Azureus 3.0.3.4 23787 Fri Aug 03 11:21:06 BST 2007 org.gudy.azureus2.plugins.download

Download

public interface Download implements DownloadEventNotifier

Management of a Torrent's activity. Note: All listener based methods are now located in {@link DownloadEventNotifier}.

A download's lifecycle:
torrent gets added
state -> QUEUED
slot becomes available, queued torrent is picked, "restart" executed
state -> WAITING
state moves through PREPARING to READY
state -> PREPARING
state -> READY
execute "start" method
state -> SEEDING -or- DOWNLOADING
if torrent is DOWNLOADING, and completes, state changes to SEEDING

Path 1 | Path 2
-------------------------+------------------------------------------------
execute "stop" method | startstop rules are met, execute "stopandQueue"
state -> STOPPING | state -> STOPPING
state -> STOPPED | state -> STOPPED
| state -> QUEUED
execute "remove" method -> deletes the download
a "stop" method call can be made when the download is in all states except STOPPED

author: parg

Fields Summary
public static final int
ST_WAITING
waiting to be told to start preparing
public static final int
ST_PREPARING
getting files ready (allocating/checking)
public static final int
ST_READY
ready to be started if required
public static final int
ST_DOWNLOADING
downloading
public static final int
ST_SEEDING
seeding
public static final int
ST_STOPPING
stopping
public static final int
ST_STOPPED
stopped, do not auto-start!
public static final int
ST_ERROR
failed
public static final int
ST_QUEUED
stopped, but ready for auto-starting
public static final String[]
ST_NAMES
public static final int
PR_HIGH_PRIORITY
Use more of the upload bandwidth than low priority downloads don't change these as they are used by remote clients
public static final int
PR_LOW_PRIORITY
Use less of the upload bandwidth than high priority downloads
public static final long
FLAG_ONLY_EVER_SEEDED
Flags values
public static final long
FLAG_SCAN_INCOMPLETE_PIECES
public static final long
FLAG_DISABLE_AUTO_FILE_MOVE
Flag value - if set, it prevents any of the "move on completion" or "move on removal" rules taking place.
public static final long
FLAG_MOVE_ON_COMPLETION_DONE
Flag value - if set, then it means this download has been considered for "move on completion", and it should not be considered again for it. This value is more for internal use rather than plugin use.
public static final long
FLAG_LOW_NOISE
Flag value - if set the user won't be bothered with popups/completion events during the download's life. This is used, for example, for downloads used to run speed-tests
Constructors Summary
Methods Summary
public java.io.File[] calculateDefaultPaths(boolean for_moving)
Returns an array of size 2 indicating the appropriate locations for this download's data files and torrent file, based on Azureus's rules regarding default save paths, and move on completion rules.
This method takes one argument - for_moving. This essentially indicates whether you are getting this information for purposes of just finding where Azureus would store these files by default, or whether you are considering moving the files from its current location.
If for_moving is false, this method will determine locations for the download and the torrent file where Azureus would store them by default (it may return the current paths used by this download).
If for_moving is true, then this method will consider the download's current location, and whether it is allowed to move it - you may not be allowed to move this download (based on Azureus's current rules) if the download doesn't exist within a default save directory already. If a download is complete, we consider whether we are allowed to move downloads on completion, and whether that includes downloads outside the default save directory.
In this case, the array may contain null indicating that the Azureus doesn't believe that the download should be moved (based on the current rules the user has set out). However, you are not prevented from changing the location of the torrent file or download.
since
2.5.0.2
param
for_moving Indicates whether you want this information for the purposes of moving the download or not.
author
amc1
return
An array of type File of size 2, first element containing the calculated location for the download's data files, and the second element containing the location for the download's torrent file.
public boolean canBeRemoved()
Tests whether or not a download can be removed. Due to synchronization issues it is possible for a download to report OK here but still fail removal.
return
throws
DownloadRemovalVetoException
since
2.0.7.0
public DownloadActivationEvent getActivationState()
Gives access to the current activation state. Note that we currently only fire the activation listener on an increase in activation requirements. This method however gives the current view of the state and takes into account decreases too
return
since
2.4.0.3
public java.lang.String getAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute)
Gets an attribute of this download. For category use the Category torrent attribute
param
attribute
return
public boolean getBooleanAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute)
Gets the value of the given attribute from the download. If no value is set, then false will be returned.
public java.lang.String getCategoryName()
Returns the name of the Category
return
name of the category
since
2.1.0.0
deprecated
Use TorrentAttribute.TA_CATEGORY (2.2.0.3)
public long getCreationTime()
returns the time this download was created in milliseconds
return
public org.gudy.azureus2.plugins.disk.DiskManager getDiskManager()
Return the disk manager, null if its not running
return
since
2.3.0.1
public org.gudy.azureus2.plugins.disk.DiskManagerFileInfo[] getDiskManagerFileInfo()
Returns info about the torrent's files. Note that this will return "stub" values if the download isn't running (not including info such as completion status)
return
since
2.3.0.1
public byte[] getDownloadPeerId()
Get the local peerID advertised to the download swarm.
return
self peer id
since
2.1.0.5
public int getDownloadRateLimitBytesPerSecond()
Get the max download rate allowed for this download.
return
upload rate in bytes per second, 0 for unlimited, -1 for download disabled
since
3013
public java.lang.String getErrorStateDetails()
When the download state is ERROR this method returns the error details
return
since
2.0.7.0
public boolean getFlag(long flag)
Get the flag value
since
2.3.0.5
param
flag FLAG value from above
return
public int getIndex()
Index of download. {@link #getPosition()}
return
index - 0 based
since
2.0.7.0
public int getIntAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute)
Gets the value of the given attribute from the download. If no value is set, then 0 will be returned.
public DownloadAnnounceResult getLastAnnounceResult()
Gives access to the last announce result received from the tracker for the download
return
since
2.0.7.0
public DownloadScrapeResult getLastScrapeResult()
Gives access to the last scrape result received from the tracker for the download
return
a non-null DownloadScrapeResult
since
2.0.7.0
public java.lang.String[] getListAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute)
public long getLongAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute)
Gets the value of the given attribute from the download. If no value is set, then 0 will be returned.
public java.util.Map getMapAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute)
public int getMaximumDownloadKBPerSecond()
public java.lang.String getName()
Returns the name of the torrent. Similar to Torrent.getName() and is usefull if getTorrent() returns null and you still need the name.
return
name of the torrent
since
2.0.8.0
public org.gudy.azureus2.plugins.peers.PeerManager getPeerManager()
return the current peer manager for the download.
return
null returned if torrent currently doesn't have one (e.g. it is stopped)
public int getPosition()
Returns the current position in the queue Completed and Incompleted downloads have seperate position sets. This means we can have a position x for Completed, and position x for Incompleted.
since
2.0.8.0
public int getPriority()
Downloads can either be low or high priority (see PR_ constants above)
return
the download's priority
deprecated
>= 2.1.0.6 does nothing
since
2.0.7.0
public java.lang.String getSavePath()
This returns the full save path for the download. If the download is a simple torrent, this will be the full path of the file being downloaded. If the download is a multiple file torrent, this will be the path to the directory containing all the files in the torrent.
return
Full save path for this download.
public int getSeedingRank()
The torrents with the highest rankings will be seeded first.
return
Seeding Rank
public int getState()
get state from above ST_ set
return
ST_ constant
since
2.0.7.0
public DownloadStats getStats()
Gives access to the download's statistics
return
since
2.0.7.0
public int getSubState()
For the STOPPING state this method gives the state that is being transited too (STOPPED, QUEUED or ERROR)
return
since
2.3.0.5
public org.gudy.azureus2.plugins.torrent.Torrent getTorrent()
Each download has a corresponding torrent
return
the download's torrent
since
2.0.7.0
public java.lang.String getTorrentFileName()
Returns the full file path and name of the .torrent file
return
File name of the torrent.
since
2.1.0.0
public int getUploadRateLimitBytesPerSecond()
Get the max upload rate allowed for this download.
return
upload rate in bytes per second, 0 for unlimited, -1 for upload disabled
public boolean hasAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute)
Returns true if the download has an explicit value stored for the given attribute.
public void initialize()
See lifecycle description above
throws
DownloadException
since
2.0.7.0
public boolean isChecking()
When a download is completed it is rechecked (if the option is enabled). This method returns true during this phase (at which time the status will be seeding)
return
since
2.3.0.6
public boolean isComplete()
Indicates if the download has completed or not, exluding any files marked as Do No Download
return
Download Complete status
since
2.1.0.4
public boolean isComplete(boolean bIncludeDND)
Indicates if the download has completed or not
param
bIncludeDND Whether to include DND files when determining completion state
return
Download Complete status
since
2.4.0.3
public boolean isForceStart()
Retrieves whether the download is force started
return
True if download is force started. False if not.
since
2.0.8.0
public boolean isInDefaultSaveDir()
Returns true if the download is being saved to one of the default save directories.
since
2.5.0.2
author
amc1
public boolean isMessagingEnabled()
Is advanced AZ messaging enabled for this download.
return
true if enabled, false if disabled
public boolean isPaused()
since
2403
return
public boolean isPersistent()
Downloads can be persistent (be remembered accross Azureus sessions), or non-persistent.
return
true - persistent
false - non-persistent
since
2.1.0.0
public boolean isPriorityLocked()
When a download's priority is locked this means that seeding rules should not change a downloads priority, it is under manual control
return
whether it is locked or not
deprecated
>= 2.0.8.0 does nothing
since
2.0.7.0
public boolean isStartStopLocked()
When a download is "start-stop locked" it means that seeding rules shouldn't start or stop the download as it is under manual control
return
True if download is locked and should not be started or stopped
since
2.0.7.0
public void moveDataFiles(java.io.File new_parent_dir)
Move a download's data files to a new location. Download must be stopped and persistent
since
2.3.0.5
param
new_parent_dir
throws
DownloadException
public void moveDataFiles(java.io.File new_parent_dir, java.lang.String new_name)
Move a download's data files to a new location, and rename the download at the same time. Download must be stopped and persistent. This is equivalent to calling moveDataFiles[File] and then renameDownload[String]. For convenience, either argument can be null, but not both.
since
3.0.2
throws
DownloadException
see
{@link #moveDataFiles(File)}
see
{@link #renameDownload(String)}
public void moveDown()
Moves the download down one position
since
2.1.0.0
public void moveTo(int position)
Moves a download and re-orders the others appropriately. Note that setPosition does not do this, it merely sets the position thus making it possible, for example, for two downloads to have the same position
param
position
since
2.3.0.7
public void moveTorrentFile(java.io.File new_parent_dir)
Move a download's torrent file to a new location. Download must be stopped and persistent
since
2.3.0.5
param
new_parent_dir
throws
DownloadException
public void moveUp()
Moves the download position up one
since
2.1.0.0
public void pause()
Pause the download
since
2501
public void recheckData()
Performs a complete recheck of the downloaded data Download must be in stopped, queued or error state Action is performed asynchronously and will progress the download through states PREPARING back to the relevant state
throws
DownloadException
since
2.1.0.3
public void remove()
Removes a download. The download must be stopped or in error. Removal may fail if another component does not want the removal to occur - in this case a "veto" exception is thrown
throws
DownloadException
throws
DownloadRemovalVetoException
since
2.0.7.0
public void remove(boolean delete_torrent, boolean delete_data)
Same as "remove" but, if successful, deletes the torrent and/or data
param
delete_torrent
param
delete_data
throws
DownloadException
throws
DownloadRemovalVetoException
since
2.2.0.3
public void renameDownload(java.lang.String name)
Renames the file (for a single file torrent) or directory (for a multi file torrent) where the download is being saved to. The download must be in a state to move the data files to a new location (see {@link #moveDataFiles(File)}).
This will not rename the displayed name for the torrent - if you wish to do that, you must do it via the {@link org.gudy.azureus2.plugins.torrent.TorrentAttribute TorrentAttribute} class.
param
name New name for the download.
see
#moveDataFiles(File)
public void requestTrackerAnnounce()
request a tracker announce
since
2.1.0.5
public void requestTrackerAnnounce(boolean immediate)
request a tracker announce
since
2.3.0.7
public void requestTrackerScrape(boolean immediate)
request a tracker announce
since
2.3.0.7
public void restart()
See lifecycle description above
throws
DownloadException
since
2.0.7.0
public void resume()
Resume the download if paused
since
2501
public void setAnnounceResult(DownloadAnnounceResult result)
public void setAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute, java.lang.String value)
Sets an attribute of this download. For category use the Category torrent attribute
param
attribute Previously created attribute
param
value Value to store. null to remove attribute
public void setBooleanAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute, boolean value)
Sets a boolean attribute on this download.
public void setCategory(java.lang.String sName)
Sets the category for the download
param
sName Category name
since
2.1.0.0
deprecated
Use TorrentAttribute.TA_CATEGORY (2.2.0.3)
public void setDownloadRateLimitBytesPerSecond(int max_rate_bps)
Set the max download rate allowed for this download.
param
max_rate_bps limit in bytes per second, 0 for unlimited, -1 for dowmload disabled
since
3013
public void setFlag(long flag, boolean set)
Set the flag value.
since
2.5.0.1
param
flag FLAG value from above
param
set true to enable the flag, false to disable it.
public void setForceStart(boolean forceStart)
Set the forcestart state of the download
param
forceStart True - Download will start, despite any Start/Stop rules/limits
False - Turn forcestart state off. Download may or may not stop, depending on Start/Stop rules/limits
since
2.0.8.0
public void setIntAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute, int value)
Sets an integer attribute on this download.
public void setListAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute, java.lang.String[] value)
param
attribute
param
value
since
2.5.0.1
public void setLongAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute, long value)
Sets a long attribute on this download.
public void setMapAttribute(org.gudy.azureus2.plugins.torrent.TorrentAttribute attribute, java.util.Map value)
param
attribute
param
value must be bencodable - key is string, value is Map, List, Long or byte[]
public void setMaximumDownloadKBPerSecond(int kb)
Sets the maximum download speed in bytes per second. 0 -> unlimited
since
2.1.0.2
param
kb
public void setMessagingEnabled(boolean enabled)
Enable or disable advanced AZ messaging for this download.
param
enabled true to enabled, false to disabled
public void setPosition(int newPosition)
Sets the position in the queue Completed and Incompleted downloads have seperate position sets
since
2.0.8.0
public void setPriority(int priority)
This method sets a download's priority
param
priority the required priority, see PR_ constants above
deprecated
>= 2.1.0.6 does nothing
since
2.0.7.0
public void setScrapeResult(DownloadScrapeResult result)
public void setSeedingRank(int rank)
The torrents with the highest rankings will be seeded first.
param
rank New Ranking
public void setSessionAuthenticator(org.gudy.azureus2.plugins.download.session.SessionAuthenticator auth)
Set the authenticator that will be used by this download to handle secure torrent session handshaking and data encryption/decryption.
param
auth handler
public void setUploadRateLimitBytesPerSecond(int max_rate_bps)
Set the max upload rate allowed for this download.
param
max_rate_bps limit in bytes per second, 0 for unlimited, -1 for upload disabled
public void start()
See lifecycle description above
throws
DownloadException
since
2.0.7.0
public void stop()
See lifecycle description above
throws
DownloadException
since
2.0.7.0
public void stopAndQueue()
See lifecycle description above
throws
DownloadException
since
2.0.8.0