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      */

   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 }