com.caoccao.javet.interop

Class V8Inspector

java.lang.Object

com.caoccao.javet.interop.V8Inspector

All Implemented Interfaces:

IJavetClosable, java.lang.AutoCloseable

public final class V8Inspector
extends java.lang.Object
implements IJavetClosable

Represents an inspector session connected to a V8 runtime.

Each V8Inspector instance maps to a separate V8 inspector session with its own CDP channel. Multiple sessions can be created on the same V8Runtime, allowing multiple DevTools clients to connect simultaneously.

Use V8Runtime.createV8Inspector(String) to create sessions. Multiple sessions can be created on the same runtime. Sessions implement IJavetClosable so they can be explicitly disconnected when no longer needed.

Since:

0.7.3

Method Summary

Modifier and Type	Method and Description
void	addListeners(IV8InspectorListener... listeners) Adds one or more inspector listeners to receive CDP notifications and responses.
void	breakProgram(java.lang.String breakReason, java.lang.String breakDetails) Forces the V8 runtime to break (pause) immediately, as if a breakpoint were hit.
void	cancelPauseOnNextStatement() Cancels a previously scheduled pause on the next statement.
void	close() Closes this inspector session, disconnecting it from the V8 runtime.
void	consoleAPIMessage(int contextGroupId, int level, java.lang.String message, java.lang.String url, int lineNumber, int columnNumber) Called by V8 when a console API message is produced.
<T extends V8Value> T	evaluate(java.lang.String expression, boolean includeCommandLineAPI) Evaluates a JavaScript expression directly through the inspector session, bypassing CDP JSON serialization.
void	flushProtocolNotifications() Called by V8 to flush any queued protocol notifications.
IJavetLogger	getLogger() Gets the logger used by this inspector session.
java.lang.String	getName() Gets the name of this inspector session.
int	getSessionId() Gets the native session ID for this inspector session.
void	installAdditionalCommandLineAPI(IV8ValueObject commandLineAPI) Called by V8 to install additional command-line API objects.
boolean	isClosed() Returns whether this session has been closed.
void	receiveNotification(java.lang.String message) Called by V8 when a CDP notification is received.
void	receiveResponse(java.lang.String message) Called by V8 when a CDP response is received.
void	removeListeners(IV8InspectorListener... listeners) Removes one or more previously added inspector listeners.
void	runIfWaitingForDebugger(int contextGroupId) Called by V8 when the runtime is waiting for a debugger connection.
void	schedulePauseOnNextStatement(java.lang.String breakReason, java.lang.String breakDetails) Schedules a pause (breakpoint) on the next JavaScript statement that executes.
void	sendRequest(java.lang.String message) Sends a CDP request message to the V8 inspector.
void	setLogger(IJavetLogger logger) Sets the logger used by this inspector session.
void	setSkipAllPauses(boolean skip) Tells V8 to skip all breakpoints (pauses) for this session.
void	waitForDebugger() Blocks the calling thread until all connected sessions have sent Runtime.runIfWaitingForDebugger.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addListeners

public void addListeners(IV8InspectorListener... listeners)

Adds one or more inspector listeners to receive CDP notifications and responses.

Parameters:

listeners - the listeners to add

breakProgram

public void breakProgram(java.lang.String breakReason,
                         java.lang.String breakDetails)

Forces the V8 runtime to break (pause) immediately, as if a breakpoint were hit. This triggers a Debugger.paused notification with the specified break reason.

Unlike schedulePauseOnNextStatement(String, String), this method breaks immediately rather than waiting for the next JavaScript statement to execute.

The caller must hold the V8 isolate lock (e.g., call from a thread that is currently executing JavaScript).

Parameters:

breakReason - a short reason string (e.g., "embedder-requested")

breakDetails - additional JSON details (can be empty)

Since:

5.0.5

close

public void close()
           throws JavetException

Closes this inspector session, disconnecting it from the V8 runtime. After closing, calls to sendRequest(String) are silently ignored. Other sessions on the same runtime are not affected.

Specified by:

close in interface IJavetClosable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

JavetException

Since:

5.0.5

cancelPauseOnNextStatement

public void cancelPauseOnNextStatement()

Cancels a previously scheduled pause on the next statement.

Since:

5.0.5

See Also:

schedulePauseOnNextStatement(String, String)

consoleAPIMessage

public void consoleAPIMessage(int contextGroupId,
                              int level,
                              java.lang.String message,
                              java.lang.String url,
                              int lineNumber,
                              int columnNumber)

Called by V8 when a console API message is produced. Dispatches to all registered listeners.

