/* * 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. *

* 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. *

* The returned request will control stepping only in the specified * thread; all other threads will be unaffected. * A sizevalue 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 size 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 depth value of {@link com.sun.jdi.request.StepRequest#STEP_INTO} will generate * step events in any called methods. A depth value * of {@link com.sun.jdi.request.StepRequest#STEP_OVER} restricts step events to the current frame * or caller frames. A depth 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. *

* 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}();
     * 
* * * @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. *

* 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. *

* 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. *

* This request (if enabled) will cause a * {@link com.sun.jdi.event.VMDeathEvent} * to be sent on termination of the target VM. *

* 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. *

* 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. *

* 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 {@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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 vmDeathRequests(); }