OpenJDK 27 · com.sun.jdi.request.EventRequest · APIdia, the JavaDoc alternative

Represents a request for notification of an event. Examples include BreakpointRequest and ExceptionRequest. When an event occurs for which an enabled request is present, an EventSet will be placed on the EventQueue. The collection of existing event requests is managed by the EventRequestManager.

The number of events generated for an event request can be controlled through filters. Filters provide additional constraints that an event must satisfy before it is placed on the event queue. Multiple filters can be used by making multiple calls to filter addition methods such as ExceptionRequest#addClassFilter(java.lang.String classPattern). Filters are added to an event one at a time only while the event is disabled. Multiple filters are applied with CUT-OFF AND, in the order it was added to the request. Only events that satisfy all filters are placed in the event queue.

The set of available filters is dependent on the event request, some examples of filters are:

Thread filters allow control over the thread for which events are generated.
Class filters allow control over the class in which the event occurs.
Instance filters allow control over the instance in which the event occurs.
Count filters allow control over the number of times an event is reported.

Filters can dramatically improve debugger performance by reducing the amount of event traffic sent from the target VM to the debugger VM.

Any method on EventRequest which takes EventRequest as an parameter may throw VMDisconnectedException if the target VM is disconnected and the VMDisconnectEvent has been or is available to be read from the EventQueue.

Any method on EventRequest which takes EventRequest as an parameter may throw VMOutOfMemoryException if the target VM has run out of memory.

Field Summary

Modifier and Type	Field and Description
public static final int	SUSPEND_ALL Suspend all threads when the event occurs
public static final int	SUSPEND_EVENT_THREAD Suspend only the thread which generated the event when the event occurs
public static final int	SUSPEND_NONE Suspend no threads when the event occurs

Method Summary

Modifier and Type	Method and Description
public void	addCountFilter(int the number of occurrences before generating an event. count) Limit the requested event to be reported at most once after a given number of occurrences.
public void	disable() Same as `setEnabled(false)`.
public void	enable() Same as `setEnabled(true)`.
public Object	Returns: the value of this property or null getProperty(Object key) Returns the value of the property with the specified key.
public boolean	Returns: `true` if enabled; `false` otherwise. isEnabled() Determines if this event request is currently enabled.
public void	putProperty(Object key, Object value) Add an arbitrary key/value "property" to this request.
public void	setEnabled(boolean `true` if the event request is to be enabled; `false` otherwise. val) Enables or disables this event request.
public void	setSuspendPolicy(int the selected suspend policy. policy) Determines the threads to suspend when the requested event occurs in the target VM.
public int	Returns: the current suspend mode for this request suspendPolicy() Returns a value which describes the threads to suspend when the requested event occurs in the target VM.

Inherited from com.sun.jdi.Mirror:: toString virtualMachine

Field Detail

SUSPEND_ALL	back to summary
public static final int SUSPEND_ALL Suspend all threads when the event occurs

SUSPEND_EVENT_THREAD	back to summary
public static final int SUSPEND_EVENT_THREAD Suspend only the thread which generated the event when the event occurs

SUSPEND_NONE	back to summary
public static final int SUSPEND_NONE Suspend no threads when the event occurs

Method Detail

addCountFilter back to summary

addCountFilter	back to summary
public void addCountFilter(int count) Limit the requested event to be reported at most once after a given number of occurrences. The event is not reported the first `count - 1` times this filter is reached. To request a one-off event, call this method with a count of 1. Once the count reaches 0, any subsequent filters in this request are applied. If none of those filters cause the event to be suppressed, the event is reported. Otherwise, the event is not reported. In either case subsequent events are never reported for this request. Parameters count:int the number of occurrences before generating an event. Exceptions InvalidRequestStateException: if this request is currently enabled or has been deleted. Filters may be added only to disabled requests. IllegalArgumentException: if `count` is less than one.

public void addCountFilter(int count)

Limit the requested event to be reported at most once after a given number of occurrences. The event is not reported the first count - 1 times this filter is reached. To request a one-off event, call this method with a count of 1.

Once the count reaches 0, any subsequent filters in this request are applied. If none of those filters cause the event to be suppressed, the event is reported. Otherwise, the event is not reported. In either case subsequent events are never reported for this request.

Parameters

count:int: the number of occurrences before generating an event.

Exceptions

InvalidRequestStateException:: if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
IllegalArgumentException:: if count is less than one.

disable back to summary

disable	back to summary
public void disable() Same as `setEnabled(false)`. Exceptions InvalidRequestStateException: if this request has been deleted.

public void disable()

Same as setEnabled(false).

Exceptions

InvalidRequestStateException:: if this request has been deleted.

enable back to summary

enable	back to summary
public void enable() Same as `setEnabled(true)`. Exceptions InvalidRequestStateException: if this request has been deleted. IllegalThreadStateException: if this is a StepRequest and the thread named in the request has died or is not yet started.

