1 /* 2 * File : Download.java 3 * Created : 06-Jan-2004 4 * By : parg 5 * 6 * Azureus - a Java Bittorrent client 7 * 8 * This program is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License as published by 10 * the Free Software Foundation; either version 2 of the License, or 11 * (at your option) any later version. 12 * 13 * This program is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * GNU General Public License for more details ( see the LICENSE file ). 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with this program; if not, write to the Free Software 20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 21 */ 22 23 package org.gudy.azureus2.plugins.download; 24 25 import java.io.File; 26 import java.util.List; 27 import java.util.Map; 28 29 import org.gudy.azureus2.plugins.download.savelocation.DefaultSaveLocationManager; 30 import org.gudy.azureus2.plugins.download.savelocation.SaveLocationChange; 31 import org.gudy.azureus2.plugins.download.savelocation.SaveLocationManager; 32 import org.gudy.azureus2.plugins.tag.Tag; 33 import org.gudy.azureus2.plugins.tag.Taggable; 34 import org.gudy.azureus2.plugins.torrent.Torrent; 35 import org.gudy.azureus2.plugins.torrent.TorrentAttribute; 36 import org.gudy.azureus2.plugins.ddb.DistributedDatabase; 37 import org.gudy.azureus2.plugins.disk.DiskManager; 38 import org.gudy.azureus2.plugins.disk.DiskManagerFileInfo; 39 import org.gudy.azureus2.plugins.network.RateLimiter; 40 import org.gudy.azureus2.plugins.peers.PeerManager; 41 42 /** 43 * Management of a Torrent's activity. 44 * 45 * <b>Note:</b> All listener based methods are now located in {@link DownloadEventNotifier}. 46 * 47 * <PRE> 48 * A download's lifecycle: 49 * torrent gets added 50 * state -> QUEUED 51 * slot becomes available, queued torrent is picked, "restart" executed 52 * state -> WAITING 53 * state moves through PREPARING to READY 54 * state -> PREPARING 55 * state -> READY 56 * execute "start" method 57 * state -> SEEDING -or- DOWNLOADING 58 * if torrent is DOWNLOADING, and completes, state changes to SEEDING 59 * 60 * Path 1 | Path 2 61 * -------------------------+------------------------------------------------ 62 * execute "stop" method | startstop rules are met, execute "stopandQueue" 63 * state -> STOPPING | state -> STOPPING 64 * state -> STOPPED | state -> STOPPED 65 * | state -> QUEUED 66 * execute "remove" method -> deletes the download 67 * a "stop" method call can be made when the download is in all states except STOPPED 68 * </PRE> 69 * 70 * @author parg 71 */ 72 73 public interface 74 Download extends DownloadEventNotifier, DownloadStub, Taggable 75 { 76 /** waiting to be told to start preparing */ 77 public static final int ST_WAITING = 1; 78 /** getting files ready (allocating/checking) */ 79 public static final int ST_PREPARING = 2; 80 /** ready to be started if required */ 81 public static final int ST_READY = 3; 82 /** downloading */ 83 public static final int ST_DOWNLOADING = 4; 84 /** seeding */ 85 public static final int ST_SEEDING = 5; 86 /** stopping */ 87 public static final int ST_STOPPING = 6; 88 /** stopped, do not auto-start! */ 89 public static final int ST_STOPPED = 7; 90 /** failed */ 91 public static final int ST_ERROR = 8; 92 /** stopped, but ready for auto-starting */ 93 public static final int ST_QUEUED = 9; 94 95 public static final String[] ST_NAMES = 96 { 97 "", 98 "Waiting", 99 "Preparing", 100 "Ready", 101 "Downloading", 102 "Seeding", 103 "Stopping", 104 "Stopped", 105 "Error", 106 "Queued", 107 }; 108 109 /** Use more of the upload bandwidth than low priority downloads 110 * don't change these as they are used by remote clients */ 111 112 public static final int PR_HIGH_PRIORITY = 1; 113 /** Use less of the upload bandwidth than high priority downloads */ 114 public static final int PR_LOW_PRIORITY = 2; 115 116 117 /** 118 * Flags values 119 * @since 2.3.0.5 120 */ 121 122 public static final long FLAG_ONLY_EVER_SEEDED = 0x00000001; 123 public static final long FLAG_SCAN_INCOMPLETE_PIECES = 0x00000002; 124 125 /** 126 * Flag value - if set, it prevents any of the "move on completion" or 127 * "move on removal" rules taking place. 128 * 129 * @since 2.5.0.1 130 */ 131 public static final long FLAG_DISABLE_AUTO_FILE_MOVE = 0x00000004; 132 133 /** 134 * Flag value - if set, then it means this download has been considered 135 * for "move on completion", and it should not be considered again for 136 * it. This value is more for internal use rather than plugin use. 137 * 138 * @since 2.5.0.1 139 */ 140 public static final long FLAG_MOVE_ON_COMPLETION_DONE = 0x00000008; 141 142 /** 143 * Flag value - if set the user won't be bothered with popups/completion events during 144 * the download's life. This is used, for example, for downloads used to run speed-tests 145 * @since 3.0.1.3 146 */ 147 148 public static final long FLAG_LOW_NOISE = 0x00000010; 149 150 /** 151 * Flag value - normally the permitted peer sources for a download are fixed and can't be changed 152 * this flag allows the permitted peer source set to be increased/decreased (but not beyond the enforced 153 * values required to honour a torrent's 'private' flag 154 */ 155 public static final long FLAG_ALLOW_PERMITTED_PEER_SOURCE_CHANGES = 0x00000020; 156 157 158 /** 159 * Flag value - if set the data will not be delete when the download is "deleted" from 160 * the v3 interface. 161 * @since 3.1.0.0 162 */ 163 public static final long FLAG_DO_NOT_DELETE_DATA_ON_REMOVE = 0x00000040; 164 165 /** 166 * Force direct delete of download data when delete requested, rather than recoverable delete, 167 * and no user prompt 168 * @since 4.3.1.5 169 */ 170 171 public static final long FLAG_FORCE_DIRECT_DELETE = 0x00000080; 172 173 /** 174 * Used to disable IP filter rules for a download when ip-filtering is enabled 175 * @since 4.7.0.3 176 */ 177 178 public static final long FLAG_DISABLE_IP_FILTER = 0x00000100; 179 180 /** 181 * @since 4.7.0.4 indicates that the download is just a metadata downloader and not a 'real' one (yet) 182 */ 183 184 public static final long FLAG_METADATA_DOWNLOAD = 0x00000200; 185 186 public static final long FLAG_LIGHT_WEIGHT = 0x00000400; 187 188 /** 189 * @since 5701 190 */ 191 192 public static final long FLAG_ERROR_REPORTED = 0x00000800; 193 194 /** 195 * @since 5721 196 */ 197 198 public static final long FLAG_INITIAL_NETWORKS_SET = 0x00001000; 199 200 201 /** get state from above ST_ set 202 * @return ST_ constant 203 * 204 * @since 2.0.7.0 205 */ 206 public int getState()207 getState(); 208 209 /** 210 * For the STOPPING state this method gives the state that is being transited too (STOPPED, QUEUED or ERROR) 211 * @return 212 * @since 2.3.0.5 213 */ 214 215 public int getSubState()216 getSubState(); 217 218 /** When the download state is ERROR this method returns the error details 219 * @return 220 * 221 * @since 2.0.7.0 222 */ 223 public String getErrorStateDetails()224 getErrorStateDetails(); 225 226 /** 227 * Get the flag value 228 * @since 2.3.0.5 229 * @param flag FLAG value from above 230 * @return 231 */ 232 getFlag(long flag)233 public boolean getFlag(long flag); 234 235 /** 236 * Set the flag value. 237 * 238 * @since 2.5.0.1 239 * @param flag FLAG value from above 240 * @param set <code>true</code> to enable the flag, <code>false</code> to disable it. 241 */ setFlag(long flag, boolean set)242 public void setFlag(long flag, boolean set); 243 244 /** 245 * get all the flags as a bitmap 246 * @since 4209 247 * @return 248 */ 249 250 public long getFlags()251 getFlags(); 252 253 /** 254 * Index of download. {@link #getPosition()} 255 * @return index - 0 based 256 * 257 * @since 2.0.7.0 258 */ 259 public int getIndex()260 getIndex(); 261 262 /** 263 * Each download has a corresponding torrent 264 * @return the download's torrent 265 * 266 * @since 2.0.7.0 267 */ 268 public Torrent getTorrent()269 getTorrent(); 270 271 /** 272 * See lifecycle description above 273 * @throws DownloadException 274 * 275 * @since 2.0.7.0 276 */ 277 public void initialize()278 initialize() 279 280 throws DownloadException; 281 282 /** 283 * See lifecycle description above 284 * @throws DownloadException 285 * 286 * @since 2.0.7.0 287 */ 288 public void start()289 start() 290 291 throws DownloadException; 292 293 /** 294 * See lifecycle description above 295 * @throws DownloadException 296 * 297 * @since 2.0.7.0 298 */ 299 public void stop()300 stop() 301 302 throws DownloadException; 303 304 /** 305 * See lifecycle description above 306 * @throws DownloadException 307 * 308 * @since 2.0.8.0 309 */ 310 public void stopAndQueue()311 stopAndQueue() 312 313 throws DownloadException; 314 315 /** 316 * See lifecycle description above 317 * @throws DownloadException 318 * 319 * @since 2.0.7.0 320 */ 321 public void restart()322 restart() 323 324 throws DownloadException; 325 326 327 /** 328 * Performs a complete recheck of the downloaded data 329 * Download must be in stopped, queued or error state 330 * Action is performed asynchronously and will progress the download through 331 * states PREPARING back to the relevant state 332 * @throws DownloadException 333 * @since 2.1.0.3 334 */ 335 336 public void recheckData()337 recheckData() 338 339 throws DownloadException; 340 341 /** 342 * When a download is "start-stop locked" it means that seeding rules shouldn't start or 343 * stop the download as it is under manual control 344 * @return True if download is locked and should not be started or stopped 345 * 346 * @since 2.0.7.0 347 */ 348 public boolean isStartStopLocked()349 isStartStopLocked(); 350 351 /** Retrieves whether the download is force started 352 * @return True if download is force started. False if not. 353 * 354 * @since 2.0.8.0 355 */ 356 public boolean isForceStart()357 isForceStart(); 358 359 /** Set the forcestart state of the download 360 * @param forceStart True - Download will start, despite any Start/Stop rules/limits<BR> 361 * False - Turn forcestart state off. Download may or may not stop, depending on 362 * Start/Stop rules/limits 363 * 364 * @since 2.0.8.0 365 */ 366 public void setForceStart(boolean forceStart)367 setForceStart(boolean forceStart); 368 369 /** 370 * Downloads can either be low or high priority (see PR_ constants above) 371 * @return the download's priority 372 * 373 * @deprecated >= 2.1.0.6 does nothing 374 * @since 2.0.7.0 375 */ 376 public int getPriority()377 getPriority(); 378 379 /** 380 * This method sets a download's priority 381 * @param priority the required priority, see PR_ constants above 382 * @deprecated >= 2.1.0.6 does nothing 383 * 384 * @since 2.0.7.0 385 */ 386 public void setPriority( int priority )387 setPriority( 388 int priority ); 389 390 /** When a download's priority is locked this means that seeding rules should not change 391 * a downloads priority, it is under manual control 392 * @return whether it is locked or not 393 * @deprecated >= 2.0.8.0 does nothing 394 * 395 * @since 2.0.7.0 396 */ 397 public boolean isPriorityLocked()398 isPriorityLocked(); 399 400 /** 401 * @since 2403 402 * @return 403 */ 404 405 public boolean isPaused()406 isPaused(); 407 408 /** 409 * Pause the download 410 * @since 2501 411 */ 412 413 public void pause()414 pause(); 415 416 /** 417 * Resume the download if paused 418 * @since 2501 419 */ 420 421 public void resume()422 resume(); 423 424 /** Returns the name of the torrent. Similar to Torrent.getName() and is usefull 425 * if getTorrent() returns null and you still need the name. 426 * @return name of the torrent 427 * 428 * @since 2.0.8.0 429 */ 430 public String getName()431 getName(); 432 433 /** Returns the full file path and name of the .torrent file 434 * 435 * @return File name of the torrent. 436 * 437 * @since 2.1.0.0 438 */ getTorrentFileName()439 public String getTorrentFileName(); 440 441 442 /** 443 * Gets an attribute of this download. For category use the Category torrent attribute 444 * @param attribute 445 * @return 446 */ 447 448 public String getAttribute( TorrentAttribute attribute )449 getAttribute( 450 TorrentAttribute attribute ); 451 452 /** 453 * Sets an attribute of this download. For category use the Category torrent attribute 454 * 455 * @param attribute Previously created attribute 456 * @param value Value to store. null to remove attribute 457 */ 458 public void setAttribute( TorrentAttribute attribute, String value )459 setAttribute( 460 TorrentAttribute attribute, 461 String value ); 462 463 public String[] getListAttribute( TorrentAttribute attribute )464 getListAttribute( 465 TorrentAttribute attribute ); 466 467 /** 468 * 469 * @param attribute 470 * @param value 471 * @since 2.5.0.1 472 */ setListAttribute(TorrentAttribute attribute, String[] value)473 public void setListAttribute(TorrentAttribute attribute, String[] value); 474 475 /** 476 * 477 * @param attribute 478 * @param value must be bencodable - key is string, value is Map, List, Long or byte[] 479 */ 480 481 public void setMapAttribute( TorrentAttribute attribute, Map value )482 setMapAttribute( 483 TorrentAttribute attribute, 484 Map value ); 485 486 public Map getMapAttribute( TorrentAttribute attribute )487 getMapAttribute( 488 TorrentAttribute attribute ); 489 490 /** 491 * Gets the value of the given attribute from the download. If no value is 492 * set, then <code>0</code> will be returned. 493 */ getIntAttribute(TorrentAttribute attribute)494 public int getIntAttribute(TorrentAttribute attribute); 495 496 /** 497 * Sets an integer attribute on this download. 498 */ setIntAttribute(TorrentAttribute attribute, int value)499 public void setIntAttribute(TorrentAttribute attribute, int value); 500 501 /** 502 * Gets the value of the given attribute from the download. If no value is 503 * set, then <code>0</code> will be returned. 504 */ getLongAttribute(TorrentAttribute attribute)505 public long getLongAttribute(TorrentAttribute attribute); 506 507 /** 508 * Sets a long attribute on this download. 509 */ setLongAttribute(TorrentAttribute attribute, long value)510 public void setLongAttribute(TorrentAttribute attribute, long value); 511 512 /** 513 * Gets the value of the given attribute from the download. If no value is 514 * set, then <code>false</code> will be returned. 515 */ getBooleanAttribute(TorrentAttribute attribute)516 public boolean getBooleanAttribute(TorrentAttribute attribute); 517 518 /** 519 * Sets a boolean attribute on this download. 520 */ setBooleanAttribute(TorrentAttribute attribute, boolean value)521 public void setBooleanAttribute(TorrentAttribute attribute, boolean value); 522 523 /** 524 * Returns <code>true</code> if the download has an explicit value stored for 525 * the given attribute. 526 */ hasAttribute(TorrentAttribute attribute)527 public boolean hasAttribute(TorrentAttribute attribute); 528 529 /** Returns the name of the Category 530 * 531 * @return name of the category 532 * 533 * @since 2.1.0.0 534 * @deprecated Use TorrentAttribute.TA_CATEGORY (2.2.0.3) 535 */ getCategoryName()536 public String getCategoryName(); 537 538 /** Sets the category for the download 539 * 540 * @param sName Category name 541 * 542 * @since 2.1.0.0 543 * @deprecated Use TorrentAttribute.TA_CATEGORY (2.2.0.3) 544 */ setCategory(String sName)545 public void setCategory(String sName); 546 547 /** 548 * @since 5701 549 * @return 550 */ 551 552 public List<Tag> getTags()553 getTags(); 554 555 /** 556 * Removes a download. The download must be stopped or in error. Removal may fail if another 557 * component does not want the removal to occur - in this case a "veto" exception is thrown 558 * @throws DownloadException 559 * @throws DownloadRemovalVetoException 560 * 561 * @since 2.0.7.0 562 */ 563 public void remove()564 remove() 565 566 throws DownloadException, DownloadRemovalVetoException; 567 568 /** 569 * Same as "remove" but, if successful, deletes the torrent and/or data 570 * @param delete_torrent 571 * @param delete_data 572 * @throws DownloadException 573 * @throws DownloadRemovalVetoException 574 * @since 2.2.0.3 575 */ 576 577 public void remove( boolean delete_torrent, boolean delete_data )578 remove( 579 boolean delete_torrent, 580 boolean delete_data ) 581 582 throws DownloadException, DownloadRemovalVetoException; 583 584 /** 585 * Returns the current position in the queue 586 * Completed and Incompleted downloads have seperate position sets. This means 587 * we can have a position x for Completed, and position x for Incompleted. 588 * 589 * @since 2.0.8.0 590 */ 591 public int getPosition()592 getPosition(); 593 594 /** 595 * returns the time this download was created in milliseconds 596 * @return 597 */ 598 599 public long getCreationTime()600 getCreationTime(); 601 602 /** 603 * Sets the position in the queue 604 * Completed and Incompleted downloads have seperate position sets 605 * 606 * @since 2.0.8.0 607 */ 608 public void setPosition( int newPosition)609 setPosition( 610 int newPosition); 611 612 /** 613 * Moves the download position up one 614 * 615 * @since 2.1.0.0 616 */ 617 public void moveUp()618 moveUp(); 619 620 /** 621 * Moves the download down one position 622 * 623 * @since 2.1.0.0 624 */ 625 public void moveDown()626 moveDown(); 627 628 /** 629 * Moves a download and re-orders the others appropriately. Note that setPosition does not do this, it 630 * merely sets the position thus making it possible, for example, for two downloads to have the same 631 * position 632 * @param position 633 * @since 2.3.0.7 634 */ 635 636 public void moveTo( int position )637 moveTo( 638 int position ); 639 640 /** 641 * Tests whether or not a download can be removed. Due to synchronization issues it is possible 642 * for a download to report OK here but still fail removal. 643 * @return 644 * @throws DownloadRemovalVetoException 645 * 646 * @since 2.0.7.0 647 */ 648 public boolean canBeRemoved()649 canBeRemoved() 650 651 throws DownloadRemovalVetoException; 652 653 public void setAnnounceResult( DownloadAnnounceResult result )654 setAnnounceResult( 655 DownloadAnnounceResult result ); 656 657 public void setScrapeResult( DownloadScrapeResult result )658 setScrapeResult( 659 DownloadScrapeResult result ); 660 661 /** 662 * Gives access to the last announce result received from the tracker for the download 663 * @return 664 * 665 * @since 2.0.7.0 666 */ 667 668 public DownloadAnnounceResult getLastAnnounceResult()669 getLastAnnounceResult(); 670 671 /** 672 * Gives access to the last scrape result received from the tracker for the download 673 * @return a non-null DownloadScrapeResult 674 * 675 * @since 2.0.7.0 676 */ 677 public DownloadScrapeResult getLastScrapeResult()678 getLastScrapeResult(); 679 680 /** 681 * Returns an aggregated scrape result of all good results, or if none the same as getLastScrapeResult 682 * @return 683 */ 684 685 public DownloadScrapeResult getAggregatedScrapeResult()686 getAggregatedScrapeResult(); 687 688 /** 689 * Gives access to the current activation state. Note that we currently only fire the activation listener 690 * on an increase in activation requirements. This method however gives the current view of the state 691 * and takes into account decreases too 692 * @return 693 * @since 2.4.0.3 694 */ 695 696 public DownloadActivationEvent getActivationState()697 getActivationState(); 698 699 /** 700 * Gives access to the download's statistics 701 * @return 702 * 703 * @since 2.0.7.0 704 */ 705 public DownloadStats getStats()706 getStats(); 707 708 /** Downloads can be persistent (be remembered across Azureus sessions), or 709 * non-persistent. 710 * 711 * @return true - persistent<br> 712 * false - non-persistent 713 * 714 * @since 2.1.0.0 715 */ 716 717 public boolean isPersistent()718 isPersistent(); 719 720 /** 721 * Sets the maximum download speed in bytes per second. 0 -> unlimited 722 * @since 2.1.0.2 723 * @param kb 724 */ 725 726 public void setMaximumDownloadKBPerSecond( int kb )727 setMaximumDownloadKBPerSecond( 728 int kb ); 729 730 /** 731 * Get the max download rate allowed for this download 732 * 733 * @return upload rate in KB/s, 0 for unlimited<BR> 734 * Since 4.8.1.3: -1 for download disabled 735 * 736 * @since 2.1.0.2 737 */ getMaximumDownloadKBPerSecond()738 public int getMaximumDownloadKBPerSecond(); 739 740 /** 741 * Get the max upload rate allowed for this download. 742 * @return upload rate in bytes per second, 0 for unlimited, -1 for upload disabled 743 */ 744 getUploadRateLimitBytesPerSecond()745 public int getUploadRateLimitBytesPerSecond(); 746 747 /** 748 * Set the max upload rate allowed for this download. 749 * @param max_rate_bps limit in bytes per second, 0 for unlimited, -1 for upload disabled 750 */ 751 setUploadRateLimitBytesPerSecond( int max_rate_bps )752 public void setUploadRateLimitBytesPerSecond( int max_rate_bps ); 753 754 /** 755 * Get the max download rate allowed for this download. 756 * @return upload rate in bytes per second, 0 for unlimited, -1 for download disabled 757 * @since 3013 758 */ 759 getDownloadRateLimitBytesPerSecond()760 public int getDownloadRateLimitBytesPerSecond(); 761 762 /** 763 * Set the max download rate allowed for this download. 764 * @param max_rate_bps limit in bytes per second, 0 for unlimited, -1 for dowmload disabled 765 * @since 3013 766 */ 767 setDownloadRateLimitBytesPerSecond( int max_rate_bps )768 public void setDownloadRateLimitBytesPerSecond( int max_rate_bps ); 769 770 771 /** 772 * @since 4.7.0.3 773 * @param limiter create via ConnectionManager 774 * @param is_upload false -> download limit 775 */ 776 777 public void addRateLimiter( RateLimiter limiter, boolean is_upload )778 addRateLimiter( 779 RateLimiter limiter, 780 boolean is_upload ); 781 782 public void removeRateLimiter( RateLimiter limiter, boolean is_upload )783 removeRateLimiter( 784 RateLimiter limiter, 785 boolean is_upload ); 786 787 /** 788 * Indicates if the download has completed or not, exluding any files marked 789 * as Do No Download 790 * 791 * @return Download Complete status 792 * @since 2.1.0.4 793 */ isComplete()794 public boolean isComplete(); 795 796 /** 797 * Indicates if the download has completed or not 798 * 799 * @param bIncludeDND Whether to include DND files when determining 800 * completion state 801 * @return Download Complete status 802 * 803 * @since 2.4.0.3 804 */ isComplete(boolean bIncludeDND)805 public boolean isComplete(boolean bIncludeDND); 806 807 /** 808 * When a download is completed it is rechecked (if the option is enabled). This method 809 * returns true during this phase (at which time the status will be seeding) 810 * @return 811 * @since 2.3.0.6 812 */ 813 814 public boolean isChecking()815 isChecking(); 816 817 /** 818 * Returns true if the download is currently in the process of having its datafiles moved 819 * @return 820 */ 821 822 public boolean isMoving()823 isMoving(); 824 825 /** 826 * This returns the full save path for the download. If the download is a simple torrent, 827 * this will be the full path of the file being downloaded. If the download is a multiple 828 * file torrent, this will be the path to the directory containing all the files in the 829 * torrent. 830 * 831 * @return Full save path for this download. 832 */ 833 834 public String getSavePath()835 getSavePath(); 836 837 /** 838 * Move a download's data files to a new location. Download must be stopped and persistent 839 * 840 * <p> 841 * 842 * If a download is running, it will be automatically paused and resumed afterwards - be 843 * aware that this behaviour may generate <tt>stateChanged</tt> events being fired. 844 * 845 * @since 2.3.0.5 846 * @param new_parent_dir 847 * @throws DownloadException 848 */ 849 850 public void moveDataFiles( File new_parent_dir )851 moveDataFiles( 852 File new_parent_dir ) 853 854 throws DownloadException; 855 856 /** 857 * Move a download's data files to a new location, and rename the download at the same time. 858 * Download must be stopped and persistent. This is equivalent to calling <tt>moveDataFiles[File]</tt> 859 * and then <tt>renameDownload[String]</tt>. 860 * 861 * For convenience, either argument can be <tt>null</tt>, but not both. 862 * 863 * <p> 864 * 865 * If a download is running, it will be automatically paused and resumed afterwards - be 866 * aware that this behaviour may generate <tt>stateChanged</tt> events being fired. 867 * 868 * @since 3.0.2 869 * @throws DownloadException 870 * @see {@link #moveDataFiles(File)} 871 * @see {@link #renameDownload(String)} 872 */ moveDataFiles(File new_parent_dir, String new_name)873 public void moveDataFiles(File new_parent_dir, String new_name) throws DownloadException; 874 875 876 /** 877 * Move a download's torrent file to a new location. Download must be stopped and persistent 878 * @since 2.3.0.5 879 * @param new_parent_dir 880 * @throws DownloadException 881 */ 882 public void moveTorrentFile( File new_parent_dir )883 moveTorrentFile( 884 File new_parent_dir ) 885 886 throws DownloadException; 887 888 /** 889 * Renames the file (for a single file torrent) or directory (for a multi file torrent) where the 890 * download is being saved to. The download must be in a state to move the data files to a new location 891 * (see {@link #moveDataFiles(File)}). 892 * 893 * <p> 894 * 895 * This will not rename the displayed name for the torrent - if you wish to do that, you must do it via 896 * the {@link org.gudy.azureus2.plugins.torrent.TorrentAttribute TorrentAttribute} class. 897 * 898 * <p> 899 * 900 * If a download is running, it will be automatically paused and resumed afterwards - be 901 * aware that this behaviour may generate <tt>stateChanged</tt> events being fired. 902 * 903 * @param name New name for the download. 904 * @see #moveDataFiles(File) 905 */ renameDownload(String name)906 public void renameDownload(String name) throws DownloadException; 907 908 /** 909 * return the current peer manager for the download. 910 * @return null returned if torrent currently doesn't have one (e.g. it is stopped) 911 */ 912 913 public PeerManager getPeerManager()914 getPeerManager(); 915 916 /** 917 * Return the disk manager, null if its not running 918 * @return 919 * @since 2.3.0.1 920 */ 921 922 public DiskManager getDiskManager()923 getDiskManager(); 924 925 /** 926 * Returns info about the torrent's files. Note that this will return "stub" values if the 927 * download isn't running (not including info such as completion status) 928 * @return 929 * @since 2.3.0.1 930 */ 931 932 public DiskManagerFileInfo[] getDiskManagerFileInfo()933 getDiskManagerFileInfo(); 934 935 /** 936 * Returns file info for the given index. Note that this will return "stub" values if the 937 * download isn't running (not including info such as completion status) 938 * @return null if index is invalid 939 * @since 4.3.1.5 940 */ 941 942 public DiskManagerFileInfo getDiskManagerFileInfo(int index)943 getDiskManagerFileInfo(int index); 944 945 /** 946 * Return the number of DiskManagerFile objects 947 * @return 948 * @since 4.6.0.5 949 */ getDiskManagerFileCount()950 public int getDiskManagerFileCount(); 951 952 /** 953 * request a tracker announce 954 * @since 2.1.0.5 955 */ 956 957 public void requestTrackerAnnounce()958 requestTrackerAnnounce(); 959 960 /** 961 * request a tracker announce 962 * @since 2.3.0.7 963 */ 964 965 public void requestTrackerAnnounce( boolean immediate )966 requestTrackerAnnounce( 967 boolean immediate ); 968 969 /** 970 * request a tracker announce 971 * @since 2.3.0.7 972 */ 973 974 public void requestTrackerScrape( boolean immediate )975 requestTrackerScrape( 976 boolean immediate ); 977 978 979 980 981 982 /** 983 * The torrents with the highest rankings will be seeded first. 984 * 985 * @return Seeding Rank 986 */ getSeedingRank()987 public int getSeedingRank(); 988 989 /** 990 * The torrents with the highest rankings will be seeded first. 991 * 992 * @param rank New Ranking 993 */ setSeedingRank(int rank)994 public void setSeedingRank(int rank); 995 996 /** 997 * Get the local peerID advertised to the download swarm. 998 * @return self peer id 999 * 1000 * @since 2.1.0.5 1001 */ getDownloadPeerId()1002 public byte[] getDownloadPeerId(); 1003 1004 /** 1005 * Is advanced AZ messaging enabled for this download. 1006 * @return true if enabled, false if disabled 1007 */ isMessagingEnabled()1008 public boolean isMessagingEnabled(); 1009 1010 /** 1011 * Enable or disable advanced AZ messaging for this download. 1012 * @param enabled true to enabled, false to disabled 1013 */ setMessagingEnabled( boolean enabled )1014 public void setMessagingEnabled( boolean enabled ); 1015 1016 1017 /** 1018 * Returns an array of size 2 indicating the appropriate locations for this 1019 * download's data files and torrent file, based on Azureus's rules regarding 1020 * default save paths, and move on completion rules. 1021 * 1022 * <p> 1023 * 1024 * This method takes one argument - <i>for_moving</i>. This essentially 1025 * indicates whether you are getting this information for purposes of just 1026 * finding where Azureus would store these files by default, or whether you 1027 * are considering moving the files from its current location. 1028 * 1029 * <p> 1030 * 1031 * If <i>for_moving</i> is <tt>false</tt>, this method will determine locations 1032 * for the download and the torrent file where Azureus would store them by 1033 * default (it may return the current paths used by this download). 1034 * 1035 * <p> 1036 * 1037 * If <i>for_moving</i> is <tt>true</tt>, then this method will consider the 1038 * download's current location, and whether it is allowed to move it - you 1039 * may not be allowed to move this download (based on Azureus's current rules) 1040 * if the download doesn't exist within a default save directory already. If 1041 * a download is complete, we consider whether we are allowed to move downloads 1042 * on completion, and whether that includes downloads outside the default save 1043 * directory. 1044 * 1045 * <p> 1046 * 1047 * In this case, the array may contain <tt>null</tt> indicating that the Azureus 1048 * doesn't believe that the download should be moved (based on the current rules 1049 * the user has set out). However, you are not prevented from changing the 1050 * location of the torrent file or download. 1051 * 1052 * @since 2.5.0.2 1053 * @param for_moving Indicates whether you want this information for the purposes 1054 * of moving the download or not. 1055 * @author amc1 1056 * @deprecated Use {@link #calculateDefaultDownloadLocation()} instead. 1057 * @return An array of type <tt>File</tt> of size 2, first element containing the 1058 * calculated location for the download's data files, and the second element 1059 * containing the location for the download's torrent file. 1060 */ calculateDefaultPaths(boolean for_moving)1061 public File[] calculateDefaultPaths(boolean for_moving); 1062 1063 /** 1064 * Returns <tt>true</tt> if the download is being saved to one of the default 1065 * save directories. 1066 * 1067 * @since 2.5.0.2 1068 * @deprecated Use {@link DefaultSaveLocationManager#isInDefaultSaveDir(Download)} instead. 1069 * @author amc1 1070 */ isInDefaultSaveDir()1071 public boolean isInDefaultSaveDir(); 1072 1073 /** 1074 * @since 3.0.4.3 1075 * @return 1076 */ 1077 isRemoved()1078 public boolean isRemoved(); 1079 1080 /** 1081 * Returns <tt>true</tt> if Azureus will allow the data files for the torrent 1082 * to be moved. 1083 * 1084 * @since 3.0.5.1 1085 */ canMoveDataFiles()1086 public boolean canMoveDataFiles(); 1087 1088 /** 1089 * Returns a {@link SaveLocationChange} object describing the appropriate location 1090 * for the download (and torrent file) to exist in, based on the download's completion 1091 * state, the <tt>for-completion</tt> rules in place, and the {@link SaveLocationManager} 1092 * object in use. 1093 * 1094 * @since 3.0.5.3 1095 */ calculateDefaultDownloadLocation()1096 public SaveLocationChange calculateDefaultDownloadLocation(); 1097 1098 /** 1099 * Apply the changes in the given {@link SaveLocationChange} object - this includes 1100 * moving torrent and data file data. 1101 * 1102 * @param slc The change to apply. 1103 * @since 3.1.0.1 1104 * @throws DownloadException If there is a problem moving the data. 1105 */ changeLocation(SaveLocationChange slc)1106 public void changeLocation(SaveLocationChange slc) throws DownloadException; 1107 1108 /** 1109 * get user-defined key/value 1110 * @param key 1111 * @return 1112 * @since 3.0.5.3 1113 */ 1114 getUserData( Object key )1115 public Object getUserData( Object key ); 1116 1117 /** 1118 * set user defined value. this is TRANSIENT and not persisted over Azureus stop/start 1119 * @param key 1120 * @param data 1121 */ setUserData( Object key, Object data )1122 public void setUserData( Object key, Object data ); 1123 1124 /** 1125 * Simple method to start the download. Will not raise an error if it 1126 * didn't work, or if the download is already running. 1127 * 1128 * @since 3.0.5.3 1129 * @param force <tt>true</tt> to force the download to be started. 1130 */ startDownload(boolean force)1131 public void startDownload(boolean force); 1132 1133 /** 1134 * Simple method to stop the download. Will not raise an error if it 1135 * didn't work, or if the download is already stopped. 1136 * 1137 * @since 3.0.5.3 1138 */ stopDownload()1139 public void stopDownload(); 1140 1141 public boolean canStubbify()1142 canStubbify(); 1143 1144 public DownloadStub stubbify()1145 stubbify() 1146 1147 throws DownloadException, DownloadRemovalVetoException; 1148 1149 /** 1150 * @since 5.4.0.1 1151 * @return 1152 */ 1153 public List<DistributedDatabase> getDistributedDatabases()1154 getDistributedDatabases(); 1155 1156 /** 1157 * Returns the "Primary" file in the download. Usually the largest one 1158 * 1159 * @since 5.0.0.1 1160 */ getPrimaryFile()1161 public DiskManagerFileInfo getPrimaryFile(); 1162 } 1163