I would like to make one of my methods "deprecated" = not used anymore.
But still I would like to have it in my API. I just want to show "warning" to anyone using that method.
How can I achieve that?
-
10Is @Deprecrated not an option for you?templatetypedef– templatetypedef2012-01-27 10:24:18 +00:00Commented Jan 27, 2012 at 10:24
-
28It is, but I did not know about it ... thats why I am asking the question :)Pavel Janicek– Pavel Janicek2012-01-27 10:26:02 +00:00Commented Jan 27, 2012 at 10:26
-
1See docs.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/…Raedwald– Raedwald2012-01-31 13:39:09 +00:00Commented Jan 31, 2012 at 13:39
-
5comments are not the place for answers!mattumotu– mattumotu2015-01-25 11:35:03 +00:00Commented Jan 25, 2015 at 11:35
Add a comment
|
8 Answers
Use @Deprecated on method.
Don't forget to add the @deprecated Javadoc tag:
/**
* Does some thing in old style.
*
* @deprecated use {@link #new()} instead.
*/
@Deprecated
public void old() {
// ...
}
4 Comments
Faizan Kazi
How do you link an external library? eg: com.hello.api.PublicController#new
asgs
@LinuxLars completely agreed! Java 9 added a couple of attributes to start making deprecation be taken seriously but adding another attribute
reason with a default value of "" couldn't have hurt
U. Windl
I'd wish the
@deprecated message in the comment could be added to @Deprecated (one spot to fix them all)...
JBStonehenge
What to do with an interface/implementation scenario? Set the method deprecated also in the Java Interface?
Use both @Deprecated annotation and the @deprecated JavaDoc tag.
The @deprecated JavaDoc tag is used for documentation purposes.
The @Deprecated annotation instructs the compiler that the method is deprecated. Here is what it says in Sun/Oracles document on the subject:
Using the
@Deprecatedannotation 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@deprecatedJavadoc tag, though the Sun compilers currently do so. Other compilers may not issue such warnings. Thus, using the@Deprecatedannotation to generate warnings is more portable that relying on the@deprecatedJavadoc tag.
You can find the full document at How and When to Deprecate APIs
3 Comments
Bohemian
Not quite true. Both javadoc and annotation tell compiler method is deprecated
ShaMan-H_Fel
@Bohemian Actually that is not quite true. The annotation is defined in the Java Language Specification section 9.6.1.6 (java.sun.com/docs/books/jls/third_edition/html/…), while the javadoc tag is not. So the annotation is part of the language. If you decide to write your own Java compiler, you may ignore the javadoc tag, but you must recognize the annotation.
Amir Pashazadeh
@ShaMan-H_Fel I believe the javadoc model works too. Because it was the only choice before Java 5, and it did work. When you marked a method with
@deprecated javadoc tag (in Java 4-), the compiler marked the method (class, field) as deprecated and the IDEs showed warnings, even when no source was available.since some minor explanations were missing
Use @Deprecated annotation on the method like this
/**
* @param basePrice
*
* @deprecated reason this method is deprecated <br/>
* {will be removed in next version} <br/>
* use {@link #setPurchasePrice()} instead like this:
*
*
* <blockquote><pre>
* getProduct().setPurchasePrice(200)
* </pre></blockquote>
*
*/
@Deprecated
public void setBaseprice(int basePrice) {
}
remember to explain:
- Why is this method no longer recommended. What problems arise when using it. Provide a link to the discussion on the matter if any. (remember to separate lines for readability
<br/> - When it will be removed. (let your users know how much they can still rely on this method if they decide to stick to the old way)
- Provide a solution or link to the method you recommend
{@link #setPurchasePrice()}
There are two things you can do:
- Add the
@Deprecatedannotation to the method, and - Add a
@deprecatedtag to the javadoc of the method
You should do both!
Quoting the java documentation on this subject:
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
Comments
Use the annotation @Deprecated for your method, and you should also mention it in your javadocs.
Comments
Take a look at the @Deprecated annotation.
Comments
Along with @Deprecated annotation on the method, include a message why it was deprecated and what is the alternate option to use.
/**
* @deprecated
* explain here why the method was deprecated, suggest alternate option to
* use
*/
Example message
Deprecated, for removal: This API element is subject to removal in a future version. since 3.0.0 in favor of bstractCompositeHealthContributorConfiguration(Function)
Comments
You must annotate the service @Deprecated
2 Comments
Ben
This duplicates another answer and adds no new content. Please don't post an answer unless you actually have something new to contribute. You can show your support for an original answer by upvoting.
James LeMaitre
Okay thank you very much, I'm new and I don't yet master all the settings Thank you very much