jdi/request/EventRequestManager.java

/*
 * Copyright (c) 1998, 2013, 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
 */

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