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
26package com.sun.jdi.request;
27
28import com.sun.jdi.*;
29
30import 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
47public interface EventRequestManager extends Mirror {
48
49    /**
50     * Creates a new disabled {@link ClassPrepareRequest}.
51     * The new event request is added to the list managed by this
52     * EventRequestManager. Use {@link EventRequest#enable()} to
53     * activate this event request.
54     *
55     * @return the created {@link ClassPrepareRequest}
56     */
57    ClassPrepareRequest createClassPrepareRequest();
58
59    /**
60     * Creates a new disabled {@link ClassUnloadRequest}.
61     * The new event request is added to the list managed by this
62     * EventRequestManager. Use {@link EventRequest#enable()} to
63     * activate this event request.
64     *
65     * @return the created {@link ClassUnloadRequest}
66     */
67    ClassUnloadRequest createClassUnloadRequest();
68
69    /**
70     * Creates a new disabled {@link ThreadStartRequest}.
71     * The new event request is added to the list managed by this
72     * EventRequestManager. Use {@link EventRequest#enable()} to
73     * activate this event request.
74     *
75     * @return the created {@link ThreadStartRequest}
76     */
77    ThreadStartRequest createThreadStartRequest();
78
79    /**
80     * Creates a new disabled {@link ThreadDeathRequest}.
81     * The new event request is added to the list managed by this
82     * EventRequestManager. Use {@link EventRequest#enable()} to
83     * activate this event request.
84     *
85     * @return the created {@link ThreadDeathRequest}
86     */
87    ThreadDeathRequest createThreadDeathRequest();
88
89    /**
90     * Creates a new disabled {@link ExceptionRequest}.
91     * The new event request is added to the list managed by this
92     * EventRequestManager. Use {@link EventRequest#enable()} to
93     * activate this event request.
94     * <P>
95     * A specific exception type and its subclasses can be selected
96     * for exception events. Caught exceptions,  uncaught exceptions,
97     * or both can be selected. Note, however, that
98     * at the time an exception is thrown, it is not always
99     * possible to determine whether it is truly caught. See
100     * {@link com.sun.jdi.event.ExceptionEvent#catchLocation} for
101     * details.
102     * @param refType If non-null, specifies that exceptions which are
103     *                instances of refType will be reported. Note: this
104     *                will include instances of sub-types.  If null,
105     *                all instances will be reported
106     * @param notifyCaught If true, caught exceptions will be reported.
107     * @param notifyUncaught If true, uncaught exceptions will be reported.
108     *
109     * @return the created {@link ExceptionRequest}
110     */
111    ExceptionRequest createExceptionRequest(ReferenceType refType,
112                                            boolean notifyCaught,
113                                            boolean notifyUncaught);
114
115    /**
116     * Creates a new disabled {@link MethodEntryRequest}.
117     * The new event request is added to the list managed by this
118     * EventRequestManager. Use {@link EventRequest#enable()} to
119     * activate this event request.
120     *
121     * @return the created {@link MethodEntryRequest}
122     */
123    MethodEntryRequest createMethodEntryRequest();
124
125    /**
126     * Creates a new disabled {@link MethodExitRequest}.
127     * The new event request is added to the list managed by this
128     * EventRequestManager. Use {@link EventRequest#enable()} to
129     * activate this event request.
130     *
131     * @return the created {@link MethodExitRequest}
132     */
133    MethodExitRequest createMethodExitRequest();
134
135     /**
136     * Creates a new disabled {@link MonitorContendedEnterRequest}.
137     * The new event request is added to the list managed by this
138     * EventRequestManager. Use {@link EventRequest#enable()} to
139     * activate this event request.
140     *
141     * Not all target virtual machines support this operation.
142     * Use {@link VirtualMachine#canRequestMonitorEvents()}
143     * to determine if the operation is supported.
144     *
145     * @return the created {@link MonitorContendedEnterRequest}
146     * @throws java.lang.UnsupportedOperationException if
147     * the target VM does not support this
148     * operation.
149     *
150     * @since 1.6
151     */
152    MonitorContendedEnterRequest createMonitorContendedEnterRequest();
153
154    /**
155     * Creates a new disabled {@link MonitorContendedEnteredRequest}.
156     * The new event request is added to the list managed by this
157     * EventRequestManager. Use {@link EventRequest#enable()} to
158     * activate this event request.
159     *
160     * Not all target virtual machines support this operation.
161     * Use {@link VirtualMachine#canRequestMonitorEvents()}
162     * to determine if the operation is supported.
163     *
164     * @return the created {@link MonitorContendedEnteredRequest}
165     * @throws java.lang.UnsupportedOperationException if
166     * the target VM does not support this
167     * operation.
168     *
169     * @since 1.6
170     */
171
172    MonitorContendedEnteredRequest createMonitorContendedEnteredRequest();
173
174    /**
175     * Creates a new disabled {@link MonitorWaitRequest}.
176     * The new event request is added to the list managed by this
177     * EventRequestManager. Use {@link EventRequest#enable()} to
178     * activate this event request.
179     *
180     * Not all target virtual machines support this operation.
181     * Use {@link VirtualMachine#canRequestMonitorEvents()}
182     * to determine if the operation is supported.
183     *
184     * @return the created {@link MonitorWaitRequest}
185     * @throws java.lang.UnsupportedOperationException if
186     * the target VM does not support this
187     * operation.
188     *
189     * @since 1.6
190     */
191    MonitorWaitRequest createMonitorWaitRequest();
192
193    /**
194     * Creates a new disabled {@link MonitorWaitedRequest}.
195     * The new event request is added to the list managed by this
196     * EventRequestManager. Use {@link EventRequest#enable()} to
197     * activate this event request.
198     *
199     * Not all target virtual machines support this operation.
200     * Use {@link VirtualMachine#canRequestMonitorEvents()}
201     * to determine if the operation is supported.
202     *
203     * @return the created {@link MonitorWaitedRequest}
204     * @throws java.lang.UnsupportedOperationException if
205     * the target VM does not support this
206     * operation.
207     *
208     * @since 1.6
209     */
210    MonitorWaitedRequest createMonitorWaitedRequest();
211
212    /**
213     * Creates a new disabled {@link StepRequest}.
214     * The new event request is added to the list managed by this
215     * EventRequestManager. Use {@link EventRequest#enable()} to
216     * activate this event request.
217     * <p>
218     * The returned request will control stepping only in the specified
219     * {@code thread}; all other threads will be unaffected.
220     * A {@code size} value of {@link com.sun.jdi.request.StepRequest#STEP_MIN} will generate a
221     * step event each time the code index changes. It represents the
222     * smallest step size available and often maps to the instruction
223     * level.
224     * A {@code size} value of {@link com.sun.jdi.request.StepRequest#STEP_LINE} will generate a
225     * step event each time the source line changes unless line number information is not available,
226     * in which case a STEP_MIN will be done instead.  For example, no line number information is
227     * available during the execution of a method that has been rendered obsolete by
228     * by a {@link com.sun.jdi.VirtualMachine#redefineClasses} operation.
229     * A {@code depth} value of {@link com.sun.jdi.request.StepRequest#STEP_INTO} will generate
230     * step events in any called methods.  A {@code depth} value
231     * of {@link com.sun.jdi.request.StepRequest#STEP_OVER} restricts step events to the current frame
232     * or caller frames. A {@code depth} value of {@link com.sun.jdi.request.StepRequest#STEP_OUT}
233     * restricts step events to caller frames only. All depth
234     * restrictions are relative to the call stack immediately before the
235     * step takes place.
236     * <p>
237     * Only one pending step request is allowed per thread.
238     * <p>
239     * Note that a typical debugger will want to cancel stepping
240     * after the first step is detected.  Thus a next line method
241     * would do the following:
242     * <pre>{@code
243     *     EventRequestManager mgr = myVM.{@link VirtualMachine#eventRequestManager eventRequestManager}();
244     *     StepRequest request = mgr.createStepRequest(myThread,
245     *                                                 StepRequest.{@link StepRequest#STEP_LINE STEP_LINE},
246     *                                                 StepRequest.{@link StepRequest#STEP_OVER STEP_OVER});
247     *     request.{@link EventRequest#addCountFilter addCountFilter}(1);  // next step only
248     *     request.enable();
249     *     myVM.{@link VirtualMachine#resume resume}();
250     * }</pre>
251     *
252     * @param thread the thread in which to step
253     * @param depth the step depth
254     * @param size the step size
255     * @return the created {@link StepRequest}
256     * @throws DuplicateRequestException if there is already a pending
257     * step request for the specified thread.
258     * @throws IllegalArgumentException if the size or depth arguments
259     * contain illegal values.
260     */
261    StepRequest createStepRequest(ThreadReference thread,
262                                  int size,
263                                  int depth);
264
265    /**
266     * Creates a new disabled {@link BreakpointRequest}.
267     * The given {@link Location} must have a valid
268     * (that is, non-negative) code index. The new
269     * breakpoint is added to the list managed by this
270     * EventRequestManager. Multiple breakpoints at the
271     * same location are permitted. Use {@link EventRequest#enable()} to
272     * activate this event request.
273     *
274     * @param location the location of the new breakpoint.
275     * @return the created {@link BreakpointRequest}
276     * @throws NativeMethodException if location is within a native method.
277     */
278    BreakpointRequest createBreakpointRequest(Location location);
279
280    /**
281     * Creates a new disabled watchpoint which watches accesses to the
282     * specified field. The new
283     * watchpoint is added to the list managed by this
284     * EventRequestManager. Multiple watchpoints on the
285     * same field are permitted.
286     * Use {@link EventRequest#enable()} to
287     * activate this event request.
288     * <P>
289     * Not all target virtual machines support this operation.
290     * Use {@link VirtualMachine#canWatchFieldAccess()}
291     * to determine if the operation is supported.
292     *
293     * @param field the field to watch
294     * @return the created watchpoint
295     * @throws java.lang.UnsupportedOperationException if
296     * the target virtual machine does not support this
297     * operation.
298     */
299    AccessWatchpointRequest createAccessWatchpointRequest(Field field);
300
301    /**
302     * Creates a new disabled watchpoint which watches accesses to the
303     * specified field. The new
304     * watchpoint is added to the list managed by this
305     * EventRequestManager. Multiple watchpoints on the
306     * same field are permitted.
307     * Use {@link EventRequest#enable()} to
308     * activate this event request.
309     * <P>
310     * Not all target virtual machines support this operation.
311     * Use {@link VirtualMachine#canWatchFieldModification()}
312     * to determine if the operation is supported.
313     *
314     * @param field the field to watch
315     * @return the created watchpoint
316     * @throws java.lang.UnsupportedOperationException if
317     * the target virtual machine does not support this
318     * operation.
319     */
320    ModificationWatchpointRequest createModificationWatchpointRequest(Field field);
321
322    /**
323     * Creates a new disabled {@link VMDeathRequest}.
324     * The new request is added to the list managed by this
325     * EventRequestManager.
326     * Use {@link EventRequest#enable()} to
327     * activate this event request.
328     * <P>
329     * This request (if enabled) will cause a
330     * {@link com.sun.jdi.event.VMDeathEvent}
331     * to be sent on termination of the target VM.
332     * <P>
333     * A VMDeathRequest with a suspend policy of
334     * {@link EventRequest#SUSPEND_ALL SUSPEND_ALL}
335     * can be used to assure processing of incoming
336     * {@link EventRequest#SUSPEND_NONE SUSPEND_NONE} or
337     * {@link EventRequest#SUSPEND_EVENT_THREAD SUSPEND_EVENT_THREAD}
338     * events before VM death.  If all event processing is being
339     * done in the same thread as event sets are being read,
340     * enabling the request is all that is needed since the VM
341     * will be suspended until the {@link com.sun.jdi.event.EventSet}
342     * containing the {@link com.sun.jdi.event.VMDeathEvent}
343     * is resumed.
344     * <P>
345     * Not all target virtual machines support this operation.
346     * Use {@link VirtualMachine#canRequestVMDeathEvent()}
347     * to determine if the operation is supported.
348     *
349     * @return the created request
350     * @throws java.lang.UnsupportedOperationException if
351     * the target VM does not support this
352     * operation.
353     *
354     * @since 1.4
355     */
356    VMDeathRequest createVMDeathRequest();
357
358    /**
359     * Removes an eventRequest. The eventRequest is disabled and
360     * the removed from the requests managed by this
361     * EventRequestManager. Once the eventRequest is deleted, no
362     * operations (for example, {@link EventRequest#setEnabled})
363     * are permitted - attempts to do so will generally cause an
364     * {@link InvalidRequestStateException}.
365     * No other eventRequests are effected.
366     * <P>
367     * Because this method changes the underlying lists of event
368     * requests, attempting to directly delete from a list returned
369     * by a request accessor (e.g. below):
370     * <PRE>
371     *   Iterator iter = requestManager.stepRequests().iterator();
372     *   while (iter.hasNext()) {
373     *      requestManager.deleteEventRequest(iter.next());
374     *  }
375     * </PRE>
376     * may cause a {@link java.util.ConcurrentModificationException}.
377     * Instead use
378     * {@link #deleteEventRequests(List) deleteEventRequests(List)}
379     * or copy the list before iterating.
380     *
381     * @param eventRequest the eventRequest to remove
382     */
383    void deleteEventRequest(EventRequest eventRequest);
384
385    /**
386     * Removes a list of {@link EventRequest}s.
387     *
388     * @see #deleteEventRequest(EventRequest)
389     *
390     * @param eventRequests the list of eventRequests to remove
391     */
392    void deleteEventRequests(List<? extends EventRequest> eventRequests);
393
394    /**
395     * Remove all breakpoints managed by this EventRequestManager.
396     *
397     * @see #deleteEventRequest(EventRequest)
398     */
399    void deleteAllBreakpoints();
400
401    /**
402     * Return an unmodifiable list of the enabled and disabled step requests.
403     * This list is a live view of these requests and thus changes as requests
404     * are added and deleted.
405     * @return the all {@link StepRequest} objects.
406     */
407    List<StepRequest> stepRequests();
408
409    /**
410     * Return an unmodifiable list of the enabled and disabled class prepare requests.
411     * This list is a live view of these requests and thus changes as requests
412     * are added and deleted.
413     * @return the all {@link ClassPrepareRequest} objects.
414     */
415    List<ClassPrepareRequest> classPrepareRequests();
416
417    /**
418     * Return an unmodifiable list of the enabled and disabled class unload requests.
419     * This list is a live view of these requests and thus changes as requests
420     * are added and deleted.
421     * @return the all {@link ClassUnloadRequest} objects.
422     */
423    List<ClassUnloadRequest> classUnloadRequests();
424
425    /**
426     * Return an unmodifiable list of the enabled and disabled thread start requests.
427     * This list is a live view of these requests and thus changes as requests
428     * are added and deleted.
429     * @return the all {@link ThreadStartRequest} objects.
430     */
431    List<ThreadStartRequest> threadStartRequests();
432
433    /**
434     * Return an unmodifiable list of the enabled and disabled thread death requests.
435     * This list is a live view of these requests and thus changes as requests
436     * are added and deleted.
437     * @return the all {@link ThreadDeathRequest} objects.
438     */
439    List<ThreadDeathRequest> threadDeathRequests();
440
441    /**
442     * Return an unmodifiable list of the enabled and disabled exception requests.
443     * This list is a live view of these requests and thus changes as requests
444     * are added and deleted.
445     * @return the all {@link ExceptionRequest} objects.
446     */
447    List<ExceptionRequest> exceptionRequests();
448
449    /**
450     * Return an unmodifiable list of the enabled and disabled breakpoint requests.
451     * This list is a live view of these requests and thus changes as requests
452     * are added and deleted.
453     * @return the list of all {@link BreakpointRequest} objects.
454     */
455    List<BreakpointRequest> breakpointRequests();
456
457    /**
458     * Return an unmodifiable list of the enabled and disabled access
459     * watchpoint requests.
460     * This list is a live view of these requests and thus changes as requests
461     * are added and deleted.
462     * @return the all {@link AccessWatchpointRequest} objects.
463     */
464    List<AccessWatchpointRequest> accessWatchpointRequests();
465
466    /**
467     * Return an unmodifiable list of the enabled and disabled modification
468     * watchpoint requests.
469     * This list is a live view of these requests and thus changes as requests
470     * are added and deleted.
471     * @return the all {@link ModificationWatchpointRequest} objects.
472     */
473    List<ModificationWatchpointRequest> modificationWatchpointRequests();
474
475    /**
476     * Return an unmodifiable list of the enabled and disabled method entry requests.
477     * This list is a live view of these requests and thus changes as requests
478     * are added and deleted.
479     * @return the list of all {@link MethodEntryRequest} objects.
480     */
481    List<MethodEntryRequest> methodEntryRequests();
482
483    /**
484     * Return an unmodifiable list of the enabled and disabled method exit requests.
485     * This list is a live view of these requests and thus changes as requests
486     * are added and deleted.
487     * @return the list of all {@link MethodExitRequest} objects.
488     */
489    List<MethodExitRequest> methodExitRequests();
490
491    /**
492     * Return an unmodifiable list of the enabled and disabled monitor contended enter requests.
493     * This list is a live view of these requests and thus changes as requests
494     * are added and deleted.
495     * @return the list of all {@link MonitorContendedEnterRequest} objects.
496     *
497     * @since 1.6
498     */
499    List<MonitorContendedEnterRequest> monitorContendedEnterRequests();
500
501    /**
502     * Return an unmodifiable list of the enabled and disabled monitor contended entered requests.
503     * This list is a live view of these requests and thus changes as requests
504     * are added and deleted.
505     * @return the list of all {@link MonitorContendedEnteredRequest} objects.
506     *
507     * @since 1.6
508     */
509    List<MonitorContendedEnteredRequest> monitorContendedEnteredRequests();
510
511    /**
512     * Return an unmodifiable list of the enabled and disabled monitor wait requests.
513     * This list is a live view of these requests and thus changes as requests
514     * are added and deleted.
515     * @return the list of all {@link MonitorWaitRequest} objects.
516     *
517     * @since 1.6
518     */
519    List<MonitorWaitRequest> monitorWaitRequests();
520
521    /**
522     * Return an unmodifiable list of the enabled and disabled monitor waited requests.
523     * This list is a live view of these requests and thus changes as requests
524     * are added and deleted.
525     * @return the list of all {@link MonitorWaitedRequest} objects.
526     *
527     * @since 1.6
528     */
529    List<MonitorWaitedRequest> monitorWaitedRequests();
530
531    /**
532     * Return an unmodifiable list of the enabled and disabled VM death requests.
533     * This list is a live view of these requests and thus changes as requests
534     * are added and deleted.
535     * Note: the unsolicited VMDeathEvent does not have a
536     * corresponding request.
537     * @return the list of all {@link VMDeathRequest} objects.
538     *
539     * @since 1.4
540     */
541    List<VMDeathRequest> vmDeathRequests();
542}
543