/*

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