很多API都需要相当数量的样板代码,比如,为了编写一个JAX-RPC的WEB服务,你需要提供一个接口和一个实现类。如果这个程序已经被加了注释Annotations以说明那个方法需要被远程调用,那么我们可以一个工具去自动生成这些样板代码。
还有一些API需要在程序代码另外维护一些文件,比如JavaBean需要一个BeanInfo类,EJB需要一个部署描述文件。如果我们能够把这些需要另外维护的文件内容以注释Annotation的方式和代码放在一起维护,一定会更加方便同时也减少出错的机会。
Java平台已经有了一些特别的注释的机制。比如transient修饰符就是一个特别的注释,表明这个字段应该被序列化子系统忽略;@deprecated javadoc标签是一个特别的标签来说明某个方法已经不再被使用了。JDK5.0提供了一个让我们自己定义我们自己注释的功能,这个功能包含了如何定义注释类型的语法,声明注释的语法,读取注释的API,一个类文件保存注释(译者注:注释可以被看作一个类,我们需要用一个.java文件保存我们自己定义的注释源码)和一个注释处理的工具。
注释并不影响代码的语义,但却影响用于处理包含有注释的程序代码的工具的处理方式,使他们(工具)能够影响运行状态的程序的语义。注释可以从源代码中读取,从编译后的.class文件中读取,也可以通过反射机制在运行时读取。
注释是JavaDoc标签的补充。一般情况下,如果我们的主要目标是影响或者产生文档,那么我们应该使用JavaDoc;否则,我们应该使用注释Annotations。
/**
* Describes the Request-For-Enhancement(RFE) that led
* to the presence of the annotated API element.
*/
public @interface RequestForEnhancement {
int id();
String synopsis();
String engineer() default "[unassigned]";
String date(); default "[unimplemented]";
}
一旦定义好了一个注释类型,你就可以用来作注释声明。注释一中特殊的修饰符,在其他修饰符(比如public,static,或者final等)使用地方都可以使用。按照惯例,注释应该放在其他修饰符的前面。注释的声明用@符号后面跟上这个注释类型的名字,再后面跟上括号,括号中列出这个注释中元素/方法的key-value对。值必须是常量。这里是一个例子,使用上面定义的注释类型:
@RequestForEnhancement(
id = 2868724,
synopsis = "Enable time-travel",
engineer = "Mr. Peabody",
date = "4/1/3007"
)
public static void travelThroughTime(Date destination) { ... }
没有元素/方法的注释被成为标记(marker)注释类型,例如
/**
* Indicates that the specification of the annotated API element
* is preliminary and subject to change.
*/
public @interface Preliminary { }
标记注释在使用的时候,其后面的括号可以省略,例如:
@Preliminary public class TimeTravel { ... }
如果注释中仅包含一个元素,这个元素的名字应该为value,例如:
/**
* Associates a copyright notice with the annotated API element.
*/
public @interface Copyright { String value(); }
如果元素的名字为value,使用这个注释的时候,元素的名字和等号可以省略,如:
@Copyright("2002 Yoyodyne Propulsion Systems")
public class OscillationOverthruster { ... }
为了将上面提到的东西结合在一起,我们创建了一个简单的基于注释的测试框架。首先我们需要一个标记注释类型用以说明一个方法是一个测试方法,并被测试工具执行。
import java.lang.annotation.*;
/**
* Indicates that the annotated method is a test method.
* This annotation should be used only on parameterless static methods.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test { }
我们可以注意到这个注释类型本省也被注释了,这种注释叫做元注释。第一注释(@Retention(RetentionPolicy.RUNTIME))表示这种类型的注释被VM保留从而使其能够通过反射在运行时读取;第二个注释@Target(ElementType.METHOD)表示这种注释只能用来注释方法。
下面是一个简单的类,其中的几个方法被加了上面的注释:
public class Foo {
@Test public static void m1() { }
public static void m2() { }
@Test public static void m3() {
throw new RuntimeException("Boom");
}
public static void m4() { }
@Test public static void m5() { }
public static void m6() { }
@Test public static void m7() {
throw new RuntimeException("Crash");
}
public static void m8() { }
}
这里是测试工具:
import java.lang.reflect.*;
public class RunTests {
public static void main(String[] args) throws Exception {
int passed = 0, failed = 0;
for (Method m : Class.forName(args[0]).getMethods()) {
if (m.isAnnotationPresent(Test.class)) {
try {
m.invoke(null);
passed++;
} catch (Throwable ex) {
System.out.printf("Test %s failed: %s %n", m, ex.getCause());
failed++;
}
}
}
System.out.printf("Passed: %d, Failed %d%n", passed, failed);
}
}
这个工具用一个类名作为参数,遍历这个类中的所有方法,并调用其中被加了@Test注释的方法。如果一个方法抛出了一个异常,那么这个测试就失败了,最终的测试结果被打印了出来。下面是程序运行的结果:
$ java RunTests Foo
Test public static void Foo.m3() failed: java.lang.RuntimeException: Boom
Test public static void Foo.m7() failed: java.lang.RuntimeException: Crash
Passed: 2, Failed 2
附:使用注释实例
元数据(metadata)可用于编译时的注释,借此被JVM识认,也可以被动态加载进来,在动态调用时读取其注释。事实上注释是一个接口,在编译时被编译成一个独立的文件,以下声明一个简单的注释(Student_Name.java):
import java.lang.annotation.*;
@Retention(RetentionPolicy.RUNTIME) //说明是用于运行时调用的
@Target(ElementType.METHOD) //说明该注释用于方法
public @interface Student_Name{
String name(); //声明一个简单的注释使用
}
以下是使用注释(Student.java):
public class Student{
@Student_Name(name="王文银") public static void speak(){
System.out.println("Hello,World!");
}
}
注意这里的语法: @Student_Name(name="王文银"),上面已经声明了这个注释是用于方法的,在方法speak()的声明前使用,当编译器在编译这个文件时,先寻找Student_Name这个注释,然后动态加载进来,同时给了name一个值“王文银”,以下是测试(RunStudent.java):
import java.lang.annotation.*;
import java.lang.reflect.*;
public class RunStudent{
public static void main(String[] args) throws Exception{
for(Method m:(new Student()).getClass().getMethods()){
if(m.isAnnotationPresent(Student_Name.class)){ //表示使用了注释的speak()方法
m.invoke(null); //调用speak()方法。此时屏幕输出Hello,World!
Student_Name a=m.getAnnotation(Student_Name.class); //获得方法的注释引用
System.out.println("Name:"+a.name()); //使用注释的方法,从而或得我们声明的 注释
}
}
}
}
最后结果输出:
Hello,World!
Name:王文银
这样,我们在源文件里所用的注释就可以被编译器所调用,这些更加有助于程序员的动态控制,不需要另外的第三方的文件提供.