When are API methods marked "deprecated" actually going to go away?

Question

I'm code reviewing a change one of my co-workers just did, and he added a bunch of calls to Date.toMonth(), Date.toYear() and other deprecated Date methods. All these methods were deprecated in JDK 1.1, but he insists that it's ok to use them because they haven't gone away yet (we're using JDK 1.5) and I'm saying they might go away any day now and he should use Calendar methods.

Has Sun/Oracle actually said when these things are going away, or does @deprecated just mean you lose style points?

Answer 1

Regarding the APIs, ... it is not specified they will be removed anytime soon.

Incompatibilities in J2SE 5.0 (since 1.4.2):

Source Compatibility

[...]
In general, the policy is as follows, except for any incompatibilities listed further below:

Deprecated APIs are interfaces that are supported only for backwards compatibility. The javac compiler generates a warning message whenever one of these is used, unless the -nowarn command-line option is used. It is recommended that programs be modified to eliminate the use of deprecated APIs, though there are no current plans to remove such APIs – with the exception of JVMDI and JVMPI – entirely from the system.

Even in its How and When To Deprecate APIs, nothing is being said about a policy regarding actually removing the deprected APIs...

---

Update 10 years later, the new JDK9+ Enhanced Deprecation clarifies the depreciation policy.
See Jens Bannmann's answer for more details.
This is also detailed in this blog post by Vojtěch Růžička, following criticisms on JEP 277.

The convention for JDK is that once a JDK API is marked as forRemoval=true in a certain Java version, it will be removed in the directly following major Java release.
That means - when something is marked as forRemoval=true in Java 9, it is supposed to be completely removed in Java 10.
Keep that in mind when using API marked for removal.

Note that this convention applies only to JDK itself and third-party libraries are free to choose any convention they see fit.

Answer 2

They're not going away. That said, they're usually deprecated because a) they're dangerous ala Thread.stop(), or b) there is a better or at least more accepted way to do it. Usually deprecated method javadoc will give you a hint as to the better way. In your case, Calendar is the recommended way to do this.

While it's conceivable that they will be removed at some point in the future, I wouldn't bet on it. If anyone ever forks Java however, they'll probably be the first thing to go...

Answer 3

One problem is you'll see lots of compiler warnings about using deprecated methods. If you also use deprecations to gradually phase out your own code, the compiler warnings will get lost in the noise and lose significance.

Answer 4

tl;dr

As of JDK 17, all original java.util.Date methods still exist, but these and other APIs can now be explicitly marked for removal. Many other deprecated APIs have been removed recently.

Full Answer

Before JDK 9, no deprecated API in the JDK was ever removed (see 20 Years Of Java Deprecation). That release, as part of a feature called Enhanced Deprecation, introduced the @Deprecated(forRemoval=true) flag and added it to dozens of previously deprecated APIs.

Also, for the first time in the language's history, JDK 9 removed APIs (full list from the Java SE 9 Specification) which had been deprecated by JDK 8 due to being an obstacle for modularization.

Since then, each JDK release has removed further APIs which were previously marked for removal, most releases have also added the forRemoval flag to previously deprecated APIs or added entirely new for-removal deprecations (see table below).

Key takeaways

1. Deprecated-for-removal APIs are very likely to be removed soon. Do take this seriously. While they may not be removed in the next release (e.g. Thread.stop() marked forRemoval in JDK 9, but was not removed before JDK 11), it can happen quickly.
2. No deprecated API is safe as even APIs that have long been deprecated could be removed quite quickly now: one JDK release sets the forRemoval flag, the following one removes the API. For example, the APIs that were removed by JDK 10 have been deprecated for at least 20 years (since JDK 1.2), so long that some people may now be surprised.
3. Nowadays, deprecations and removal happen much more quickly as Oracle switched to a 6-month release cycle with JDK 10.

Notable removals & proposals

Release	Removed	Deprecated since	Proposed for removal
JDK 10 March 2018	Some APIs in the SecurityManager and Runtime classes (full list)	JDK 1.2	java.security.acl package, finalize() methods on certain I/O classes, several other previously deprecated APIs (full list)
JDK 11 September 2018	Thread.destroy() and Thread.stop(), several other methods and the Policy class (full list)	JDK 9 & 10	java.util.jar.Pack200 APIs (full list)
JDK 12 March 2019	finalize() methods of certain I/O classes (full list)	JDK 10	none
JDK 13 September 2019	Runtime.traceInstructions() and Runtime.traceMethodCalls() (full list)	JDK 9	javax.security.cert package, methods on java.lang.String related to the "text blocks" preview feature and a few other methods (full list)
JDK 14 March 2020	java.security.acl package and java.util.jar.Pack200 APIs (full list)	JDK 10 & 11	Thread.resume(), Thread.suspend() and related ThreadGroup methods; ConstantBootstraps(), Modifier() and ToolProvider() constructors (full list)
JDK 15 September 2020	ConstantBootstraps() and Modifier() constructors (full list)	JDK 14	java.rmi.activation package (full list)
JDK 16 March 2021	ToolProvider() constructor (full list)	JDK 14	Constructors of primitive wrapper classes such as Integer, Double or Boolean; ThreadGroup methods destroy(), stop(), isDaemon() and friends; URLDecoder() constructor; finalize() methods of certain color-related AWT classes (full list)
JDK 17 September 2021	java.rmi.activation package, URLDecoder() constructor (full list)	JDK 15 & 16	java.applet package, java.lang.SecurityManager and related APIs such as checkAccess() on Thread/ThreadGroup (full list)