public final class ExecutionListener extends Object implements AutoCloseable
The following example prints the characters of every executed statement of simple JavaScript
loop.
Prints the following result:
Context context = Context.create("js");
ExecutionListeners listener = ExecutionListeners.newBuilder()
.onEnter((e) -> System.out.println(
e.getLocation().getCharacters()))
.statements(true)
.attach(context.getEngine());
context.eval("js", "for (var i = 0; i < 2; i++);");
listener.close();
i = 0 i < 2 i++ i < 2 i++ i < 2
ExecutionListener.newBuilder()
. At least
one event consumer and one filtered source element needs to be enabled. To complete the listener
attachment ExecutionListener.Builder.attach(Engine)
needs to be invoked. Attach
may be invoked multiple times for one builder.
All execution listeners are automatically closed when the engine closed
.
To close a listener earlier ExecutionListener.close()
may be invoked. Execution listeners are
AutoCloseable
and can therefore be used in try-with-resources blocks.
OnEnter
: An event that is notified when an execution of an
element is entered. This event is consumed before any input values are executed.
OnReturn
: An event that is notified when an execution of
an element was entered and completed.
IllegalArgumentException
will be
thrown by the builder when it is attached
.
Event consumers may throw any Java host exception. Such exceptions will be reported to the
context as PolyglotException
instances. The thrown exception may be accessed using
PolyglotException.asHostException()
.
source location
and
root name
data is available. Other event data will return
null
by default.
The collection of the following event data may be enabled:
Return values
: Enables access to
return values
in OnReturn
events.
Input values
: Enables access to
input values
in OnReturn
events.
Errors
: Enables access to
errors
in OnReturn
events.
Provided event instances may escape the event consumer and remain usable until the engine is closed.
Roots
: Filter for marked program locations that represent a
root of a function, method or closure.
Statements
: Filter for marked program locations that
represent a statement.
Expressions
: Filter for marked program locations that
represent an expression.
IllegalArgumentException
will be thrown by the builder when it is attached
. Not all source
elements may be supported by a language. If the language does not support listening to a source
element then no events will be triggered.
If multiple source elements are enabled, multiple or one event may be reported per source location. If this behavior is not desirable than multiple execution listeners for each source element can be created and attached.
By default the execution listener is applied to all sources
that were loaded. A
source filter
may be attached to limit the number of
sources that will trigger events.
Attaching
and closing
execution listeners are
expensive operations and typically require to traverse through all loaded code. Code that was
previously optimized will be deoptimized in the process. It is most efficient to attach an
execution listener before any code is executed and let execution listeners automatically close
with the engine.
Modifier and Type | Class and Description |
---|---|
class |
ExecutionListener.Builder
A builder used to construct execution events.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes and detaches this execution listener from the engine.
|
static ExecutionListener.Builder |
newBuilder()
Creates a builder that can be used to attach execution listeners.
|
public void close()
Attaching
and closing
execution listeners are
expensive operations and typically require to traverse through all loaded code. Code that was
previously optimized will be deoptimized in the process. It is most efficient to attach an
execution listener before any code is executed and let execution listeners automatically
close with the engine.
close
in interface AutoCloseable
ExecutionListener.Builder.attach(Engine)
public static ExecutionListener.Builder newBuilder()
A minimal example on how to build and attach a listener:
ExecutionListeners listener = ExecutionListeners.newBuilder()
.onEnter((e) -> ...)
.statements(true)
.attach(context.getEngine());
ExecutionListener