Tuesday July 14, 2009 Joseph D. Darcy's Sun Weblog
Joseph D. Darcy's Sun Weblog
Tuesday July 14, 2009
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
(4941777,
6583872).
When an API element is deprecated,
the recommended practice is to both apply the
@Deprecated annotation
as well as use the
"@deprecated"
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.
Post a Comment:
Comments are closed for this entry.
Calendar
| « November 2009 | ||||||
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
1 | 2 | 3 | 5 | 6 | 7 | |
8 | 9 | 10 | 11 | 12 | 13 | 14 |
15 | 16 | 17 | 19 | 20 | 21 | |
22 | 23 | 24 | 25 | 26 | 27 | 28 |
29 | 30 | |||||
| Today | ||||||
RSS Feeds
All
/Annotation Processing
/General
/Java
/JavaOne
/Numerics
/OpenJDK
Search
Links
- Blogroll
-
- News
Navigation
Referers
Today's Page Hits: 836
Thanks, that was nice to hear about!
Posted by James Stansell on July 15, 2009 at 06:42 AM PDT #
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?
Posted by Luke on July 15, 2009 at 10:12 AM PDT #
@Luke,
To date, we have valued continued binary compatibility with code calling the deprecated elements more than cleaning up the API.
Posted by Joe Darcy on July 15, 2009 at 11:04 AM PDT #
Joe,
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.
Posted by Gili on July 27, 2009 at 03:15 PM PDT #
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).
Posted by Ben on August 04, 2009 at 04:31 AM PDT #
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.
Posted by Justin Lee on August 07, 2009 at 03:58 PM PDT #
@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.
Posted by Joe Darcy on August 08, 2009 at 11:22 AM PDT #