CODEWITHSUNDEEP
javaannotations
JustinDanielson
JustinDanielson

Reputation: 3185

Java Function Annotation Help, use @Deprecated?

Scenario:
Java 1.6

class Animal { 
    private String name; 
    ...  
    public String getName() { return name; }  
    ...
}

class CatDog extends Animal {
    private String dogName;
    private String catName;
    ...
    public String getDogName() { return dogName; }
    public String getCatName() { return catName; }
    public String[] getNames() { return new String[]{ catName, dogName }; }
    ...
    public String getName() { return "ERROR! DO NOT USE ME"; }
}

Problem:
getName doesn't make sense and shouldn't be used in this example. I'm reading about @Deprecated annotation. Is there a more appropriate annotation method?

Questions:
A) Is it possible to force an error when this function is used (before runtime)?
B) Is there a way to display a customized warning/error message for the annotation method I will use? Ideally when the user is hovering over deprecated/error function.

Upvotes: 32

Views: 43338

Answers (4)

Sarvar Nishonboyev
Sarvar Nishonboyev

Reputation: 13090

After refactoring our User class, we could not remove userGuid property, because it was used by mobile apps. Therefore, I have marked it as deprecated. The good thing is dev tools such as IntellijIdea recognize it and shows the message.

public User {
    ...

    /**
     * @Deprecated userGuid equals to guid but SLB mobile app is using user_guid.
     * This is going to be removed in the future.
     */
    @Deprecated
    public String getUserGuid() {
        return guid;
    }
}

enter image description here

Upvotes: 5

Erich Musick
Erich Musick

Reputation: 192

Deprecated is the way to go ... you can also configure the compiler to flag certain things as an error as opposed to a warning, but as Edward pointed out, you generally deprecate a method so that you don't have to completely clean up all references to it at this point in time.

In Eclipse, to configure Errors and Warnings, go to Window -> Preferences. Under Java -> Compiler -> Errors/Warnings, you'll see a section for Deprecated APIs. You may choose to instruct the compiler to ignore, warn, or error when a method is deprecated. Of course, if you're working with other developers, they would have to configure their compiler the same way .

Upvotes: 3

Edward
Edward

Reputation: 6292

Generally, you use @Deprecated for methods that have been made obsolete by a newer version of your software, but which you're keeping around for API compatibility with code that depends on the old version. I'm not sure if it's exactly the best tag to use in this scenario, because getName is still being actively used by other subclasses of Animal, but it will certainly alert users of the CatDog class that they shouldn't call that method.

If you want to cause an error at compile time when that function is used, you can change your compiler options to consider use of @Deprecated methods to be an error instead of a warning. Of course, you can't guarantee that everyone who uses your library will set this option, and there's no way I know of to force a compile error just based on the language specification. Removing the method from CatDog will still allow clients to call it, since the client will just be invoking the default implementation from the superclass Animal (which presumably you still want to include that method).

It is certainly possible, however, to display a custom message when the user hovers over the deprecated method. The Javadoc @deprecated tag allows you to specify an explanation of why a method was deprecated, and it will pop up instead of the usual description of the method when the user hovers over the method in an IDE like Eclipse. It would look like this:

/**
 * 
 * @deprecated Do not use this method!
 */
 @Deprecated
 public String getName() {
     throw new UnsupportedOperationException();
 }

(Note that you can make your implementation of the method throw an exception to guarantee that if the user didn't notice the @Deprecated tag at compile time, they'll definitely notice it at runtime).

Upvotes: 67

Voo
Voo

Reputation: 30216

Deprecation means the method shouldn't be used any longer and that it may be removed in future releases. Basically exactly what you want.

Yes there's a trivially easy way to get a compile error when someone tries to use the method: Remove the method - that'll cause errors at linktime for any code that tries to use it, generally not to be recommended for obvious reasons, but if there's a really good reason to break backwards compatibility, that's the easiest way to achieve it. You could also make the method signature incompatible (always possible), but really the simplest solution that works is generally the best.

If you want a custom message when someone hovers over the method, use the javadoc for it, that's exactly what it's there for:

/**
     * @deprecated
     * explanation of why function was deprecated, if possible include what 
     * should be used.
     */

Upvotes: 18

Related Questions