Committing the patch for Bugzilla 328924 "Impossible to use the debugger from outside the omj.tools.debugger package"

js/rhino/toolsrc/org/mozilla/javascript/tools/debugger/GuiCallback.java

@@ -20,6 +20,7 @@
  *
  * Contributor(s):
  * Igor Bukanov, igor@fastmail.fm
+ * Cameron McCormack
  *
  * Alternatively, the contents of this file may be used under the
  * terms of the GNU Public License (the "GPL"), in which case the
@@ -32,20 +33,36 @@
  * the provisions above, a recipient may use your version of this
  * file under either the NPL or the GPL.
  */
-
-
 package org.mozilla.javascript.tools.debugger;
 
-public interface GuiCallback
-{
-    public void updateSourceText(Dim.SourceInfo sourceInfo);
+/**
+ * Interface for communication between the debugger and its GUI.  This
+ * should be implemented by the GUI.
+ */
+public interface GuiCallback {
 
-    public void enterInterrupt(Dim.StackFrame lastFrame,
-                               String threadTitle,
-                               String alertMessage);
+    /**
+     * Called when the source text of some script has been changed.
+     */
+    void updateSourceText(Dim.SourceInfo sourceInfo);
 
-    public boolean isGuiEventThread();
+    /**
+     * Called when the interrupt loop has been entered.
+     */
+    void enterInterrupt(Dim.StackFrame lastFrame,
+                        String threadTitle,
+                        String alertMessage);
 
-    public void dispatchNextGuiEvent()
-        throws InterruptedException;
+    /**
+     * Returns whether the current thread is the GUI's event thread.
+     * This information is required to avoid blocking the event thread
+     * from the debugger.
+     */
+    boolean isGuiEventThread();
+
+    /**
+     * Processes the next GUI event.  This manual pumping of GUI events
+     * is necessary when the GUI event thread itself has been stopped.
+     */
+    void dispatchNextGuiEvent() throws InterruptedException;
 }

js/rhino/toolsrc/org/mozilla/javascript/tools/debugger/Main.java

@@ -14,7 +14,7 @@
  * November 21, 2000.
  *
  * The Initial Developer of the Original Code is SeeBeyond Corporation.
-
+ *
  * Portions created by SeeBeyond are
  * Copyright (C) 2000 SeeBeyond Technology Corporation. All
  * Rights Reserved.
@@ -23,6 +23,7 @@
  * Igor Bukanov
  * Matt Gould
  * Christopher Oliver
+ * Cameron McCormack
  *
  * Alternatively, the contents of this file may be used under the
  * terms of the GNU Public License (the "GPL"), in which case the
@@ -41,236 +42,192 @@ package org.mozilla.javascript.tools.debugger;
 import java.io.InputStream;
 import java.io.PrintStream;
 
+import javax.swing.JFrame;
+
 import org.mozilla.javascript.*;
 import org.mozilla.javascript.tools.shell.Global;
 
-
-public class Main implements ContextListener
-{
-    // The class implements ContextListener only for compatibility!
-
-    Dim dim;
-    SwingGui debugGui;
+/**
+ * Rhino script debugger main class.  This class links together a
+ * debugger object ({@link Dim}) and a debugger GUI object ({@link SwingGui}).
+ * {@link ContextListener} is only implemented for compatibility.
+ */
+public class Main implements ContextListener {
 
     /**
-     * Class to consolidate all internal implementations of interfaces
-     * to avoid class generation bloat.
+     * The debugger.
      */
-    private static class IProxy implements Runnable, ScopeProvider
-    {
-        static final int EXIT_ACTION = 1;
-        static final int SCOPE_PROVIDER = 2;
+    private Dim dim;
 
-        private final int type;
-        Scriptable scope;
+    /**
+     * The debugger frame.
+     */
+    private SwingGui debugGui;
 
-        IProxy(int type)
-        {
-            this.type = type;
-        }
-
-        public static ScopeProvider newScopeProvider(Scriptable scope)
-        {
-            IProxy scopeProvider = new IProxy(SCOPE_PROVIDER);
-            scopeProvider.scope = scope;
-            return scopeProvider;
-        }
-
-        public void run()
-        {
-            if (type != EXIT_ACTION) Kit.codeBug();
-            System.exit(0);
-        }
-
-        public Scriptable getScope()
-        {
-            if (type != SCOPE_PROVIDER) Kit.codeBug();
-            if (scope == null) Kit.codeBug();
-            return scope;
-        }
-    }
-
-    //
-    // public interface
-    //
-
-    public Main(String title)
-    {
+    /**
+     * Creates a new Main.
+     */
+    public Main(String title) {
         dim = new Dim();
         debugGui = new SwingGui(dim, title);
-        dim.callback = debugGui;
-    }
-
-    public void doBreak() {
-        dim.breakFlag = true;
-    }
-
-   /**
-    *  Toggle Break-on-Exception behavior
-    */
-    public void setBreakOnExceptions(boolean value) {
-        dim.breakOnExceptions = value;
-        debugGui.menubar.breakOnExceptions.setSelected(value);
-    }
-
-   /**
-    *  Toggle Break-on-Enter behavior
-    */
-    public void setBreakOnEnter(boolean value) {
-        dim.breakOnEnter = value;
-        debugGui.menubar.breakOnEnter.setSelected(value);
-    }
-
-   /**
-    *  Toggle Break-on-Return behavior
-    */
-    public void setBreakOnReturn(boolean value) {
-        dim.breakOnReturn = value;
-        debugGui.menubar.breakOnReturn.setSelected(value);
     }
 
     /**
-     *
-     * Remove all breakpoints
+     * Returns the debugger window {@link JFrame}.
      */
-    public void clearAllBreakpoints()
-    {
+    public JFrame getDebugFrame() {
+        return debugGui;
+    }
+
+    /**
+     * Breaks execution of the script.
+     */
+    public void doBreak() {
+        dim.setBreak();
+    }
+
+    /**
+     * Sets whether execution should break when a script exception is thrown.
+     */
+    public void setBreakOnExceptions(boolean value) {
+        dim.setBreakOnExceptions(value);
+        debugGui.getMenubar().getBreakOnExceptions().setSelected(value);
+    }
+
+    /**
+     * Sets whether execution should break when a function is entered.
+     */
+    public void setBreakOnEnter(boolean value) {
+        dim.setBreakOnEnter(value);
+        debugGui.getMenubar().getBreakOnEnter().setSelected(value);
+    }
+
+    /**
+     * Sets whether execution should break when a function is left.
+     */
+    public void setBreakOnReturn(boolean value) {
+        dim.setBreakOnReturn(value);
+        debugGui.getMenubar().getBreakOnReturn().setSelected(value);
+    }
+
+    /**
+     * Removes all breakpoints.
+     */
+    public void clearAllBreakpoints() {
         dim.clearAllBreakpoints();
     }
 
-   /**
-    *  Resume Execution
-    */
-    public void go()
-    {
+    /**
+     * Resumes execution of the script.
+     */
+    public void go() {
         dim.go();
     }
 
-    public void setScope(Scriptable scope)
-    {
+    /**
+     * Sets the scope to be used for script evaluation.
+     */
+    public void setScope(Scriptable scope) {
         setScopeProvider(IProxy.newScopeProvider(scope));
     }
 
+    /**
+     * Sets the {@link ScopeProvider} that provides a scope to be used
+     * for script evaluation.
+     */
     public void setScopeProvider(ScopeProvider p) {
-        dim.scopeProvider = p;
+        dim.setScopeProvider(p);
     }
 
     /**
      * Assign a Runnable object that will be invoked when the user
-     * selects "Exit..." or closes the Debugger main window
+     * selects "Exit..." or closes the Debugger main window.
      */
     public void setExitAction(Runnable r) {
-        debugGui.exitAction = r;
+        debugGui.setExitAction(r);
     }
 
     /**
-     * Get an input stream to the Debugger's internal Console window
+     * Returns an {@link InputStream} for stdin from the debugger's internal
+     * Console window.
      */
-
     public InputStream getIn() {
-        return debugGui.console.getIn();
+        return debugGui.getConsole().getIn();
     }
 
     /**
-     * Get an output stream to the Debugger's internal Console window
+     * Returns a {@link PrintStream} for stdout to the debugger's internal
+     * Console window.
      */
-
     public PrintStream getOut() {
-        return debugGui.console.getOut();
+        return debugGui.getConsole().getOut();
     }
 
     /**
-     * Get an error stream to the Debugger's internal Console window
+     * Returns a {@link PrintStream} for stderr in the Debugger's internal
+     * Console window.
      */
-
     public PrintStream getErr() {
-        return debugGui.console.getErr();
+        return debugGui.getConsole().getErr();
     }
 
-    public void pack()
-    {
+    /**
+     * Packs the debugger GUI frame.
+     */
+    public void pack() {
         debugGui.pack();
     }
 
-    public void setSize(int w, int h)
-    {
+    /**
+     * Sets the debugger GUI frame dimensions.
+     */
+    public void setSize(int w, int h) {
         debugGui.setSize(w, h);
     }
 
     /**
-     * @deprecated Use {@link #setSize(int, int)} instead.
+     * Sets the visibility of the debugger GUI frame.
      */
-    public void setSize(java.awt.Dimension dimension)
-    {
-        debugGui.setSize(dimension.width, dimension.height);
-    }
-
-    public void setVisible(boolean flag)
-    {
+    public void setVisible(boolean flag) {
         debugGui.setVisible(flag);
     }
 
-    public boolean isVisible()
-    {
+    /**
+     * Returns whether the debugger GUI frame is visible.
+     */
+    public boolean isVisible() {
         return debugGui.isVisible();
     }
 
-    public void dispose()
-    {
+    /**
+     * Frees any resources held by the debugger.
+     */
+    public void dispose() {
+        clearAllBreakpoints();
+        dim.go();
         debugGui.dispose();
+        dim = null;
     }
 
-    public void attachTo(ContextFactory factory)
-    {
+    /**
+     * Attaches the debugger to the given {@link ContextFactory}.
+     */
+    public void attachTo(ContextFactory factory) {
         dim.attachTo(factory);
     }
 
     /**
-     * @deprecated
-     * The method does nothing and is only present for compatibility.
+     * Detaches from the current {@link ContextFactory}.
      */
-    public void setOptimizationLevel(int level)
-    {
+    public void detach() {
+        dim.detach();
     }
 
     /**
-     * @deprecated
-     * The method is only present for compatibility and should not be called.
+     * Main entry point.  Creates a debugger attached to a Rhino
+     * {@link org.mozilla.tools.shell.Main} shell session.
      */
-    public void contextEntered(Context cx)
-    {
-        throw new IllegalStateException();
-    }
-
-    /**
-     * @deprecated
-     * The method is only present for compatibility and should not be called.
-     */
-    public void contextExited(Context cx)
-    {
-        throw new IllegalStateException();
-    }
-
-    /**
-     * @deprecated
-     * The method is only present for compatibility and should not be called.
-     */
-    public void contextCreated(Context cx)
-    {
-        throw new IllegalStateException();
-    }
-
-    /**
-     * @deprecated
-     * The method is only present for compatibility and should not be called.
-     */
-    public void contextReleased(Context cx)
-    {
-        throw new IllegalStateException();
-    }
-
-    public static void main(String[] args)
-    {
+    public static void main(String[] args) {
         Main main = new Main("Rhino JavaScript Debugger");
         main.doBreak();
         main.setExitAction(new IProxy(IProxy.EXIT_ACTION));
@@ -296,37 +253,47 @@ public class Main implements ContextListener
         org.mozilla.javascript.tools.shell.Main.exec(args);
     }
 
-    public static void mainEmbedded(String title)
-    {
+    /**
+     * Entry point for embedded applications.  This method attaches
+     * to the global {@link ContextFactory} with a scope of a newly
+     * created {@link Global} object.  No I/O redirection is performed
+     * as with {@link #main(String[])}.
+     */
+    public static void mainEmbedded(String title) {
         ContextFactory factory = ContextFactory.getGlobal();
         Global global = new Global();
         global.init(factory);
         mainEmbedded(factory, global, title);
     }
 
-    // same as plain main(), stdin/out/err redirection removed and
-    // explicit ContextFactory and scope
+    /**
+     * Entry point for embedded applications.  This method attaches
+     * to the given {@link ContextFactory} with the given scope.  No
+     * I/O redirection is performed as with {@link #main(String[])}.
+     */
     public static void mainEmbedded(ContextFactory factory,
                                     Scriptable scope,
-                                    String title)
-    {
+                                    String title) {
         mainEmbeddedImpl(factory, scope, title);
     }
 
-    // same as plain main(), stdin/out/err redirection removed and
-    // explicit ContextFactory and ScopeProvider
+    /**
+     * Entry point for embedded applications.  This method attaches
+     * to the given {@link ContextFactory} with the given scope.  No
+     * I/O redirection is performed as with {@link #main(String[])}.
+     */
     public static void mainEmbedded(ContextFactory factory,
                                     ScopeProvider scopeProvider,
-                                    String title)
-    {
+                                    String title) {
         mainEmbeddedImpl(factory, scopeProvider, title);
     }
 
-
+    /**
+     * Helper method for {@link #mainEmbedded}.
+     */
     private static void mainEmbeddedImpl(ContextFactory factory,
                                          Object scopeProvider,
-                                         String title)
-    {
+                                         String title) {
         if (title == null) {
             title = "Rhino JavaScript Debugger (embedded usage)";
         }
@@ -352,5 +319,112 @@ public class Main implements ContextListener
         main.setSize(600, 460);
         main.setVisible(true);
     }
-}
 
+    // Deprecated methods
+
+    /**
+     * @deprecated Use {@link #setSize(int, int)} instead.
+     */
+    public void setSize(java.awt.Dimension dimension) {
+        debugGui.setSize(dimension.width, dimension.height);
+    }
+
+    /**
+     * @deprecated
+     * The method does nothing and is only present for compatibility.
+     */
+    public void setOptimizationLevel(int level) {
+    }
+
+    /**
+     * @deprecated
+     * The method is only present for compatibility and should not be called.
+     */
+    public void contextEntered(Context cx) {
+        throw new IllegalStateException();
+    }
+
+    /**
+     * @deprecated
+     * The method is only present for compatibility and should not be called.
+     */
+    public void contextExited(Context cx) {
+        throw new IllegalStateException();
+    }
+
+    /**
+     * @deprecated
+     * The method is only present for compatibility and should not be called.
+     */
+    public void contextCreated(Context cx) {
+        throw new IllegalStateException();
+    }
+
+    /**
+     * @deprecated
+     * The method is only present for compatibility and should not be called.
+     */
+    public void contextReleased(Context cx)
+    {
+        throw new IllegalStateException();
+    }
+
+    /**
+     * Class to consolidate all internal implementations of interfaces
+     * to avoid class generation bloat.
+     */
+    private static class IProxy implements Runnable, ScopeProvider {
+
+        // Constants for 'type'.
+        public static final int EXIT_ACTION = 1;
+        public static final int SCOPE_PROVIDER = 2;
+
+        /**
+         * The type of interface.
+         */
+        private final int type;
+
+        /**
+         * The scope object to expose when {@link #type} =
+         * {@link #SCOPE_PROVIDER}.
+         */
+        private Scriptable scope;
+
+        /**
+         * Creates a new IProxy.
+         */
+        public IProxy(int type) {
+            this.type = type;
+        }
+
+        /**
+         * Creates a new IProxy that acts as a {@link ScopeProvider}.
+         */
+        public static ScopeProvider newScopeProvider(Scriptable scope) {
+            IProxy scopeProvider = new IProxy(SCOPE_PROVIDER);
+            scopeProvider.scope = scope;
+            return scopeProvider;
+        }
+
+        // ContextAction
+
+        /**
+         * Exit action.
+         */
+        public void run() {
+            if (type != EXIT_ACTION) Kit.codeBug();
+            System.exit(0);
+        }
+
+        // ScopeProvider
+
+        /**
+         * Returns the scope for script evaluations.
+         */
+        public Scriptable getScope() {
+            if (type != SCOPE_PROVIDER) Kit.codeBug();
+            if (scope == null) Kit.codeBug();
+            return scope;
+        }
+    }
+}

js/rhino/toolsrc/org/mozilla/javascript/tools/debugger/ScopeProvider.java

@@ -14,13 +14,14 @@
  * November 21, 2000.
  *
  * The Initial Developer of the Original Code is See Beyond Corporation.
-
+ *
  * Portions created by See Beyond are
  * Copyright (C) 2000 See Beyond Communications Corporation. All
  * Rights Reserved.
  *
  * Contributor(s):
  * Christopher Oliver
+ * Cameron McCormack
  *
  * Alternatively, the contents of this file may be used under the
  * terms of the GNU Public License (the "GPL"), in which case the
@@ -33,11 +34,17 @@
  * the provisions above, a recipient may use your version of this
  * file under either the NPL or the GPL.
  */
-
 package org.mozilla.javascript.tools.debugger;
 
 import org.mozilla.javascript.Scriptable;
 
+/**
+ * Interface to provide a scope object for script evalutaion to the debugger.
+ */
 public interface ScopeProvider {
-    public Scriptable getScope();
+
+    /**
+     * Returns the scope object to be used for script evaluation.
+     */
+    Scriptable getScope();
 };