Musings on JDK development

  • Java
    July 14, 2009

Deprecation in the JDK

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
Vector and Hashtable.
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
@Deprecated annotation
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.

Join the discussion

Comments ( 7 )
  • James Stansell Wednesday, July 15, 2009

    Thanks, that was nice to hear about!

  • Luke Wednesday, July 15, 2009

    I understand the imperative business need to maintain backward compatibility in the Java language and API, but what I don't understand is why no API (class or even method) ever gets \*eliminated\*.

    Take the deprecated elements of java.util.Date. I believe they've been deprecated for several versions but there's no plan to eliminate them. Why can't there be a rule that any API element that's deprecated for two versions gets eliminated in the next version?

  • Joe Darcy Wednesday, July 15, 2009


    To date, we have valued continued binary compatibility with code calling the deprecated elements more than cleaning up the API.

  • Gili Monday, July 27, 2009


    I understand Sun's point of view, but I tend to agree with Luke.

    Also, I'm not sure I understand the value of adding a less-harmful-than-deprecration annotation. I would prefer if there was only one kind of annotation (deprecation) and it was applied to the aforementioned cases. Boolean's default constructor should be deprecated. In the rare case where its usage is warranted users can use @SuppressWarning.

  • Ben Tuesday, August 4, 2009

    Maybe you need a more severe annotation, like @Removed. Keep the implementation there (to preserve binary compatibility), but make usage of an API with this annotation a compiler error (to break source compatibility).

  • Justin Lee Friday, August 7, 2009

    If it's not too late, Ben's idea should go into project coin. I've blogged a bit of an expansion of the idea here: http://www.antwerkz.com/re-deprecation-in-the-jdk/ . It's a \*really\* simple change that'd make for a big impact.

  • Joe Darcy Saturday, August 8, 2009

    @Justin and @Ben,

    Hmmm, today by default javac doesn't use rt.jar when compiling, it uses a separate file, ct.sym, which hides various JDK implementation classes. It should be possible to strip out the deprecated elements from ct.sym too.

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.