【java9】java9新特性之增强@Deprecated注解

一个使用@Deprecated注解的元素，无论是一个类或是一个方法，可能是由以下原因导致了不应该再使用它：

1. 使用它可能会导致错误；
2. 在未来的版本中不被兼容；
3. 在未来的版本中可能会被删除；
4. 存在更好的更有效的替代方法；

如果一个程序或代码片段使用了@Deprecated注解的元素，那么编译器就会生成一个警告信息，表明这个元素是不被推荐使用的。

@Deprecated注解很早就存在了，从Java5开始就引入了：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}

在Java9中，@Deprecated注解引入了一些新特性，主要是为了提高代码的可读性和可维护性。其中一些新特性包括：

1. forRemoval参数：@Deprecated注解现在支持一个新的boolean类型参数forRemoval，用于指示该API是否已经过时，并计划在将来的版本中删除。这使得开发人员可以更清晰地了解哪些API是过时的，并且哪些API是可以安全使用的。

2. since参数：@Deprecated注解还支持一个新的String类型参数since，用于指定自从哪个版本开始该API已经过时。这有助于开发人员更容易地查找替代方案或了解过时API的历史。

3. 替代建议：对于过时的API，通常会提供替代方案或建议。在Java 9中，@Deprecated注解可以包含一个新的String类型参数，用于提供开发人员关于替代方案的建议或指南。

这些新特性使得开发人员能够更好地管理和维护他们的代码库，确保代码的健壮性和可维护性。

在Java9中，使用@Deprecated注解的方式与以前的版本相同，但是现在可以使用forRemoval、since和替代建议这些新特性。

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, MODULE, PARAMETER, TYPE})
public @interface Deprecated {
    /**
     * Returns the version in which the annotated element became deprecated.
     * The version string is in the same format and namespace as the value of
     * the {@code @since} javadoc tag. The default value is the empty
     * string.
     *
     * @return the version string
     * @since 9
     */
    String since() default "";

    /**
     * Indicates whether the annotated element is subject to removal in a
     * future version. The default value is {@code false}.
     *
     * @return whether the element is subject to removal
     * @since 9
     */
    boolean forRemoval() default false;
}

下面是一些示例：

1. 使用@Deprecated注解并指定forRemoval参数：

@Deprecated(forRemoval = true)
public void oldMethod() {
  // ...
}

这表明该方法已经过时，并且计划在将来的版本中删除。如果开发人员尝试使用该方法，编译器将发出警告。

2. 使用@Deprecated注解并指定since参数和替代建议：

@Deprecated(since = "1.5", forRemoval = false, 
            replacement = "newMethod()")
public void oldMethod() {
  // ...
}

public void newMethod() {
  // ...
}

这表明该方法自从1.5版本开始已经过时，但是不打算在将来的版本中删除，并且建议使用newMethod()方法作为替代方案。