Name: jk109818 Date: 01/28/2002


FULL PRODUCT VERSION :
java version "1.3.1_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_01a)
Java HotSpot(TM) Client VM (build 1.3.1_01, mixed mode)

FULL OPERATING SYSTEM VERSION :
N/A

ADDITIONAL OPERATING SYSTEMS :
N/A


A DESCRIPTION OF THE PROBLEM :
There is a very bad and incorrect example in the
documentation for java.lang.Thread.Thread(). It declares a
Thread-inherited class, but then ignores it and instead
instantiates a new Thread instance (which does not override
run()), and then it acts as if 'new' returning 'null'
somehow indicated that a thread could not be started, even
though 'new' can never return null in Java! Pretty much
everything about this example is wrong. Please fix it.

Some other problems with the Thread class documentation:
1) The class should probably state at least SOMETHING about
the minimum number of supported priorities that can be
assumed. As it is, the only priorities that can be assumed
to exist and be distinct are NORMAL, MIN_PRIORITY, and
MAX_PRIORITY. It is also not clear to what degree (if any)
aliasing of priorities to operating system priorities can
occur: Does a thread running at NORMAL_PRIORITY+1 prevent
execution of a thread running at NORMAL_PRIORITY? Or could
they be mapped to the same operating system priority?

2) It is not clear whether calling setPriority() on the
currently executing thread is guaranteed to result in
immediate rescheduling. (so that, for instance, if the
thread is not now the highest-priority thread, that it will
immediately pause so that that thread can run.)

3) It is not clear what is meant by the phrase "Threads
with higher priority are executed in preference to threads
with lower priority" -- is this intended to mean that if a
high-priority thread is scheduled and executable, that a
low-priority thread cannot run at all? Or that the high-
priority thread will get twice as many timeslices? or ...?
This kind of vagueness makes it difficult to use priorities
for much of anything.


STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Read the documentation.
2. Note that it is broken.


This bug can be reproduced always.
(Review ID: 138380)
======================================================================