4.3、预定义的注解类型

这篇Java教程基于JDK1.8。教程中的示例和实践不会使用未来发行版中的优化建议。

预定义的注解类型

JAVA SE API中预定义了一批注解。有些注解是提供给Java编译器使用，有些则是提供给其他注解使用。

Java语言使用的注解类型

java.lang 中预定义的注解有：@Deprecated, @Override 和 @SuppressWarnings。

@Deprecated @Deprecated 注解表示被标记的元素已经废弃而不建议再使用。当程序使用有@Deprecated修饰的类、字段或方法时，编译器将会生成警告信息。当元素废弃时，也应当在JavaDoc中使用@deprecated将其标知出来，如下文所示。在Javadoc的注解和类注解使用at符号(@)并不是巧合，它们在概念上是相关的。而且要注意在javadoc标记中是小些字母d开头，而在注解中是大写字母D开头。

 // Javadoc comment follows
    /**
     * @deprecated
     * explanation of why it was deprecated
     */
    @Deprecated
    static void deprecatedMethod() { }
}

@Override @Override注解告诉编译器该元素重写了父类的这个元素。方法重写将在接口与继承中予以详述。

// mark method as a superclass method
// that has been overridden
@Override 
int overriddenMethod() { }

虽然重写一个方法并不是必须要使用该注解，但它有助于防止错误。如果标记为@Override 的方法错误的重写了它父类的方法，编译器会报错。

@SuppressWarnings @SuppressWarnings注解告诉编译器抑制它将生成的特定警告。下面的例子中，编译器将生成一个警告信息，通过使用SuppressWarnings注解将抑制即将生成的警告信息。

// use a deprecated method and tell 
// compiler not to generate a warning
@SuppressWarnings("deprecation")
void useDeprecatedMethod() {
    // deprecation warning
    // - suppressed
    objectOne.deprecatedMethod();
}

每一个编译警告都有一个分类。Java语言规范列出了两个分类：被抑制的 和 非检查性的。当与泛型出现之前编写的遗留代码进行交互时，可能会出现非检查性的警告。为了抑制多个分类的警告，可以用下面这种方式：

@SuppressWarnings({"unchecked", "deprecation"})

@SafeVarargs @SafeVarargs注解应用于方法或构造函数时，断言代码不会对其varargs参数执行潜在的不安全操作。当该注解类型被使用时，与可变参数使用相关的未检查警告将被抑制。

@FunctionalInterface @FunctionalInterface 是Java SE 8 中引入的注解，表示类型声明是一个函数接口，这在Java语言规范中有定义。

描述其他注解类型的注解

描述其他注解的注解称为元注解。在 java.lang.annotation 中定义了多个元注解。

@Retention @Retention 描述了一个注解的保留期：
- RetentionPolicy.SOURCE - 该级别的注解仅仅只保留在源码期，在编译器会被忽略
- RetentionPolicy.CLASS - 该级别的注解会保留在编译器，但是在运行期会被忽略
- RetentionPolicy.RUNTIME - 该级别的注解保留在JVM，所以可以在运行期使用

@Documented @Documented 指明利用JavaDoc工具生成JavaDoc时被描述的注解是否应该出现在JavaDoc中。
@Target @Target 标记一个注解标明该注解可以用在哪种类型的Java元素上。一个注解可以被指向以下元素：

- ElementType.ANNOTATION_TYPE - 可以用在任何类型上
- ElementType.CONSTRUCTOR - 可以用在构造器上
- ElementType.FIELD - 可以用在字段或者属性上
- ElementType.LOCAL_VARIABLE - 可以用在局部变量上
- ElementType.METHOD - 可以用在方法级别上
- ElementType.PACKAGE - 可以用在包类型上
- ElementType.PARAMETER - 可以用在方法参数上
- ElementType.TYPE - 可以用在类的任何元素上

@Inherited @Inherited 标明该类型注解是否可以从父类继承。就是指当查询注解并发现类上没有注解时，将会查询父类的注解。该注解只能用在类型声明上。

@Repeatable @Repeatable是Java SE 8 引入的注解，表示该注解在同一个类型声明上可以注解多次。