Module io.quarkus.qute.debug
Package io.quarkus.qute.debug.agent

Class DebuggeeAgent

java.lang.Object
io.quarkus.qute.debug.agent.DebuggeeAgent
All Implemented Interfaces:
JavaSourceResolver, Debugger
public class DebuggeeAgent extends Object implements Debugger
The DebuggeeAgent manages the debugging process for Qute templates.

It acts as the core component on the debuggee side:

  • Tracks and manages Qute Engine instances for debugging.
  • Manages breakpoints, stack frames, scopes, and variables.
  • Receives trace events from Qute templates and maps them to DAP events.
  • Notifies registered DebuggerListeners of relevant events (stopped, threads changes, output, termination, etc.).

  • Constructor Details

    • DebuggeeAgent

      public DebuggeeAgent()
      Creates a new DebuggeeAgent instance.

  • Method Details

    • track

      public void track(io.quarkus.qute.Engine engine)
      Starts tracking the given Qute engine for debugging.
      Parameters:
      engine - the engine to track.

    • getState

      public DebuggerState getState(int threadId)
      Description copied from interface: Debugger
      Returns the current state of the remote debugger for a given thread.
      Specified by:
      getState in interface Debugger
      Parameters:
      threadId - the ID of the thread
      Returns:
      the current DebuggerState of the thread

    • pause

      public void pause(int threadId)
      Description copied from interface: Debugger
      Pauses the execution of the template engine on the specified thread.
      Specified by:
      pause in interface Debugger
      Parameters:
      threadId - the ID of the thread to pause

    • resume

      public void resume(int threadId)
      Description copied from interface: Debugger
      Resumes the execution of the template engine on the specified thread.
      Specified by:
      resume in interface Debugger
      Parameters:
      threadId - the ID of the thread to resume

    • onStartTemplate

      public void onStartTemplate(io.quarkus.qute.trace.TemplateEvent event)
      Called when a template starts executing.
      Parameters:
      event - the start template event.

    • onBeforeResolve

      public void onBeforeResolve(io.quarkus.qute.trace.ResolveEvent event)
      Called whenever a Qute template node is processed.
      Parameters:
      event - the resolve event representing the current node.

    • onAfterResolve

      public void onAfterResolve(io.quarkus.qute.trace.ResolveEvent event)

    • onEndTemplate

      public void onEndTemplate(io.quarkus.qute.trace.TemplateEvent event)
      Called when template execution ends.
      Parameters:
      event - the end template event.

    • setBreakpoints

      public org.eclipse.lsp4j.debug.Breakpoint[] setBreakpoints(org.eclipse.lsp4j.debug.SourceBreakpoint[] sourceBreakpoints, org.eclipse.lsp4j.debug.Source source)
      Description copied from interface: Debugger
      Sets breakpoints in a source file.
      Specified by:
      setBreakpoints in interface Debugger
      Parameters:
      sourceBreakpoints - the breakpoints to set
      source - the source file where breakpoints are applied
      Returns:
      the actual breakpoints that were set

    • getThread

      public org.eclipse.lsp4j.debug.Thread getThread(int threadId)
      Description copied from interface: Debugger
      Returns the thread with the given ID.
      Specified by:
      getThread in interface Debugger
      Parameters:
      threadId - the ID of the thread
      Returns:
      the corresponding Thread object

    • getThreads

      public org.eclipse.lsp4j.debug.Thread[] getThreads()
      Description copied from interface: Debugger
      Returns the list of threads known to the debugger.
      Specified by:
      getThreads in interface Debugger
      Returns:
      an array of Thread objects

    • addDebuggerListener

      public void addDebuggerListener(DebuggerListener listener)
      Description copied from interface: Debugger
      Registers a debugger listener to receive debug events.
      Specified by:
      addDebuggerListener in interface Debugger
      Parameters:
      listener - the listener to register

    • removeDebuggerListener

      public void removeDebuggerListener(DebuggerListener listener)
      Removes a debugger listener and unlocks all threads if there are no listeners left.
      Specified by:
      removeDebuggerListener in interface Debugger
      Parameters:
      listener - the listener to remove.

    • unlockAllDebuggeeThreads

      public void unlockAllDebuggeeThreads()
      Unlocks and terminates all debuggee threads, then clears all tracked engines.

    • terminate

      public void terminate()
      Description copied from interface: Debugger
      Terminates the debugging session.
      Specified by:
      terminate in interface Debugger

    • stepIn

      public void stepIn(int threadId)
      Description copied from interface: Debugger
      Performs a "step in" operation for the given thread.
      Specified by:
      stepIn in interface Debugger
      Parameters:
      threadId - the ID of the thread

    • stepOut

      public void stepOut(int threadId)
      Description copied from interface: Debugger
      Performs a "step out" operation for the given thread.
      Specified by:
      stepOut in interface Debugger
      Parameters:
      threadId - the ID of the thread

    • stepOver

      public void stepOver(int threadId)
      Description copied from interface: Debugger
      Performs a "step over" operation for the given thread.
      Specified by:
      stepOver in interface Debugger
      Parameters:
      threadId - the ID of the thread

    • next

      public void next(int threadId)
      Description copied from interface: Debugger
      Moves to the next statement for the given thread (alias for step over).
      Specified by:
      next in interface Debugger
      Parameters:
      threadId - the ID of the thread

    • completions

      public CompletableFuture<org.eclipse.lsp4j.debug.CompletionsResponse> completions(org.eclipse.lsp4j.debug.CompletionsArguments args)
      Description copied from interface: Debugger
      Provides code completions for the specified context.
      Specified by:
      completions in interface Debugger
      Parameters:
      args - the CompletionsArguments for the current context
      Returns:
      a CompletableFuture<org.eclipse.lsp4j.debug.CompletionsResponse> with the suggested completions

    • getSourceReference

      public org.eclipse.lsp4j.debug.SourceResponse getSourceReference(int sourceReference)
      Description copied from interface: Debugger
      Returns the source code template for a given source reference.
      Specified by:
      getSourceReference in interface Debugger
      Parameters:
      sourceReference - the source reference
      Returns:
      the source code template for a given source reference

    • getStackFrames

      public org.eclipse.lsp4j.debug.StackTraceResponse getStackFrames(int threadId, Integer startFrame, Integer levels)
      Description copied from interface: Debugger
      Returns the stack frames for the specified thread.
      Specified by:
      getStackFrames in interface Debugger
      Parameters:
      threadId - the ID of the thread
      startFrame - the index of the first frame to return; if omitted frames start at 0.
      levels - the maximum number of frames to return. If levels is not specified or 0, all frames are returned.
      Returns:
      an array of StackFrame objects and the total frames

    • getScopes

      public org.eclipse.lsp4j.debug.Scope[] getScopes(int frameId)
      Description copied from interface: Debugger
      Returns the variable scopes for the given stack frame.
      Specified by:
      getScopes in interface Debugger
      Parameters:
      frameId - the ID of the stack frame
      Returns:
      an array of Scope objects

    • getVariables

      public org.eclipse.lsp4j.debug.Variable[] getVariables(int variablesReference)
      Description copied from interface: Debugger
      Retrieves the variables for a given variable reference.
      Specified by:
      getVariables in interface Debugger
      Parameters:
      variablesReference - the reference ID for the variable
      Returns:
      an array of child Variable objects

    • evaluate

      public CompletableFuture<org.eclipse.lsp4j.debug.EvaluateResponse> evaluate(Integer frameId, String expression, String context)
      Description copied from interface: Debugger
      Evaluates the given expression in the context of the specified frame.
      Specified by:
      evaluate in interface Debugger
      Parameters:
      frameId - the ID of the stack frame (nullable)
      expression - the expression to evaluate
      context - the evaludation context
      Returns:
      a CompletableFuture that completes with the evaluation result

    • findStackFrame

      public RemoteStackFrame findStackFrame(Integer frameId)
      Finds a stack frame by its ID across all threads.

    • getVariablesRegistry

      public VariablesRegistry getVariablesRegistry()

    • getSourceTemplateRegistry

      public SourceTemplateRegistry getSourceTemplateRegistry(io.quarkus.qute.Engine engine)

    • setJavaSourceResolver

      public void setJavaSourceResolver(JavaSourceResolver javaSourceResolver)

    • setEnabled

      public void setEnabled(boolean enabled)
      Description copied from interface: Debugger
      Enables or disables the debugger.
      Specified by:
      setEnabled in interface Debugger
      Parameters:
      enabled - true to enable the debugger, false to disable it

    • isEnabled

      public boolean isEnabled()
      Description copied from interface: Debugger
      Returns whether the debugger is currently enabled.
      Specified by:
      isEnabled in interface Debugger
      Returns:
      true if enabled, false otherwise

    • reset

      public void reset()
      Resets the agent by unlocking all threads and clearing tracked engines.

    • resolveJavaSource

      public CompletableFuture<JavaSourceLocationResponse> resolveJavaSource(JavaSourceLocationArguments params)
      Description copied from interface: JavaSourceResolver
      Resolves the Java method or class referenced from a Qute template for the purpose of setting breakpoints.

      The JavaSourceLocationArguments contains the parsed information from a qute-java:// URI. The method returns a CompletableFuture that completes with a JavaSourceLocationResponse containing the Java file URI and the start line of the template content (or the method/class if applicable).

      Specified by:
      resolveJavaSource in interface JavaSourceResolver
      Parameters:
      params - the arguments describing the Java element to resolve
      Returns:
      a future completing with the resolved Java source location

    • getJavaSourceResolver

      public JavaSourceResolver getJavaSourceResolver()