public void enable()

Same as setEnabled(true).

Exceptions

InvalidRequestStateException:: if this request has been deleted.
IllegalThreadStateException:: if this is a StepRequest and the thread named in the request has died or is not yet started.

getProperty back to summary

getProperty	back to summary
public Object getProperty(Object key) Returns the value of the property with the specified key. Only properties added with `putProperty` will return a non-null value. Returns:Object the value of this property or null See Also `putProperty`

public Object getProperty(Object key)

Returns the value of the property with the specified key. Only properties added with putProperty will return a non-null value.

Returns:Object: the value of this property or null
See Also: putProperty

isEnabled back to summary

isEnabled	back to summary
public boolean isEnabled() Determines if this event request is currently enabled. Returns:boolean `true` if enabled; `false` otherwise.

public boolean isEnabled()

Determines if this event request is currently enabled.

Returns:boolean: true if enabled; false otherwise.

putProperty back to summary

putProperty	back to summary
public void putProperty(Object key, Object value) Add an arbitrary key/value "property" to this request. The property can be used by a client of the JDI to associate application information with the request; These client-set properties are not used internally by the JDI. The `get/putProperty` methods provide access to a small per-instance map. This is not to be confused with `java.util.Properties`. If value is null this method will remove the property. See Also `getProperty`

public void putProperty(Object key, Object value)

Add an arbitrary key/value "property" to this request. The property can be used by a client of the JDI to associate application information with the request; These client-set properties are not used internally by the JDI.

The get/putProperty methods provide access to a small per-instance map. This is not to be confused with java.util.Properties.

If value is null this method will remove the property.

See Also: getProperty

setEnabled back to summary

setEnabled	back to summary
public void setEnabled(boolean val) Enables or disables this event request. While this event request is disabled, the event request will be ignored and the target VM will not be stopped if any of its threads reaches the event request. Disabled event requests still exist, and are included in event request lists such as `EventRequestManager#breakpointRequests()`. Parameters val:boolean `true` if the event request is to be enabled; `false` otherwise. Exceptions InvalidRequestStateException: if this request has been deleted. IllegalThreadStateException: if this is a StepRequest, `val` is `true`, and the thread named in the request has died or is not yet started.

public void setEnabled(boolean val)

Enables or disables this event request. While this event request is disabled, the event request will be ignored and the target VM will not be stopped if any of its threads reaches the event request. Disabled event requests still exist, and are included in event request lists such as EventRequestManager#breakpointRequests().

Parameters

val:boolean: true if the event request is to be enabled; false otherwise.

Exceptions

InvalidRequestStateException:: if this request has been deleted.
IllegalThreadStateException:: if this is a StepRequest, val is true, and the thread named in the request has died or is not yet started.

setSuspendPolicy back to summary

setSuspendPolicy	back to summary
public void setSuspendPolicy(int policy) Determines the threads to suspend when the requested event occurs in the target VM. Use `SUSPEND_ALL` to suspend all threads in the target VM (the default). Use `SUSPEND_EVENT_THREAD` to suspend only the thread which generated the event. Use `SUSPEND_NONE` to suspend no threads. Thread suspensions through events have the same functionality as explicitly requested suspensions. See `ThreadReference#suspend` and `VirtualMachine#suspend` for details. Parameters policy:int the selected suspend policy. Exceptions InvalidRequestStateException: if this request is currently enabled or has been deleted. Suspend policy may only be set in disabled requests. IllegalArgumentException: if the policy argument contains an illegal value.

public void setSuspendPolicy(int policy)

Determines the threads to suspend when the requested event occurs in the target VM. Use SUSPEND_ALL to suspend all threads in the target VM (the default). Use SUSPEND_EVENT_THREAD to suspend only the thread which generated the event. Use SUSPEND_NONE to suspend no threads.

Thread suspensions through events have the same functionality as explicitly requested suspensions. See ThreadReference#suspend and VirtualMachine#suspend for details.

Parameters

policy:int: the selected suspend policy.

Exceptions

InvalidRequestStateException:: if this request is currently enabled or has been deleted. Suspend policy may only be set in disabled requests.
IllegalArgumentException:: if the policy argument contains an illegal value.

suspendPolicy back to summary

suspendPolicy	back to summary
public int suspendPolicy() Returns a value which describes the threads to suspend when the requested event occurs in the target VM. The returned value is `SUSPEND_ALL`, `SUSPEND_EVENT_THREAD`, or `SUSPEND_NONE`. Returns:int the current suspend mode for this request

public int suspendPolicy()

Returns a value which describes the threads to suspend when the requested event occurs in the target VM. The returned value is SUSPEND_ALL, SUSPEND_EVENT_THREAD, or SUSPEND_NONE.

Returns:int: the current suspend mode for this request

public Interface EventRequest

Field Summary

Method Summary

Field Detail

Method Detail