1 /*
2 * Copyright (c) 1998, 2005, 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.event;
27
28 import com.sun.jdi.*;
29
30 import java.util.Set;
31
32 /**
33 * Several {@link Event} objects may be created at a given time by
34 * the target {@link VirtualMachine}. For example, there may be
35 * more than one {@link com.sun.jdi.request.BreakpointRequest}
36 * for a given {@link Location}
37 * or you might single step to the same location as a
38 * BreakpointRequest. These {@link Event} objects are delivered
39 * together as an EventSet. For uniformity, an EventSet is always used
40 * to deliver {@link Event} objects. EventSets are delivered by
41 * the {@link EventQueue}.
42 * EventSets are unmodifiable.
43 * <P>
44 * Associated with the issuance of an event set, suspensions may
45 * have occurred in the target VM. These suspensions correspond
46 * with the {@link #suspendPolicy() suspend policy}.
47 * To assure matching resumes occur, it is recommended,
48 * where possible,
49 * to complete the processing of an event set with
50 * {@link #resume() EventSet.resume()}.
51 * <P>
52 * The events that are grouped in an EventSet are restricted in the
53 * following ways:
54 * <P>
55 * <UL>
56 * <LI>Always singleton sets:
57 * <UL>
58 * <LI>{@link VMStartEvent}
59 * <LI>{@link VMDisconnectEvent}
60 * </UL>
61 * <LI>Only with other VMDeathEvents:
62 * <UL>
63 * <LI>{@link VMDeathEvent}
64 * </UL>
65 * <LI>Only with other ThreadStartEvents for the same thread:
66 * <UL>
67 * <LI>{@link ThreadStartEvent}
68 * </UL>
69 * <LI>Only with other ThreadDeathEvents for the same thread:
70 * <UL>
71 * <LI>{@link ThreadDeathEvent}
72 * </UL>
73 * <LI>Only with other ClassPrepareEvents for the same class:
74 * <UL>
75 * <LI>{@link ClassPrepareEvent}
76 * </UL>
77 * <LI>Only with other ClassUnloadEvents for the same class:
78 * <UL>
79 * <LI>{@link ClassUnloadEvent}
80 * </UL>
81 * <LI>Only with other AccessWatchpointEvents for the same field access:
82 * <UL>
83 * <LI>{@link AccessWatchpointEvent}
84 * </UL>
85 * <LI>Only with other ModificationWatchpointEvents for the same field
86 * modification:
87 * <UL>
88 * <LI>{@link ModificationWatchpointEvent}
89 * </UL>
90 * <LI>Only with other ExceptionEvents for the same exception occurrance:
91 * <UL>
92 * <LI>{@link ExceptionEvent}
93 * </UL>
94 * <LI>Only with other MethodExitEvents for the same method exit:
95 * <UL>
96 * <LI>{@link MethodExitEvent}
97 * </UL>
98 * <LI>Only with other Monitor contended enter events for the same monitor object:
99 * <UL>
100 * <LI>Monitor Contended Enter Event
101 * </UL>
102 * <LI>Only with other Monitor contended entered events for the same monitor object:
103 * <UL>
104 * <LI>Monitor Contended Entered Event
105 * </UL>
106 * <LI>Only with other Monitor wait events for the same monitor object:
107 * <UL>
108 * <LI>Monitor Wait Event
109 * </UL>
110 * <LI>Only with other Monitor waited events for the same monitor object:
111 * <UL>
112 * <LI>Monitor Waited Event
113 * </UL>
114 * <LI>Only with other members of this group, at the same location
115 * and in the same thread:
116 * <UL>
117 * <LI>{@link BreakpointEvent}
118 * <LI>{@link StepEvent}
119 * <LI>{@link MethodEntryEvent}
120 * </UL>
121 * </UL>
122 *
123 * @see Event
124 * @see EventQueue
125 *
126 * @author Robert Field
127 * @since 1.3
128 */
129
130 @jdk.Supported
131 public interface EventSet extends Mirror, Set<Event> {
132
133 /**
134 * Returns the policy used to suspend threads in the target VM
135 * for this event set. This policy is selected from the suspend
136 * policies for each event's request; the target VM chooses the
137 * policy which suspends the most threads. The target VM
138 * suspends threads according to that policy
139 * and that policy is returned here. See
140 * {@link com.sun.jdi.request.EventRequest} for the possible
141 * policy values.
142 * <p>
143 * In rare cases, the suspend policy may differ from the requested
144 * value if a {@link ClassPrepareEvent} has occurred in a
145 * debugger system thread. See {@link ClassPrepareEvent#thread}
146 * for details.
147 *
148 * @return the suspendPolicy which is either
149 * {@link com.sun.jdi.request.EventRequest#SUSPEND_ALL SUSPEND_ALL},
150 * {@link com.sun.jdi.request.EventRequest#SUSPEND_EVENT_THREAD SUSPEND_EVENT_THREAD} or
151 * {@link com.sun.jdi.request.EventRequest#SUSPEND_NONE SUSPEND_NONE}.
152 */
153 int suspendPolicy();
154
155 /**
156 * Return an iterator specific to {@link Event} objects.
157 */
158 EventIterator eventIterator();
159
160 /**
161 * Resumes threads suspended by this event set. If the {@link #suspendPolicy}
162 * is {@link com.sun.jdi.request.EventRequest#SUSPEND_ALL}, a call
163 * to this method is equivalent to
164 * {@link com.sun.jdi.VirtualMachine#resume}. If the
165 * suspend policy is
166 * {@link com.sun.jdi.request.EventRequest#SUSPEND_EVENT_THREAD},
167 * a call to this method is equivalent to
168 * {@link com.sun.jdi.ThreadReference#resume} for the event thread.
169 * Otherwise, a call to this method is a no-op.
170 */
171 void resume();
172 }