IN THIS APPENDIX
This appendix summarizes the public and protected members of the ThreadGroup class. It is based on Sun Microsystems'Java Development Kit 1.2. Information has been combined from Sun's API documentation, source code, reflection on the distributed classes, and the Java Language Specification.
Many of the methods and both of the constructors can throw a SecurityException. SecurityException is a subclass of RuntimeException, so try/catch blocks are not required for any of the methods of ThreadGroup that might throw it. By default, an application does not have a SecurityManager defined (using JDK 1.0, 1.1, or 1.2 from Sun Microsystems). An applet, on the other hand, might have a SecurityManager present. In general, this exception is thrown when the calling thread is not permitted to perform the requested action. Many times, the security check is done by invoking the checkAccess() method on ThreadGroup, which in turn checks to see if a SecurityManager has been installed, and if so, invokes its checkAccess(ThreadGroup) method. For most of your application programming, you can safely ignore the possibility of a SecurityException being thrown.
Throughout this appendix, the terms "this thread" and "current thread" are used. The "current thread" term refers to the thread that invoked the method. The "this thread" term refers to the Thread instance that the method will affect. For example, suppose threadA executes the following statement:
threadB.checkAccess();
threadA would be considered the "current thread," and threadB would be considered "this thread." The API documentation for checkAccess() would read something like, "throws a SecurityException if the current thread is not permitted to access this thread." This translates to "throws a SecurityException if threadA is not permitted to access threadB." It's a subtle difference worth noticing.
Two constructors exist for creating new thread groups.
public ThreadGroup(ThreadGroup parentGroup, String groupName)
throws SecurityException
Creates a new ThreadGroup that is a child group of parentGroup and has the name groupName. The parent group's checkAccess() method is invoked to see if the current thread is allowed to create a new ThreadGroup in parentGroup, which can result in a SecurityException being thrown. If parentGroup is null, a NullPointerException will be thrown.
The new ThreadGroup will have the same maximum thread priority and daemon status as its parent. These can be changed with setMaxPriority() and setDaemon(). See Chapter 10 for more information.
There are no static methods on ThreadGroup; all the methods are instance methods.
public int activeCount()
Returns the number of active threads in this thread group and all its subgroups. Related method: enumerate(). See Chapter 10 for more information.
public int activeGroupCount()
Returns the number of active thread groups in this thread group and all its subgroups.
public final void checkAccess() throws SecurityException
Checks to see if there is a SecurityManager and if it will allow the current thread to access this ThreadGroup. Throws a SecurityException if the current thread is denied access. Many other methods of ThreadGroup invoke checkAccess() internally.
public final void destroy()
throws SecurityException, IllegalThreadStateException
Destroys this thread group and all its subgroups. If any of the groups is not empty (meaning that all the threads within have not died), an IllegalThreadStateException will be thrown. It throws a SecurityException if the current thread is denied access to this thread group.
public int enumerate(Thread[] dest, boolean includeSubgroups)
throws SecurityException
Collects a reference to all the threads in this thread group (and recursively all its subgroups if includeSubgroups is true) and copies these Thread references into dest. A SecurityException can be thrown if the operation is not allowed by checkAccess(). The number of references copied into dest is returned. If dest is too small, the extra Thread references are quietly thrown away. The activeCount() method can be used to estimate the size needed for the dest array. In general, dest should be about twice the size you think you'll need to be sure that all the threads get copied into it. Related methods: activeCount(), enumerate(Thread[]). See Chapter 10 for more information.
public int enumerate(Thread[] dest) throws SecurityException
public int enumerate(ThreadGroup[] dest, boolean includeSubgroups)
throws SecurityException
Collects a reference to all the thread groups in this thread group (and recursively all its subgroups if includeSubgroups is true) and copies these ThreadGroup references into dest. A SecurityException can be thrown if the operation is not allowed by checkAccess(). The number of references copied into dest is returned. If dest is too small, the extra ThreadGroup references are quietly thrown away. The activeGroupCount() method can be used to estimate the size needed for the dest array. In general, dest should be about twice the size you think you'll need to be sure that all the thread groups get copied into it. Related methods: activeGroupCount(), enumerate(ThreadGroup[]).
public int enumerate(ThreadGroup[] dest) throws SecurityException
public final int getMaxPriority()
Returns the maximum priority that any thread in this group or one of its subgroups can have. Related method: setMaxPriority(). See Chapters 6 and 10 for more information.
public final String getName()
Returns the name of this thread group. See Chapter 10 for more information.
public final ThreadGroup getParent() throws SecurityException
Returns the parent thread group of this thread group, or null if this thread group does not have a parent (top thread group). A SecurityException can be thrown if the parent is not null and its checkAccess() method disapproves. See Chapter 10 for more information.
public final void interrupt() throws SecurityException
Interrupts all the threads in this thread group and all its subgroups. A SecurityException can be thrown if any of the threads or thread groups disapprove. See Chapter 5 for more information.
public final boolean isDaemon()
Returns true if this thread group is a daemon thread group, false otherwise. A daemon thread group is automatically destroyed when the last of its threads dies. Related method: setDaemon().
public synchronized boolean isDestroyed()
Returns true if this thread group has been destroyed, false otherwise. Related method: destroy().
public void list()
Dumps information about all the threads in this thread group and all its subgroups to System.out by invoking toString() on each Thread. Really only useful for debugging.
public final boolean parentOf(ThreadGroup group)
Returns true if this thread group is an ancestor of group, false otherwise. Related method: getParent().
public final void setDaemon(boolean newStatus)
throws SecurityException
If newStatus is true, this thread group will be automatically destroyed when all its threads have died. Otherwise, if newStatus is false, it will be a normal thread group. A SecurityException will be thrown if the current thread does not have permission to modify this thread group. Related method: isDaemon().
public final void setMaxPriority(int newMax) throws SecurityException
Sets the maximum priority that a thread in this thread group (and all its subgroups) can have. Threads already running at a priority higher than this are not affected. A SecurityException will be thrown if the current thread does not have permission to modify this thread group. Related method: getMaxPriority().
public String toString()
Returns a string representation of this thread group including its name and maximum thread priority.
public void uncaughtException(Thread deadThread, Throwable exception)
The Java VM calls this method when a thread in this thread group throws an Exception or Error that is not caught inside run(). The thread that did not catch the exception is deadThread, and the Throwable that it did not catch is exception. This method can be over-ridden in a subclass of ThreadGroup to intercept this information. If it is not overridden, the default behavior is for it to invoke the uncaughtException() method of this group's parent group. If this group does not have a parent and the Throwable is anything other than an instance of ThreadDeath, a stack trace is printed to System.err.
The methods in this section have been deprecated and should only be used if absolutely necessary.
public boolean allowThreadSuspension(boolean newState)
public final void resume() throws SecurityException
Deprecated! Resumes all the threads in this thread group (and its subgroups). A SecurityException will be thrown if the current thread does not have access permission. Related method: suspend(). See Chapter 10 for more information.
public final void stop() throws SecurityException
Deprecated! Stops all the threads in this thread group (and its subgroups). A SecurityException will be thrown if the current thread does not have access permission. Related methods: suspend() and resume(). See Chapter 10 for more information.
public final void suspend() throws SecurityException
Deprecated! Suspends all the threads in this thread group (and its subgroups). A SecurityException will be thrown if the current thread does not have access permission. Related method: resume(). See Chapter 10 for more information.