/*
 *                 Sun Public License Notice
 * 
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 * 
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2003 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.openide.debugger;

import java.beans.PropertyChangeListener;

import org.openide.text.Line;
import org.openide.src.ConstructorElement;

/**
* Provides a minimal interface between the IDE and a debugger.
* It permits
* control of the state of the debugger and creation of breakpoints and
* watches.
* 
You may find an instance in {@link org.openide.util.Lookup}.
*
* @deprecated Use new Debugger API (http://www.netbeans.org/download/dev/javadoc/).
* @author   Jan Jancura, Jaroslav Tulach
*/
public abstract class Debugger {
    /** Debugger state when the debugger is not running at all. */
    public static final int DEBUGGER_NOT_RUNNING = 1;
    /** Debugger state when the debugger is starting to run. */
    public static final int DEBUGGER_STARTING = 2;
    /** Debugger state when the debugger is running user code. */
    public static final int DEBUGGER_RUNNING = 3;
    /** Debugger state when the debugger is stopped, for example at a breakpoint. */
    public static final int DEBUGGER_STOPPED = 4;

    /** Name of property for the debugger's state. */
    public static final String PROP_STATE = "state"; // NOI18N
    /** Name of property for the set of breakpoints in the system. */
    public static final String PROP_BREAKPOINTS = "breakpoints"; // NOI18N
    /** Name of property for the set of watches in the system. */
    public static final String PROP_WATCHES = "watches"; // NOI18N
    /** Name of property for the debugger's current line. */
    public static final String PROP_CURRENT_LINE = "currentLine"; // NOI18N

    /** */
    public static final int ACTION_BREAKPOINT_HIT = 1;
    /** */
    public static final int ACTION_TRACE_OVER = 2;
    /** */
    public static final int ACTION_TRACE_INTO = 3;
    /** */
    public static final int ACTION_STEP_OUT = 4;

    /** Start a new debugging session.
    * The current debugging session, if any, should be stopped first.
    * The provided information specifies the class to start and
    * arguments to pass it, and the name of class to stop debugging in, if applicable.
    *
    * @param info debugger startup info
    * @exception DebuggerException if an error occurs while starting the debugger
    */
    public abstract void startDebugger (DebuggerInfo info) throws DebuggerException;

    /**
    * Finish the debugger session.
    * @throws DebuggerException if there was problem during cleanup
    */
    public abstract void finishDebugger () throws DebuggerException;

    /**
    * Trace into (a statement).
    * @throws DebuggerException if there is a problem during execution
    */
    public abstract void traceInto () throws DebuggerException;

    /**
    * Trace over (a statement).
    * @throws DebuggerException if there is a problem during execution
    */
    public abstract void traceOver () throws DebuggerException;

    /**
    * Go.
    * This should continue executing user code until a breakpoint is hit or the debugger finishes.
    * @throws DebuggerException if there is a problem during execution
    */
    public abstract void go () throws DebuggerException;

    /**
    * Step out (of a statement).
    * @throws DebuggerException if there is a problem during execution
    */
    public abstract void stepOut () throws DebuggerException;

    // BREAKPOINTS

    /** Create a new breakpoint assigned to a specific line.
    * The line is represented by a line object that can change its
    * position as the text is modified.
    *
    * @param l line to create breakpoint at
    * @return the new breakpoint
    */
    public abstract Breakpoint createBreakpoint (Line l);

    /** Create a new breakpoint assigned to a specific line.
    * Allows creation of a hidden breakpoint.
    *
    * @param l line to create breakpoint at
    * @param hidden true if the breakpoint should be hidden from the user
    * @return the new breakpoint
    */
    public abstract Breakpoint createBreakpoint (Line l, boolean hidden);

    /** Find the breakpoint assigned to a given line.
    *
    * @param l line to find the breakpoint at
    * @return the breakpoint or null if there is no such breakpoint
    */
    public abstract Breakpoint findBreakpoint (Line l);

    /** Create a new breakpoint assigned to a method (or constructor).
    * The method is represented by a method (or constructor) source element that
    * must have a declaring class.
    *
    * @param method method or constructor with {@link org.openide.src.MemberElement#getDeclaringClass valid} declaring class
    * @return the new breakpoint
    * @exception IllegalArgumentException if the method does not have a declaring class
    */
    public abstract Breakpoint createBreakpoint (ConstructorElement method);

    /** Create a new breakpoint assigned to a method (or constructor).
    * The method is represented by a method (or constructor) source element that
    * must have a declaring class.
    * Allows creation of a hidden breakpoint.
    *
    * @param method method or constructor with {@link org.openide.src.MemberElement#getDeclaringClass valid} declaring class
    * @param hidden true if the breakpoint should be hidden from the user
    * @return the new breakpoint
    * @exception IllegalArgumentException if the method does not have a declaring class
    */
    public abstract Breakpoint createBreakpoint (ConstructorElement method, boolean hidden);

    /** Find the breakpoint assigned to a method (or constructor).
    *
    * @param method method or constructor to find the breakpoint of
    * @return the breakpoint or null if there is no such breakpoint
    * @exception IllegalArgumentException if the method does not have a declaring class
    */
    public abstract Breakpoint findBreakpoint (ConstructorElement method);

    /** Get all breakpoints in the system.
    *
    * @return all breakpoints
    */
    public abstract Breakpoint[] getBreakpoints ();

    /**
    * Remove all breakpoints from the system.
    */
    public abstract void removeAllBreakpoints ();



    // WATCHES

    /** Create new uninitialized watch. The watch is visible (not hidden).
    *
    * @return the new watch
    */
    public abstract Watch createWatch ();

    /** Create a watch with its expression set to an initial value.
    * Also
    * allows creation of a hidden watch (not presented to the user), for example
    * for internal use in the editor to obtain values of variables
    * under the mouse pointer.
    *
    * @param expr expression to watch for (the format is the responsibility of the debugger implementation, but it is typically a variable name)
    * @param hidden true if the watch should be hidden from the user
    * @return the new watch
    */
    public abstract Watch createWatch (String expr, boolean hidden);

    /**
    * Get all watches in the system.
    *
    * @return all watches
    */
    public abstract Watch[] getWatches ();

    /**
    * Remove all watches from the system.
    */
    public abstract void removeAllWatches ();

    // PROPERTIES

    /** Get the state of the debugger.
    *
    * @return {@link #DEBUGGER_NOT_RUNNING}, {@link #DEBUGGER_RUNNING}, {@link #DEBUGGER_STOPPED}, or {@link #DEBUGGER_STARTING}
    */
    public abstract int getState ();

    /** Get the current line of debugger.
    *
    * @return current line
    */
    public abstract Line getCurrentLine ();

    /**
    * Add a property change listener.
    *
    * @param l the listener to add
    */
    public abstract void addPropertyChangeListener (PropertyChangeListener l);

    /**
    * Remove a property change listener.
    *
    * @param l the listener to remove
    */
    public abstract void removePropertyChangeListener (PropertyChangeListener l);
}