Tips
做一个终身学习的人。
主要介绍以下内容:
如何弃用API
@deprecate Javadoc标签和@Deprecation注解在弃用的API中的角色
用于生成弃用警告的详细规则
在JDK 9中更新@Deprecation注解
JDK 9中的新的弃用警告
如何使用@SuppressWarnings注解来抑制JDK 9中的不同类型的弃用警告
如何使用jdeprscan静态分析工具来扫描编译的代码库,以查找已弃用的JDK API的用法
一. 什么是弃用
Java中的弃用是提供有关API生命周期的信息的一种方式。 可以弃用模块,包,类型,构造函数,方法,字段,参数和局部变量。 当弃用API时,要告诉其用户:
不要使用API,因为它存在风险。
API已经迁移,因为存在API的更好的替代方案。
API已经迁移,因为API将在以后的版本中被删除。
二. 如何弃用API
JDK有两个用于弃用API的结构:
@deprecated Javadoc标签
@Deprecated注解
@deprecated Javadoc标签已添加到JDK 1.1中,它允许使用丰富的HTML文本格式功能指定关于弃用的详细信息。JDK 5.0中添加了java.lang.Deprecated注解类型,并且可以在已被弃用的API元素上使用。 在JDK 9之前,注解不包含任何元素。 它在运行时保留。
@deprecated标签和@Deprecated注解应该一起使用。 两者都应该存在或两者都不存在。 @Deprecation注解不允许指定弃用的描述,因此必须使用@deprecated标签来提供描述。
Tips
在API元素上使用@deprecated标签(而不是@Deprecated注解)会生成编译器警告。 在JDK 9之前,需要使用-Xlint:dep-ann编译器标志来查看这些警告。
下面包含FileCopier类的声明。 假设这个类作为类库迁移的一部分。 该类使用@Deprecation注解表示弃用。 它的Javadoc使用@deprecated标签来提供不推荐使用的详细信息,例如不推荐使用的时间,它的替换和删除通知。 在JDK 9之前,@Deprecated注解类型不包含任何元素,因此必须使用Javadoc中已弃用的API的@deprecated标签提供有关弃用的所有详细信息。 请注意,Javadoc中使用的@since标签表示FileCopier类自该库的版本1.2以来已经存在,而@deprecated标签表示该类自版本1.4以来已被弃用。
// FileCopier.java
package com.jdojo.deprecation;
import java.io.File;
/**
* The class consists of static methods that can be used to
* copy files and directories.
*
* @deprecated Deprecated since 1.4. Not safe to use. Use the
* java.nio.file.Files
class instead. This class
* will be removed in a future release of this library.
*
* @since 1.2
*/
@Deprecated
public class FileCopier {
// No direct instantiation supported.
private FileCopier() {
}
/**
* Copies the contents of src to dst.
* @param src The source file
* @param dst The destination file
* @return true if the copy is successfully,
* false otherwise.
*/
public static boolean copy(File src, File dst) {
// More code goes here
return true;
}
// More methods go here
}
Javadoc工具将@deprecated标签的内容移动到生成的Javadoc中的顶部,以引起读者的注意。 当不被弃用的代码使用不推荐使用的API时,编译器会生成警告。 请注意,使用@Deprecated注解标注API不会生成警告;但是,使用已经使用@Deprecated注解标注的API。 如果在类本身之外使用FileCopier类,则会收到关于使用不推荐使用的类的编译器警告。
三. JDK 9中@Deprecated注解的更新
假设编译了代码并将其部署到生产环境中。如果升级了JDK版本或包含旧应用程序使用的新的已弃用的API的库/框架,则不会收到任何警告,并且将错过从不推荐使用的API迁移的机会。必须重新编译代码以接收警告。没有任何扫描和分析编译代码(例如JAR文件)的工具,并报告使用已弃用的API。更坏的情况是,从旧版本中删除不推荐使用的API,而旧的编译代码会收到意外的运行时错误。当他们查看不赞成使用的元素Javadoc时,开发人员也感到困惑 —— 当API被废弃时,无法表达何种方式,以及在将来的版本中是否会删除已弃用的API。所有可以做的是在文本中将这些信息指定为@deprecated标签的一部分。 JDK 9尝试通过增强@Deprecated注解来解决这些问题。注解在JDK 9中已增加两个新元素:since和forRemoval。
在JDK 9之前,注解的声明如下:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}
在JDK 9中,弃用注解的声明更改为以下内容:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, MODULE, PARAMETER, TYPE})
public @interface Deprecated {