IN THIS APPENDIX
This appendix summarizes the public and protected members of the Thread 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 some 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 Thread 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 Thread, which in turn checks to see if a SecurityManager has been installed, and if so, invokes its checkAccess(Thread) 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.
The only publicly accessible member variables are used to specify the range of priority values that can be passed to setPriority().
public static final int MAX_PRIORITY
The highest thread-scheduling priority that can be passed to setPriority() for a particular VM. Generally, it is 10 for an application and 6 for an applet. Threads running at this level might hog the processor and should be designed to block frequently to give other threads a chance to run. See Chapter 6, "Thread Prioritization," for more information.
public static final int MIN_PRIORITY
The lowest thread-scheduling priority that can be passed to setPriority() for a particular VM. Generally, it is 1. Threads running at this priority might not get much processor time and might not get any if there are other higher-priority threads running. See Chapter 6 for more information.
public static final int NORM_PRIORITY
A not-too-high, not-too-low thread-scheduling priority for setPriority(). Generally, it is 5. Threads running at this priority usually get a chance to run without hogging the processor. See Chapter 6 for more information.
Several constructors are available for creating new Thread instances. Most of them are variations on the main constructor with certain values defaulted.
public Thread(ThreadGroup group, Runnable target, String name)
throws SecurityException
Creates a new thread that belongs to group, executes the run() method of target, and is named name. This is the main constructor for Thread that is invoked indirectly by the other constructors.
The new Thread will belong to the ThreadGroup referenced by group. If group is null, the new Thread will belong to the same ThreadGroup as the thread that constructed it (Thread.currentThread().getThreadGroup()). A SecurityException is thrown if the thread that invoked the constructor is not permitted by the SecurityManager to add a thread to the specified ThreadGroup.
When the thread is started, the run() method of the Runnable referenced by target will be invoked. When run() returns, the thread dies. If target is null, the run() method of the Thread itself will be invoked (typically this will have been overridden in a subclass to do something useful).
The thread will be named using name. If name is null, a NullPointerException will be thrown. To automatically generate a name for the thread, use a different constructor.
The new Thread will have the same priority, daemon status, and context class loader as the Thread that creates it. These settings can be changed with setPriority(), setDaemon(), and setContextClassLoader(). See Chapter 3, "Creating and Starting a Thread," for more information.
public Thread(ThreadGroup group, Runnable target)
throws SecurityException
Equivalent to using the main constructor like this: Thread(group, target, genName), where genName is an automatically generated name of the form Thread-16.
public Thread(ThreadGroup group, String name) throws SecurityException
Equivalent to using the main constructor like this: Thread(group, null, name).
public Thread(Runnable target, String name)
Equivalent to using the main constructor like this: Thread(null, target, name).
public Thread(Runnable target)
Equivalent to using the main constructor like this: Thread(null, target, genName), where genName is an automatically generated name of the form Thread-2.
Thread has several static methods that are used without reference to a specific thread. Generally, they implicitly refer to the current thread.
public static int activeCount()
Returns the number of active threads in the invoking thread's ThreadGroup. Convenience method for:
Thread.currentThread().getThreadGroup().activeCount()
See Chapter 10, "Thread Groups," for more information.
public static native Thread currentThread()
Returns a reference to the Thread object associated with the thread that invoked the method. Used in code to determine which thread is currently executing the section of code. See Chapter 3 for more information.
public static void dumpStack()
Used only during debugging to print a stack trace for the current thread. Convenience method for:
(new Exception("Trace")).printStackTrace()
public static int enumerate(Thread[] dest) throws SecurityException
Collects a reference to all the threads in the current thread's thread group (and recursively in all its subgroups) and copies these Thread references into dest. A SecurityException might be thrown if the operation is not allowed (by the checkAccess() method of ThreadGroup). 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. This is a convenience method for:
Thread.currentThread().getThreadGroup().enumerate(dest)
See Chapter 10 for more information.
public static boolean interrupted()
Returns the interrupted status of the current thread and sets the status false. If this method is called twice in a row, the second call will always return false (provided that the current thread is not re-interrupted between calls!). Related methods: interrupt() and isInterrupted(). See Chapter 5, "Gracefully Stopping Threads," for more information.
public static native void sleep(long ms) throws InterruptedException
Causes the current thread to stop execution for the specified number of milliseconds (approximately). If the thread is interrupted while sleeping, it wakes up early and throws an InterruptedException. Unlike the wait() method on Object, sleep() does not release any locks while resting. Related method: interrupt(). See Chapter 3 for more information.
public static void sleep(long ms, int nanoseconds)
throws InterruptedException
Causes the current thread to stop execution for the specified number of milliseconds plus the specified number of nanoseconds (approximately). If the thread is interrupted while sleeping, it wakes up early and throws an InterruptedException. Unlike the wait() method on Object, sleep() does not release any locks while resting. Related method: interrupt(). See Chapter 3 for more information.
public static native void yield()
Causes the current thread to yield the processor to other threads. Generally only threads of equal priority that were waiting to run get a chance. Depending on the VM implementation, lower-priority threads might or might not get a chance to run. This method can be used to better share the processor resources. Related method: Thread.sleep(). See Chapter 6 for more information.
The instance methods refer to a specific thread, unlike the static methods that refer to the current thread.
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 Thread. It throws a SecurityException if the current thread is denied access. Many other methods of Thread invoke checkAccess() internally.
public void destroy()
Destroys the thread without any cleanup. Still not implemented as of JDK 1.2—it will throw a NoSuchMethodError if called.
public ClassLoader getContextClassLoader() throws SecurityException
Returns the context ClassLoader for this thread. SecurityException might be thrown if the current thread is not allowed to access the class loader. Related method: setContextClassLoader().
public final String getName()
Returns the name of the thread. Related method: setName(). See Chapter 3 for more information.
public final int getPriority()
Returns the priority of the thread. Related method: setPriority(). Related variables: Thread.MAX_PRIORITY, Thread.MIN_PRIORITY, and Thread.NORM_PRIORITY. See Chapter 6 for more information.
public final ThreadGroup getThreadGroup()
Returns the ThreadGroup to which the thread belongs if the thread is still alive, or null if it has died.
public void interrupt() throws SecurityException
Interrupt this thread by setting its interrupted status to true. This will cause some blocking methods like the wait() method on Object and the sleep method on Thread to throw an InterruptedException. It can throw a SecurityException if the current thread is not permitted to access this thread. Related methods: isInterrupted(), Thread.interrupted(), and Thread.sleep(). See Chapter 5 for more information.
public final native boolean isAlive()
Returns true if this thread is still alive, false otherwise. A thread is considered to be alive from just after it has been started until just after the run() method returns. Related methods: start(), run(), stop(). See Chapter 5 for more information.
public final boolean isDaemon()
Returns true if this thread is a daemon thread, or false otherwise. A daemon thread continues to run only as long as there is at least one non-daemon thread still running in the VM. Related method: setDaemon(). See Chapter 5 for more information.
public boolean isInterrupted()
Returns the interrupted status of this thread and (unlike interrupted())does not change the status. Related methods: interrupt(), Thread.interrupted(). See Chapter 5 for more information.
public final void join() throws InterruptedException
Causes the current thread to block and wait an unlimited amount of time for this thread to die. It will throw an InterruptedException if interrupted while waiting for this thread to die. Related methods: join(long), join(long, int), interrupt(), and isAlive(). See Chapter 8, "Inter-thread Communication," for more information.
public final synchronized void join(long ms)
throws InterruptedException
Causes the current thread to block and wait ms milliseconds for this thread to die. It will throw an InterruptedException if interrupted while waiting for this thread to die. Related methods: join(), join(long, int), interrupt(), and isAlive(). See Chapter 8 for more information.
public final synchronized void join(long ms, int ns)
throws InterruptedException
Causes the current thread to block and wait ms milliseconds plus ns nanoseconds for this thread to die. It will throw an InterruptedException if interrupted while waiting for this thread to die. Related methods: join(), join(long), interrupt(), and isAlive(). See Chapter 8 for more information.
public void run()
If this method was not overridden in a subclass, it does nothing but call the run() method of the Runnable passed to the constructor. If no Runnable was specified, this method returns right away. When this method returns, the thread dies. Related method: start(). See Chapter 4, "Implementing Runnable Versus Extending Thread," for more information.
public void setContextClassLoader(ClassLoader newLoader)
throws SecurityException
Specifies a new class loader for this thread. Throws a SecurityException if the current thread is not permitted to modify this thread. Related method: getContextClassLoader().
public final void setDaemon(boolean newStatus)
throws SecurityException
If newStatus is true, this thread will be a daemon thread and will automatically die when no non-daemon threads are left running in the VM. If newStatus is false, this thread is a normal thread. This method must be called before this thread is started. It throws a SecurityException if the current thread is not permitted to modify this thread. Related method: isDaemon(). See Chapter 5 for more information.
public final void setName(String newName) throws SecurityException
Changes the name of this thread to newName. Throws a SecurityException if the current thread is not permitted to modify this thread. Related method: getName(). See Chapter 3 for more information.
public final void setPriority(int newPriority)
throws SecurityException, IllegalArgumentException
Changes the thread-scheduling priority of this thread to newPriority. If this thread's ThreadGroup has a maximum priority set for the group and newPriority exceeds that maximum, newPriority is silently reduced to the group's maximum allowable value. Throws an IllegalArgumentException if newPriority is not at least Thread.MIN_PRIORITY or if greater than Thread.MAX_PRIORITY. Throws a SecurityException if the current thread is not permitted to modify this thread. Related method: getPriority(). Related methods on ThreadGroup are setMaxPriority() and getMaxPriority(). See Chapter 6 for more information.
public native synchronized void start()
throws IllegalThreadStateException
Causes the VM to spawn a new thread that begins execution by calling run(); start() immediately returns. Throws IllegalThreadStateException (subclass of RuntimeException) if the thread has already been started. Related methods: run(), isAlive(), and stop(). See Chapter 3 for more information.
The methods in this section have been deprecated and should only be used if absolutely necessary. Alternatives for stop(), suspend(), and resume() are presented in Chapter 5.
public native int countStackFrames()
Deprecated! Counts the number of stack frames for a suspended thread.
public final void resume() throws SecurityException
Deprecated! Allows this thread to resume execution after being suspended. Throws a SecurityException if the current thread is not permitted to access this thread. Related method: suspend(). See Chapter 5 for more information.
public final void stop() throws SecurityException
Deprecated! Causes this thread to stop what it is doing and throw a ThreadDeath (subclass of Error). Throws a SecurityException if the current thread is not permitted to modify this thread. Related methods: start(), suspend(), resume(). See Chapter 5 for more information.
public final synchronized void stop(Throwable except)
throws SecurityException
Deprecated! Causes this thread to stop what it is doing and throw the Throwable object except. Throws a SecurityException if the current thread is not permitted to modify this thread. Related methods: stop(), start(), suspend(), resume(). See Chapter 5 for more information.
public final void suspend() throws SecurityException
Deprecated! Causes this thread to temporarily stop execution until the resume() method is invoked. Throws a SecurityException if the current thread is not permitted to modify this thread. Related methods: resume(), stop(). See Chapter 5 for more information.