Using IOException to communicate a desire to abort the download is a little

pesky and pushes annoying requirements on users of the Getdown download
services (like Yohoho and ToyBox).

Instead we'll allow Downloader.download() to return false to indicate that the
download was aborted by an observer, and the observers will simply return false
to indicate that they wish the download to be aborted.

While I was in there, I moved the Downloader and its concrete implementations
into a getdown.net package because it annoyed me that they were in
getdown.launcher.

src/java/com/threerings/getdown/data/Application.java

@@ -1027,23 +1027,35 @@ public class Application
     protected void downloadConfigFile ()
         throws IOException
     {
-        checkForAnotherGetdown();
+        requireNoOtherGetdownRunning();
         downloadControlFile(CONFIG_FILE, false);
         updateConfigModtime();
     }
 
     /**
-     * Checks the modtime on CONFIG_FILE and if it's changed since the last time this was called,
+     * Checks the modtime on CONFIG_FILE and returns whether it has changed since the last time
-     * raise a MultipleGetdownRunning exception
+     * this method was called.
      */
-    public void checkForAnotherGetdown ()
+    public boolean checkForAnotherGetdown ()
-        throws MultipleGetdownRunning
     {
         File config = getLocalPath(CONFIG_FILE);
         if (_lastConfigModtime != -1 && _lastConfigModtime < config.lastModified()) {
-            throw new MultipleGetdownRunning();
+            return true;
         }
         _lastConfigModtime = config.lastModified();
+        return false;
+    }
+
+    /**
+     * Calls {@link #checkForAnotherGetdown} and throws a {@link MultipleGetdownRunning} if it
+     * detects that another Getdown instance is running.
+     */
+    public void requireNoOtherGetdownRunning ()
+        throws MultipleGetdownRunning
+    {
+        if (checkForAnotherGetdown()) {
+            throw new MultipleGetdownRunning();
+        }
     }
 
     /**
@@ -1054,8 +1066,9 @@ public class Application
     {
         File config = getLocalPath(CONFIG_FILE);
         _lastConfigModtime = System.currentTimeMillis();
-        if(!config.setLastModified(_lastConfigModtime) && !_warnedAboutSetLastModified){
+        if (!config.setLastModified(_lastConfigModtime) && !_warnedAboutSetLastModified) {
-            Log.warning("Unable to set modtime on config file, will be unable to check for other instances of getdown running");
+            Log.warning("Unable to set modtime on config file, will be unable to check for " +
+                        "other instances of getdown running.");
             _warnedAboutSetLastModified = true;
         }
     }
@@ -1152,7 +1165,7 @@ public class Application
         // Check that another getdown hasn't started running since we started downloading this
         // file. The rename will obliterate the modtime we're tracking to keep multiple instances
         // from running.
-        checkForAnotherGetdown(); 
+        requireNoOtherGetdownRunning(); 
 
         // now move the temporary file over the original
         File original = getLocalPath(path);

src/java/com/threerings/getdown/launcher/Getdown.java

@@ -62,6 +62,9 @@ import com.samskivert.util.StringUtil;
 import com.threerings.getdown.Log;
 import com.threerings.getdown.data.Application;
 import com.threerings.getdown.data.Resource;
+import com.threerings.getdown.net.Downloader;
+import com.threerings.getdown.net.HTTPDownloader;
+import com.threerings.getdown.net.TorrentDownloader;
 import com.threerings.getdown.tools.Patcher;
 import com.threerings.getdown.util.ConfigUtil;
 import com.threerings.getdown.util.LaunchUtil;
@@ -359,9 +362,9 @@ public abstract class Getdown extends Thread
                 // now force our UI to be recreated with the updated info
                 createInterface(true);
             }
-            _app.checkForAnotherGetdown();
+            _app.requireNoOtherGetdownRunning();
             // Update the modtime here to stake a claim that we're going to getdown eventually
-            _app.updateConfigModtime(); 
+            _app.updateConfigModtime();
             if (_delay > 0) {
                 try {
                     Log.info("Waiting " + _delay + " minutes before beginning actual work");
@@ -413,7 +416,7 @@ public abstract class Getdown extends Thread
                     // Only launch if we aren't in silent mode. Some mystery program starting out
                     // of the blue would be disconcerting.
                     if (!_silent || _launchInSilent) {
-                        _app.checkForAnotherGetdown();
+                        _app.requireNoOtherGetdownRunning();
                         launch();
                     }
                     return;
@@ -628,34 +631,29 @@ public abstract class Getdown extends Thread
                 updateStatus("m.resolving");
             }
 
-            public void downloadProgress (int percent, long remaining)
+            public boolean downloadProgress (int percent, long remaining) {
-                throws IOException {
+                // check for another getdown running at 0 and every 10% after that
-                // Check for another getdown running at 0 and every 10% after that
                 if (_lastCheck == -1 || percent >= _lastCheck + 10) {
-                    _app.checkForAnotherGetdown();
+                    if (_app.checkForAnotherGetdown()) {
+                        return false;
+                    }
                     _lastCheck = percent;
                 }
                 setStatus("m.downloading", percent, remaining, true);
                 if (percent > 0) {
                     reportTrackingEvent("progress", percent);
                 }
+                return true;
             }
 
-            public void downloadFailed (Resource rsrc, Exception e)
+            public void downloadFailed (Resource rsrc, Exception e) {
-                throws IOException {
+                updateStatus(MessageUtil.tcompose("m.failure", e.getMessage()));
-                if (e instanceof MultipleGetdownRunning) {
+                Log.warning("Download failed [rsrc=" + rsrc + "].");
-                    throw (IOException)e;
+                Log.logStackTrace(e);
-                } else {
-                    updateStatus(MessageUtil.tcompose("m.failure", e.getMessage()));
-                    Log.warning("Download failed [rsrc=" + rsrc + "].");
-                    Log.logStackTrace(e);
-                }
             }
-            
+
-            /**
+            /** The last percentage at which we checked for another getdown running, or -1 for not
-             * The last percentage at which we checked for another getdown running, or -1 for not
+             * having checked at all. */
-             * having checked at all.
-             */
             protected int _lastCheck = -1;
         };
 
