1 /*

     2  * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package com.sun.jdi.request;

    27 

    28 import com.sun.jdi.*;

    29 

    30 import java.util.List;

    31 

    32 /**

    33  * Manages the creation and deletion of {@link EventRequest}s. A single

    34  * implementor of this interface exists in a particuar VM and

    35  * is accessed through {@link VirtualMachine#eventRequestManager()}

    36  *

    37  * @see EventRequest

    38  * @see com.sun.jdi.event.Event

    39  * @see BreakpointRequest

    40  * @see com.sun.jdi.event.BreakpointEvent

    41  * @see VirtualMachine

    42  *

    43  * @author Robert Field

    44  * @since  1.3

    45  */

    46 

    47 @jdk.Exported

    48 public interface EventRequestManager extends Mirror {

    49 

    50     /**

    51      * Creates a new disabled {@link ClassPrepareRequest}.

    52      * The new event request is added to the list managed by this

    53      * EventRequestManager. Use {@link EventRequest#enable()} to

    54      * activate this event request.

    55      *

    56      * @return the created {@link ClassPrepareRequest}

    57      */

    58     ClassPrepareRequest createClassPrepareRequest();

    59 

    60     /**

    61      * Creates a new disabled {@link ClassUnloadRequest}.

    62      * The new event request is added to the list managed by this

    63      * EventRequestManager. Use {@link EventRequest#enable()} to

    64      * activate this event request.

    65      *

    66      * @return the created {@link ClassUnloadRequest}

    67      */

    68     ClassUnloadRequest createClassUnloadRequest();

    69 

    70     /**

    71      * Creates a new disabled {@link ThreadStartRequest}.

    72      * The new event request is added to the list managed by this

    73      * EventRequestManager. Use {@link EventRequest#enable()} to

    74      * activate this event request.

    75      *

    76      * @return the created {@link ThreadStartRequest}

    77      */

    78     ThreadStartRequest createThreadStartRequest();

    79 

    80     /**

    81      * Creates a new disabled {@link ThreadDeathRequest}.

    82      * The new event request is added to the list managed by this

    83      * EventRequestManager. Use {@link EventRequest#enable()} to

    84      * activate this event request.

    85      *

    86      * @return the created {@link ThreadDeathRequest}

    87      */

    88     ThreadDeathRequest createThreadDeathRequest();

    89 

    90     /**

    91      * Creates a new disabled {@link ExceptionRequest}.

    92      * The new event request is added to the list managed by this

    93      * EventRequestManager. Use {@link EventRequest#enable()} to

    94      * activate this event request.

    95      * <P>

    96      * A specific exception type and its subclasses can be selected

    97      * for exception events. Caught exceptions,  uncaught exceptions,

    98      * or both can be selected. Note, however, that

    99      * at the time an exception is thrown, it is not always

   100      * possible to determine whether it is truly caught. See

   101      * {@link com.sun.jdi.event.ExceptionEvent#catchLocation} for

   102      * details.

   103      * @param refType If non-null, specifies that exceptions which are

   104      *                instances of refType will be reported. Note: this

   105      *                will include instances of sub-types.  If null,

   106      *                all instances will be reported

   107      * @param notifyCaught If true, caught exceptions will be reported.

   108      * @param notifyUncaught If true, uncaught exceptions will be reported.

   109      *

   110      * @return the created {@link ExceptionRequest}

   111      */

   112     ExceptionRequest createExceptionRequest(ReferenceType refType,

   113                                             boolean notifyCaught,

   114                                             boolean notifyUncaught);

   115 

   116     /**

   117      * Creates a new disabled {@link MethodEntryRequest}.

   118      * The new event request is added to the list managed by this

   119      * EventRequestManager. Use {@link EventRequest#enable()} to

   120      * activate this event request.

   121      *

   122      * @return the created {@link MethodEntryRequest}

   123      */

   124     MethodEntryRequest createMethodEntryRequest();

   125 

   126     /**

   127      * Creates a new disabled {@link MethodExitRequest}.

   128      * The new event request is added to the list managed by this

   129      * EventRequestManager. Use {@link EventRequest#enable()} to

   130      * activate this event request.

   131      *

   132      * @return the created {@link MethodExitRequest}

   133      */

   134     MethodExitRequest createMethodExitRequest();

   135 

   136      /**

   137      * Creates a new disabled {@link MonitorContendedEnterRequest}.

   138      * The new event request is added to the list managed by this

   139      * EventRequestManager. Use {@link EventRequest#enable()} to

   140      * activate this event request.

   141      *

   142      * Not all target virtual machines support this operation.

   143      * Use {@link VirtualMachine#canRequestMonitorEvents()}

   144      * to determine if the operation is supported.

   145      *

   146      * @return the created {@link MonitorContendedEnterRequest}

   147      * @throws java.lang.UnsupportedOperationException if

   148      * the target VM does not support this

   149      * operation.

   150      *

   151      * @since 1.6

   152      */

   153     MonitorContendedEnterRequest createMonitorContendedEnterRequest();

   154 

   155     /**

   156      * Creates a new disabled {@link MonitorContendedEnteredRequest}.

   157      * The new event request is added to the list managed by this

   158      * EventRequestManager. Use {@link EventRequest#enable()} to

   159      * activate this event request.

   160      *

   161      * Not all target virtual machines support this operation.

   162      * Use {@link VirtualMachine#canRequestMonitorEvents()}

   163      * to determine if the operation is supported.

   164      *

   165      * @return the created {@link MonitorContendedEnteredRequest}

   166      * @throws java.lang.UnsupportedOperationException if

   167      * the target VM does not support this

   168      * operation.

   169      *

   170      * @since 1.6

   171      */

   172 

   173     MonitorContendedEnteredRequest createMonitorContendedEnteredRequest();

   174 

   175     /**

   176      * Creates a new disabled {@link MonitorWaitRequest}.

   177      * The new event request is added to the list managed by this

   178      * EventRequestManager. Use {@link EventRequest#enable()} to

   179      * activate this event request.

   180      *

   181      * Not all target virtual machines support this operation.

   182      * Use {@link VirtualMachine#canRequestMonitorEvents()}

   183      * to determine if the operation is supported.

   184      *

   185      * @return the created {@link MonitorWaitRequest}

   186      * @throws java.lang.UnsupportedOperationException if

   187      * the target VM does not support this

   188      * operation.

   189      *

   190      * @since 1.6

   191      */

   192     MonitorWaitRequest createMonitorWaitRequest();

   193 

   194     /**

   195      * Creates a new disabled {@link MonitorWaitedRequest}.

   196      * The new event request is added to the list managed by this

   197      * EventRequestManager. Use {@link EventRequest#enable()} to

   198      * activate this event request.

   199      *

   200      * Not all target virtual machines support this operation.

   201      * Use {@link VirtualMachine#canRequestMonitorEvents()}

   202      * to determine if the operation is supported.

   203      *

   204      * @return the created {@link MonitorWaitedRequest}

   205      * @throws java.lang.UnsupportedOperationException if

   206      * the target VM does not support this

   207      * operation.

   208      *

   209      * @since 1.6

   210      */

   211     MonitorWaitedRequest createMonitorWaitedRequest();

   212 

   213     /**

   214      * Creates a new disabled {@link StepRequest}.

   215      * The new event request is added to the list managed by this

   216      * EventRequestManager. Use {@link EventRequest#enable()} to

   217      * activate this event request.

   218      * <p>

   219      * The returned request will control stepping only in the specified

   220      * <code>thread</code>; all other threads will be unaffected.

   221      * A <code>size</code>value of {@link com.sun.jdi.request.StepRequest#STEP_MIN} will generate a

   222      * step event each time the code index changes. It represents the

   223      * smallest step size available and often maps to the instruction

   224      * level.

   225      * A <code>size</code> value of {@link com.sun.jdi.request.StepRequest#STEP_LINE} will generate a

   226      * step event each time the source line changes unless line number information is not available,

   227      * in which case a STEP_MIN will be done instead.  For example, no line number information is

   228      * available during the execution of a method that has been rendered obsolete by

   229      * by a {@link com.sun.jdi.VirtualMachine#redefineClasses} operation.

   230      * A <code>depth</code> value of {@link com.sun.jdi.request.StepRequest#STEP_INTO} will generate

   231      * step events in any called methods.  A <code>depth</code> value

   232      * of {@link com.sun.jdi.request.StepRequest#STEP_OVER} restricts step events to the current frame

   233      * or caller frames. A <code>depth</code> value of {@link com.sun.jdi.request.StepRequest#STEP_OUT}

   234      * restricts step events to caller frames only. All depth

   235      * restrictions are relative to the call stack immediately before the

   236      * step takes place.

   237      * <p>

   238      * Only one pending step request is allowed per thread.

   239      * <p>

   240      * Note that a typical debugger will want to cancel stepping

   241      * after the first step is detected.  Thus a next line method

   242      * would do the following:

   243      * <code>

   244      * <pre>

   245      *     EventRequestManager mgr = myVM.{@link VirtualMachine#eventRequestManager eventRequestManager}();

   246      *     StepRequest request = mgr.createStepRequest(myThread,

   247      *                                                 StepRequest.{@link StepRequest#STEP_LINE STEP_LINE},

   248      *                                                 StepRequest.{@link StepRequest#STEP_OVER STEP_OVER});

   249      *     request.{@link EventRequest#addCountFilter addCountFilter}(1);  // next step only

   250      *     request.enable();

   251      *     myVM.{@link VirtualMachine#resume resume}();

   252      * </pre>

   253      * </code>

   254      *

   255      * @param thread the thread in which to step

   256      * @param depth the step depth

   257      * @param size the step size

   258      * @return the created {@link StepRequest}

   259      * @throws DuplicateRequestException if there is already a pending

   260      * step request for the specified thread.

   261      * @throws IllegalArgumentException if the size or depth arguments

   262      * contain illegal values.

   263      */

   264     StepRequest createStepRequest(ThreadReference thread,

   265                                   int size,

   266                                   int depth);

   267 

   268     /**

   269      * Creates a new disabled {@link BreakpointRequest}.

   270      * The given {@link Location} must have a valid

   271      * (that is, non-negative) code index. The new

   272      * breakpoint is added to the list managed by this

   273      * EventRequestManager. Multiple breakpoints at the

   274      * same location are permitted. Use {@link EventRequest#enable()} to

   275      * activate this event request.

   276      *

   277      * @param location the location of the new breakpoint.

   278      * @return the created {@link BreakpointRequest}

   279      * @throws NativeMethodException if location is within a native method.

   280      */

   281     BreakpointRequest createBreakpointRequest(Location location);

   282 

   283     /**

   284      * Creates a new disabled watchpoint which watches accesses to the

   285      * specified field. The new

   286      * watchpoint is added to the list managed by this

   287      * EventRequestManager. Multiple watchpoints on the

   288      * same field are permitted.

   289      * Use {@link EventRequest#enable()} to

   290      * activate this event request.

   291      * <P>

   292      * Not all target virtual machines support this operation.

   293      * Use {@link VirtualMachine#canWatchFieldAccess()}

   294      * to determine if the operation is supported.

   295      *

   296      * @param field the field to watch

   297      * @return the created watchpoint

   298      * @throws java.lang.UnsupportedOperationException if

   299      * the target virtual machine does not support this

   300      * operation.

   301      */

   302     AccessWatchpointRequest createAccessWatchpointRequest(Field field);

   303 

   304     /**

   305      * Creates a new disabled watchpoint which watches accesses to the

   306      * specified field. The new

   307      * watchpoint is added to the list managed by this

   308      * EventRequestManager. Multiple watchpoints on the

   309      * same field are permitted.

   310      * Use {@link EventRequest#enable()} to

   311      * activate this event request.

   312      * <P>

   313      * Not all target virtual machines support this operation.

   314      * Use {@link VirtualMachine#canWatchFieldModification()}

   315      * to determine if the operation is supported.

   316      *

   317      * @param field the field to watch

   318      * @return the created watchpoint

   319      * @throws java.lang.UnsupportedOperationException if

   320      * the target virtual machine does not support this

   321      * operation.

   322      */

   323     ModificationWatchpointRequest createModificationWatchpointRequest(Field field);

   324 

   325     /**

   326      * Creates a new disabled {@link VMDeathRequest}.

   327      * The new request is added to the list managed by this

   328      * EventRequestManager.

   329      * Use {@link EventRequest#enable()} to

   330      * activate this event request.

   331      * <P>

   332      * This request (if enabled) will cause a

   333      * {@link com.sun.jdi.event.VMDeathEvent}

   334      * to be sent on termination of the target VM.

   335      * <P>

   336      * A VMDeathRequest with a suspend policy of

   337      * {@link EventRequest#SUSPEND_ALL SUSPEND_ALL}

   338      * can be used to assure processing of incoming

   339      * {@link EventRequest#SUSPEND_NONE SUSPEND_NONE} or

   340      * {@link EventRequest#SUSPEND_EVENT_THREAD SUSPEND_EVENT_THREAD}

   341      * events before VM death.  If all event processing is being

   342      * done in the same thread as event sets are being read,

   343      * enabling the request is all that is needed since the VM

   344      * will be suspended until the {@link com.sun.jdi.event.EventSet}

   345      * containing the {@link com.sun.jdi.event.VMDeathEvent}

   346      * is resumed.

   347      * <P>

   348      * Not all target virtual machines support this operation.

   349      * Use {@link VirtualMachine#canRequestVMDeathEvent()}

   350      * to determine if the operation is supported.

   351      *

   352      * @return the created request

   353      * @throws java.lang.UnsupportedOperationException if

   354      * the target VM does not support this

   355      * operation.

   356      *

   357      * @since 1.4

   358      */

   359     VMDeathRequest createVMDeathRequest();

   360 

   361     /**

   362      * Removes an eventRequest. The eventRequest is disabled and

   363      * the removed from the requests managed by this

   364      * EventRequestManager. Once the eventRequest is deleted, no

   365      * operations (for example, {@link EventRequest#setEnabled})

   366      * are permitted - attempts to do so will generally cause an

   367      * {@link InvalidRequestStateException}.

   368      * No other eventRequests are effected.

   369      * <P>

   370      * Because this method changes the underlying lists of event

   371      * requests, attempting to directly delete from a list returned

   372      * by a request accessor (e.g. below):

   373      * <PRE>

   374      *   Iterator iter = requestManager.stepRequests().iterator();

   375      *   while (iter.hasNext()) {

   376      *      requestManager.deleteEventRequest(iter.next());

   377      *  }

   378      * </PRE>

   379      * may cause a {@link java.util.ConcurrentModificationException}.

   380      * Instead use

   381      * {@link #deleteEventRequests(List) deleteEventRequests(List)}

   382      * or copy the list before iterating.

   383      *

   384      * @param eventRequest the eventRequest to remove

   385      */

   386     void deleteEventRequest(EventRequest eventRequest);

   387 

   388     /**

   389      * Removes a list of {@link EventRequest}s.

   390      *

   391      * @see #deleteEventRequest(EventRequest)

   392      *

   393      * @param eventRequests the list of eventRequests to remove

   394      */

   395     void deleteEventRequests(List<? extends EventRequest> eventRequests);

   396 

   397     /**

   398      * Remove all breakpoints managed by this EventRequestManager.

   399      *

   400      * @see #deleteEventRequest(EventRequest)

   401      */

   402     void deleteAllBreakpoints();

   403 

   404     /**

   405      * Return an unmodifiable list of the enabled and disabled step requests.

   406      * This list is a live view of these requests and thus changes as requests

   407      * are added and deleted.

   408      * @return the all {@link StepRequest} objects.

   409      */

   410     List<StepRequest> stepRequests();

   411 

   412     /**

   413      * Return an unmodifiable list of the enabled and disabled class prepare requests.

   414      * This list is a live view of these requests and thus changes as requests

   415      * are added and deleted.

   416      * @return the all {@link ClassPrepareRequest} objects.

   417      */

   418     List<ClassPrepareRequest> classPrepareRequests();

   419 

   420     /**

   421      * Return an unmodifiable list of the enabled and disabled class unload requests.

   422      * This list is a live view of these requests and thus changes as requests

   423      * are added and deleted.

   424      * @return the all {@link ClassUnloadRequest} objects.

   425      */

   426     List<ClassUnloadRequest> classUnloadRequests();

   427 

   428     /**

   429      * Return an unmodifiable list of the enabled and disabled thread start requests.

   430      * This list is a live view of these requests and thus changes as requests

   431      * are added and deleted.

   432      * @return the all {@link ThreadStartRequest} objects.

   433      */

   434     List<ThreadStartRequest> threadStartRequests();

   435 

   436     /**

   437      * Return an unmodifiable list of the enabled and disabled thread death requests.

   438      * This list is a live view of these requests and thus changes as requests

   439      * are added and deleted.

   440      * @return the all {@link ThreadDeathRequest} objects.

   441      */

   442     List<ThreadDeathRequest> threadDeathRequests();

   443 

   444     /**

   445      * Return an unmodifiable list of the enabled and disabled exception requests.

   446      * This list is a live view of these requests and thus changes as requests

   447      * are added and deleted.

   448      * @return the all {@link ExceptionRequest} objects.

   449      */

   450     List<ExceptionRequest> exceptionRequests();

   451 

   452     /**

   453      * Return an unmodifiable list of the enabled and disabled breakpoint requests.

   454      * This list is a live view of these requests and thus changes as requests

   455      * are added and deleted.

   456      * @return the list of all {@link BreakpointRequest} objects.

   457      */

   458     List<BreakpointRequest> breakpointRequests();

   459 

   460     /**

   461      * Return an unmodifiable list of the enabled and disabled access

   462      * watchpoint requests.

   463      * This list is a live view of these requests and thus changes as requests

   464      * are added and deleted.

   465      * @return the all {@link AccessWatchpointRequest} objects.

   466      */

   467     List<AccessWatchpointRequest> accessWatchpointRequests();

   468 

   469     /**

   470      * Return an unmodifiable list of the enabled and disabled modification

   471      * watchpoint requests.

   472      * This list is a live view of these requests and thus changes as requests

   473      * are added and deleted.

   474      * @return the all {@link ModificationWatchpointRequest} objects.

   475      */

   476     List<ModificationWatchpointRequest> modificationWatchpointRequests();

   477 

   478     /**

   479      * Return an unmodifiable list of the enabled and disabled method entry requests.

   480      * This list is a live view of these requests and thus changes as requests

   481      * are added and deleted.

   482      * @return the list of all {@link MethodEntryRequest} objects.

   483      */

   484     List<MethodEntryRequest> methodEntryRequests();

   485 

   486     /**

   487      * Return an unmodifiable list of the enabled and disabled method exit requests.

   488      * This list is a live view of these requests and thus changes as requests

   489      * are added and deleted.

   490      * @return the list of all {@link MethodExitRequest} objects.

   491      */

   492     List<MethodExitRequest> methodExitRequests();

   493 

   494     /**

   495      * Return an unmodifiable list of the enabled and disabled monitor contended enter requests.

   496      * This list is a live view of these requests and thus changes as requests

   497      * are added and deleted.

   498      * @return the list of all {@link MonitorContendedEnterRequest} objects.

   499      *

   500      * @since 1.6

   501      */

   502     List<MonitorContendedEnterRequest> monitorContendedEnterRequests();

   503 

   504     /**

   505      * Return an unmodifiable list of the enabled and disabled monitor contended entered requests.

   506      * This list is a live view of these requests and thus changes as requests

   507      * are added and deleted.

   508      * @return the list of all {@link MonitorContendedEnteredRequest} objects.

   509      *

   510      * @since 1.6

   511      */

   512     List<MonitorContendedEnteredRequest> monitorContendedEnteredRequests();

   513 

   514     /**

   515      * Return an unmodifiable list of the enabled and disabled monitor wait requests.

   516      * This list is a live view of these requests and thus changes as requests

   517      * are added and deleted.

   518      * @return the list of all {@link MonitorWaitRequest} objects.

   519      *

   520      * @since 1.6

   521      */

   522     List<MonitorWaitRequest> monitorWaitRequests();

   523 

   524     /**

   525      * Return an unmodifiable list of the enabled and disabled monitor waited requests.

   526      * This list is a live view of these requests and thus changes as requests

   527      * are added and deleted.

   528      * @return the list of all {@link MonitorWaitedRequest} objects.

   529      *

   530      * @since 1.6

   531      */

   532     List<MonitorWaitedRequest> monitorWaitedRequests();

   533 

   534     /**

   535      * Return an unmodifiable list of the enabled and disabled VM death requests.

   536      * This list is a live view of these requests and thus changes as requests

   537      * are added and deleted.

   538      * Note: the unsolicited VMDeathEvent does not have a

   539      * corresponding request.

   540      * @return the list of all {@link VMDeathRequest} objects.

   541      *

   542      * @since 1.4

   543      */

   544     List<VMDeathRequest> vmDeathRequests();

   545 }