/*
* File : Download.java
* Created : 06-Jan-2004
* By : parg
*
* Azureus - a Java Bittorrent client
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details ( see the LICENSE file ).
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
package org.gudy.azureus2.plugins.download;
import java.io.File;
import java.util.Map;
import org.gudy.azureus2.plugins.torrent.Torrent;
import org.gudy.azureus2.plugins.torrent.TorrentAttribute;
import org.gudy.azureus2.plugins.disk.DiskManager;
import org.gudy.azureus2.plugins.disk.DiskManagerFileInfo;
import org.gudy.azureus2.plugins.download.session.SessionAuthenticator;
import org.gudy.azureus2.plugins.peers.PeerManager;
/**
* Management of a Torrent's activity.
*
* <b>Note:</b> All listener based methods are now located in {@link DownloadEventNotifier}.
*
* <PRE>
* 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
* </PRE>
*
* @author parg
*/
public interface
Download extends DownloadEventNotifier
{
/** waiting to be told to start preparing */
public static final int ST_WAITING = 1;
/** getting files ready (allocating/checking) */
public static final int ST_PREPARING = 2;
/** ready to be started if required */
public static final int ST_READY = 3;
/** downloading */
public static final int ST_DOWNLOADING = 4;
/** seeding */
public static final int ST_SEEDING = 5;
/** stopping */
public static final int ST_STOPPING = 6;
/** stopped, do not auto-start! */
public static final int ST_STOPPED = 7;
/** failed */
public static final int ST_ERROR = 8;
/** stopped, but ready for auto-starting */
public static final int ST_QUEUED = 9;
public static final String[] ST_NAMES =
{
"",
"Waiting",
"Preparing",
"Ready",
"Downloading",
"Seeding",
"Stopping",
"Stopped",
"Error",
"Queued",
};
/** 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_HIGH_PRIORITY = 1;
/** Use less of the upload bandwidth than high priority downloads */
public static final int PR_LOW_PRIORITY = 2;
/**
* Flags values
* @since 2.3.0.5
*/
public static final long FLAG_ONLY_EVER_SEEDED = 0x00000001;
public static final long FLAG_SCAN_INCOMPLETE_PIECES = 0x00000002;
/**
* Flag value - if set, it prevents any of the "move on completion" or
* "move on removal" rules taking place.
*
* @since 2.5.0.1
*/
public static final long FLAG_DISABLE_AUTO_FILE_MOVE = 0x00000004;
/**
* 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.
*
* @since 2.5.0.1
*/
public static final long FLAG_MOVE_ON_COMPLETION_DONE = 0x00000008;
/**
* 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
* @since 3.0.1.3
*/
public static final long FLAG_LOW_NOISE = 0x00000010;
/** get state from above ST_ set
* @return ST_ constant
*
* @since 2.0.7.0
*/
public int
getState();
/**
* 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 int
getSubState();
/** When the download state is ERROR this method returns the error details
* @return
*
* @since 2.0.7.0
*/
public String
getErrorStateDetails();
/**
* Get the flag value
* @since 2.3.0.5
* @param flag FLAG value from above
* @return
*/
public boolean getFlag(long flag);
/**
* Set the flag value.
*
* @since 2.5.0.1
* @param flag FLAG value from above
* @param set <code>true</code> to enable the flag, <code>false</code> to disable it.
*/
public void setFlag(long flag, boolean set);
/**
* Index of download. {@link #getPosition()}
* @return index - 0 based
*
* @since 2.0.7.0
*/
public int
getIndex();
/**
* Each download has a corresponding torrent
* @return the download's torrent
*
* @since 2.0.7.0
*/
public Torrent
getTorrent();
/**
* See lifecycle description above
* @throws DownloadException
*
* @since 2.0.7.0
*/
public void
initialize()
throws DownloadException;
/**
* See lifecycle description above
* @throws DownloadException
*
* @since 2.0.7.0
*/
public void
start()
throws DownloadException;
/**
* See lifecycle description above
* @throws DownloadException
*
* @since 2.0.7.0
*/
public void
stop()
throws DownloadException;
/**
* See lifecycle description above
* @throws DownloadException
*
* @since 2.0.8.0
*/
public void
stopAndQueue()
throws DownloadException;
/**
* See lifecycle description above
* @throws DownloadException
*
* @since 2.0.7.0
*/
public void
restart()
throws DownloadException;
/**
* 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
recheckData()
throws DownloadException;
/**
* 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 boolean
isStartStopLocked();
/** Retrieves whether the download is force started
* @return True if download is force started. False if not.
*
* @since 2.0.8.0
*/
public boolean
isForceStart();
/** Set the forcestart state of the download
* @param forceStart True - Download will start, despite any Start/Stop rules/limits<BR>
* False - Turn forcestart state off. Download may or may not stop, depending on
* Start/Stop rules/limits
*
* @since 2.0.8.0
*/
public void
setForceStart(boolean forceStart);
/**
* 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 int
getPriority();
/**
* 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
setPriority(
int priority );
/** 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
isPriorityLocked();
/**
* @since 2403
* @return
*/
public boolean
isPaused();
/**
* Pause the download
* @since 2501
*/
public void
pause();
/**
* Resume the download if paused
* @since 2501
*/
public void
resume();
/** 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 String
getName();
/** Returns the full file path and name of the .torrent file
*
* @return File name of the torrent.
*
* @since 2.1.0.0
*/
public String getTorrentFileName();
/**
* Gets an attribute of this download. For category use the Category torrent attribute
* @param attribute
* @return
*/
public String
getAttribute(
TorrentAttribute attribute );
/**
* 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
setAttribute(
TorrentAttribute attribute,
String value );
public String[]
getListAttribute(
TorrentAttribute attribute );
/**
*
* @param attribute
* @param value
* @since 2.5.0.1
*/
public void setListAttribute(TorrentAttribute attribute, String[] value);
/**
*
* @param attribute
* @param value must be bencodable - key is string, value is Map, List, Long or byte[]
*/
public void
setMapAttribute(
TorrentAttribute attribute,
Map value );
public Map
getMapAttribute(
TorrentAttribute attribute );
/**
* Gets the value of the given attribute from the download. If no value is
* set, then <code>0</code> will be returned.
*/
public int getIntAttribute(TorrentAttribute attribute);
/**
* Sets an integer attribute on this download.
*/
public void setIntAttribute(TorrentAttribute attribute, int value);
/**
* Gets the value of the given attribute from the download. If no value is
* set, then <code>0</code> will be returned.
*/
public long getLongAttribute(TorrentAttribute attribute);
/**
* Sets a long attribute on this download.
*/
public void setLongAttribute(TorrentAttribute attribute, long value);
/**
* Gets the value of the given attribute from the download. If no value is
* set, then <code>false</code> will be returned.
*/
public boolean getBooleanAttribute(TorrentAttribute attribute);
/**
* Sets a boolean attribute on this download.
*/
public void setBooleanAttribute(TorrentAttribute attribute, boolean value);
/**
* Returns <code>true</code> if the download has an explicit value stored for
* the given attribute.
*/
public boolean hasAttribute(TorrentAttribute attribute);
/** 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 String getCategoryName();
/** 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 setCategory(String sName);
/**
* 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()
throws DownloadException, DownloadRemovalVetoException;
/**
* 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
remove(
boolean delete_torrent,
boolean delete_data )
throws DownloadException, DownloadRemovalVetoException;
/**
* 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
getPosition();
/**
* returns the time this download was created in milliseconds
* @return
*/
public long
getCreationTime();
/**
* Sets the position in the queue
* Completed and Incompleted downloads have seperate position sets
*
* @since 2.0.8.0
*/
public void
setPosition(
int newPosition);
/**
* Moves the download position up one
*
* @since 2.1.0.0
*/
public void
moveUp();
/**
* Moves the download down one position
*
* @since 2.1.0.0
*/
public void
moveDown();
/**
* 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
moveTo(
int position );
/**
* 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 boolean
canBeRemoved()
throws DownloadRemovalVetoException;
public void
setAnnounceResult(
DownloadAnnounceResult result );
public void
setScrapeResult(
DownloadScrapeResult result );
/**
* Gives access to the last announce result received from the tracker for the download
* @return
*
* @since 2.0.7.0
*/
public DownloadAnnounceResult
getLastAnnounceResult();
/**
* 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 DownloadScrapeResult
getLastScrapeResult();
/**
* 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 DownloadActivationEvent
getActivationState();
/**
* Gives access to the download's statistics
* @return
*
* @since 2.0.7.0
*/
public DownloadStats
getStats();
/** Downloads can be persistent (be remembered accross Azureus sessions), or
* non-persistent.
*
* @return true - persistent<br>
* false - non-persistent
*
* @since 2.1.0.0
*/
public boolean
isPersistent();
/**
* Sets the maximum download speed in bytes per second. 0 -> unlimited
* @since 2.1.0.2
* @param kb
*/
public void
setMaximumDownloadKBPerSecond(
int kb );
public int
getMaximumDownloadKBPerSecond();
/**
* Get the max upload rate allowed for this download.
* @return upload rate in bytes per second, 0 for unlimited, -1 for upload disabled
*/
public int getUploadRateLimitBytesPerSecond();
/**
* 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 setUploadRateLimitBytesPerSecond( int max_rate_bps );
/**
* 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 int getDownloadRateLimitBytesPerSecond();
/**
* 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 setDownloadRateLimitBytesPerSecond( int max_rate_bps );
/**
* 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();
/**
* 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 isComplete(boolean bIncludeDND);
/**
* 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
isChecking();
/**
* 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 String
getSavePath();
/**
* 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(
File new_parent_dir )
throws DownloadException;
/**
* 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 <tt>moveDataFiles[File]</tt>
* and then <tt>renameDownload[String]</tt>.
*
* For convenience, either argument can be <tt>null</tt>, but not both.
*
* @since 3.0.2
* @throws DownloadException
* @see {@link #moveDataFiles(File)}
* @see {@link #renameDownload(String)}
*/
public void moveDataFiles(File new_parent_dir, String new_name) throws DownloadException;
/**
* 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
moveTorrentFile(
File new_parent_dir )
throws DownloadException;
/**
* 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)}).
*
* <p>
*
* 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 renameDownload(String name) throws DownloadException;
/**
* return the current peer manager for the download.
* @return null returned if torrent currently doesn't have one (e.g. it is stopped)
*/
public PeerManager
getPeerManager();
/**
* Return the disk manager, null if its not running
* @return
* @since 2.3.0.1
*/
public DiskManager
getDiskManager();
/**
* 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 DiskManagerFileInfo[]
getDiskManagerFileInfo();
/**
* request a tracker announce
* @since 2.1.0.5
*/
public void
requestTrackerAnnounce();
/**
* request a tracker announce
* @since 2.3.0.7
*/
public void
requestTrackerAnnounce(
boolean immediate );
/**
* request a tracker announce
* @since 2.3.0.7
*/
public void
requestTrackerScrape(
boolean immediate );
/**
* The torrents with the highest rankings will be seeded first.
*
* @return Seeding Rank
*/
public int getSeedingRank();
/**
* The torrents with the highest rankings will be seeded first.
*
* @param rank New Ranking
*/
public void setSeedingRank(int rank);
/**
* Get the local peerID advertised to the download swarm.
* @return self peer id
*
* @since 2.1.0.5
*/
public byte[] getDownloadPeerId();
/**
* Is advanced AZ messaging enabled for this download.
* @return true if enabled, false if disabled
*/
public boolean isMessagingEnabled();
/**
* Enable or disable advanced AZ messaging for this download.
* @param enabled true to enabled, false to disabled
*/
public void setMessagingEnabled( boolean enabled );
/**
* 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 setSessionAuthenticator( SessionAuthenticator auth );
/**
* 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.
*
* <p>
*
* This method takes one argument - <i>for_moving</i>. 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.
*
* <p>
*
* If <i>for_moving</i> is <tt>false</tt>, 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).
*
* <p>
*
* If <i>for_moving</i> is <tt>true</tt>, 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.
*
* <p>
*
* In this case, the array may contain <tt>null</tt> 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 <tt>File</tt> 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 File[] calculateDefaultPaths(boolean for_moving);
/**
* Returns <tt>true</tt> if the download is being saved to one of the default
* save directories.
*
* @since 2.5.0.2
* @author amc1
*/
public boolean isInDefaultSaveDir();
}
|
