Difference between a deprecated and a legacy API?

by

From the official Sun glossary:

deprecation: Refers to a class, interface, constructor, method or field that is no longer recommended, and may cease to exist in a future version.

From the how-and-when to deprecate guide:

You may have heard the term, “self-deprecating humor,” or humor that minimizes the speaker’s importance. A deprecated class or method is like that. It is no longer important. It is so unimportant, in fact, that you should no longer use it, since it has been superseded and may cease to exist in the future.

The @Deprecated annotation went a step further and warn of danger:

A program element annotated @Deprecated is one that programmers are discouraged from using, typically because it is dangerous, or because a better alternative exists.

References

Note that the official glossary does not define what “legacy” means. In all likelihood, it may be a term that Josh Bloch used without an exact definition. The implication, though, is always that a legacy class should never be used in new code, and better replacement exists.

Perhaps an old code using legacy but non-deprecated class requires no action, since for now at least, they aren’t in danger of ceasing to exist in future version.

In contrast, deprecation explicitly warns that they may cease to exist, so action should be taken to migrate to the replacement.

Quotes from Effective Java 2nd Edition

For comparison on how these terms are used in context, these are quotes from the book where the word “deprecated” appears:

Item 7: Avoid finalizers: The only methods that claim to guarantee finalization are System.runFinalizersOnExit and its evil twin Runtime.runFinalizersOnExit. These methods are fatally flawed and have been deprecated.

Item 66: Synchronize access to shared mutable data: The libraries provide the Thread.stop method, but this method was deprecated long ago because it’s inherently unsafe — its use can result in data corruption.

Item 70: Document thread safety: The System.runFinalizersOnExit method is thread-hostile and has been deprecated.

Item 73: Avoid thread groups: They allow you to apply certain Thread primitives to a bunch of threads at once. Several of these primitives have been deprecated, and the remainder are infrequently used. […] thread groups are obsolete.

By contrast, these are the quotes where the word “legacy” appears:

Item 23: Don’t use raw types in new code: They are provided for compatibility and interoperability with legacy code that predates the introduction of generics.

Item 25: Prefer lists to arrays: Erasure is what allows generic types to interoperate freely with legacy code that does not use generics.

Item 29: Consider typesafe heterogeneous containers: These wrappers are useful for tracking down who adds an incorrectly typed element to a collection in an application that mixes generic and legacy code.

Item 54: Use native methods judiciously: They provide access to libraries of legacy code, which could in turn provide access to legacy data. […] It is also legitimate to use native methods to access legacy code. […] If you must use native methods to access low-level resources or legacy libraries, use as little native code as possible and test it thoroughly.

Item 69: Prefer concurrency utilities to wait and notify: While you should always use the concurrency utilities in preference to wait and notify, you might have to maintain legacy code that uses wait and notify.

These quotes were not carefully selected: they’re ALL instances where the word “deprecated” and “legacy” appear in the book. Bloch’s message is clear here:

  • Deprecated methods, e.g. Thread.stop, are dangerous, and should never be used at all.
  • On the other hand, e.g. wait/notify can stay in legacy code, but should not be used in new code.

My own subjective opinion

My interpretation is that deprecating something is admitting that it is a mistake, and was never good to begin with. On the other hand, classifying that something is a legacy is admitting that it was good enough in the past, but it has served its purpose and is no longer good enough for the present and the future.

More Related Contents:

  1. When to use LinkedList over ArrayList in Java?
  2. Java 8 Distinct by property
  3. How can I turn a List of Lists into a List in Java 8?
  4. How to convert int[] into List in Java?
  5. How can I initialise a static Map?
  6. How to count the number of occurrences of an element in a List
  7. Which is more efficient, a for-each loop, or an iterator?
  8. Which Java Collection should I use?
  9. Convert an array of primitive longs into a List of Longs
  10. Is there a common Java utility to break a list into batches?
  11. How can I convert int[] to Integer[] in Java?
  12. Sorted collection in Java
  13. Why can Java Collections not directly store Primitives types?
  14. Immutable vs Unmodifiable collection [duplicate]
  15. Identify duplicates in a List
  16. Removing items from a list [duplicate]
  17. Collections.synchronizedList and synchronized
  18. Converting ArrayList of Characters to a String?
  19. Casting an array of Objects into an array of my intended class
  20. How Iterator’s remove method actually remove an object
  21. loop on list with remove [duplicate]
  22. How do you query object collections in Java (Criteria/SQL-like)?
  23. Remove empty collections from a JSON with Gson
  24. best way to pick a random subset from a collection?
  25. Is it possible in java make something like Comparator but for implementing custom equals() and hashCode()
  26. Map that could be iterated in the order of values
  27. Why does TreeSet throw a ClassCastException?
  28. Shortcut for adding to List in a HashMap
  29. ArrayList vs. Vectors in Java if thread safety isn’t a concern
  30. How to do map inversion with Guava with non-unique values?

Leave a Comment