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

Class RemoteStackFrame

java.lang.Object
org.eclipse.lsp4j.debug.StackFrame
io.quarkus.qute.debug.agent.frames.RemoteStackFrame
public class RemoteStackFrame extends org.eclipse.lsp4j.debug.StackFrame
Represents a single Qute stack frame in the debugging process.

A RemoteStackFrame corresponds to the evaluation of a TemplateNode during the rendering of a Qute template. It encapsulates the current execution context, including variables, scopes, and the source template being processed.

This class integrates with the Debug Adapter Protocol (DAP) through StackFrame, enabling external debuggers (like VSCode or IntelliJ) to display Qute stack frames, inspect variables, and evaluate expressions.

  • Field Details

    • EMPTY_STACK_FRAMES

      public static final org.eclipse.lsp4j.debug.StackFrame[] EMPTY_STACK_FRAMES
      Represents an empty array of stack frames.

  • Constructor Details

    • RemoteStackFrame

      public RemoteStackFrame(io.quarkus.qute.trace.ResolveEvent event, RemoteStackFrame previousFrame, SourceTemplateRegistry sourceTemplateRegistry, VariablesRegistry variablesRegistry, RemoteThread remoteThread)
      Creates a new RemoteStackFrame.
      Parameters:
      event - the resolve event describing the current execution
      previousFrame - the previous stack frame, may be null
      sourceTemplateRegistry - registry for mapping templates to debug sources
      variablesRegistry - registry for managing variables
      remoteThread - the owning remote thread

  • Method Details

    • getTemplateId

      public String getTemplateId()
      Returns:
      the template ID associated with this frame

    • getTemplateUri

      public URI getTemplateUri()
      Returns:
      the template URI associated with this frame, or null if unavailable

    • getSource

      public RemoteSource getSource()
      Overrides:
      getSource in class org.eclipse.lsp4j.debug.StackFrame

    • getPrevious

      public RemoteStackFrame getPrevious()
      Returns:
      the previous stack frame, or null if none exists

    • getScopes

      public Collection<RemoteScope> getScopes()
      Returns the list of scopes for this frame.

      Scopes include:

      • Locals — variables specific to the current template
      • Globals — shared Qute global variables
      • Namespace resolvers — registered resolvers for namespace:expression
      Returns:
      a collection of RemoteScope

    • evaluate

      public CompletableFuture<Object> evaluate(String expression)
      Evaluates an arbitrary Qute expression in the current frame context.

      If the expression looks like a conditional (e.g. user.age > 18), it is parsed and evaluated as a conditional expression. Otherwise, it is evaluated as a simple Qute value expression.

      Parameters:
      expression - the Qute expression or condition to evaluate
      Returns:
      a CompletableFuture resolving to the evaluation result

    • evaluateConditionInRenderThread

      public CompletableFuture<Object> evaluateConditionInRenderThread(io.quarkus.qute.TemplateNode ifNode, boolean ignoreError)
      Evaluates a parsed conditional expression within the render thread context.

      This is used for conditional breakpoints: before suspending execution, the condition must be evaluated safely inside the render thread.

      Calling evaluateConditionInRenderThread() from a suspended state ensures the evaluation is scheduled on the render thread asynchronously (via RemoteThread.evaluateInRenderThread(java.util.concurrent.Callable)), avoiding deadlocks or premature resumption.

      Parameters:
      ifNode - the parsed TemplateNode representing the condition
      ignoreError - whether to ignore evaluation errors and return false
      Returns:
      a future resolving to true or false

    • evaluateCondition

      public CompletableFuture<Object> evaluateCondition(io.quarkus.qute.TemplateNode ifNode, boolean ignoreError)
      Evaluates the given Qute if node in the current context.

      This method converts the Qute TemplateNode result into a boolean value. If evaluation fails and ignoreError is true, it returns false instead of throwing an exception.

      This method runs synchronously inside the render thread. It is typically called by evaluateConditionInRenderThread(TemplateNode, boolean).

    • getEngine

      public io.quarkus.qute.Engine getEngine()
      Returns:
      the current Qute engine

    • getEvent

      public io.quarkus.qute.trace.ResolveEvent getEvent()
      Returns:
      the current ResolveEvent associated with this frame

    • createEvalContext

      public io.quarkus.qute.EvalContext createEvalContext(Object base)
      Creates a new EvalContext for the given base object.