Parameters:

contextGroupId - the context group ID

level - the message severity level

message - the console message text

url - the source URL

lineNumber - the source line number

columnNumber - the source column number

evaluate

public <T extends V8Value> T evaluate(java.lang.String expression,
                                      boolean includeCommandLineAPI)

Evaluates a JavaScript expression directly through the inspector session, bypassing CDP JSON serialization. This returns the raw V8 value, which is faster than using Runtime.evaluate via sendRequest(String).

The caller must hold the V8 isolate lock. The returned value is a Javet V8 value that must be closed when no longer needed (if it is a reference type).

Type Parameters:

T - the expected V8 value type

Parameters:

expression - the JavaScript expression to evaluate

includeCommandLineAPI - whether to include the command-line API scope

Returns:

the evaluation result as a V8 value, or null if the session is closed, the expression could not be run, or the result is empty

Since:

5.0.5

flushProtocolNotifications

public void flushProtocolNotifications()

Called by V8 to flush any queued protocol notifications. Dispatches to all registered listeners.

installAdditionalCommandLineAPI

public void installAdditionalCommandLineAPI(IV8ValueObject commandLineAPI)

Called by V8 to install additional command-line API objects. Dispatches to all registered listeners.

Parameters:

commandLineAPI - the command-line API object provided by V8

getLogger

public IJavetLogger getLogger()

Gets the logger used by this inspector session.

Returns:

the logger

getName

public java.lang.String getName()

Gets the name of this inspector session.

Returns:

the session name

getSessionId

public int getSessionId()

Gets the native session ID for this inspector session.

Returns:

the session ID

Since:

5.0.5

isClosed

public boolean isClosed()

Returns whether this session has been closed.

Specified by:

isClosed in interface IJavetClosable

Returns:

true if closed

Since:

5.0.5

receiveNotification

public void receiveNotification(java.lang.String message)

Called by V8 when a CDP notification is received. Dispatches to all registered listeners.

Parameters:

message - the CDP notification JSON message

receiveResponse

public void receiveResponse(java.lang.String message)

Called by V8 when a CDP response is received. Dispatches to all registered listeners.

Parameters:

message - the CDP response JSON message

removeListeners

public void removeListeners(IV8InspectorListener... listeners)

Removes one or more previously added inspector listeners.

Parameters:

listeners - the listeners to remove

runIfWaitingForDebugger

public void runIfWaitingForDebugger(int contextGroupId)

Called by V8 when the runtime is waiting for a debugger connection. Dispatches to all registered listeners.

Parameters:

contextGroupId - the context group ID

schedulePauseOnNextStatement

public void schedulePauseOnNextStatement(java.lang.String breakReason,
                                         java.lang.String breakDetails)

Schedules a pause (breakpoint) on the next JavaScript statement that executes. The pause happens asynchronously — the next time V8 is about to execute a statement, it will trigger a Debugger.paused notification with the specified reason.

This is useful for programmatic "break on next" functionality without needing to set a breakpoint at a specific source location.

Call cancelPauseOnNextStatement() to revoke a scheduled pause before it fires.

Parameters:

breakReason - a short reason string (e.g., "ambiguous")

breakDetails - additional JSON details (can be empty)

Since:

5.0.5

sendRequest

public void sendRequest(java.lang.String message)
                 throws JavetException

Sends a CDP request message to the V8 inspector. Notifies listeners and dispatches the message.

Parameters:

message - the CDP request JSON message

Throws:

JavetException - the javet exception

setLogger

public void setLogger(IJavetLogger logger)

Sets the logger used by this inspector session.

Parameters:

logger - the logger

setSkipAllPauses

public void setSkipAllPauses(boolean skip)

Tells V8 to skip all breakpoints (pauses) for this session. This is useful for temporarily disabling debugging without removing breakpoints. Call setSkipAllPauses(false) to re-enable pausing.

Parameters:

skip - true to skip all pauses, false to re-enable

Since:

5.0.5

waitForDebugger

public void waitForDebugger()

Blocks the calling thread until all connected sessions have sent Runtime.runIfWaitingForDebugger. This method must be called from a thread that does not already hold the V8 isolate lock (typically an execution thread, before running any JavaScript).

The inspector must have been created with waitForDebugger = true (via V8Runtime.createV8Inspector(String, boolean)) for this to work. When called, the method acquires the V8 lock and enters a message-pumping loop, dispatching any incoming CDP messages while waiting. Once V8 invokes the runIfWaitingForDebugger callback, the loop exits and this method returns, allowing the thread to proceed with script execution.

Since:

5.0.5