Java-Annotation使用大全

Java Annotation 使用大全

一、Annotation 究竟是什么？

Annotation 提供了一条与程序元素关联任何信息或者任何元数据（metadata）的途径。从某些方面看，annotation就像修饰符一样被使用，并应用于包、类型、构造方法、方法、成员变量、参数、本地变量的声明中。

这些信息被存储在 annotation 的“name=value”结构对中。 annotation 类型是一种接口，能够通过 java 反射 API 的方式提供对其信息的访问。

annotation 能被用来为某个程序元素（类、方法、成员变量等）关联任何的信息。需要注意的是，这里存在着一个基本的潜规则：annotaion 不能影响程序代码的执行，无论增加、删除 annotation，代码都始终如一的执行。

另外，尽管一些 annotation 通过 java 的反射 api 方法在运行时被访问，而 java 语言解释器在工作时忽略了这些annotation。正是由于 java 虚拟机忽略了 annotation，导致了 annotation 类型在代码中是“不起作用”的；只有通过某种配套的工具才会对 annotation 类型中的信息进行访问和处理。本文中将涵盖标准的 annotation 和 meta- annotation类型，陪伴这些 annotation 类型的工具是 java 编译器（当然要以某种特殊的方式处理它们）。

由于上述原因，annotation 在使用时十分简便。一个本地变量可以被一个以 NonNull 命名的 annotation 类型所标注，来作为对这个本地变量不能被赋予 null 值的断言。而我们可以编写与之配套的一个 annotation 代码分析工具，使用它来对具有前面变量的代码进行解析，并且尝试验证这个断言。当然这些代码并不必自己编写。在 JDK安装后，在 JDK/bin 目录中可以找到名为“apt”的工具，它提供了处理 annotation 的框架：它启动后扫描源代码中的 annotation，并调用我们定义好的 annotation 处理器完成我们所要完成的工作（比如验证前面例子中的断言）。说到这里， annotation 的强大功能似乎可以替代 XDoclet 这类的工具了，随着我们的深入，大家会更加坚信这一点。

这段文字开始介绍 annotation 相关技术。在此大家将看到 java5.0 的标准 annotation 类型，这种标准类型就是前文中所说的“内建”类型，它们可以直接被 javac 支持。

可喜的是，在 java6.0beta 版中的 javac 已经加入了对自定义 annotation 的支持。

1。Annotation 的概念和语法：

首先，关键的概念是理解 annotation 是与一个程序元素相关联信息或者元数据的标注。它从不影响 java 程序的执行，但是对例如编译器警告或者像文档生成器等辅助工具产生影响。下面是常用的 annotation 列表，我们应该注意在 annotation 和 annotation 类型之间的不同：

A.annotation：

annotation 使用了在 java5.0 所带来的新语法，它的行为十分类似 public、final 这样的修饰符。每个 annotation 具有一个名字和成员个数 >=0。每个 annotation 的成员具有被称为 name=value 对的名字和值（就像 javabean 一样），name=value 装载了 annotation 的信息。

B.annotation 类型：

annotation 类型定义了 annotation 的名字、类型、成员默认值。一个 annotation 类型可以说是一个特殊的 java 接口，它的成员变量是受限制的，而声明 annotation 类型时需要使用新语法。当我们通过 java 反射 api 访问 annotation时，返回值将是一个实现了该 annotation 类型接口的对象，通过访问这个对象我们能方便的访问到其 annotation成员。后面的章节将提到在 java5.0 的 java.lang 包里包含的 3 个标准 annotation 类型。

C.annotation 成员：

annotation 的成员在 annotation 类型中以无参数的方法的形式被声明。其方法名和返回值定义了该成员的名字和类型。在此有一个特定的默认语法：允许声明任何 annotation 成员的默认值：一个 annotation 可以将 name=value对作为没有定义默认值的 annotation 成员的值，当然也可以使用 name=value 对来覆盖其它成员默认值。这一点有些近似类的继承特性，父类的构造函数可以作为子类的默认构造函数，但是也可以被子类覆盖。

D.marker annotation 类型：

一个没有成员定义的 annotation 类型被称为 marker annotation。这种 annotation 类型仅使用自身的存在与否来为我们提供信息。如后面要说的 Override。E.meta-annotation：meta -annotation 也称为元 annotation，它是被用来声明 annotation 类型的 annotation。Java5.0 提供了一些标准的元-annotation 类型。下面介绍的 target、retention 就是 meta-annotation。

F.target：

annotation 的 target 是一个被标注的程序元素。target 说明了 annotation 所修饰的对象范围：annotation 可被用于packages、 types（类、接口、枚举、annotation 类型）、类型成员（方法、构造方法、成员变量、枚举值）、方法参数和本地变量（如循环变量、catch 参数）。在 annotation 类型的声明中使用了 target 可更加明晰其修饰的目标。

G.retention：

annotation 的 retention 定义了该 annotation 被保留的时间长短：某些 annotation 仅出现在源代码中，而被编译器丢弃；而另一些却被编译在 class 文件中；编译在 class 文件中的 annotation 可能会被虚拟机忽略，而另一些在 class被装载时将被读取（请注意并不影响 class 的执行，因为 annotation 与 class 在使用上是被分离的）。使用这个meta-annotation 可以对 annotation 的“生命周期” 限制。

H.metadata：

由于 metadata 被广泛使用于各种计算机开发过程中，所以当我们在这里谈论的 metadata 即元数据通常指被annotation 装载的信息或者 annotation 本身。

2。使用标准 Annotation：

java5.0 在 java.lang 包中定义了 3 种标准的 annotation 类型：

A.Override：

java.lang.Override 是一个 marker annotation 类型，它被用作标注方法。它说明了被标注的方法重载了父类的方法，起到了断言的作用。如果我们使用了这种 annotation 在一个没有覆盖父类方法的方法时，java 编译器将以一个编译错误来警示。

这个 annotaton 常常在我们试图覆盖父类方法而确又写错了方法名时发挥威力。使用方法极其简单：在使用此 annotation 时只要在被修饰的方法前面加上@Override。

下面的代码是一个使用@Override 修饰一个企图重载父类的 toString 方法，而又存在拼写错误的 sample：

清单 1：

@Override

public String toSting() { // 注意方法名拼写错了

return "[" + super.toString() + "]";

}

B.Deprecated：

同样 Deprecated 也是一个 marker annotation。当一个类型或者类型成员使用@Deprecated 修饰的话，编译器将不鼓励使用这个被标注的程序元素。而且这种修饰具有一定的 “延续性”：如果我们在代码中通过继承或者覆盖的方式使用了这个过时的类型或者成员，虽然继承或者覆盖后的类型或者成员并不是被声明为 @Deprecated，但编译器仍然要报警。

值得注意，@Deprecated 这个 annotation 类型和 javadoc 中的 @deprecated 这个 tag 是有区别的：前者是 java 编译器识别的，而后者是被 javadoc 工具所识别用来生成文档（包含程序成员为什么已经过时、它应当如何被禁止或者替代的描述）。

在 java5.0，java 编译器仍然象其从前版本那样寻找@deprecated 这个 javadoc tag，并使用它们产生警告信息。但是这种状况将在后续版本中改变，我们应在现在就开始使用@Deprecated 来修饰过时的方法而不是 @deprecated javadoc tag。

清单 2：

【下载地址】

百度网盘链接：https://pan.baidu.com/s/1MN7tVwoMx-sYHcCwWYfrDQ

提取码：vscv