View Javadoc
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 }