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 Detail

      • ST_WAITING

        static final int ST_WAITING
        waiting to be told to start preparing
        See Also:
        Constant Field Values
      • ST_PREPARING

        static final int ST_PREPARING
        getting files ready (allocating/checking)
        See Also:
        Constant Field Values
      • ST_QUEUED

        static final int ST_QUEUED
        stopped, but ready for auto-starting
        See Also:
        Constant Field Values
      • ST_NAMES

        static final java.lang.String[] ST_NAMES
      • FLAG_ONLY_EVER_SEEDED

        static final long FLAG_ONLY_EVER_SEEDED
        Flags values
        Since:
        2.3.0.5
        See Also:
        Constant Field Values
      • FLAG_SCAN_INCOMPLETE_PIECES

        static final long FLAG_SCAN_INCOMPLETE_PIECES
        See Also:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
      • FLAG_INITIAL_NETWORKS_SET

        static final long FLAG_INITIAL_NETWORKS_SET
        Since:
        5721
        See Also:
        Constant Field Values
      • FLAG_SEQUENTIAL_DOWNLOAD

        static final long FLAG_SEQUENTIAL_DOWNLOAD
        Since:
        BiglyBT 1.0.2.1
        See Also:
        Constant Field Values
      • FLAG_DISABLE_STOP_AFTER_ALLOC

        static final long FLAG_DISABLE_STOP_AFTER_ALLOC
        Since:
        BiglyBT 2.0.0.1
        See Also:
        Constant Field Values
      • UD_KEY_STOP_REASON

        static final java.lang.Object UD_KEY_STOP_REASON
    • Method Detail

      • 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

        java.lang.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
      • setStopReason

        void setStopReason​(java.lang.String reason)
      • getStopReason

        java.lang.String getStopReason()
      • 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

        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.
        Specified by:
        getName in interface DownloadStub
        Returns:
        name of the torrent
        Since:
        2.0.8.0
      • getTorrentFileName

        java.lang.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

        java.lang.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,
                          java.lang.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

        java.lang.String[] getListAttribute​(TorrentAttribute attribute)
      • setListAttribute

        void setListAttribute​(TorrentAttribute attribute,
                              java.lang.String[] value)
        Parameters:
        attribute -
        value -
        Since:
        2.5.0.1
      • setMapAttribute

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

        java.util.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
        Returns:
      • 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

        java.lang.String getCategoryName()
        Returns the name of the Category
        Returns:
        name of the category
        Since:
        2.1.0.0
      • setCategory

        void setCategory​(java.lang.String sName)
        Sets the category for the download
        Parameters:
        sName - Category name
        Since:
        2.1.0.0
      • getTags

        java.util.List<Tag> getTags()
        Returns:
        Since:
        5701
      • 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
      • 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

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

        void moveDataFiles​(java.io.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​(java.io.File new_parent_dir,
                           java.lang.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​(java.io.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​(java.lang.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:
        moveDataFiles(File)
      • 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
      • getUserData

        java.lang.Object getUserData​(java.lang.Object key)
        get user-defined key/value
        Parameters:
        key -
        Returns:
        Since:
        3.0.5.3
      • setUserData

        void setUserData​(java.lang.Object key,
                         java.lang.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()
      • getDistributedDatabases

        java.util.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