Modified code to handle an exception that propagates up past iterate(). It

still causes the thread to exit by default, but it provides a mechanism
for overriding that behavior and it logs the exception rather than quietly
dying.


git-svn-id: https://samskivert.googlecode.com/svn/trunk@334 6335cc39-0255-0410-8fd6-9bcaacd3b74c

projects/samskivert/src/java/com/samskivert/util/LoopingThread.java

@@ -1,5 +1,5 @@
 //
-// $Id: LoopingThread.java,v 1.3 2001/08/11 22:43:29 mdb Exp $
+// $Id: LoopingThread.java,v 1.4 2001/10/02 22:35:26 mdb Exp $
 //
 // samskivert library - useful routines for java programs
 // Copyright (C) 2001 Michael Bayne
@@ -20,6 +20,8 @@
 
 package com.samskivert.util;
 
+import com.samskivert.Log;
+
 /**
  * The looping thread provides the basic functionality for a thread that
  * does its processing in a simple loop. This is characteristic of most
@@ -45,9 +47,8 @@ public class LoopingThread extends Thread
     }
 
     /**
-     * Processes the loop. Derived classes should override
-     * <code>iterate()</code> to perform whatever action needs to be
-     * performed inside the loop.
+     * Processes the loop. Derived classes should override {@link iterate}
+     * to perform whatever action needs to be performed inside the loop.
      */
     public void run ()
     {
@@ -55,7 +56,11 @@ public class LoopingThread extends Thread
             willStart();
 
             while (isRunning()) {
-                iterate();
+                try {
+                    iterate();
+                } catch (Exception e) {
+                    handleIterateFailure(e);
+                }
             }
 
         } finally {
@@ -65,8 +70,8 @@ public class LoopingThread extends Thread
 
     /**
      * Called to wake the thread up from any blocking wait that it might
-     * be in. This function should result in the thread exiting the
-     * iterate() function as soon as possible so that the running flag can
+     * be in. This function should result in the thread exiting the {@link
+     * iterate} function as soon as possible so that the running flag can
      * be checked and the thread can cleanly exit.
      */
     protected void kick ()
@@ -76,8 +81,8 @@ public class LoopingThread extends Thread
 
     /**
      * Called before the thread enters the processing loop. Any
-     * initialization that needs to be performed prior to the
-     * <code>iterate()</code> loop can be done here.
+     * initialization that needs to be performed prior to the {@link
+     * iterate} loop can be done here.
      */
     protected void willStart ()
     {
@@ -85,19 +90,35 @@ public class LoopingThread extends Thread
 
     /**
      * This is the main body of the loop. It will be called over and over
-     * again until the thread is requested to exit via a call to
-     * <code>shutdown()</code>. At minimum, a derived class must override
-     * this function and do something useful.
+     * again until the thread is requested to exit via a call to {@link
+     * shutdown}. At minimum, a derived class must override this function
+     * and do something useful.
      */
     protected void iterate ()
     {
         throw new RuntimeException("Derived class must implement iterate().");
     }
 
+    /**
+     * If an exception propagates past {@link iterate}, it will be caught
+     * and supplied to this function, which may want to do something
+     * useful with it. Presently, the exception is logged and the thread
+     * is allowed to terminate.
+     */
+    protected void handleIterateFailure (Exception e)
+    {
+        // log the exception
+        Log.warning("LoopingThread.iterate() uncaught exception.");
+        Log.logStackTrace(e);
+
+        // and shut the thread down
+        shutdown();
+    }
+
     /**
      * Called after the thread has been requested to exit. Any cleanup
-     * that should take place after the <code>iterate()</code> loop has
-     * exited can be done here.
+     * that should take place after the {@link iterate} loop has exited
+     * can be done here.
      */
     protected void didShutdown ()
     {
@@ -105,10 +126,10 @@ public class LoopingThread extends Thread
 
     /**
      * Indicates whether or not the thread should still be running. If a
-     * thread is calling this within <code>iterate()</code>, it should
-     * exit quickly and cleanly if the function returns false. It is
-     * automatically called as part of the iterate() loop, so normally a
-     * derived-class won't have to call it.
+     * thread is calling this within {@link iterate}, it should exit
+     * quickly and cleanly if the function returns false. It is
+     * automatically called as part of the {@link iterate} loop, so
+     * normally a derived-class won't have to call it.
      */
     protected synchronized boolean isRunning ()
     {