Interface Download

All Superinterfaces:
DownloadEventNotifier, DownloadStub, Taggable
All Known Implementing Classes:
DownloadImpl, LWSDownload, RPDownload
public interface Download extends DownloadEventNotifier, DownloadStub, Taggable
Management of a Torrent's activity. Note: All listener based methods are now located in 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

  • Field Details

    • ST_WAITING

      static final int ST_WAITING
      waiting to be told to start preparing
      See Also:

    • ST_PREPARING

      static final int ST_PREPARING
      getting files ready (allocating/checking)
      See Also:

    • ST_READY

      static final int ST_READY
      ready to be started if required
      See Also:

    • ST_DOWNLOADING

      static final int ST_DOWNLOADING
      downloading
      See Also:

    • ST_SEEDING

      static final int ST_SEEDING
      seeding
      See Also:

    • ST_STOPPING

      static final int ST_STOPPING
      stopping
      See Also:

    • ST_STOPPED

      static final int ST_STOPPED
      stopped, do not auto-start!
      See Also:

    • ST_ERROR

      static final int ST_ERROR
      failed
      See Also:

    • ST_QUEUED

      static final int ST_QUEUED
      stopped, but ready for auto-starting
      See Also:

    • ST_NAMES

      static final String[] ST_NAMES

    • FLAG_ONLY_EVER_SEEDED

      static final long FLAG_ONLY_EVER_SEEDED
      Flags values
      Since:
      2.3.0.5
      See Also:

    • FLAG_SCAN_INCOMPLETE_PIECES

      static final long FLAG_SCAN_INCOMPLETE_PIECES
      See Also:

    • FLAG_DISABLE_AUTO_FILE_MOVE

      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.
      Since:
      2.5.0.1
      See Also:

    • FLAG_MOVE_ON_COMPLETION_DONE

      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.
      Since:
      2.5.0.1
      See Also:

    • FLAG_LOW_NOISE

      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
      Since:
      3.0.1.3
      See Also:

    • FLAG_ALLOW_PERMITTED_PEER_SOURCE_CHANGES

      static final long FLAG_ALLOW_PERMITTED_PEER_SOURCE_CHANGES
      Flag value - normally the permitted peer sources for a download are fixed and can't be changed this flag allows the permitted peer source set to be increased/decreased (but not beyond the enforced values required to honour a torrent's 'private' flag
      See Also:

    • FLAG_DO_NOT_DELETE_DATA_ON_REMOVE

      static final long FLAG_DO_NOT_DELETE_DATA_ON_REMOVE
      Flag value - if set the data will not be delete when the download is "deleted" from the v3 interface.
      Since:
      3.1.0.0
      See Also:

    • FLAG_FORCE_DIRECT_DELETE

      static final long FLAG_FORCE_DIRECT_DELETE
      Force direct delete of download data when delete requested, rather than recoverable delete, and no user prompt
      Since:
      4.3.1.5
      See Also:

    • FLAG_DISABLE_IP_FILTER

      static final long FLAG_DISABLE_IP_FILTER
      Used to disable IP filter rules for a download when ip-filtering is enabled
      Since:
      4.7.0.3
      See Also:

    • FLAG_METADATA_DOWNLOAD

      static final long FLAG_METADATA_DOWNLOAD
      Since:
      4.7.0.4 indicates that the download is just a metadata downloader and not a 'real' one (yet)
      See Also:

    • FLAG_LIGHT_WEIGHT

      static final long FLAG_LIGHT_WEIGHT
      See Also:

    • FLAG_ERROR_REPORTED

      static final long FLAG_ERROR_REPORTED
      Since:
      5701
      See Also:

    • FLAG_INITIAL_NETWORKS_SET

      static final long FLAG_INITIAL_NETWORKS_SET
      Since:
      5721
      See Also:

    • FLAG_SEQUENTIAL_DOWNLOAD

      static final long FLAG_SEQUENTIAL_DOWNLOAD
      Since:
      BiglyBT 1.0.2.1
      See Also:

    • FLAG_DISABLE_STOP_AFTER_ALLOC

      static final long FLAG_DISABLE_STOP_AFTER_ALLOC
      Since:
      BiglyBT 2.0.0.1
      See Also:

    • UD_KEY_START_REASON

      static final Object UD_KEY_START_REASON

    • UD_KEY_STOP_REASON

      static final Object UD_KEY_STOP_REASON

    • UD_KEY_QUEUE_REASON

      static final Object UD_KEY_QUEUE_REASON

  • Method Details

    • getState

      int getState()
      get state from above ST_ set
      Returns:
      ST_ constant
      Since:
      2.0.7.0

    • getSubState

      int getSubState()
      For the STOPPING state this method gives the state that is being transited too (STOPPED, QUEUED or ERROR)
      Returns:
      Since:
      2.3.0.5

    • getErrorStateDetails

      String getErrorStateDetails()
      When the download state is ERROR this method returns the error details
      Returns:
      Since:
      2.0.7.0

    • getFlag

      boolean getFlag(long flag)
      Get the flag value
      Parameters:
      flag - FLAG value from above
      Returns:
      Since:
      2.3.0.5

    • setFlag

      void setFlag(long flag, boolean set)
      Set the flag value.
      Parameters:
      flag - FLAG value from above
      set - true to enable the flag, false to disable it.
      Since:
      2.5.0.1

    • getFlags

      long getFlags()
      get all the flags as a bitmap
      Returns:
      Since:
      4209

    • getTorrent

      Torrent getTorrent()
      Each download has a corresponding torrent
      Specified by:
      getTorrent in interface DownloadStub
      Returns:
      the download's torrent
      Since:
      2.0.7.0

    • initialize

      void initialize() throws DownloadException
      See lifecycle description above
      Throws:
      DownloadException
      Since:
      2.0.7.0

    • start

      void start() throws DownloadException
      See lifecycle description above
      Throws:
      DownloadException
      Since:
      2.0.7.0

    • stop

      void stop() throws DownloadException
      See lifecycle description above
      Throws:
      DownloadException
      Since:
      2.0.7.0

    • setStartReason

      void setStartReason(String reason)

    • getStartReason

      String getStartReason()

    • setQueueReason

      void setQueueReason(String reason)

    • getQueueReason

      String getQueueReason()

    • setStopReason

      void setStopReason(String reason)

    • getStopReason

      String getStopReason()

    • stopAndQueue

      void stopAndQueue() throws DownloadException
      See lifecycle description above
      Throws:
      DownloadException
      Since:
      2.0.8.0

    • stopAndRemove

      void stopAndRemove(boolean delete_torrent, boolean delete_data) throws DownloadException, DownloadRemovalVetoException
      Throws:
      DownloadException
      DownloadRemovalVetoException
      Since:
      BiglyBT 2.6.0.1

    • restart

      void restart() throws DownloadException
      See lifecycle description above
      Throws:
      DownloadException
      Since:
      2.0.7.0

    • recheckData

      void recheckData() 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

    • isStartStopLocked

      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
      Returns:
      True if download is locked and should not be started or stopped
      Since:
      2.0.7.0

    • isForceStart

      boolean isForceStart()
      Retrieves whether the download is force started
      Returns:
      True if download is force started. False if not.
      Since:
      2.0.8.0

    • setForceStart

      void setForceStart(boolean forceStart)
      Set the forcestart state of the download
      Parameters:
      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

    • isPaused

      boolean isPaused()
      Returns:
      Since:
      2403

    • pause

      void pause()
      Pause the download
      Since:
      2501

    • resume

      void resume()
      Resume the download if paused
      Since:
      2501

    • getName

      String getName()
      Returns the name of the torrent. Similar to Torrent.getName() and is useful if getTorrent() returns null and you still need the name.
      Specified by:
      getName in interface DownloadStub
      Returns:
      name of the torrent
      Since:
      2.0.8.0

    • getTorrentFileName

      String getTorrentFileName()
      Returns the full file path and name of the .torrent file
      Returns:
      File name of the torrent.
      Since:
      2.1.0.0

    • getAttribute

      String getAttribute(TorrentAttribute attribute)
      Gets an attribute of this download. For category use the Category torrent attribute
      Parameters:
      attribute -
      Returns:

    • setAttribute

      void setAttribute(TorrentAttribute attribute, String value)
      Sets an attribute of this download. For category use the Category torrent attribute
      Parameters:
      attribute - Previously created attribute
      value - Value to store. null to remove attribute

    • getListAttribute

      String[] getListAttribute(TorrentAttribute attribute)

    • setListAttribute

      void setListAttribute(TorrentAttribute attribute, String[] value)
      Parameters:
      attribute -
      value -
      Since:
      2.5.0.1

    • setMapAttribute

      void setMapAttribute(TorrentAttribute attribute, Map value)
      Parameters:
      attribute -
      value - must be bencodable - key is string, value is Map, List, Long or byte[]

    • getMapAttribute

      Map getMapAttribute(TorrentAttribute attribute)

    • getIntAttribute

      int getIntAttribute(TorrentAttribute attribute)
      Gets the value of the given attribute from the download. If no value is set, then 0 will be returned.

    • setIntAttribute

      void setIntAttribute(TorrentAttribute attribute, int value)
      Sets an integer attribute on this download.

    • getLongAttribute

      long getLongAttribute(TorrentAttribute attribute)
      Gets the value of the given attribute from the download. If no value is set, then 0 will be returned.
      Specified by:
      getLongAttribute in interface DownloadStub
      Parameters:
      attribute -
      Returns:

    • setLongAttribute

      void setLongAttribute(TorrentAttribute attribute, long value)
      Sets a long attribute on this download.
      Specified by:
      setLongAttribute in interface DownloadStub

    • getBooleanAttribute

      boolean getBooleanAttribute(TorrentAttribute attribute)
      Gets the value of the given attribute from the download. If no value is set, then false will be returned.

    • setBooleanAttribute

      void setBooleanAttribute(TorrentAttribute attribute, boolean value)
      Sets a boolean attribute on this download.

    • hasAttribute

      boolean hasAttribute(TorrentAttribute attribute)
      Returns true if the download has an explicit value stored for the given attribute.

    • getCategoryName

      String getCategoryName()
      Returns the name of the Category
      Returns:
      name of the category
      Since:
      2.1.0.0

    • setCategory

      void setCategory(String sName)
      Sets the category for the download
      Parameters:
      sName - Category name
      Since:
      2.1.0.0

    • getTags

      List<Tag> getTags()
      Returns:
      Since:
      5701

    • remove

      void remove() throws DownloadException, DownloadRemovalVetoException
      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
      Specified by:
      remove in interface DownloadStub
      Throws:
      DownloadException
      DownloadRemovalVetoException
      Since:
      2.0.7.0

    • remove

      void remove(boolean delete_torrent, boolean delete_data) throws DownloadException, DownloadRemovalVetoException
      Same as "remove" but, if successful, deletes the torrent and/or data
      Parameters:
      delete_torrent -
      delete_data -
      Throws:
      DownloadException
      DownloadRemovalVetoException
      Since:
      2.2.0.3

    • getPosition

      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

    • getCreationTime

      long getCreationTime()
      returns the time this download was created in milliseconds
      Returns:

    • setPosition

      void setPosition(int newPosition)
      Sets the position in the queue Completed and Incompleted downloads have seperate position sets
      Since:
      2.0.8.0

    • moveUp

      void moveUp()
      Moves the download position up one
      Since:
      2.1.0.0

    • moveDown

      void moveDown()
      Moves the download down one position
      Since:
      2.1.0.0

    • moveTo

      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
      Parameters:
      position -
      Since:
      2.3.0.7

    • canBeRemoved

      boolean canBeRemoved() throws DownloadRemovalVetoException
      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.
      Returns:
      Throws:
      DownloadRemovalVetoException
      Since:
      2.0.7.0

    • setAnnounceResult

      void setAnnounceResult(DownloadAnnounceResult result)

    • setScrapeResult

      void setScrapeResult(DownloadScrapeResult result)

    • getLastAnnounceResult

      DownloadAnnounceResult getLastAnnounceResult()
      Gives access to the last announce result received from the tracker for the download
      Returns:
      Since:
      2.0.7.0

    • getLastScrapeResult

      DownloadScrapeResult getLastScrapeResult()
      Gives access to the last scrape result received from the tracker for the download
      Returns:
      a non-null DownloadScrapeResult
      Since:
      2.0.7.0

    • getAggregatedScrapeResult

      default DownloadScrapeResult getAggregatedScrapeResult()
      Returns an aggregated scrape result of all good results, or if none the same as getLastScrapeResult
      Returns:

    • getAggregatedScrapeResult

      DownloadScrapeResult getAggregatedScrapeResult(boolean allow_caching)

    • getActivationState

      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
      Returns:
      Since:
      2.4.0.3

    • getStats

      DownloadStats getStats()
      Gives access to the download's statistics
      Returns:
      Since:
      2.0.7.0

    • isPersistent

      boolean isPersistent()
      Downloads can be persistent (be remembered across client sessions), or non-persistent.
      Returns:
      true - persistent
      false - non-persistent
      Since:
      2.1.0.0

    • setMaximumDownloadKBPerSecond

      void setMaximumDownloadKBPerSecond(int kb)
      Sets the maximum download speed in bytes per second. 0 -> unlimited
      Parameters:
      kb -
      Since:
      2.1.0.2

    • getMaximumDownloadKBPerSecond

      int getMaximumDownloadKBPerSecond()
      Get the max download rate allowed for this download
      Returns:
      upload rate in KB/s, 0 for unlimited
      Since 4.8.1.3: -1 for download disabled
      Since:
      2.1.0.2

    • getUploadRateLimitBytesPerSecond

      int getUploadRateLimitBytesPerSecond()
      Get the max upload rate allowed for this download.
      Returns:
      upload rate in bytes per second, 0 for unlimited, -1 for upload disabled

    • setUploadRateLimitBytesPerSecond

      void setUploadRateLimitBytesPerSecond(int max_rate_bps)
      Set the max upload rate allowed for this download.
      Parameters:
      max_rate_bps - limit in bytes per second, 0 for unlimited, -1 for upload disabled

    • getDownloadRateLimitBytesPerSecond

      int getDownloadRateLimitBytesPerSecond()
      Get the max download rate allowed for this download.
      Returns:
      upload rate in bytes per second, 0 for unlimited, -1 for download disabled
      Since:
      3013

    • setDownloadRateLimitBytesPerSecond

      void setDownloadRateLimitBytesPerSecond(int max_rate_bps)
      Set the max download rate allowed for this download.
      Parameters:
      max_rate_bps - limit in bytes per second, 0 for unlimited, -1 for dowmload disabled
      Since:
      3013

    • addRateLimiter

      void addRateLimiter(RateLimiter limiter, boolean is_upload)
      Parameters:
      limiter - create via ConnectionManager
      is_upload - false -> download limit
      Since:
      4.7.0.3

    • removeRateLimiter

      void removeRateLimiter(RateLimiter limiter, boolean is_upload)

    • isComplete

      boolean isComplete()
      Indicates if the download has completed or not, exluding any files marked as Do No Download
      Returns:
      Download Complete status
      Since:
      2.1.0.4

    • isComplete

      boolean isComplete(boolean bIncludeDND)
      Indicates if the download has completed or not
      Parameters:
      bIncludeDND - Whether to include DND files when determining completion state
      Returns:
      Download Complete status
      Since:
      2.4.0.3

    • isChecking

      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)
      Returns:
      Since:
      2.3.0.6

    • isMoving

      boolean isMoving()
      Returns true if the download is currently in the process of having its datafiles moved
      Returns:

    • getSavePath

      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.
      Specified by:
      getSavePath in interface DownloadStub
      Returns:
      Full save path for this download.

    • moveDataFiles

      void moveDataFiles(File new_parent_dir) throws DownloadException
      Move a download's data files to a new location.

      If a download is running, it will be automatically paused and resumed afterwards - be aware that this behaviour may generate stateChanged events being fired.

      Parameters:
      new_parent_dir - New location. Note that non-simple torrents' data will be placed in a subdirectory of the torrent's name (getName()) under this new_parent_dir
      Throws:
      DownloadException
      Since:
      2.3.0.5

    • moveDataFiles

      void moveDataFiles(File new_parent_dir, String new_name) 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 moveDataFiles[File] and then renameDownload[String]. For convenience, either argument can be null, but not both.

      If a download is running, it will be automatically paused and resumed afterwards - be aware that this behaviour may generate stateChanged events being fired.

      Parameters:
      new_parent_dir - new location to move torrent data files to. If null, and simple torrent, torrent data file will be renamed new_name. If null, and not simple torrent, torrent end path will be changed to new_name.
      new_name - For simple torrent, changes the filename of the downloaded file. For non-simple torrent, changes the end path for the downloaded files. If null, torrent data files will be moved to new_parent_dir, with a subfolder of getName().
      Throws:
      DownloadException
      Since:
      3.0.2

    • moveTorrentFile

      void moveTorrentFile(File new_parent_dir) throws DownloadException
      Move a download's torrent file to a new location. Download must be stopped and persistent
      Parameters:
      new_parent_dir -
      Throws:
      DownloadException
      Since:
      2.3.0.5

    • renameDownload

      void renameDownload(String name) 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 moveDataFiles(File)).

      This will not rename the displayed name for the torrent - if you wish to do that, you must do it via the TorrentAttribute class.

      If a download is running, it will be automatically paused and resumed afterwards - be aware that this behaviour may generate stateChanged events being fired.

      Parameters:
      name - New name for the download.
      Throws:
      DownloadException
      See Also:

    • getPeerManager

      PeerManager getPeerManager()
      return the current peer manager for the download.
      Returns:
      null returned if torrent currently doesn't have one (e.g. it is stopped)

    • getDiskManager

      DiskManager getDiskManager()
      Return the disk manager, null if its not running
      Returns:
      Since:
      2.3.0.1

    • getDiskManagerFileInfo

      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)
      Returns:
      Since:
      2.3.0.1

    • getDiskManagerFileInfo

      DiskManagerFileInfo getDiskManagerFileInfo(int index)
      Returns file info for the given index. Note that this will return "stub" values if the download isn't running (not including info such as completion status)
      Returns:
      null if index is invalid
      Since:
      4.3.1.5

    • getDiskManagerFileCount

      int getDiskManagerFileCount()
      Return the number of DiskManagerFile objects
      Returns:
      Since:
      4.6.0.5

    • requestTrackerAnnounce

      void requestTrackerAnnounce()
      request a tracker announce
      Since:
      2.1.0.5

    • requestTrackerAnnounce

      void requestTrackerAnnounce(boolean immediate)
      request a tracker announce
      Since:
      2.3.0.7

    • requestTrackerScrape

      void requestTrackerScrape(boolean immediate)
      request a tracker announce
      Since:
      2.3.0.7

    • getSeedingRank

      Download.SeedingRank getSeedingRank()
      The torrents with the highest rankings will be seeded first.
      Returns:
      Seeding Rank

    • setSeedingRank

      void setSeedingRank(Download.SeedingRank rank)
      The torrents with the highest rankings will be seeded first.
      Parameters:
      rank - New Ranking

    • getDownloadPeerId

      byte[] getDownloadPeerId()
      Get the local peerID advertised to the download swarm.
      Returns:
      self peer id
      Since:
      2.1.0.5

    • isMessagingEnabled

      boolean isMessagingEnabled()
      Is advanced AZ messaging enabled for this download.
      Returns:
      true if enabled, false if disabled

    • setMessagingEnabled

      void setMessagingEnabled(boolean enabled)
      Enable or disable advanced AZ messaging for this download.
      Parameters:
      enabled - true to enabled, false to disabled

    • isRemoved

      boolean isRemoved()
      Returns:
      Since:
      3.0.4.3

    • canMoveDataFiles

      boolean canMoveDataFiles()
      Returns true if the client will allow the data files for the torrent to be moved.
      Since:
      3.0.5.1

    • calculateDefaultDownloadLocation

      SaveLocationChange calculateDefaultDownloadLocation()
      Returns a SaveLocationChange object describing the appropriate location for the download (and torrent file) to exist in, based on the download's completion state, the for-completion rules in place, and the SaveLocationManager object in use.
      Since:
      3.0.5.3

    • changeLocation

      void changeLocation(SaveLocationChange slc) throws DownloadException
      Apply the changes in the given SaveLocationChange object - this includes moving torrent and data file data.
      Parameters:
      slc - The change to apply.
      Throws:
      DownloadException - If there is a problem moving the data.
      Since:
      3.1.0.1

    • getUserData

      Object getUserData(Object key)
      get user-defined key/value
      Parameters:
      key -
      Returns:
      Since:
      3.0.5.3

    • setUserData

      void setUserData(Object key, Object data)
      set user defined value. this is TRANSIENT and not persisted over the client stop/start
      Parameters:
      key -
      data -

    • startDownload

      void startDownload(boolean force)
      Simple method to start the download. Will not raise an error if it didn't work, or if the download is already running.
      Parameters:
      force - true to force the download to be started.
      Since:
      3.0.5.3

    • stopDownload

      void stopDownload()
      Simple method to stop the download. Will not raise an error if it didn't work, or if the download is already stopped.
      Since:
      3.0.5.3

    • canStubbify

      boolean canStubbify()

    • stubbify

      DownloadStub stubbify() throws DownloadException, DownloadRemovalVetoException
      Throws:
      DownloadException
      DownloadRemovalVetoException

    • getDistributedDatabases

      List<DistributedDatabase> getDistributedDatabases()
      Returns:
      Since:
      5.4.0.1

    • getPrimaryFile

      DiskManagerFileInfo getPrimaryFile()
      Returns the "Primary" file in the download. Usually the largest one
      Since:
      5.0.0.1