Using Extra Arguments for Requests


Overview

With both profiles and the low-level API, you are able to provide extra arguments in the form of JDIArgument or one of its derivatives: JDIRequestArgument or JDIEventArgument. The extra arguments are used to set additional configuration options on requests as well as provide additional filtering and logic when receiving events.

Methods like getOrCreateBreakpointRequest accept a variable number of extra arguments at the end of the method (defaulting to no extra arguments).

val s: ScalaVirtualMachine = /* some virtual machine */

// Set a custom property accessible on the request object AND limit reporting
// to the first three occurrences
s.getOrCreateBreakpointRequest(
  "file.scala", 
  37, 
  CustomProperty("key", "value"), 
  MaxTriggerFilter(3)
)

How It Works

JDI Event Process Steps

  1. Callbacks in the form of event handlers and event pipelines are retrieved for requests that correspond to the incoming JDI event
  2. Filters are applied on the event to determine if it is relevant to the callbacks
  3. Custom data stored on the request and the event are extracted to be returned to the callbacks when provided event data request arguments
  4. Callbacks that passed their associated filters are invoked with any extracted data alongside the actual JDI event
  5. The associated threads are resumed after all callbacks have finished, unless NoResume or another special event argument is provided

Request Arguments

JDIRequestArgument instances come in two flavors: JDIRequestProperty and JDIRequestFilter.

Properties are used to configure information about a request such as its suspension level.

Filters are used to narrow down what a request reports. In the case of a breakpoint request, you might limit the thread where the breakpoint can occur or the specific instance of a class that can trigger the event.

Request Properties

Case ClassDescription
EnabledPropertySets whether or not the request is enabled.
SuspendPolicyPropertySets the suspend policy of the request.
CustomPropertyAdds a key/value pair to the request that can be referenced when receiving events for that request.
UniqueIdPropertyAdds a unique id to the request via a custom property.

Request Filters

Case ClassDescription
ClassExclusionFilterLimits reporting of events to only classes not specified by this filter.
ClassInclusionFilterLimits reporting of events to only classes specified by this filter.
ClassReferenceFilterSimilar to ClassInclusionFilter, but takes a JDI ReferenceType instead of a string name.
CountFilterLimits reporting to only occur after N-1 occurrences of the event. Furthermore, the event is only reported once.
InstanceFilterLimits reporting of events to a specific instance of a class.
SourceNameFilterLimits reporting of events to classes whose source name matches the specified pattern.
ThreadFilterLimits reporting of events to the specific thread.

Event Arguments

JDIEventArgument instances come in two flavors: JDIEventDataRequest and JDIEventFilter.

Data requests are used to collect information from an event and its associated request and include it in callbacks and pipelines that expect event data.

Filters are used to narrow down which events trigger callbacks and get fed to pipelines. Common use cases include filtering based on a provided unique id or custom property to a request (as the associated request is available in an event).

There are also a couple of event arguments that directly extend JDIEventArgument and are used for special purposes.

Event Data Request

Case ClassDescription
CustomPropertyDataRequestRetrieves a custom property from the request associated with the event.

Event Filter

Case ClassDescription
MaxTriggerFilterLimits triggering of event callbacks and pipelines to the first N events.
MinTriggerFilterLimits triggering of event callbacks and pipelines to all but the first N events.
MethodNameFilterLimits triggering of event callbacks and pipelines if they are locatable to only those whose method name matches.
CustomPropertyFilterLimits triggering of event callbacks and pipelines to events whose requests contain a matching custom property.
UniqueIdPropertyFilterLimits triggering of event callbacks and pipelines to events whose requests contain a matching unique id.
WildcardPatternFilterLimits triggering of event callbacks and pipelines to events whose method or class name matches the given wildcard.
Case ClassDescription
AndFilterCombines the truthiness of two other filters such that BOTH must allow the event.
OrFilterCombines the truthiness of two other filters such that EITHER must allow the event.
NotFilterFlips a filter such that an event is allowed only if the filter disallows the event.

Miscellaneous Event Arguments

Case ClassDescription
NoResumeIf provided, does not resume the JVM after the event is processed.
YesResumeIf provided, does resume the JVM after the event is processed. This is the default.