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

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 actually said when these things are going away, or does "@deprecated" just mean you lose style points?

From stackoverflow

• 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...

  Simon : care to elaborate, or justify your position?

  Simon : that's better :-)

• If the deprecated methods went away, they could break existing code.

  While maintaining a clean API is important, the deprecated methods aren't getting in anyone's way. Sure, there are now better ways to do things, so new methods replace old ones. But there wouldn't be any gain made (besides a cleaner API) by getting rid of the old ones.

  Think of "deprecated" as meaning "outdated", but not necessarily "on the chopping block".

  jjnguy : I hope the core API doesn't use its own deprecated methods.

• Well, "not gone yet" and "never going away" are two very different things. Thats the whole point of deprecation. They can go away with any future release. Using them is an at your own risk proposition. Just be aware that some future release of the JDK may leave your code in an unusable state.

• Deprecated features features that are superseded and should be avoided. Although they remain in the JDK, they are discouraged as there are better methods available. The methods are left in the API to support backward compatibility, but should generally be avoided as they could be removed in future versions of the API.

  It is technically ok to use deprecated methods, but generally the reason it was deprecated in the first place was that a better/faster/cleaner API has been developed.

• Sun tend to be extremely paranoid when it comes to changes that impact backwards compatibility, so I wouldn't expect to see the methods go away any time soon.

  But deprecated methods could go away at any time in the future, and are normally deprecated for a reason - either because they're unreliable, because they have unpleasant side effects, or simply because there's a better or more elegant way of doing things. The JavaDoc for the method will normally detail which of these is the case and what the acceptable way of carrying out the same operation is these days. Quite frequently the deprecated method will have been replaced with an implementation that calls the 'correct' method anyway, so you're just adding a level of indirection anyway.

  You'll also have plenty of compilation warnings if you use these methods, which could be reason enough to avoid them in itself...

• 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...

  DoctaJonez : Even though they are unlikely to be removed, it is important to note why they have been deprecated. Usually it is because a method or class does not behave as expected in certain situations. This means that by using a deprecated method or class you risk introducing errors into your code.

• I've definitely seen deprecated functions go away - from old versions of Java to the current (I started on 1.1, and some stuff distinctly DID NOT WORK in 1.4).

  Other languages handle deprecation differently - Python has been known in the past, for example, to remove deprecated functionality after just a release or two.

• 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.

• I have a better recommendation: rather than telling him to use Calendar, you should switch to either JodaTime or JSR-310's pre-release version. Some methods on java.util.Date may be deprecated, but in my opinion the whole class should be deprecated, along with Calendar. The developers of JSR-310 seem to agree, although I doubt they'll ever bite the bullet and deprecate it.

  In no particular order, here's what's wrong with Date:

  • Its internal representation is milliseconds since the epoch; therefore, cannot represent dates before the epoch.

  • All of its useful methods (e.g. toString) first normalize the date according to the local timezone. When working with UTC Date instances, this can get really annoying; you're forced to use Calendar or you will make very bad errors.

  • Calendar. It just stinks. Might win the award for worst API ever.

  • Always represents an instant-in-time. No way to represent specific days, or specific years. No way to represent timezone-less dates values.

  • Has almost no useful methods. See e.g. JodaTime's fluent interface for doing date arithmetic.

  • Should have been named Datetime, considering that it is one.