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}; all other threads will be unaffected.
221 * A {@code size} 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} 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} value of {@link com.sun.jdi.request.StepRequest#STEP_INTO} will generate
231 * step events in any called methods. A {@code depth} 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} 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 * <pre>{@code
244 * EventRequestManager mgr = myVM.{@link VirtualMachine#eventRequestManager eventRequestManager}();
245 * StepRequest request = mgr.createStepRequest(myThread,
246 * StepRequest.{@link StepRequest#STEP_LINE STEP_LINE},
247 * StepRequest.{@link StepRequest#STEP_OVER STEP_OVER});
248 * request.{@link EventRequest#addCountFilter addCountFilter}(1); // next step only
249 * request.enable();
250 * myVM.{@link VirtualMachine#resume resume}();
251 * }</pre>
252 *
253 * @param thread the thread in which to step
254 * @param depth the step depth
255 * @param size the step size
256 * @return the created {@link StepRequest}
257 * @throws DuplicateRequestException if there is already a pending
258 * step request for the specified thread.
259 * @throws IllegalArgumentException if the size or depth arguments
260 * contain illegal values.
261 */
262 StepRequest createStepRequest(ThreadReference thread,
263 int size,
264 int depth);
265
266 /**
267 * Creates a new disabled {@link BreakpointRequest}.
268 * The given {@link Location} must have a valid
269 * (that is, non-negative) code index. The new
270 * breakpoint is added to the list managed by this
271 * EventRequestManager. Multiple breakpoints at the
272 * same location are permitted. Use {@link EventRequest#enable()} to
273 * activate this event request.
274 *
275 * @param location the location of the new breakpoint.
276 * @return the created {@link BreakpointRequest}
277 * @throws NativeMethodException if location is within a native method.
278 */
279 BreakpointRequest createBreakpointRequest(Location location);
280
281 /**
282 * Creates a new disabled watchpoint which watches accesses to the
283 * specified field. The new
284 * watchpoint is added to the list managed by this
285 * EventRequestManager. Multiple watchpoints on the
286 * same field are permitted.
287 * Use {@link EventRequest#enable()} to
288 * activate this event request.
289 * <P>
290 * Not all target virtual machines support this operation.
291 * Use {@link VirtualMachine#canWatchFieldAccess()}
292 * to determine if the operation is supported.
293 *
294 * @param field the field to watch
295 * @return the created watchpoint
296 * @throws java.lang.UnsupportedOperationException if
297 * the target virtual machine does not support this
298 * operation.
299 */
300 AccessWatchpointRequest createAccessWatchpointRequest(Field field);
301
302 /**
303 * Creates a new disabled watchpoint which watches accesses to the
304 * specified field. The new
305 * watchpoint is added to the list managed by this
306 * EventRequestManager. Multiple watchpoints on the
307 * same field are permitted.
308 * Use {@link EventRequest#enable()} to
309 * activate this event request.
310 * <P>
311 * Not all target virtual machines support this operation.
312 * Use {@link VirtualMachine#canWatchFieldModification()}
313 * to determine if the operation is supported.
314 *
315 * @param field the field to watch
316 * @return the created watchpoint
317 * @throws java.lang.UnsupportedOperationException if
318 * the target virtual machine does not support this
319 * operation.
320 */
321 ModificationWatchpointRequest createModificationWatchpointRequest(Field field);
322
323 /**
324 * Creates a new disabled {@link VMDeathRequest}.
325 * The new request is added to the list managed by this
326 * EventRequestManager.
327 * Use {@link EventRequest#enable()} to
328 * activate this event request.
329 * <P>
330 * This request (if enabled) will cause a
331 * {@link com.sun.jdi.event.VMDeathEvent}
332 * to be sent on termination of the target VM.
333 * <P>
334 * A VMDeathRequest with a suspend policy of
335 * {@link EventRequest#SUSPEND_ALL SUSPEND_ALL}
336 * can be used to assure processing of incoming
337 * {@link EventRequest#SUSPEND_NONE SUSPEND_NONE} or
338 * {@link EventRequest#SUSPEND_EVENT_THREAD SUSPEND_EVENT_THREAD}
339 * events before VM death. If all event processing is being
340 * done in the same thread as event sets are being read,
341 * enabling the request is all that is needed since the VM
342 * will be suspended until the {@link com.sun.jdi.event.EventSet}
343 * containing the {@link com.sun.jdi.event.VMDeathEvent}
344 * is resumed.
345 * <P>
346 * Not all target virtual machines support this operation.
347 * Use {@link VirtualMachine#canRequestVMDeathEvent()}
348 * to determine if the operation is supported.
349 *
350 * @return the created request
351 * @throws java.lang.UnsupportedOperationException if
352 * the target VM does not support this
353 * operation.
354 *
355 * @since 1.4
356 */
357 VMDeathRequest createVMDeathRequest();
358
359 /**
360 * Removes an eventRequest. The eventRequest is disabled and
361 * the removed from the requests managed by this
362 * EventRequestManager. Once the eventRequest is deleted, no
363 * operations (for example, {@link EventRequest#setEnabled})
364 * are permitted - attempts to do so will generally cause an
365 * {@link InvalidRequestStateException}.
366 * No other eventRequests are effected.
367 * <P>
368 * Because this method changes the underlying lists of event
369 * requests, attempting to directly delete from a list returned
370 * by a request accessor (e.g. below):
371 * <PRE>
372 * Iterator iter = requestManager.stepRequests().iterator();
373 * while (iter.hasNext()) {
374 * requestManager.deleteEventRequest(iter.next());
375 * }
376 * </PRE>
377 * may cause a {@link java.util.ConcurrentModificationException}.
378 * Instead use
379 * {@link #deleteEventRequests(List) deleteEventRequests(List)}
380 * or copy the list before iterating.
381 *
382 * @param eventRequest the eventRequest to remove
383 */
384 void deleteEventRequest(EventRequest eventRequest);
385
386 /**
387 * Removes a list of {@link EventRequest}s.
388 *
389 * @see #deleteEventRequest(EventRequest)
390 *
391 * @param eventRequests the list of eventRequests to remove
392 */
393 void deleteEventRequests(List<? extends EventRequest> eventRequests);
394
395 /**
396 * Remove all breakpoints managed by this EventRequestManager.
397 *
398 * @see #deleteEventRequest(EventRequest)
399 */
400 void deleteAllBreakpoints();
401
402 /**
403 * Return an unmodifiable list of the enabled and disabled step requests.
404 * This list is a live view of these requests and thus changes as requests
405 * are added and deleted.
406 * @return the all {@link StepRequest} objects.
407 */
408 List<StepRequest> stepRequests();
409
410 /**
411 * Return an unmodifiable list of the enabled and disabled class prepare requests.
412 * This list is a live view of these requests and thus changes as requests
413 * are added and deleted.
414 * @return the all {@link ClassPrepareRequest} objects.
415 */
416 List<ClassPrepareRequest> classPrepareRequests();
417
418 /**
419 * Return an unmodifiable list of the enabled and disabled class unload requests.
420 * This list is a live view of these requests and thus changes as requests
421 * are added and deleted.
422 * @return the all {@link ClassUnloadRequest} objects.
423 */
424 List<ClassUnloadRequest> classUnloadRequests();
425
426 /**
427 * Return an unmodifiable list of the enabled and disabled thread start requests.
428 * This list is a live view of these requests and thus changes as requests
429 * are added and deleted.
430 * @return the all {@link ThreadStartRequest} objects.
431 */
432 List<ThreadStartRequest> threadStartRequests();
433
434 /**
435 * Return an unmodifiable list of the enabled and disabled thread death requests.
436 * This list is a live view of these requests and thus changes as requests
437 * are added and deleted.
438 * @return the all {@link ThreadDeathRequest} objects.
439 */
440 List<ThreadDeathRequest> threadDeathRequests();
441
442 /**
443 * Return an unmodifiable list of the enabled and disabled exception requests.
444 * This list is a live view of these requests and thus changes as requests
445 * are added and deleted.
446 * @return the all {@link ExceptionRequest} objects.
447 */
448 List<ExceptionRequest> exceptionRequests();
449
450 /**
451 * Return an unmodifiable list of the enabled and disabled breakpoint requests.
452 * This list is a live view of these requests and thus changes as requests
453 * are added and deleted.
454 * @return the list of all {@link BreakpointRequest} objects.
455 */
456 List<BreakpointRequest> breakpointRequests();
457
458 /**
459 * Return an unmodifiable list of the enabled and disabled access
460 * watchpoint requests.
461 * This list is a live view of these requests and thus changes as requests
462 * are added and deleted.
463 * @return the all {@link AccessWatchpointRequest} objects.
464 */
465 List<AccessWatchpointRequest> accessWatchpointRequests();
466
467 /**
468 * Return an unmodifiable list of the enabled and disabled modification
469 * watchpoint requests.
470 * This list is a live view of these requests and thus changes as requests
471 * are added and deleted.
472 * @return the all {@link ModificationWatchpointRequest} objects.
473 */
474 List<ModificationWatchpointRequest> modificationWatchpointRequests();
475
476 /**
477 * Return an unmodifiable list of the enabled and disabled method entry requests.
478 * This list is a live view of these requests and thus changes as requests
479 * are added and deleted.
480 * @return the list of all {@link MethodEntryRequest} objects.
481 */
482 List<MethodEntryRequest> methodEntryRequests();
483
484 /**
485 * Return an unmodifiable list of the enabled and disabled method exit requests.
486 * This list is a live view of these requests and thus changes as requests
487 * are added and deleted.
488 * @return the list of all {@link MethodExitRequest} objects.
489 */
490 List<MethodExitRequest> methodExitRequests();
491
492 /**
493 * Return an unmodifiable list of the enabled and disabled monitor contended enter requests.
494 * This list is a live view of these requests and thus changes as requests
495 * are added and deleted.
496 * @return the list of all {@link MonitorContendedEnterRequest} objects.
497 *
498 * @since 1.6
499 */
500 List<MonitorContendedEnterRequest> monitorContendedEnterRequests();
501
502 /**
503 * Return an unmodifiable list of the enabled and disabled monitor contended entered requests.
504 * This list is a live view of these requests and thus changes as requests
505 * are added and deleted.
506 * @return the list of all {@link MonitorContendedEnteredRequest} objects.
507 *
508 * @since 1.6
509 */
510 List<MonitorContendedEnteredRequest> monitorContendedEnteredRequests();
511
512 /**
513 * Return an unmodifiable list of the enabled and disabled monitor wait requests.
514 * This list is a live view of these requests and thus changes as requests
515 * are added and deleted.
516 * @return the list of all {@link MonitorWaitRequest} objects.
517 *
518 * @since 1.6
519 */
520 List<MonitorWaitRequest> monitorWaitRequests();
521
522 /**
523 * Return an unmodifiable list of the enabled and disabled monitor waited requests.
524 * This list is a live view of these requests and thus changes as requests
525 * are added and deleted.
526 * @return the list of all {@link MonitorWaitedRequest} objects.
527 *
528 * @since 1.6
529 */
530 List<MonitorWaitedRequest> monitorWaitedRequests();
531
532 /**
533 * Return an unmodifiable list of the enabled and disabled VM death requests.
534 * This list is a live view of these requests and thus changes as requests
535 * are added and deleted.
536 * Note: the unsolicited VMDeathEvent does not have a
537 * corresponding request.
538 * @return the list of all {@link VMDeathRequest} objects.
539 *
540 * @since 1.4
541 */
542 List<VMDeathRequest> vmDeathRequests();
543 }