A quick note on the deprecation policy used in the JDK, a question which comes up from time to time.
The general policy for several feature releases is that core JDK components are only marked as
deprecated if they are actively harmful. If using a class or method is just ill-advised, that is usually not sufficient to earn the deprecated mark.
The platform javadoc falls short of deprecating, but does discourage the use of certain API elements,
from particular methods, like the no-arg
Boolean constructor, to entire classes, like
At some point, this kind of advice might be formalized with a less-harmful-than-deprecated "denigration" facility based a combination of javadoc tags and annotations to allow programmatic checks be made for usage of these less harmful API elements too
(title="Deprecate Boolean constructor">4941777,
title="(coll) Direct uninformed users away from Vector/Hashtable">6583872).
When an API element is deprecated,
the recommended practice is to both apply the
as well as use the
javadoc tag. Using the annotation places more of the semantics of the code in the source code proper as opposed to a comment while using the javadoc tag allows alternate functionality to be recommended along with the specification for the element.