在本部分的快速指南中,我们将会查看 Java 的 deprecated API 和如何在程序中使用 @Deprecated 注解。
作为程序的进化和迭代,随着时间的推移,在项目中总会有些类,构造方法,字段,类型或者方法不建议人们继续继续使用。
为了避免程序向后兼容的问题,而导致程序或者 API 不能使用,我们将会对不再使用的元素使用 @Deprecate 注解来声明。
@Deprecated 主要目的是告诉其他的开发者标记的元素不要在程序中继续使用了。
同时我们还建议在 @Deprecated 注解后面添加一些说明的文本来解释如果希望程序或者 API 具有相同的功能应该使用何种其他的方法。
package com.ossez.annotations;
public class ClassWithDeprecatedMethod {
/**
* Calculate period between versions
* * @deprecated
* * This method is no longer acceptable to compute time between versions.
* * <p> Use {@link ClassWithDeprecatedMethod#updatedMethod()} instead.
*/
@Deprecated
public static void deprecatedMethod() {
}
/**
* Updated Method instead of deprecatedMethod.
*/
public static void updatedMethod() {
}
}
请注意,如果一个 Java 的元素被声明了,但是又在程序或者项目的其他地方被引用的话,编译器将会显示丢弃(deprecated)API 的警告。
在上面的示例代码中,如果 deprecatedMethod 被调用了,只有调用 deprecatedMethod 这个方法显示丢弃的警告。
同时请注意,通过使用 Javadoc @deprecate 标记,我们将会在 Java 文档中也被标记丢弃。
上面的代码,如果在 IDE 中查看文本,将会显示为如下:
针对 Java 9 的 @Deprecated 注解,还添加了 since 和 forRemoval 属性。
since – 接受字符串的输入参数,用于定义我们丢弃的内容从哪个版本开始。默认为空字符串。
forRemoval – 使用布尔(boolean)类型,用于标记我们丢弃的内容是不是从下一个发行的版本就会被删除。默认为 false。
如下面的代码中对上面属性的定义。需要注意的是,这个功能最低的版本为 Java 9,如果你还在使用 Java 8 的话,是不能被支持的,将会出现编译错误。
/**
* Calculate period between versions
* * @deprecated
* * This method is no longer acceptable to compute time between versions.
* * <p> Use {@link ClassWithDeprecatedMethod#updatedMethod()} instead.
*/
@Deprecated(since = "4.5", forRemoval = true)
public static void deprecatedMethod() {
}
上面的内容表示的是 deprecatedMethod 方法是从版本 4.5 开始准备丢弃的,同时已经计划在下一个主要的发行版本中完全丢弃删除。
通过添加上面的内容,如果我们现在还在尝试使用这个方法的话,将会通知编译器给我们一个非常强烈的警告。
同时,当前的主流 IDE 工具也能够明显的显示上面强提示。例如在 IntelliJ 中,删除线将会使用一个红色的删除线来替代当前使用的黑色删除线。
在这个快速文章中,我们看到了如何使用 @Deprecated 声明来标记不再使用的元素,以及针对 Java 9 我们可以为其设置一些其他的属性以及这些属性的默认值。
完整的代码,请参考 GitHub 中的项目,可能项目中的源代码和文章中使用的代码有所不同,请以 GitHub 中的代码为主。
代码和内容的完整链接为:https://www.cwiki.us/display/JAVAZH/Java+@Deprecated+Annotation
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。