The NetBeans Debugger Core API definition. Debugger Core API interfaces allows to install differrent debugger inlementations to one IDE, and share some UI components among them.

## Basic debugger model

Debugger Core API represents debugger as some tree structure. {@link org.netbeans.api.debugger.DebuggerManager} represents root of this tree. It manages list of {@link org.netbeans.api.debugger.Breakpoint}s, {@link org.netbeans.api.debugger.Watch}es and running {@link org.netbeans.api.debugger.Session}s. All watches and breakpoints registerred here are shared for all running sessions.
{@link org.netbeans.api.debugger.Session} represents one process or application running in debug mode. Each Session manages list of supported programming languages. Support for each programming language is represented by some instance of {@link org.netbeans.api.debugger.DebuggerEngine}. DebuggerEngine is a main intergation point for all Debugger Plug-ins. Most of Service Providers (like {@link org.netbeans.spi.debugger.ActionsProvider} or different Models) should be registered for some concrete type of DebuggerEngine.

    {@link org.netbeans.api.debugger.DebuggerManager}
      |
      |- {@link org.netbeans.api.debugger.Breakpoint}(s)
      |
      |- {@link org.netbeans.api.debugger.Watch}(es)
      |
      |- {@link org.netbeans.api.debugger.Session}(s)   <programming language 1 -> {@link org.netbeans.api.debugger.DebuggerEngine} 1>
                      <programming language 2 -> {@link org.netbeans.api.debugger.DebuggerEngine} 2>
                       ...

