/*
* Copyright (c) 1998, 2005, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package com.sun.jdi.request;
import com.sun.jdi.*;
import java.util.List;
/**
* Manages the creation and deletion of {@link EventRequest}s. A single
* implementor of this interface exists in a particuar VM and
* is accessed through {@link VirtualMachine#eventRequestManager()}
*
* @see EventRequest
* @see com.sun.jdi.event.Event
* @see BreakpointRequest
* @see com.sun.jdi.event.BreakpointEvent
* @see VirtualMachine
*
* @author Robert Field
* @since 1.3
*/
public interface EventRequestManager extends Mirror {
/**
* Creates a new disabled {@link ClassPrepareRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* @return the created {@link ClassPrepareRequest}
*/
ClassPrepareRequest createClassPrepareRequest();
/**
* Creates a new disabled {@link ClassUnloadRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* @return the created {@link ClassUnloadRequest}
*/
ClassUnloadRequest createClassUnloadRequest();
/**
* Creates a new disabled {@link ThreadStartRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* @return the created {@link ThreadStartRequest}
*/
ThreadStartRequest createThreadStartRequest();
/**
* Creates a new disabled {@link ThreadDeathRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* @return the created {@link ThreadDeathRequest}
*/
ThreadDeathRequest createThreadDeathRequest();
/**
* Creates a new disabled {@link ExceptionRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
* <P>
* 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
* {@link com.sun.jdi.event.ExceptionEvent#catchLocation} for
* details.
* @param 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
* @param notifyCaught If true, caught exceptions will be reported.
* @param notifyUncaught If true, uncaught exceptions will be reported.
*
* @return the created {@link ExceptionRequest}
*/
ExceptionRequest createExceptionRequest(ReferenceType refType,
boolean notifyCaught,
boolean notifyUncaught);
/**
* Creates a new disabled {@link MethodEntryRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* @return the created {@link MethodEntryRequest}
*/
MethodEntryRequest createMethodEntryRequest();
/**
* Creates a new disabled {@link MethodExitRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* @return the created {@link MethodExitRequest}
*/
MethodExitRequest createMethodExitRequest();
/**
* Creates a new disabled {@link MonitorContendedEnterRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canRequestMonitorEvents()}
* to determine if the operation is supported.
*
* @return the created {@link MonitorContendedEnterRequest}
* @throws java.lang.UnsupportedOperationException if
* the target VM does not support this
* operation.
*
* @since 1.6
*/
MonitorContendedEnterRequest createMonitorContendedEnterRequest();
/**
* Creates a new disabled {@link MonitorContendedEnteredRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canRequestMonitorEvents()}
* to determine if the operation is supported.
*
* @return the created {@link MonitorContendedEnteredRequest}
* @throws java.lang.UnsupportedOperationException if
* the target VM does not support this
* operation.
*
* @since 1.6
*/
MonitorContendedEnteredRequest createMonitorContendedEnteredRequest();
/**
* Creates a new disabled {@link MonitorWaitRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canRequestMonitorEvents()}
* to determine if the operation is supported.
*
* @return the created {@link MonitorWaitRequest}
* @throws java.lang.UnsupportedOperationException if
* the target VM does not support this
* operation.
*
* @since 1.6
*/
MonitorWaitRequest createMonitorWaitRequest();
/**
* Creates a new disabled {@link MonitorWaitedRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
*
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canRequestMonitorEvents()}
* to determine if the operation is supported.
*
* @return the created {@link MonitorWaitedRequest}
* @throws java.lang.UnsupportedOperationException if
* the target VM does not support this
* operation.
*
* @since 1.6
*/
MonitorWaitedRequest createMonitorWaitedRequest();
/**
* Creates a new disabled {@link StepRequest}.
* The new event request is added to the list managed by this
* EventRequestManager. Use {@link EventRequest#enable()} to
* activate this event request.
* <p>
* The returned request will control stepping only in the specified
* <code>thread</code>; all other threads will be unaffected.
* A <code>size</code>value of {@link com.sun.jdi.request.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 <code>size</code> value of {@link com.sun.jdi.request.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 {@link com.sun.jdi.VirtualMachine#redefineClasses} operation.
* A <code>depth</code> value of {@link com.sun.jdi.request.StepRequest#STEP_INTO} will generate
* step events in any called methods. A <code>depth</code> value
* of {@link com.sun.jdi.request.StepRequest#STEP_OVER} restricts step events to the current frame
* or caller frames. A <code>depth</code> value of {@link com.sun.jdi.request.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.
* <p>
* Only one pending step request is allowed per thread.
* <p>
* 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:
* <code>
* <pre>
* 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}();
* </pre>
* </code>
*
* @param thread the thread in which to step
* @param depth the step depth
* @param size the step size
* @return the created {@link StepRequest}
* @throws DuplicateRequestException if there is already a pending
* step request for the specified thread.
* @throws IllegalArgumentException if the size or depth arguments
* contain illegal values.
*/
StepRequest createStepRequest(ThreadReference thread,
int size,
int depth);
/**
* Creates a new disabled {@link BreakpointRequest}.
* The given {@link 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 {@link EventRequest#enable()} to
* activate this event request.
*
* @param location the location of the new breakpoint.
* @return the created {@link BreakpointRequest}
* @throws NativeMethodException if location is within a native method.
*/
BreakpointRequest createBreakpointRequest(Location location);
/**
* 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 {@link EventRequest#enable()} to
* activate this event request.
* <P>
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canWatchFieldAccess()}
* to determine if the operation is supported.
*
* @param field the field to watch
* @return the created watchpoint
* @throws java.lang.UnsupportedOperationException if
* the target virtual machine does not support this
* operation.
*/
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 {@link EventRequest#enable()} to
* activate this event request.
* <P>
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canWatchFieldModification()}
* to determine if the operation is supported.
*
* @param field the field to watch
* @return the created watchpoint
* @throws java.lang.UnsupportedOperationException if
* the target virtual machine does not support this
* operation.
*/
ModificationWatchpointRequest createModificationWatchpointRequest(Field field);
/**
* Creates a new disabled {@link VMDeathRequest}.
* The new request is added to the list managed by this
* EventRequestManager.
* Use {@link EventRequest#enable()} to
* activate this event request.
* <P>
* This request (if enabled) will cause a
* {@link com.sun.jdi.event.VMDeathEvent}
* to be sent on termination of the target VM.
* <P>
* A VMDeathRequest with a suspend policy of
* {@link EventRequest#SUSPEND_ALL SUSPEND_ALL}
* can be used to assure processing of incoming
* {@link EventRequest#SUSPEND_NONE SUSPEND_NONE} or
* {@link EventRequest#SUSPEND_EVENT_THREAD 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 {@link com.sun.jdi.event.EventSet}
* containing the {@link com.sun.jdi.event.VMDeathEvent}
* is resumed.
* <P>
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canRequestVMDeathEvent()}
* to determine if the operation is supported.
*
* @return the created request
* @throws java.lang.UnsupportedOperationException if
* the target VM does not support this
* operation.
*
* @since 1.4
*/
VMDeathRequest createVMDeathRequest();
/**
* 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, {@link EventRequest#setEnabled})
* are permitted - attempts to do so will generally cause an
* {@link InvalidRequestStateException}.
* No other eventRequests are effected.
* <P>
* 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):
* <PRE>
* Iterator iter = requestManager.stepRequests().iterator();
* while (iter.hasNext()) {
* requestManager.deleteEventRequest(iter.next());
* }
* </PRE>
* may cause a {@link java.util.ConcurrentModificationException}.
* Instead use
* {@link #deleteEventRequests(List) deleteEventRequests(List)}
* or copy the list before iterating.
*
* @param eventRequest the eventRequest to remove
*/
void deleteEventRequest(EventRequest eventRequest);
/**
* Removes a list of {@link EventRequest}s.
*
* @see #deleteEventRequest(EventRequest)
*
* @param eventRequests the list of eventRequests to remove
*/
void deleteEventRequests(List<? extends EventRequest> eventRequests);
/**
* Remove all breakpoints managed by this EventRequestManager.
*
* @see #deleteEventRequest(EventRequest)
*/
void deleteAllBreakpoints();
/**
* 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.
* @return the all {@link StepRequest} objects.
*/
List<StepRequest> stepRequests();
/**
* 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.
* @return the all {@link ClassPrepareRequest} objects.
*/
List<ClassPrepareRequest> classPrepareRequests();
/**
* 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.
* @return the all {@link ClassUnloadRequest} objects.
*/
List<ClassUnloadRequest> classUnloadRequests();
/**
* 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.
* @return the all {@link ThreadStartRequest} objects.
*/
List<ThreadStartRequest> threadStartRequests();
/**
* 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.
* @return the all {@link ThreadDeathRequest} objects.
*/
List<ThreadDeathRequest> threadDeathRequests();
/**
* 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.
* @return the all {@link ExceptionRequest} objects.
*/
List<ExceptionRequest> exceptionRequests();
/**
* 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.
* @return the list of all {@link BreakpointRequest} objects.
*/
List<BreakpointRequest> breakpointRequests();
/**
* 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.
* @return the all {@link AccessWatchpointRequest} objects.
*/
List<AccessWatchpointRequest> accessWatchpointRequests();
/**
* 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.
* @return the all {@link ModificationWatchpointRequest} objects.
*/
List<ModificationWatchpointRequest> modificationWatchpointRequests();
/**
* 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.
* @return the list of all {@link MethodEntryRequest} objects.
*/
List<MethodEntryRequest> methodEntryRequests();
/**
* 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.
* @return the list of all {@link MethodExitRequest} objects.
*/
List<MethodExitRequest> methodExitRequests();
/**
* 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.
* @return the list of all {@link MonitorContendedEnterRequest} objects.
*
* @since 1.6
*/
List<MonitorContendedEnterRequest> monitorContendedEnterRequests();
/**
* 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.
* @return the list of all {@link MonitorContendedEnteredRequest} objects.
*
* @since 1.6
*/
List<MonitorContendedEnteredRequest> monitorContendedEnteredRequests();
/**
* 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.
* @return the list of all {@link MonitorWaitRequest} objects.
*
* @since 1.6
*/
List<MonitorWaitRequest> monitorWaitRequests();
/**
* 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.
* @return the list of all {@link MonitorWaitedRequest} objects.
*
* @since 1.6
*/
List<MonitorWaitedRequest> monitorWaitedRequests();
/**
* 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.
* @return the list of all {@link VMDeathRequest} objects.
*
* @since 1.4
*/
List<VMDeathRequest> vmDeathRequests();
}