Java基础教程(16)--注解

一.注解基础知识

1.注解的格式

  最简单的注解就像下面这样：

@Entity

  @符号指示编译器其后面的内容是注解。在下面的例子中，注解的名称为Override：

@Override
void superMethod() {...}

  注解可以有若干个属性。可以在使用注解时指定属性的值：

@Auther(name = "maconn")
class MyClass {
    ...
}

  如果注解只有一个属性，则可以省略属性的名称：

@Auther("maconn")
class MyClass {
    ...
}

  如果注解没有属性，或不需要指定属性的值，则可以省略括号，就像上面的@Override注解。

  可以在一个声明上使用多个注解：

@Auther("maconn")
@Entity
class MyClass {
    ...
}

  有些一个注解可以在一个声明上使用多次，这种注解称为重复注解：

@Author("maconn")
@Author("anotherPerson")
class MyClass { ... }

  重复注解时Java8引入的特性。稍后我们将会讲解更多有关重复注解的内容。

  可以使用java.lang或java.lang.annotation包中的注解，例如前面的Override就是Java中预定义的注解；也可以定义自己的注解类型，前面的例子中，Entity和Author就是自定义的注解。

2.在什么地方使用注解

  注解可以用在类型的声明上面，例如类的声明，域的声明，方法的声明等。从Java8开始，注解还可以用在使用这些类型的地方，下面是几个例子：

• 创建对象时：

new @Interned MyObject();

• 类型转换：

myString = (@NotNull String) str;

• 实现接口时：

class UnmodifiableList<T> implements @Readonly List<@Readonly T> { ... }

• 抛出异常时：

void monitorTemperature() throws @Critical TemperatureException { ... }

  这种注解称为类型注解，稍后将进行深入讨论。

二.自定义注解

  注解可以用来替换代码中的部分注释。假设一个项目中的每个类都需要一些包含重要信息的注释：

public class Generation3List extends Generation2List {
   // Author: maconn
   // Date: 2018/12/23
   // Current revision: 1.0
   // Last modified: 2018/12/23

   ...
}

  要使用注解添加相同的元数据，必须先定义注解：

@interface ClassPreamble {
   String author();
   String date();
   double currentRevision() default 1;
   String lastModified() default "N/A";
}

  注解的定义看上去有点像接口的定义，只不过interface关键字前面多了一个@符号。注解实际上是一种特殊的接口，有关这部分的内容会在后面介绍到。

  上面的注解定义中包含了注解属性的声明，看上去就像定义了一个方法一样。可以为属性定义默认值。

  定义好注解之后，就可以向下面这样使用了：

@ClassPreamble (
   author = "maconn",
   date = "2018/12/23",
   currentRevision = 1.0,
   lastModified = "2018/12/23",
)
public class Generation3List extends Generation2List {
    ...
}

三.预定义注解

  在Java API中已经为我们预先定义了几个注解。这其中有几个是供Java编译器使用的，还有些注解是用在别的注解上的。

给Java编译器使用的注解

@Deprecated：@Deprecated注解表示被标记的元素已经被弃用或者说不再推荐使用。如果在程序中使用带有@Deprecated注解的方法、类或域，编译器就会给出警告。当一个元素被弃用时，也应该在同时在Javadoc中使用@deprecated（注意Javadoc中的@deprcated首字母是小写）标记，就像下面这样：

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

@Override：@Override注解告诉编译器该元素旨在覆盖超类中声明的元素。假设超类中声明了一个int overriddenMethod()方法，当在子类中重写这个方法时，可以加上@Override注解，就像下面这样：

@Override
int overriddenMethod() {
    ...
}

  虽然在重写方法时不需要使用此批注，但使用它有助于防止出错。如果@Override标记的方法无法正确覆盖其超类中的方法，则编译器会给出错误。

@SuppressWarnings：@SuppressWarnings注解可以让编译器忽略它指定的警告。在以下示例中，使用了不推荐使用的方法，编译器通常会生成警告。但是，在添加@SuppressWarnings注解后，编译器将不再给出警告。

@SuppressWarnings("deprecation")
void useDeprecatedMethod() {
    objectOne.deprecatedMethod();
}

  每个警告都属于一个类别。在Java中警告有两个类别：deprecation和unchecked。如果要同时忽略这两种警告，可以使用以下语法：

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

@SafeVarargs：当应用于方法或构造函数时，@SafeVarargs注解断言代码不会对可变参数列表执行潜在的不安全操作。使用此注注解时，有关可变参数列表的unchecked警告将会被忽略。