One DebuggerEngine can manage more than one language. And it can be used for more than one Session. In extreme example, there may be one DebuggerManager only for several different sessions and for many different languages.
The only way how to add some language, session or engine to this tree is method {@link org.netbeans.api.debugger.DebuggerManager#startDebugging(DebuggerInfo)}. The only method how to remove something is {@link org.netbeans.api.debugger.DebuggerEngine.Destructor}.

## Exension of basic model - lookups, Meta-inf/debugger

Basic debugger model is very simple, and it should be extended by some additional services (see Debugger SPI documentation for default set of additional services). As the Debugger API interfaces should be (and are) final, we use lookup pattern for this purpose.
List of 'extensible' interfaces:

- {@link org.netbeans.api.debugger.DebuggerManager}: methods {@link org.netbeans.api.debugger.DebuggerManager#lookup(String,Class)} and {@link org.netbeans.api.debugger.DebuggerManager#lookupFirst(String,Class)}
- {@link org.netbeans.api.debugger.DebuggerInfo}: methods {@link org.netbeans.api.debugger.DebuggerInfo#lookup(String,Class)} and {@link org.netbeans.api.debugger.DebuggerInfo#lookupFirst(String,Class)}
- {@link org.netbeans.api.debugger.Session}: methods {@link org.netbeans.api.debugger.Session#lookup(String,Class)} and {@link org.netbeans.api.debugger.Session#lookupFirst(String,Class)}
- {@link org.netbeans.api.debugger.DebuggerEngine}: methods {@link org.netbeans.api.debugger.DebuggerEngine#lookup(String,Class)}, {@link org.netbeans.api.debugger.DebuggerEngine#lookupFirst(String,Class)}, {@link org.netbeans.api.debugger.DebuggerManager#lookup(String,Class)} and {@link org.netbeans.api.debugger.DebuggerManager#lookupFirst(String,Class)}

There are two ways how to registrer services. The first possibility is to put 'live' instance of some service to the interface when a new instance is created. This solution is supported by methods: {@link org.netbeans.api.debugger.DebuggerInfo#create(String,Object[])}, {@link org.netbeans.spi.debugger.SessionProvider#getServices()} and {@link org.netbeans.spi.debugger.DebuggerEngineProvider#getServices()}. Second possibility (and preferred one) is to register service to Meta-inf/debugger folder. The way how to do it is described in Debugger SPI documentation.

## Debugger Start Process

The process which implements starting of debugger in Debugger Core module is very simple. There is one instance of {@link org.netbeans.api.debugger.DebuggerInfo} and {@link org.netbeans.api.debugger.DebuggerManager#startDebugging(DebuggerInfo)} method on the begining of this process. DebuggerInfo determines a set of debugger Sessions to be started:

    List sessionProviders = debuggerInfo.lookup (null, SessionsProvider.class);

A new instance of {@link org.netbeans.api.debugger.Session} is created for every {@link org.netbeans.spi.debugger.SessionProvider} after that. A set of DebuggerEngines is created for each Session in the second step:

    List engineProviders = session.lookup (null, DebuggerEngineProvider.class);

Each {@link org.netbeans.spi.debugger.DebuggerEngineProvider} drives creation of one new instance of {@link org.netbeans.api.debugger.DebuggerEngine}. So, the debugger start process creates a tree of new Sessions and new DebuggerEngines and registers them to the DebuggerManager. Thats all.

## Debugger Start Process - advanced version

Debugger API supports two enhancements to the standard debugger start process:

1. Start new DebuggerEngine for already existing Session
2. Create a new Session for already existing DebuggerEngine.

{@link org.netbeans.spi.debugger.DelegatingSessionProvider} interface is designed to support first usecase. You should implement and register this interface in Meta-inf/debugger, to delegate on some existing Session.
Second usecase is supported by interface {@link org.netbeans.spi.debugger.DelegatingDebuggerEngineProvider}.

## Debugger Actions - how does it work

debuggercore-ui module installs some basic set of standard debugger actions to NetBeans toolbar and menu. Debugger actions (javax.swing.Action) are private. Each action is represented by some constant in {@link org.netbeans.api.debugger.ActionsManager} (like {@link org.netbeans.api.debugger.ActionsManager#ACTION_STEP_INTO}).
ActionsManager manages list of registered {@link org.netbeans.spi.debugger.ActionProvider}s. It contains mapping between action constant and ActionProvider registerred for this constant. For example:
instance of DebuggerEngine which represents JPDA debugger contains mapping:
ActionsManager.ACTION_STEP_INTO --> JPDAStepIntoActionProvider
How to implement and register some debugger action:

    public class JPDAStepIntoAction extends ActionsProviderSupport {

        JPDAStepIntoAction () {
            jpdaDebugger.add...Listener (
                new Listener () {
                    public ...event () {
                        // set state of action here
                        setEnabled ( state );
                    }
                }
            );
        }
        public boolean doAction (Object action) {
            // put implementation of action here
            return true; // action successful
        }
    }

And JPDAStepIntoAction should be registerred in file:
META-INF/debugger/{DebuggerEngineTypeID}/org.netbeans.spi.debugger.ActionsProvider
Following two diagrams will show how the action system works:
Diagram 1 - what happens when user press Step Into Action:

1. StepIntoAction calls {@link org.netbeans.api.debugger.ActionsManager#doAction(Object)} for {@link org.netbeans.api.debugger.ActionsManager#ACTION_STEP_INTO}, when its invoked by the user.
2. {@link org.netbeans.api.debugger.ActionsManager} finds proper {@link org.netbeans.spi.debugger.ActionsProvider} registered for given action. Than it calls {@link org.netbeans.spi.debugger.ActionsProvider#doAction(Object)}.
3. {@link org.netbeans.api.debugger.ActionsManager} notifies all {@link org.netbeans.api.debugger.ActionsManagerListener}s about it, when the action is done.

     user            StepIntoAction                                 DebuggerEngine                       StepIntoActionProvider                   DebuggerEngineListener
                  (javax.swing.Action)                                    |                                 (ActionsProvider)                                |
                           |                                              |                                         |                                        |
      o  press  ->  actionPerformed (...)                                 |                                         |                                        |
     _|_ action          calls                                            |                                         |                                        |
      |  button     currentDebuggerEngine.         -->       doAction (ACTION_STEP_INTO)                            |                                        |
     / \                doAction                                          |                                         |                                        |
                    (ACTION_STEP_INTO)                           finds ActionsProviders                             |                                        |
                           |                                   registerred for given action        -->   doAction (ACTION_STEP_INTO)                         |
                           |                                    and calls doAction on them                  implementation of                                |
                           |                                              |                               Step Into Action is here                           |
                           |                                              |                        <--              |                                        |
                           |                                  fires PROP_ACTION_PERFORMED                           |                                        |
                           |                                              |                        -->             -|->                              actionPerformed (..)
                           |                                              |                                         |                                  listener impl.
                           | <--                                        <-|-                                      <-|-                                    <--|
                           |                                              |                                         |                                        |

Diagram 2 - what happens when the state of Step Into Action is changed:

1. Debugger implementation should recognize that the state of Step Into action should be changed, and it should notify StepIntoActionProvider about it.
2. StepIntoActionProvider should fire {@link org.netbeans.spi.debugger.ActionsProviderListener#actionStateChange(Object,boolean)} for {@link org.netbeans.api.debugger.ActionsManager#ACTION_STEP_INTO}.
3. {@link org.netbeans.api.debugger.DebuggerEngine} is listenning on all installed {@link org.netbeans.spi.debugger.ActionsProvider}s and fires all action state changes using {@link org.netbeans.api.debugger.DebuggerEngineListener#actionStateChanged(Object,boolean)}.
4. StepIntoAction listens on {@link org.netbeans.api.debugger.DebuggerEngine}, and it updates its state when some actionStateChanged is fired.

          debugger    StepIntoActionProvider          DebuggerEngine.ActionsProviderListener                StepIntoAction.DebuggerEngineListener
                         (ActionsProvider)                            |                                           (javax.swing.Action)
                                |                                     |                                                    |
       _  state of   ->  fire action state                            |                                                    |
      |?|  action            change           -->   actionStateChange (ACTION_STEP_INTO, enabled)                          |
       ¯  should be             |                                     |                                                    |
          changed               |                         fire DebuggerEngineListener                                      |
                                |                            actionStateChanged                   -->             actionStateChanged
                                |                                     |                                             updates a state
                                |                                     |                                                of action
                                |<--                                <-|-                          <--                      |