Interface EventRequestManager

All Superinterfaces:
Mirror
public interface EventRequestManager extends Mirror
Manages the creation and deletion of EventRequests. A single implementor of this interface exists in a particular VM and is accessed through VirtualMachine.eventRequestManager()
Since:
1.3
See Also:

  • Method Details Link icon

    • createClassPrepareRequest Link icon

      ClassPrepareRequest createClassPrepareRequest()
      Creates a new disabled ClassPrepareRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.
      Returns:
      the created ClassPrepareRequest

    • createClassUnloadRequest Link icon

      ClassUnloadRequest createClassUnloadRequest()
      Creates a new disabled ClassUnloadRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.
      Returns:
      the created ClassUnloadRequest

    • createThreadStartRequest Link icon

      ThreadStartRequest createThreadStartRequest()
      Creates a new disabled ThreadStartRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.
      Returns:
      the created ThreadStartRequest

    • createThreadDeathRequest Link icon

      ThreadDeathRequest createThreadDeathRequest()
      Creates a new disabled ThreadDeathRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.
      Returns:
      the created ThreadDeathRequest

    • createExceptionRequest Link icon

      ExceptionRequest createExceptionRequest(ReferenceType refType, boolean notifyCaught, boolean notifyUncaught)
      Creates a new disabled ExceptionRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

      A specific exception type and its subclasses can be selected for exception events. Caught exceptions, uncaught exceptions, or both can be selected. Note, however, that at the time an exception is thrown, it is not always possible to determine whether it is truly caught. See ExceptionEvent.catchLocation() for details.

      Parameters:
      refType - If non-null, specifies that exceptions which are instances of refType will be reported. Note: this will include instances of sub-types. If null, all instances will be reported
      notifyCaught - If true, caught exceptions will be reported.
      notifyUncaught - If true, uncaught exceptions will be reported.
      Returns:
      the created ExceptionRequest

    • createMethodEntryRequest Link icon

      MethodEntryRequest createMethodEntryRequest()
      Creates a new disabled MethodEntryRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.
      Returns:
      the created MethodEntryRequest

    • createMethodExitRequest Link icon

      MethodExitRequest createMethodExitRequest()
      Creates a new disabled MethodExitRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.
      Returns:
      the created MethodExitRequest

    • createMonitorContendedEnterRequest Link icon

      MonitorContendedEnterRequest createMonitorContendedEnterRequest()
      Creates a new disabled MonitorContendedEnterRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request. Not all target virtual machines support this operation. Use VirtualMachine.canRequestMonitorEvents() to determine if the operation is supported.
      Returns:
      the created MonitorContendedEnterRequest
      Throws:
      UnsupportedOperationException - if the target VM does not support this operation.
      Since:
      1.6

    • createMonitorContendedEnteredRequest Link icon

      MonitorContendedEnteredRequest createMonitorContendedEnteredRequest()
      Creates a new disabled MonitorContendedEnteredRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request. Not all target virtual machines support this operation. Use VirtualMachine.canRequestMonitorEvents() to determine if the operation is supported.
      Returns:
      the created MonitorContendedEnteredRequest
      Throws:
      UnsupportedOperationException - if the target VM does not support this operation.
      Since:
      1.6

    • createMonitorWaitRequest Link icon

      MonitorWaitRequest createMonitorWaitRequest()
      Creates a new disabled MonitorWaitRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request. Not all target virtual machines support this operation. Use VirtualMachine.canRequestMonitorEvents() to determine if the operation is supported.
      Returns:
      the created MonitorWaitRequest
      Throws:
      UnsupportedOperationException - if the target VM does not support this operation.
      Since:
      1.6

    • createMonitorWaitedRequest Link icon

      MonitorWaitedRequest createMonitorWaitedRequest()
      Creates a new disabled MonitorWaitedRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request. Not all target virtual machines support this operation. Use VirtualMachine.canRequestMonitorEvents() to determine if the operation is supported.
      Returns:
      the created MonitorWaitedRequest
      Throws:
      UnsupportedOperationException - if the target VM does not support this operation.
      Since:
      1.6

    • createStepRequest Link icon

      StepRequest createStepRequest(ThreadReference thread, int size, int depth)
      Creates a new disabled StepRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

      The returned request will control stepping only in the specified thread; all other threads will be unaffected. A size value of StepRequest.STEP_MIN will generate a step event each time the code index changes. It represents the smallest step size available and often maps to the instruction level. A size value of StepRequest.STEP_LINE will generate a step event each time the source line changes unless line number information is not available, in which case a STEP_MIN will be done instead. For example, no line number information is available during the execution of a method that has been rendered obsolete by by a VirtualMachine.redefineClasses(Map) operation. A depth value of StepRequest.STEP_INTO will generate step events in any called methods. A depth value of StepRequest.STEP_OVER restricts step events to the current frame or caller frames. A depth value of StepRequest.STEP_OUT restricts step events to caller frames only. All depth restrictions are relative to the call stack immediately before the step takes place.

      Only one pending step request is allowed per thread.

      Note that a typical debugger will want to cancel stepping after the first step is detected. Thus a next line method would do the following: 

      
    EventRequestManager mgr = myVM.{@link VirtualMachine#eventRequestManager eventRequestManager}();
    StepRequest request = mgr.createStepRequest(myThread,
                                                StepRequest.{@link StepRequest#STEP_LINE STEP_LINE},
                                                StepRequest.{@link StepRequest#STEP_OVER STEP_OVER});
    request.{@link EventRequest#addCountFilter addCountFilter}(1);  // next step only
    request.enable();
    myVM.{@link VirtualMachine#resume resume}();
      Parameters:
      thread - the thread in which to step
      size - the step size
      depth - the step depth
      Returns:
      the created StepRequest
      Throws:
      DuplicateRequestException - if there is already a pending step request for the specified thread.
      IllegalArgumentException - if the size or depth arguments contain illegal values.

    • createBreakpointRequest Link icon

      BreakpointRequest createBreakpointRequest(Location location)
      Creates a new disabled BreakpointRequest. The given Location must have a valid (that is, non-negative) code index. The new breakpoint is added to the list managed by this EventRequestManager. Multiple breakpoints at the same location are permitted. Use EventRequest.enable() to activate this event request.
      Parameters:
      location - the location of the new breakpoint.
      Returns:
      the created BreakpointRequest
      Throws:
      NativeMethodException - if location is within a native method.

    • createAccessWatchpointRequest Link icon

      AccessWatchpointRequest createAccessWatchpointRequest(Field field)
      Creates a new disabled watchpoint which watches accesses to the specified field. The new watchpoint is added to the list managed by this EventRequestManager. Multiple watchpoints on the same field are permitted. Use EventRequest.enable() to activate this event request.

      Not all target virtual machines support this operation. Use VirtualMachine.canWatchFieldAccess() to determine if the operation is supported.

      Parameters:
      field - the field to watch
      Returns:
      the created watchpoint
      Throws:
      UnsupportedOperationException - if the target virtual machine does not support this operation.

    • createModificationWatchpointRequest Link icon

      ModificationWatchpointRequest createModificationWatchpointRequest(Field field)
      Creates a new disabled watchpoint which watches accesses to the specified field. The new watchpoint is added to the list managed by this EventRequestManager. Multiple watchpoints on the same field are permitted. Use EventRequest.enable() to activate this event request.

      Not all target virtual machines support this operation. Use VirtualMachine.canWatchFieldModification() to determine if the operation is supported.

      Parameters:
      field - the field to watch
      Returns:
      the created watchpoint
      Throws:
      UnsupportedOperationException - if the target virtual machine does not support this operation.

    • createVMDeathRequest Link icon

      VMDeathRequest createVMDeathRequest()
      Creates a new disabled VMDeathRequest. The new request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

      This request (if enabled) will cause a VMDeathEvent to be sent on termination of the target VM.

      A VMDeathRequest with a suspend policy of SUSPEND_ALL can be used to assure processing of incoming SUSPEND_NONE or SUSPEND_EVENT_THREAD events before VM death. If all event processing is being done in the same thread as event sets are being read, enabling the request is all that is needed since the VM will be suspended until the EventSet containing the VMDeathEvent is resumed.

      Not all target virtual machines support this operation. Use VirtualMachine.canRequestVMDeathEvent() to determine if the operation is supported.

      Returns:
      the created request
      Throws:
      UnsupportedOperationException - if the target VM does not support this operation.
      Since:
      1.4

    • deleteEventRequest Link icon

      void deleteEventRequest(EventRequest eventRequest)
      Removes an eventRequest. The eventRequest is disabled and the removed from the requests managed by this EventRequestManager. Once the eventRequest is deleted, no operations (for example, EventRequest.setEnabled(boolean)) are permitted - attempts to do so will generally cause an InvalidRequestStateException. No other eventRequests are effected.

      Because this method changes the underlying lists of event requests, attempting to directly delete from a list returned by a request accessor (e.g. below): 

        Iterator iter = requestManager.stepRequests().iterator();
  while (iter.hasNext()) {
     requestManager.deleteEventRequest(iter.next());
 }
      may cause a ConcurrentModificationException. Instead use deleteEventRequests(List) or copy the list before iterating.
      Parameters:
      eventRequest - the eventRequest to remove

    • deleteEventRequests Link icon

      void deleteEventRequests(List<? extends EventRequest> eventRequests)
      Removes a list of EventRequests.
      Parameters:
      eventRequests - the list of eventRequests to remove
      See Also:

    • deleteAllBreakpoints Link icon

      void deleteAllBreakpoints()
      Remove all breakpoints managed by this EventRequestManager.
      See Also:

    • stepRequests Link icon

      List<StepRequest> stepRequests()
      Return an unmodifiable list of the enabled and disabled step requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the all StepRequest objects.

    • classPrepareRequests Link icon

      List<ClassPrepareRequest> classPrepareRequests()
      Return an unmodifiable list of the enabled and disabled class prepare requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the all ClassPrepareRequest objects.

    • classUnloadRequests Link icon

      List<ClassUnloadRequest> classUnloadRequests()
      Return an unmodifiable list of the enabled and disabled class unload requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the all ClassUnloadRequest objects.

    • threadStartRequests Link icon

      List<ThreadStartRequest> threadStartRequests()
      Return an unmodifiable list of the enabled and disabled thread start requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the all ThreadStartRequest objects.

    • threadDeathRequests Link icon

      List<ThreadDeathRequest> threadDeathRequests()
      Return an unmodifiable list of the enabled and disabled thread death requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the all ThreadDeathRequest objects.

    • exceptionRequests Link icon

      List<ExceptionRequest> exceptionRequests()
      Return an unmodifiable list of the enabled and disabled exception requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the all ExceptionRequest objects.

    • breakpointRequests Link icon

      List<BreakpointRequest> breakpointRequests()
      Return an unmodifiable list of the enabled and disabled breakpoint requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the list of all BreakpointRequest objects.

    • accessWatchpointRequests Link icon

      List<AccessWatchpointRequest> accessWatchpointRequests()
      Return an unmodifiable list of the enabled and disabled access watchpoint requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the all AccessWatchpointRequest objects.

    • modificationWatchpointRequests Link icon

      List<ModificationWatchpointRequest> modificationWatchpointRequests()
      Return an unmodifiable list of the enabled and disabled modification watchpoint requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the all ModificationWatchpointRequest objects.

    • methodEntryRequests Link icon

      List<MethodEntryRequest> methodEntryRequests()
      Return an unmodifiable list of the enabled and disabled method entry requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the list of all MethodEntryRequest objects.

    • methodExitRequests Link icon

      List<MethodExitRequest> methodExitRequests()
      Return an unmodifiable list of the enabled and disabled method exit requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the list of all MethodExitRequest objects.

    • monitorContendedEnterRequests Link icon

      List<MonitorContendedEnterRequest> monitorContendedEnterRequests()
      Return an unmodifiable list of the enabled and disabled monitor contended enter requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the list of all MonitorContendedEnterRequest objects.
      Since:
      1.6

    • monitorContendedEnteredRequests Link icon

      List<MonitorContendedEnteredRequest> monitorContendedEnteredRequests()
      Return an unmodifiable list of the enabled and disabled monitor contended entered requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the list of all MonitorContendedEnteredRequest objects.
      Since:
      1.6

    • monitorWaitRequests Link icon

      List<MonitorWaitRequest> monitorWaitRequests()
      Return an unmodifiable list of the enabled and disabled monitor wait requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the list of all MonitorWaitRequest objects.
      Since:
      1.6

    • monitorWaitedRequests Link icon

      List<MonitorWaitedRequest> monitorWaitedRequests()
      Return an unmodifiable list of the enabled and disabled monitor waited requests. This list is a live view of these requests and thus changes as requests are added and deleted.
      Returns:
      the list of all MonitorWaitedRequest objects.
      Since:
      1.6

    • vmDeathRequests Link icon

      List<VMDeathRequest> vmDeathRequests()
      Return an unmodifiable list of the enabled and disabled VM death requests. This list is a live view of these requests and thus changes as requests are added and deleted. Note: the unsolicited VMDeathEvent does not have a corresponding request.
      Returns:
      the list of all VMDeathRequest objects.
      Since:
      1.4