注解（四）：预定义注解类型

发表于 更新于 分类于 ， 阅读次数： Changyan：

在 Java SE API 中预定义了一系列注解类型。一些注解类型被 Java 编译器使用，一些应用到其他注解上。

Java 语言使用的注解类型

在 java.lang 中预定义的注解类型是 @Deprecated、@Override 和 @SuppressWarnings。

@Deprecated @Deprecated 注解表明被标记的元素是过时的且不应该继续使用。不管什么时候程序使用了一个有 @Deprecated 注解的方法、类或属性，编译期都会生成一个告警。当一个元素是过时的，应该使用 Javadoc @deprecated 标签记入文档，像下面的例子展示的。在 Javadoc 注释和在注解中使用 @ 符号不是同时发生的：从概念上它们是有关系的。并且，注意 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 注解告诉编译器禁止指定的告警，否则会生成该告警。在下面的例子中，使用了一个过时的方法，编译器通常会生成一个告警。然而，在这个例子中，注解使告警被禁止。

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

每一个编译告警属于一种分类。Java 语言规范列出了两种分类：deprecation 和 unchecked。unchecked 告警发生在范型出现之前结合遗传代码编写时。禁止多种类型警告，使用下面的语法：

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

@SafeVarargs @SafeVarargs 注解，当应用到一个方法或构造方法时，代码不会对可变参数执行潜在的不安全的操作。当这种注解类型被使用时，跟可变参数相关的未检查告警被禁止。

@FunctionalInterface @FunctionalInterface 注解，在 Java SE 8 中被引进，表明这个类型声明是一个功能性接口，像 Java 语言规范中定义的。

应用到其他注解上的注解

应用到其他注解上的注解被叫做元注解。在 java.lang.annotation 中定义了几种元注解类型。

@Retention @Retention 注解指定被标记的注解如何存储：

  • RetentionPolicy.SOURCE - 被标记的注解只在源码级别被保留且被编译器忽略。
  • RetentionPolicy.CLASS - 被标记的注解在编译期被编译器保留，但被 Java 虚拟机（JVM）忽略。
  • 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 中被引入，表明被标记的注解可以对同一个声明或类型使用被应用多次。获取更多信息，参见重复注解。