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;
27
28import java.util.List;
29
30/**
31 * A thread group object from the target VM.
32 * A ThreadGroupReference is an {@link ObjectReference} with additional
33 * access to threadgroup-specific information from the target VM.
34 *
35 * @author Robert Field
36 * @author Gordon Hirsch
37 * @author James McIlree
38 * @since  1.3
39 */
40public interface ThreadGroupReference extends ObjectReference {
41
42    /**
43     * Returns the name of this thread group.
44     *
45     * @return the string containing the thread group name.
46     */
47    String name();
48
49    /**
50     * Returns the parent of this thread group.
51     *
52     * @return a {@link ThreadGroupReference} mirroring the parent of this
53     * thread group in the target VM, or null if this is a top-level
54     * thread group.
55     */
56    ThreadGroupReference parent();
57
58    /**
59     * Suspends all threads in this thread group. Each thread
60     * in this group and in all of its subgroups will be
61     * suspended as described in {@link ThreadReference#suspend}.
62     * This is not guaranteed to be an atomic
63     * operation; if the target VM is not interrupted at the time
64     * this method is
65     * called, it is possible that new threads will be created
66     * between the time that threads are enumerated and all of them
67     * have been suspended.
68     * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
69     */
70    void suspend();
71
72    /**
73     * Resumes all threads in this thread group. Each thread
74     * in this group and in all of its subgroups will be
75     * resumed as described in {@link ThreadReference#resume}.
76     * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
77     */
78    void resume();
79
80    /**
81     * Returns a List containing a {@link ThreadReference} for each live thread
82     * in this thread group. Only the live threads in this immediate thread group
83     * (and not its subgroups) are returned.  A thread is alive if it
84     * has been started and has not yet been stopped.
85     *
86     * @return a List of {@link ThreadReference} objects mirroring the
87     * live threads from this thread group in the target VM.
88     */
89    List<ThreadReference> threads();
90
91    /**
92     * Returns a List containing each active {@link ThreadGroupReference} in this
93     * thread group. Only the active thread groups in this immediate thread group
94     * (and not its subgroups) are returned.
95     * See {@link java.lang.ThreadGroup}
96     * for information about 'active' ThreadGroups.
97     * @return a List of {@link ThreadGroupReference} objects mirroring the
98     * active thread groups from this thread group in the target VM.
99     */
100    List<ThreadGroupReference> threadGroups();
101}
102