java 注释类型
J2SE 5.0 (Tiger) 的发布是 Java 语言发展史上的一个重要的里程碑 , 是迄今为止在 Java 编程方面所取得的最大进步。
J2SE 5.0 提供了很多令人激动的特性。这些特性包括范型 (generics) 的支持 , 枚举类型 (enumeration) 的支持 , 元数据 (metadata) 的支持 , 自动拆箱 (unboxing)/ 装箱 (autoboxing), 可变个数参数 (varargs), 静态导入 (static imports), 以及新的线程架构 (Thread framework)。
随着 J2SE 5.0 的推出 , 越来越多的集成开发环境 (IDE) 支持 J2SE 5.0 的开发。 著名的开源 Java IDE Eclipse 从 3.1M4 开始支持 J2SE 5.0 的开发 , 目前最新的版本是 3.1RC4。
本系列将介绍 J2SE 5.0 中三个比较重要的特性 : 枚举类型 , 注释类型 , 范型 , 并在此基础上介绍在如何在 Eclipse 3.1 开发环境中开发枚举类型 , 注释类型和范型应用。本文将介绍注释类型。
2. 注释类型
2.1 注释类型简介
J2SE 5.0 提供了很多新的特性。其中的一个很重要的特性，就是对元数据 (Metadata) 的支持。在 J2SE5.0 中，这种元数据叫作注释 (Annotation)。通过使用注释 , 程序开发人员可以在不改变原有逻辑的情况下，在源文件嵌入一些补充的信息。代码分析工具，开发工具和部署工具可以通过这些补充信息进行验证或者进行部署。举个例子，比如说你希望某个方法的参数或者返回值不为空，虽然我们可以在 Java doc 中说明，但是表达同样意思的说法有很多，比如"The return value should not be null"或者"null is not allowed here"。测试工具很难根据这些语言来分析出程序员所期望的前提条件 (Pre-condition) 和执行后的条件 (Post-condition)。 而使用注释 (Annotation)，这个问题就可以轻而易举的解决了。
2.2 定义注释
J2SE5.0 支持用户自己定义注释。定义注释很简单，注释是由 @Interface 关键字来声明的。比如下面是一个最简单的注释（Annotation）。
清单 1 一个最简单的注释
public @interface TODO{}
|
除了定义清单 1 中的注释以外，我们还可以在注释（Annotation）中加入域定义。方法很简单，不需定义 Getter 和 Setter 方法，而只需一个简单的方法，比如：
清单 2 为注释加入域
public @interface TODO{
String priority();
}
|
定义了这个注释之后，我们在程序中引用就可以使用这个注释了。
清单 3 使用自定义的注释
@TODO(
priority="high"
)
public void calculate(){
//body omission
}
|
由于 TODO 中只定义了一个域，使用 TODO 的时候，可以简写为
清单 4 单域注释的简写
@TODO("high")
|
类似的，你可以在你的注释（Annotation）类型中定义多个域，也可以为每个域定义缺省值。比如：
清单 5 定义缺省值
public @interface TODO{
String priority();
String owner();
boolean testable() default true;
}
|
如果定义了缺省值，在使用的时候可以不用再赋值。比如：
清单 6 使用定义了缺省值的注释
@TODO(
priority="high"，
owner="Catherine"
)
public void calculate(){
//body omission
}
|
在这个例子中，testable 用缺省值 true。
和上文一样，我们使用 Eclipse 3.1 作为集成的编译运行环境。Eclipse 3.1 提供了向导帮助用户来定义注释。 1 ．首先我们创建一个 Plug-in 项目，com.catherine.lab.annotation.demo。在 Package Explorer 中选中包 package com.catherine.lab.annotation.demo, 2. 点击 New->Other->Java->Annotation，弹出了下面的对话框。4. 输入注释的名称，在这里例子中输入 TODO, 点击 Finish, 图 2 中的注释就生成了。
图 1 创建注释向导
图 2 注释向导生成的代码
2.2.1 注释的类型
从上面的例子中，我们可以看出，按照使用者所需要传入的参数数目， 注释（Annotation）的类型可以分为三种。
第一种是标记注释类型：
标记注释 (Marker) 是最简单的注释 , 不需要定义任何域。下面要介绍的 Override 和 Deprecated 都是标记类型的。当然，如果一个注释类型提供了所有域的缺省值，那么这个注释类型也可以认为是一个注释类型。使用标记类型的语法很简单。
清单 7 标记注释的用法
@MarkerAnnotation |
第二种是单值注释类型 : 单值注释类型只有一个域。语法也很简单：
清单 8 单值注释的用法
@SingleValueAnnotation("some value")
|
第三种是全值注释类型。 全注释类型其实并不算是一个真正的类型，只是使用注释类型完整的语法：
清单 9 全值注释的用法
@MultipleValueAnnotation(
key1=value1,
key2=value2,
key3=value3,
)
|
2.2.2 J2SE 的内建注释 (build-in annotation)
在程序中不仅可以使用自己定义的注释，还可以使用 J2SE5.0 中内建的注释类型。下面我们就详细来介绍 J2SE5.0 提供的注释类型。J2SE 5.0 中预定义了三种注释注释类型：
Override ：java.lang.Override 表示当前的方法重写了父类的某个方法，如果父类的对应的方法并不存在，将会发生编译错误。
Deprecated：java.lang.Deprecated 表示 并不鼓励使用当前的方法或者域变量。
SuppressWarnings: java.lang.SuppressWarnings 关闭编译器告警，这样，在编译 1.5 之前的代码的时候，不会出现大量不关心的无关的告警。
下面举一个使用 Override 的例子。Override 这个注释类型在使用模板方法（Template Method，图 2）非常有用。熟悉设计模式的读者们一定知道，模板方法中通常定义了抽象类，并且这个抽象类中定义了主要的控制流。子类就是通过重写父类中控制流中所调用的方法来实现自己的逻辑。有的时候，父类会将这些方法定义为抽象方法，但是有的时候也会提供缺省实现。在后者的情况下，子类可以不实现这个方法。
这样就带来一个问题，如果你希望在子类中重写这个方法，但是无意中写错了方法的名字，这个错误是很难被发现的。因为你希望重写的这个方法，会被编译器当作一个新的方法而不是重写父类的方法。而现在使用 @Override，这个担心就是不必要的。如果你拼错了你希望重写的方法，编译器会报错，告诉你父类没有相应的方法。
图 2 模板方法的类图
清单 10 给出了模板方法的一个例子。这个例子中有定义了两个类，SubClass 和 BaseClass。其中 SubClass 继承了 BaseClass，并且希望重写 BaseClass 的方法 doPartII（）。然而 SubClass 中错误的拼写了这个方法的名称。图 3 显示了 SubClass 中的编译错误。熟悉 eclipse 的读者会看到在编辑器里出现了 Error Marker，说明这一行有编译错误。将鼠标指向这行，显示了错误信息。
清单 10 模板方法
public abstract class BaseClass{ // 模板方法的基类
public void doWork(){
doPartI(); // 先调用 doPartI() 方法
doPartII();// 之后调用 doPartII() 方法
}
public abstract void doPartI();
public void doPartII(){
}
}
public class SubClass extend BaseClass{
public void doPartI(){
};
@Override
public void doPortII(){// 拼写错误，产生编译错误
System.out.println("override the method of superclass");
}
}
|
图 3 Override 应用的例子
2.2.3 注释的注释
值得注意的是，J2SE5.0 还提供了四种用于注释的注释类型。有以下的四种：
1. Target：用来指定这个注释（Annotation）是为哪种类型而定义的。比如，这个类型可能只是为 method 定义的。比如 override, 不能用 @override 来修饰 class 或者 field。
比如清单 11 中定义了一个注释：TODO，而这个注释定义了 Target 为 ElementType.method。因此，TODO 只能用来修饰方法，不能用来修饰类或者类变量。图 5 中给出了一个非法使用 TODO 的例子。在 MyCalculator 中，定义了一个布尔型的变量 isReady, 如果用 TODO 来修饰这个类变量的话，会出现编译错误。而用 TODO 来修饰方法 calculateRate()，则不会出现编译错误。这是因为 TODO 的定义已经规定了，只能用来修饰方法。
清单 11 Target 的用法
@Target({ElementType.METHOD})
public @interface TODO {
int priority() default 0;
}
|
图 5 TODO 注释的非法使用
2.Retention：Retention 的策略可以从以下三种中选取：
- RetentionPolicy.SOURCE：编译器编译之后会会从 class file 中除去注释（Annotation）。
- Retention.CLASS: 注释（Annotation）保留在 class file 中，但是 VM 不会处理。
- RetentionPolicy.RUNTIME,：注释（Annotation）保留在 class file,VM 会进行处理。
请注意，如果你希望在运行时查找到这些注释在什么地方被用到，一定要在定义注释的时候，选择 RetentionPolicy.RUNTIME, 否则即使你用注释修饰了类变量或者方法，在运行时也没有办法获得这个信息的。
3.Documented：这个注释（Annotation）将作为 public API 的一部分。
4.Inherited ： 假设注释（Annotation）定义的时候使用了 Inherited, 那么如果这个注释（Annotation）修饰某个 class，这个类的子类也被这个注释（Annotation）所修饰。
2.3 注释的应用
下面各小节显示了在哪些情况下可以使用注释以及如何使用注释。
2.3.1 动态查找注释
当我们定义好了注释以后，我们可以开发一些分析工具来解释这些注释。这里通常要用到 Java 的反射特性。比如说我们希望找到某个对象 / 方法 / 域使用了哪些注释，或者获得某个特定的注释，或者判断是否使用某个特定的注释 , 我们可以参考下面这个例子。这个例子中定义了两个注释：TODO 和 TOFORMATE。在 MyCalculator 类中，TODO 用来修饰方法 calculateRate，而 TOFORMATE 用来修饰类变量 concurrency 和 debitDate。而在类 TestCalculator 的 main 函数中，通过 Java 反射特性，我们查找到使用这些注释的类变量和方法。清单 12- 清单 15 分别显示这些类的定义。
清单 12 TODO 注释的定义
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface TODO {
int priority() default 0;
}
|
清单 13 TOFORMATE 的定义
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface TOFORMATE {
}
|
清单 14 使用注释的类 MyCalculator
public class MyCalculator {
boolean isReady;
@TOFORMATE double concurrency;
@TOFORMATE Date debitDate;
public MyCalculator() {
super();
}
@TODO
public void calculateRate(){
System.out.println("Calculating...");
}
}
|
清单 15 动态查找注释
public class TestCalculator {
public static void main(String[] args) {
MyCalculator cal = new MyCalculator();
cal.calculateRate();
try {
Class c = cal.getClass();
Method[] methods = c.getDeclaredMethods();
for (Method m: methods) {
// 判断这个方法有没有使用 TODO
if (m.isAnnotationPresent(TODO.class))
System.out.println("Method "+m.getName()+": the TODO is present");
}
Field[] fields = c.getDeclaredFields();
for (Field f : fields) {
// 判断这个域有没有使用 TOFORMATE
if (f.isAnnotationPresent(TOFORMATE.class))
System.out.println("Field "+f.getName()+": the TOFORMATE is present");
}
} catch (Exception exc) {
exc.printStackTrace();
}
}
}
|
下面我们来运行这个例子，这个例子的运行结果如图 10 所示。
运行结果和我们先前的定义是一致的。在运行时，我们可以获得注释使用的相关信息。
图 6 运行结果
在我们介绍了什么是注释以后，你可能会想知道注释可以应用到什么地方呢？使用注释有什么好处呢？在下面的小节中我们将介绍一个稍复杂的例子。从这个例子中，你将体会到注释所以提供的强大的描述机制（declarative programming）。
2.3.2 使用注释替代 Visitor 模式
在 J2SE 5.0 以前，我们在设计应用的时候，我们经常会使用 Visitor 这个设计模式。Visitor 这个模式一般是用于为我们已经设计好了一组类添加方法，而不需要担心改变定义好的类。比如说我们已经定义了好了一组类结构，但是我们希望将这些类的对象部分数据输出到某种格式的文件中。
Vistor 模式的实现
使用 Vistor 模式，首先我们在 Employee 这个类中加入 export 方法，export 方法如图 11 所示。Export 方法接受 Exporter 对象作为参数，并在方法体中调用 exporter 对象的 visit() 方法。
图 11 使用 Vistor 模式实现格式输出
在这里我们定义了一个 Exporter 抽象类，我们可以通过继承 Exporter 类，重写其 visit 方法来实现不同格式的文件输出。图 11 种给出 visit 方法的实现是一个简单的例子。如果要实现输出成 XML 格式的，可以定义 Exporter 子类：XMLExporter。如果希望输出成文本的可以定义 TXTExporter。但是这样做不够灵活的地方在于，如果 Employee 加入其他的域变量，那么相应的 visitor 类也需要进行修改。这就违反了面向对象 Open for Extension, close for Modification 的原则。
使用注释替代 Vistor 模式
使用注释（Annotation），也可以完成数据输出的功能。首先定义一个新的注释类型：@Exportable。然后定义一个抽象的解释器 ExportableGenerator，将 Employee 对象传入解释器。在解释器中，查找哪些域使用了 Exportable 这个注释（Annotation），将这些域 (Field) 按照一定格式输出。图 12 给出了 Exportable 注释的定义。
清单 16 注释 Exportable 的定义
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Exportable {
}
|
清单 17- 清单 20 中给出了包含数据的这些类的定义以及这些类是如何使用注释 Exportable 的。 图 18 定义了 Main 函数，使用 ExporterGenerator 来产生输出文件。清单 21 给出了使用注释来实现这一功能的两个类：ExporterGenerator 和 TXTExporterGenerator。其中 ExporterGenerator 定义了一个基本的框架。而 TXTExporterGenerator 继承了 ExporterGenerator，并且重写了 outputField 方法，在这个方法中实现了特定格式的输出。用户可以继承这个 ExporterGenerator，并且实现其中的抽象方法来定义自己期望的格式。
清单 17 Employee 的类定义
public abstract class Employee {
public abstract String getName();
public abstract String getEmpNo();
public Employee() {
super();
}
}
|
清单 18 Regular 的类定义
public class Regular extends Employee{
@Exportable String name;
@Exportable String address;
@Exportable String title;
@Exportable String phone;
@Exportable String location;
@Exportable Date onboardDate;
@Exportable ArrayList |
清单 19 Vendor 的类定义
public class Vendor extends Employee {
@Exportable String name;
@Exportable String company;
@Exportable String team;
@Exportable String workingHours;
String empNo;
public Vendor(String name, String company, String team, String hours) {
super();
this.name = name;
this.company = company;
this.team = team;
workingHours = hours;
}
}
|
清单 20 Contractor 的类定义
public class Contractor extends Employee{
@Exportable String name;
@Exportable String company;
@Exportable String contractDuration;
String empNo;
public Contractor(String name, String company) {
super();
// TODO Auto-generated constructor stub
this.name = name;
this.company = company;
contractDuration ="1";
}
}
|
清单 21 Supplemental 的类定义
public class Contractor extends Employee{
@Exportable String name;
@Exportable String company;
@Exportable String contractDuration;
String empNo;
public Contractor(String name, String company) {
super();
this.name = name;
this.company = company;
contractDuration ="1";
}
}
|
清单 22 使用 ExportableGenerator 的程序
public class TestExportable {
public TestExportable() {
super();
}
public static void main(String[] args) {
Regular em=new Regular("Catherine","IBM","Software Engineer"
,"82888288","BJ", new Date());
Employee vn1=new Vendor("Steve","IBM","PVC","8");
Employee vn2=new Vendor("Steve","IBM","PVC","8");
Employee ct=new Contractor("Joe","IBM");
Employee sup=new Supplemental("Linda","IBM","8");
em.addMemeber(vn1);
em.addMemeber(vn2);
em.addMemeber(ct);
em.addMemeber(sup);
PrintWriter ps;
try {
ps = new PrintWriter(new FileOutputStream(
new File("C:\\test.output"),true));
ExportableGenerator eg=new TXTExportableGenerator(ps);
eg.genDoc(em,0);
eg.flush();
} catch (FileNotFoundException e) {
e.printStackTrace();
}
}
}
|
清单 23 ExportableGenerator
public abstract class ExportableGenerator {
PrintWriter out = null;
public ExportableGenerator(PrintWriter out) {
super();
this.out = out;
}
public void genDoc(Employee e, int tagNum) {
Class employee = e.getClass();
Field[] fields = employee.getDeclaredFields();
outputFieldHeader(out,e);
for (Field f : fields) {
if (f.isAnnotationPresent(Exportable.class)) {
if (f.getType() != ArrayList.class) {
for(int i=0; i |
清单 24 TXTExportableGenerator
public class TXTExportableGenerator extends ExportableGenerator {
public TXTExportableGenerator(PrintWriter out) {
super(out);
}
@Override
protected void outputSimpleField(PrintWriter out, Field f,Object obj) {
out.print(f.getName());
out.print("=");
out.print(value(f,obj));
out.print(";");
out.println();
}
@Override
protected void outputFieldHeader(PrintWriter out,Object e) {
}
@Override
protected void outputFieldFooter(PrintWriter out,Object e) {
//out.println(e.getClass().getName()+":");
}
}
|
在这个例子中，我们将一个 Employee 对象的部分内容输出到文件 C:\test.output 中。图 19 显示了这个例子的输出结果。
图 12 输出结果
通过这种方法，我们可以动态生成 Employee 对象的域输出，而不需要在程序中写明要输出哪些确定的域。如果需要更为丰富的格式，我们可以定义多个注释类型。通过对不同注释以及属性的解析，实现格式化的文件输出。
2.4 注释类型的小结
所谓元数据，指的是关于信息的信息。一般而言，代码分析工具，测试工具或者部署工具会使用元数据来产生配置信息以及使用配置信息产生控制逻辑。这些工具通常使用 Java 的反射特性，重构元数据的信息，并对这些信息进行解释。
新的技术会不断改变程序设计和开发人员的设计思想。那么注释（Annotation）给我们带来了什么呢 ? 仅仅在代码分析，或者是开发测试框架和部署框架的时候才有用么？ 我认为并不是这样。从上面的例子可以看出，注释（Annotation）的应用范围其实是很广泛的。在我们的应用中充分的利用元数据，可以提高的软件的质量和可维护性。