java annotation 手册.doc

Java Annotation 手册

一、Annotation 究竟是什么？

Annotation 提供了一条与程序元素关联任何信息或者任何元数据（metadata）的途径。从某

些方面看，

annotation 就像修饰符一样被使用，并应用于包、类型、构造方法、方法、成员变量、参数 、

本地变量的

声明中。这些信息被存储在 annotation 的“name=value”结构对中。annotation 类型是一种接

口，能够通

语言解释器在

工作时忽略了这些 annotation。正是由于 java 虚拟机忽略了 annotation，导致了 annotation 类

型在代码中

是“不起作用”的；只有通过某种配套的工具才会对 annotation 类型中的信息进行访问和处理。

本文中将

涵盖标准的 annotation 和 meta-annotation 类型，陪伴这些 annotation 类型的工具是 java 编译

器（当然要

以某种特殊的方式处理它们）。

由于上述原因，annotation 在使用时十分简便。一个本地变量可以被一个以 NonNull 命名的

annotation 类

架：它启动后扫描源代码中的 annotation，并调用我们定义好的 annotation 处理器完成我们

所要完成的工

作（比如验证前面例子中的断言）。说到这里， annotation 的强大功能似乎可以替代

XDoclet 这类的工具

了，随着我们的深入，大家会更加坚信这一点。

注：详细描述请参看 jsr250 规范：

http://www.jcp.org/aboutJava/communityprocess/pfd/jsr250/

二、Annotation 的定义：

这段文字开始介绍 annotation 相关技术。在此大家将看到 java5.0 的标准 annotation 类型，这

种标准类型

首先，关键的概念是理解 annotation 是与一个程序元素相关联信息或者元数据的标注。它

序的执行，但是对例如编译器警告或者像文档生成器等辅助工具产生影响。

下面是常用的 annotation 列表，我们应该注意在 annotation 和 annotation 类型之间的不同：

A.annotation：

annotation 使用了在 java5.0 所带来的新语法，它的行为十分类似 public、final 这样的修饰符。

每个

annotation 具有一个名字和成员个数>=0。每个 annotation 的成员具有被称为 name=value 对

的名字和值（

就像 javabean 一样），name=value 装载了 annotation 的信息。

B.annotation 类型：

annotation 类型定义了 annotation 的名字、类型、成员默认值。一个 annotation 类型可以说

是一个特殊的

annotation 类型。

C.annotation 成员：

annotation 的成员在 annotation 类型中以无参数的方法的形式被声明。其方法名和返回值定

义了该成员的

名字和类型。在此有一个特定的默认语法：允许声明任何 annotation 成员的默认值：一个

annotation 可以

将 name=value 对作为没有定义默认值的 annotation 成员的值，当然也可以使用 name=value

对来覆盖其它成

员默认值。这一点有些近似类的继承特性，父类的构造函数可以作为子类的默认构造函数

E.meta-annotation：

meta-annotation 也称为元 annotation，它是被用来声明 annotation 类型的 annotation。Java5.0

提供了一

些标准的元-annotation 类型。下面介绍的 target、retention 就是 meta-annotation。

F.target：

annotation 的 target 是一个被标注的程序元素。target 说明了 annotation 所修饰的对象范围：

可被用于 packages、types（类、接口、枚举、annotation 类型）、类型成员（方法、构造方

法、成员变

量、枚举值）、方法参数和本地变量（如循环变量、catch 参数）。在 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 类型，它被用作标注方法。它说明了被标注的方

这个 annotaton 常常在我们试图覆盖父类方法而确又写错了方法名时发挥威力。

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

误的 sample：

清单 1：

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

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

}

B.Deprecated：

同样 Deprecated 也是一个 marker annotation。当一个类型或者类型成员使用@Deprecated 修

饰的话，编译

器将不鼓励使用这个被标注的程序元素。而且这种修饰具有一定的“延续性”：如果我们在

代码中通过继

承或者覆盖的方式使用了这个过时的类型或者成员，虽然继承或者覆盖后的类型或者成员

何被禁止或者替代的描述）。

在 java5.0，java 编译器仍然象其从前版本那样寻找@deprecated 这个 javadoc tag，并使用它

们产生警告

信息。但是这种状况将在后续版本中改变，我们应在现在就开始使用@Deprecated 来修饰

过时的方法而不

是@deprecated javadoc tag。

清单 2：

下面是一段使用@Deprecated 的代码：

/**

* 这里是 javadoc 的@deprecated 声明.

* @deprecated No one has players for this format any more. Use VHS instead.

*/

@Deprecated public class Betamax { ... }

此种警告从某种

程度上代表了程序错误。例如当我们使用一个 generic collection 类而又没有提供它的类型时，

编译器将

提示出"unchecked warning"的警告。

通常当这种情况发生时，我们就需要查找引起警告的代码。如果它真的表示错误，我们就

需要纠正它。例

如如果警告信息表明我们代码中的 switch 语句没有覆盖所有可能的 case，那么我们就应增

加一个默认的

case 来避免这种警告。

相仿，有时我们无法避免这种警告，例如，我们使用必须和非 generic 的旧代码交互的

generic

有效，同时编