@SafeVarargs
public static <T> T useVarargs(T... args) {
    return args.length > 0 ? args[0] : null;
}

@FunctionalInterface：@FunctionalInterface注解是Java8引入的注解，作用在接口上以表明该接口是函数式接口（函数式接口是指只有一个抽象方法的接口）。

作用于其他注解的注解

  作用于其他注解的注解被称为元注解。在java.lang.annotation包中定义了以下几个元注解：

@Retention：@Retention注解用于定义注解的保留策略：

• RetentionPolicy.SOURCE - 注解仅存在于源码中，编译时将会被忽略。
• RetentionPolicy.CLASS - 注解会在class字节码文件中存在，但会被JVM忽略。
• RetentionPolicy.RUNTIME - 注解会被JVM保留，因此可以在运行时环境使用。

@Documented：@Documented注解用来定义被标注的注解在使用时是否会出现在Javadoc文档中。考虑下面的例子：

import java.lang.annotation.Documented ;

@MyAnnotation(name="maconn")
public class AnnotationDemo{
	public void foo() {}
}

@Documented
@interface MyAnnotation{
    public String name();
}

  在上面的例子中，我们自定义了一个注解MyAnnotation，注意它的定义上有一个@Documented注解。我们在AnnotationDemo类上使用了@MyAnnotation，然后这个源文件使用javadoc命令提取文档，结果如下：



  可以看到，AnnotationDemo类上的注解@MyAnnotation出现在了文档中。正常情况下，没有@Documented注解的注解是不会出现在文档中的。下面的例子中，我们去掉MyAnnotation注解上的@Documented：

import java.lang.annotation.Documented ;

@MyAnnotation(name="maconn")
public class AnnotationDemo{
	public void foo() {}
}

@interface MyAnnotation{
    public String name();
}

  然后重新生成文档：



  可以看到，@MyAnnotation注解并没有出现在文档里。

@Target：@Target注解作用在另外一个注解上用来限制这个注解可以用在哪些类型上：

• ElementType.ANNOTATION_TYPE 可以应用于注解类型。
• ElementType.CONSTRUCTOR 可以应用于构造函数。
• ElementType.FIELD 可以应用于域。
• ElementType.LOCAL_VARIABLE 可以应用于局部变量。
• ElementType.METHOD 可以应用于方法。
• ElementType.PACKAGE 可以应用于包声明。
• ElementType.PARAMETER 可以应用于方法的参数。
• ElementType.TYPE 可以应用于类，接口或枚举类型。

@Inherited：@Inherited注解表明子类可以继承此注解，如果一个类使用此注解，则它的子类也继承此注解。此注解仅适用于类声明。

@Repeatable：@Repeatable是Java8中引入的注解。@Repeatable注解标记的注解可以在一个类型上使用多次。

四.重复注解

  有些时候，可能需要将多个相同的注解用在一个类型上。从Java8开始，可以使用重读注解做到这一点。例如，假设我们要编写一个定时任务。现在要设置定时器在每个月的最后一天和每个周五的23:00运行方法doSomething。要设置定时器，需要创建一个@Schedule注解并将其应用于doSomething方法两次。如下面的代码所示：

@Schedule（dayOfMonth =“last”）
@Schedule（dayOfWeek =“Fri”，hour =“23”）
public void doSomeThing() {
    ...
}

  出于兼容性的原因，重复注解被存储在由Java编译器生成的容器注解内。为了使编译器执行此操作，需要以下两个步骤：

第1步：声明一个可重复的注解

  要重复的注解上一定要使用元注解@Repeatable标记。下面的例子定义了重复注解@Schedule：

import java.lang.annotation.Repeatable;

@Repeatable(Schedules.class)
public @interface Schedule {
  String dayOfMonth() default "first";
  String dayOfWeek() default "Mon";
  int hour() default 12;
}

  @Repeatable注解的值，是用来存储这个重复注解的容器注解。在这个例子中，@Repeatable注解的值是Schedules.class，因此重复注解@Schedule都存储在@Schedules中。

  如果在同一个类型上使用多个相同的注解并且这个注解不是重复注解时，将会产生编译时错误。

第2步：声明容器注解

  容器注解必须有一个数组类型的value元素，且数组元素的类型必须是一个可重复注解。下面声明了容器注解@Schedules：

public @interface Schedules {
    Schedule[] value();
}