@@ -680,7 +678,9 @@ public abstract class Getdown extends Thread
         }
 
         // start the download and wait for it to complete
-        dl.download();
+        if (!dl.download()) {
+            throw new MultipleGetdownRunning();
+        }
     }
 
     /**

src/java/com/threerings/getdown/net/DownloadAbortedException.java

@@ -0,0 +1,30 @@
+//
+// $Id$
+//
+// Getdown - application installer, patcher and launcher
+// Copyright (C) 2004-2006 Three Rings Design, Inc.
+//
+// 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, or (at your option)
+// any later version.
+//
+// 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.
+//
+// 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.,
+// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+
+package com.threerings.getdown.net;
+
+import java.io.IOException;
+
+/**
+ * Used to terminate the download process in its midst.
+ */
+public class DownloadAbortedException extends IOException
+{
+}

src/java/com/threerings/getdown/net/Downloader.java

@@ -18,69 +18,63 @@
 // this program; if not, write to the: Free Software Foundation, Inc.,
 // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
 
-package com.threerings.getdown.launcher;
+package com.threerings.getdown.net;
 
 import java.io.File;
 import java.io.IOException;
+
 import java.util.List;
 
 import com.threerings.getdown.Log;
 import com.threerings.getdown.data.Resource;
 
 /**
- * Handles the download of a collection of files, first issuing HTTP head
+ * Handles the download of a collection of files, first issuing HTTP head requests to obtain size
- * requests to obtain size information and then downloading the files
+ * information and then downloading the files individually, reporting progress back via a callback
- * individually, reporting progress back via a callback interface.
+ * interface.
  */
 public abstract class Downloader extends Thread
 {
     /**
-     * An interface used to communicate status back to an external entity.
+     * An interface used to communicate status back to an external entity.  <em>Note:</em> these
-     * <em>Note:</em> these methods are all called on the download thread,
+     * methods are all called on the download thread, so implementors must take care to only
-     * so implementors must take care to only execute thread-safe code or
+     * execute thread-safe code or simply pass a message to the AWT thread, for example.
-     * simply pass a message to the AWT thread, for example.
      */
     public interface Observer
     {
         /**
-         * Called before the downloader begins the series of HTTP head
+         * Called before the downloader begins the series of HTTP head requests to determine the
-         * requests to determine the size of the files it needs to
+         * size of the files it needs to download.
-         * download.
          */
         public void resolvingDownloads ();
 
         /**
-         * Called to inform the observer of ongoing progress toward
+         * Called to inform the observer of ongoing progress toward completion of the overall
-         * completion of the overall downloading task.  The caller is
+         * downloading task. The caller is guaranteed to get at least one call reporting 100%
-         * guaranteed to get at least one call reporting 100% completion.
+         * completion.
          *
-         * @param percent the percent completion, in terms of total file
+         * @param percent the percent completion, in terms of total file size, of the downloads.
-         * size, of the downloads.
+         * @param remaining the estimated download time remaining in seconds, or <code>-1</code> if
-         * @param remaining the estimated download time remaining in
+         * the time can not yet be determined.
-         * seconds, or <code>-1</code> if the time can not yet be
+         *
-         * determined.
+         * @return true if the download should continue, false if it should be aborted.
-         * @throws IOException if getdown shouldn't continue in its current state. 
          */
-        public void downloadProgress (int percent, long remaining) throws IOException;
+        public boolean downloadProgress (int percent, long remaining);
 
         /**
-         * Called if a failure occurs while checking for an update or
+         * Called if a failure occurs while checking for an update or downloading a file.
-         * downloading a file.
          *
-         * @param rsrc the resource that was being downloaded when the
+         * @param rsrc the resource that was being downloaded when the error occurred, or
-         * error occurred, or <code>null</code> if the failure occurred
+         * <code>null</code> if the failure occurred while resolving downloads.
-         * while resolving downloads.
          * @param e the exception detailing the failure.
-         * @throws IOException if getdown shouldn't continue after this failure.
          */
-        public void downloadFailed (Resource rsrc, Exception e) throws IOException;
+        public void downloadFailed (Resource rsrc, Exception e);
     }
 
     /**
-     * Creates a downloader that will download the supplied list of
+     * Creates a downloader that will download the supplied list of resources and communicate with
-     * resources and communicate with the specified observer. The {@link
+     * the specified observer. The {@link #download} method must be called on the downloader to
-     * #download} method must be called on the downloader to initiate the
+     * initiate the download process.
-     * download process.
      */
     public Downloader (List<Resource> resources, Observer obs)
     {
@@ -95,20 +89,16 @@ public abstract class Downloader extends Thread
     @Override
     public void run ()
     {
-        try {
+        download();
-            download();
-        } catch (IOException e) {
-            // This was either logged or reported to our observer in download, so we're good.
-        }
     }
 
     /**
-     * Start downloading the resources in this Downloader.
+     * Start downloading the resources in this downloader.
-     * 
+     *
-     * @throws IOException if an unrecoverable error was discovered in dowloading. 
+     * @return true if the download completed or failed for unexpected reasons (in which case the
+     * observer will have been notified), false if it was aborted by the observer.
      */
-    public void download ()
+    public boolean download ()
-        throws IOException
     {
         Resource current = null;
         try {
@@ -132,12 +122,17 @@ public abstract class Downloader extends Thread
                 download(resource);
             }
 
-            // finally report our download completion if we did not
+            // finally report our download completion if we did not already do so when downloading
-            // already do so when downloading our final resource
+            // our final resource
             if (_obs != null && !_complete) {
-                _obs.downloadProgress(100, 0);
+                if (!_obs.downloadProgress(100, 0)) {
+                    return false;
+                }
             }
 
+        } catch (DownloadAbortedException e) {
+            return false;
+
         } catch (Exception e) {
             if (_obs != null) {
                 _obs.downloadFailed(current, e);
@@ -145,6 +140,7 @@ public abstract class Downloader extends Thread
                 Log.logStackTrace(e);
             }
         }
+        return true;
     }
 
     /**
@@ -163,8 +159,7 @@ public abstract class Downloader extends Thread
     protected abstract long checkSize (Resource rsrc) throws IOException;
 
     /**
-     * Downloads the specified resource from its remote location to its
+     * Downloads the specified resource from its remote location to its local location.
-     * local location.
      */
     protected void download (Resource rsrc)
         throws IOException
@@ -173,23 +168,20 @@ public abstract class Downloader extends Thread
         File parent = new File(rsrc.getLocal().getParent());
         if (!parent.exists()) {
             if (!parent.mkdirs()) {
-                Log.warning("Failed to create target directory for " +
+                Log.warning("Failed to create target directory for resource '" + rsrc + "'. " +
-                            "resource '" + rsrc + "'. Download will " +
+                            "Download will certainly fail.");
-                            "certainly fail.");
             }
         }
         doDownload(rsrc);
     }
 
     /**
-     * Periodically called by the protocol-specific downloaders
+     * Periodically called by the protocol-specific downloaders to update their progress.
-     * to update their progress.
-     * @throws IOException 
      */
