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.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.Exported 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 */ suspendPolicy()153 int suspendPolicy(); 154 155 /** 156 * Return an iterator specific to {@link Event} objects. 157 */ eventIterator()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 */ resume()171 void resume(); 172 } 173