J2SE5.0支持用户自己定义注释。定义注释很简单,注释是由@Interface关键字来声明的。比如下面是一个最简单的注释(Annotation)。
清单1一个最简单的注释
public @interface TODO{} |
除了定义清单1中的注释以外,我们还可以在注释(Annotation)中加入域定义。方法很简单,不需定义Getter和Setter方法,而只需一个简单的方法,比如:
清单2 为注释加入域
public @interface TODO{ |
定义了这个注释之后,我们在程序中引用就可以使用这个注释了。
清单3 使用自定义的注释
@TODO( |
由于TODO中只定义了一个域,使用TODO的时候,可以简写为
清单4 单域注释的简写
@TODO("high") |
类似的,你可以在你的注释(Annotation)类型中定义多个域,也可以为每个域定义缺省值。比如:
清单5定义缺省值
public @interface TODO{ |
如果定义了缺省值,在使用的时候可以不用再赋值。比如:
清单6使用定义了缺省值的注释
@TODO(
priority="high",
owner="Catherine"
)
public void calculate(){
//body omission
}
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.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的定义已经规定了,只能用来修饰方法。
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.1动态查找注释
当我们定义好了注释以后,我们可以开发一些分析工具来解释这些注释。这里通常要用到Java的反射特性。比如说我们希望找到某个对象/方法/域使用 了哪些注释,或者获得某个特定的注释,或者判断是否使用某个特定的注释, 我们可以参考下面这个例子。这个例子中定义了两个注释:TODO和TOFORMATE。在MyCalculator类中,TODO用来修饰方法 calculateRate,而TOFORMATE用来修饰类变量concurrency和debitDate。而在类TestCalculator的 main函数中,通过Java反射特性,我们查找到使用这些注释的类变量和方法。清单12-清单15分别显示这些类的定义。
清单12 TODO注释的定义
@Target({ElementType.METHOD}) |
清单13 TOFORMATE的定义
@Target({ElementType.FIELD}) |
清单14 使用注释的类MyCalculator
public class MyCalculator { |
清单15动态查找注释
public class TestCalculator { |
下面我们来运行这个例子,这个例子的运行结果如图10所示。
运行结果和我们先前的定义是一致的。在运行时,我们可以获得注释使用的相关信息。
图6 运行结果
在我们介绍了什么是注释以后,你可能会想知道注释可以应用到什么地方呢?使用注释有什么好处呢?在下面的小节中我们将介绍一个稍复杂的例子。从这个例子中,你将体会到注释所以提供的强大的描述机制(declarative programming)。