32

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.

Improve this question

4 Answers 4

Reset to default
67

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

Improve this answer
Sign up to request clarification or add additional context in comments.

4 Comments

Thanks, I overlooked throwing an exception. It seems this is my best choice.
Would I have to use @Override as well to ensure that the base class function is not used?
@Override isn't necessary for overriding to work - it's just a helpful annotation that tells you when you intend to override a method and makes the compiler warn you if you actually didn't (because you misspelled it or something). The base class function will not be used in the subclass if an override exists, regardless of whether it has @Override.
Throwing an exception like that means that you didn't deprecate the function, you actually removed it. However, you did so in a way that is noticed at runtime instead of at compile time. In that case you should just remove the function, so it's clear at compile time that you can't do that.
18

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. */
Improve this answer

1 Comment

I need the method in the base class. :/
5

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

Improve this answer

Comments

3

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 .

Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.