-    protected void updateObserver () throws IOException
+    protected void updateObserver ()
+        throws IOException
     {
-        // notify the observer if it's been sufficiently long
+        // notify the observer if it's been sufficiently long since our last notification
-        // since our last notification
         long now = System.currentTimeMillis();
         if ((now - _lastUpdate) >= UPDATE_DELAY) {
             _lastUpdate = now;
@@ -199,24 +191,24 @@ public abstract class Downloader extends Thread
             long bps = (secs == 0) ? 0 : (_currentSize / secs);
 
             // compute our percentage completion
-            int pctdone = (_totalSize == 0) ? 0 :
+            int pctdone = (_totalSize == 0) ? 0 : (int)((_currentSize * 100f) / _totalSize);
-                (int)((_currentSize * 100f) / _totalSize);
 
             // estimate our time remaining
-            long remaining = (bps <= 0 || _totalSize == 0) ? -1 :
+            long remaining = (bps <= 0 || _totalSize == 0) ? -1 : (_totalSize - _currentSize) / bps;
-                (_totalSize - _currentSize) / bps;
 
             // make sure we only report 100% exactly once
             if (pctdone < 100 || !_complete) {
                 _complete = (pctdone == 100);
-                _obs.downloadProgress(pctdone, remaining);
+                if (!_obs.downloadProgress(pctdone, remaining)) {
+                    throw new DownloadAbortedException();
+                }
             }
         }   
     }
 
     /**
-     * Accomplishes the copying of the resource from remote location to
+     * Accomplishes the copying of the resource from remote location to local location using
-     * local location using protocol-specific code
+     * protocol-specific code
      */
     protected abstract void doDownload (Resource rsrc) throws IOException;
 
