Debug session

The DebugSession allows to:

• Start the session
• Start the session script
• Step or continue the execution to the next breakpoint
• Create breakpoints, or edit their properties
• End the session

Note that:

• The session does not provide any graphical interface. An actual graphical interface can be provided by the Debug listener
• The session does not execute the script by itself. You must define the code to execute it by defining a Session Hook

Steps for configuring a session

The following diagram shows the steps which must be used to configure a session:

• Initializing the session allows to show correctly exceptions which could be encountered when trying to compile the script^[1]
  The session will still work correctly if this steps is not performed, but in this case exceptions encountered when trying to compile the script will be thrown
• Installing the script is performed in exactly the same way as without debugging. Note that this step can also be performed before the session is initialized
• Creating the session effectively creates the session
• Setting the session hook defines what code will be performed when the session script will be started
• Starting the session effectively crates the rsources associated with the session
• Starting the script starts the session hook (hence the script code)^[2]
  It allows you to specify which script method will be called, or even specify more complex code involving Java code and calling several script methods
• Ending the session release all the resources handled by the session

Steps order

If you install the script before initializing the session, you will have a bubbling exception if the script is not compilable. For example in that case:

      DebuggingWrapper<Script> wrapper = new GroovyScriptWrapper<Script>() {
      };
      
      File file = <the script>
      wrapper.installScript(file); // install the script
      wrapper.initializeDebugSession(); // initialize the Debug session
      
      DebugSession<Script> session = wrapper.createDebugSession();
      SessionHook<Script> hook = ...

If the script is not compilable, an exception will be thrown. But the following code will work correctly:

      DebuggingWrapper<Script> wrapper = new GroovyScriptWrapper<Script>() {
      };
      
      File file = <the script>
      wrapper.initializeDebugSession(); // initialize the Debug session
      wrapper.installScript(file); // install the script
      
      DebugSession<Script> session = wrapper.createDebugSession();
      SessionHook<Script> hook = ...

Initializing a session

The DebuggingWrapper.initializeDebugSession() method tells the wrapper that the wrapper is in a Debug session (it will exit this state when the session will end). This allows to correctly present the exceptions associated with uncompilable scripts.

Note that if you don't call this method prior to create effectively the session, the session will still work correctly but then exceptions associated with uncompilable scripts won't be handled nicely.

Creating a session

The DebuggingWrapper.createDebugSession() method allows to create a session. It is only available for DebuggingWrappers.

For example:

      DebuggingWrapper<Script> wrapper = new GroovyScriptWrapper<Script>() {
      };
      
      File file = <the script>
      wrapper.initializeDebugSession(); // initialize the Debug session
      wrapper.installScript(file); // install the script
            
      // create the session      
      DebugSession<Script> session = wrapper.createDebugSession();

Note that the session will only start after the DebugSession.startSession() has been called.

Setting the Session Hook

The DebugSession.setSessionHook(SessionHook) will specify the code which will be executed after the start of the session. The most simple code to execute is just calling the code of one of the Script interface method. For example for the following script interface:

      public interface Script {
        public int compute() {
        }
      }

We can perform:

      DebuggingWrapper<Script> wrapper = new GroovyScriptWrapper<Script>() {
      };
      
      File file = <the script>
      wrapper.initializeDebugSession();
      wrapper.installScript(file);
            
      DebugSession<Script> session = wrapper.createDebugSession();
      SessionHook<Script> hook = new SessionHook<> {
        public Object start(Script script) {
          return script.compute();
        }
      }
      session.setSessionHook(hook);

Starting a session

To start the session, call DebugSession.startSession().

Starting the session will initialize all the resources needed by the session, but it will not yet start the script.

Adding breakpoints

It is possible to add a breakpoint by DebugSession.addBreakpoint(int). The method will return:

• null if there is no step defined on the specified line
• A breakpoint by default
• A step if there was previously a breakpoint at this line number

It is possible to edit each breakpoint to add conditions for stopping on this breakpoint.

Starting the script

Starting the session does not start the script code itself. To effectively start the script code, you will need to call DebugSession.startScript().

It will call the SessionHook.start(S) with the script object as argument.

For example:

      DebuggingWrapper<Script> wrapper = new GroovyScriptWrapper<Script>() {
      };
      
      File file = <the script>
      wrapper.initializeDebugSession();
      wrapper.installScript(file);
            
      DebugSession<Script> session = wrapper.createDebugSession();
      SessionHook<Script> hook = new SessionHook<> {
        public Object start(Script script) {
          return script.compute();
        }
      }
      session.setSessionHook(hook);

      session.startSession();
      session.startScript(); // here the script.compute() method is effectively executed

Ending the session

The DebugSession.endSession() ends the session and release the resources associated with this session.

Using children sessions

It is possible to start another debug session in the context of one parent session. This can be useful for example if you want to start another ScrippWrapper in the Script helper.