Wednesday, 19 December 2012

What is the meaning of Deprecated ? How and When To Deprecate APIs ..!

What "Deprecated" Means

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.
Java provides a way to express deprecation because, as a class evolves, its API (application programming interface) inevitably changes: methods are renamed for consistency, new and better methods are added, and fields change. But such changes introduce a problem. You need to keep the old API around until developers make the transition to the new one, but you don't want them to continue programming to the old API.
The ability to deprecate a class, method, or member field solves the problem. Java supports two mechanisms for deprecation: and an annotation, (supported starting with J2SE 5.0) and a Javadoc tag (supported since 1.1). Existing calls to the old API continue to work, but the annotation causes the compiler to issue a warning when it finds references to deprecated program elements. The Javadoc tag and associated comments warn users against using the deprecated item and tell them what to use instead.

When to Deprecate

When you design an API, carefully consider whether it supersedes an old API. If it does, and you wish to encourage developers (users of the API) to migrate to the new API, then deprecate the old API. Valid reasons to deprecate an API include:
  • It is insecure, buggy, or highly inefficient
  • It is going away in a future release
  • It encourages bad coding practices
Deprecation is a reasonable choice in all these cases because it preserves "backward compatibility" while encouraging developers to change to the new API. Also, the deprecation comments help developers decide when to move to the new API, and so should briefly mention the technical reasons for deprecation.
It is not necessary to deprecate individual member fields (properties) of a deprecated class, unless of course you want to explain a specific point about a property.

How to Deprecate

Starting with J2SE 5.0, you deprecate a class, method, or field by using the @Deprecated annotation. Additionally, you can use the @deprecated Javadoc tag tell developers what to use instead.
Using the annotation causes the Java compiler to generate warnings when the deprecated class, method, or field is used. The compiler suppresses deprecation warnings if a deprecated compilation unit uses a deprecated class, method, or field. This enables you to build legacy APIs without generating warnings.
You are strongly recommended to use the Javadoc @deprecated tag with appropriate comments explaining how to use the new API. This ensures developers will have a workable migration path from the old API to the new API. For more information, see Using the @deprecated Javadoc Tag.
NOTE: The Java Language Specification requires compilers to issue warnings when classes, methods, or fields marked with the @Deprecated annotation are used. Compilers are not required by the Java Language Specification to issue warnings when classes, methods, or fields marked with the @deprecated Javadoc tag are accessed, although the Sun compilers currently do so. However, there is no guarantee that the Sun compiler will always issue such warnings.

Using the @Deprecated Annotation

J2SE 5.0 introduces a new language feature called annotations (also called metadata). One of the Java language's built-in annotations is the @Deprecated annotation. To use it, you simply precede the class, method, or member declaration with "@Deprecated."
Using the @Deprecated annotation to deprecate a class, method, or field ensures that all compilers will issue warnings when code uses that program element. In contrast, there is no guarantee that all compilers will always issue warnings based on the @deprecated Javadoc tag, though the Sun compilers currently do so. Other compilers may not issue such warnings. Thus, using the @Deprecated annotation to generate warnings is more portable that relying on the @deprecated Javadoc tag.
In addition, the @Deprecated annotation causes the javadoc-generated documentation to be marked "Deprecated" wherever that program element appears.
NOTE: Deprecation applies to classes and to individual methods or properties, not to their names. It is possible for a single method to have deprecated and non-deprecated overloadings. It is possible for a non-deprecated property to hide or override a deprecated one, which removes deprecation. As developer of an API, it is your responsibility to deprecate overrides of a deprecated method, if in fact they should be deprecated.


The following is a simple example of using the @Deprecated annotation from java.lang.Thread:
class Thread implements Runnable {
    public final void stop() {
  synchronized (this) {

Using the @deprecated Javadoc Tag

You can use the @deprecated tag to make Javadoc show a program element as deprecated. The @deprecated tag must be followed by a space or newline. In the paragraph following the @deprecated tag, explain why the item has been deprecated and suggest what to use instead.
Javadoc generates special HTML based on @deprecated tags: it moves the paragraph following the @deprecated tag to the front of the description, placing it in italics and preceding it with a warning, "Note: foo is deprecated", in bold. It also adds "Deprecated" in bold to any index entries mentioning the deprecated entity.
The tagged paragraph can be empty, but empty deprecation paragraphs are bad form, because they do not help the user fix the warnings that arise from the deprecation. Include paragraphs marked with @link or@see tags that refer to the new versions of the same functionality. It is usually not a good idea to mention a timetable for phase-out of the deprecated API; this is a business decision that is best communicated other ways.
For more information on using the @deprecated Javadoc tag, see Javadoc - The Java API Documentation Generator.


The following examples show how to use the @deprecated Javadoc tag. They also illustrate the @Deprecated annotation, to emphasize that the two should be used together.
Here is an example of the most common form of a deprecated method (for Javadoc 1.2 and later):
 * @deprecated  As of release 1.3, replaced by {@link #getPreferredSize()}
@Deprecated public Dimension preferredSize() {
return getPreferredSize();
If the API reorganization was more than renaming, the deprecation may be more complex. Here is an example of a method that is being retracted:
 * Delete multiple items from the list.
 * @deprecated  Not for public use.
 *    This method is expected to be retained only as a package
 *    private method.  Replaced by
 *    {@link #remove(int)} and {@link #removeAll()}
@Deprecated public synchronized void delItems(int start, int end) {


  1. I was wondering if you ever considered changing the layout of your website?
    Its very well written; I love what youve got to say.
    But maybe you could a little more in the way of content so people could connect
    with it better. Youve got an awful lot of
    text for only having 1 or 2 pictures. Maybe you could space it out better?
    Also visit my web page : cheap ways to make money online

  2. I'm not sure where you're getting your information, but good
    topic. I needs to spend some time learning more or understanding more.
    Thanks for magnificent information I was looking for this information for my mission.
    Review my blog :: play slots online for real cash

  3. Hey I know this is off topic but I was wondering if you knew of any widgets I
    could add to my blog that automatically tweet my newest
    twitter updates. I've been looking for a plug-in like this for quite some time and was hoping maybe you would have some experience with something like this. Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to your new updates.
    My homepage ; play slots online for money

  4. Awesome things here. I'm very glad to look your article. Thanks so much and I'm looking forward to contact you.
    Will you kindly drop me a e-mail?
    Feel free to visit my web site ; Free Slots Real Money

  5. Thanκfulness to my fаtheг whо shared with mе abоut thіs blog,
    this website іs in fact awesome.

    Feel fгee to visіt my website: diamondlinks review

  6. Beachbody, Inc.'s P90 X program consists of 12 workout each P90 X Workout Schedule for those that don't understand.
    The three options order of p90x ab ripper are provides a highly bioavailable
    source of essential amino acids. It gives you much of the information leave them behind?

    my site :: how to p90x program

  7. we desire samsung laser printer vehicle driver.

    my webpage; xerox phaser 8560mfp ink

  8. Howdy would you mind letting me know which webhost you're working with? I've
    loaded your blog in 3 different internet browsers
    and I must say this blog loads a lot faster then most.
    Can you suggest a good internet hosting provider at a reasonable price?
    Many thanks, I appreciate it!

    my web site ... Acne treatment


Related Posts Plugin for WordPress, Blogger...