@@ -241,15 +233,13 @@ public abstract class Downloader extends Thread
     /** The current transfer rate in bytes per second. */
     protected long _bytesPerSecond;
 
-    /** The time at which the last progress update was posted to the
+    /** The time at which the last progress update was posted to the progress observer. */
-     * progress observer. */
     protected long _lastUpdate;
 
-    /** Whether the download has completed and the progress observer
+    /** Whether the download has completed and the progress observer notified. */
-     * notified. */
     protected boolean _complete;
 
-    /** The delay in milliseconds between notifying progress observers of
+    /** The delay in milliseconds between notifying progress observers of file download
-     * file download progress. */
+     * progress. */
     protected static final long UPDATE_DELAY = 500L;
 }

src/java/com/threerings/getdown/net/HTTPDownloader.java

@@ -1,4 +1,24 @@
-package com.threerings.getdown.launcher;
+//
+// $Id$
+//
+// Getdown - application installer, patcher and launcher
+// Copyright (C) 2004-2006 Three Rings Design, Inc.
+//
+// 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, or (at your option)
+// any later version.
+//
+// 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.
+//
+// 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.,
+// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+
+package com.threerings.getdown.net;
 
 import java.io.FileOutputStream;
 import java.io.IOException;
@@ -59,8 +79,7 @@ public class HTTPDownloader extends Downloader
         throws IOException
     {
         // download the resource from the specified URL
-        HttpURLConnection ucon = (HttpURLConnection)
+        HttpURLConnection ucon = (HttpURLConnection)rsrc.getRemote().openConnection();
-            rsrc.getRemote().openConnection();
         ucon.connect();
 
         // make sure we got a satisfactory response code

src/java/com/threerings/getdown/net/TorrentDownloader.java

@@ -1,4 +1,24 @@
-package com.threerings.getdown.launcher;
+//
+// $Id$
+//
+// Getdown - application installer, patcher and launcher
+// Copyright (C) 2004-2006 Three Rings Design, Inc.
+//
+// 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, or (at your option)
+// any later version.
+//
+// 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.
+//
+// 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.,
+// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+
+package com.threerings.getdown.net;
 
 import java.io.IOException;
 import java.util.HashMap;