Annotations中文翻译
2024-07-21 02:14:10
供稿：网友
by me
许多api都需要一定数量的样板编码。例如，为了写一个jax-rpc web服务，你必须提供一对接口和实现组合。如果一个被远程访问的程序被注释标识所装饰，那么这个模板就可以利用工具来自动生成。
还有一些apis需要额外文件（side files）和程序一起并行来维持。例如，javabean需要一个beaninfo类和该bean一起并行维持，而企业级javabean（ejb）则需要一个配置描述符。如果在额外文件中的信息以程序注释的形式保存在程序本身中，那将更加便利并且使错误倾向更少。
java平台已经拥有了特别的注释机制。例如transient修饰是一个特别的注释标识：该区域应该被连续子系统忽略。而@deprecated标识是一种特殊注释标识：方法不应该再被使用。到了5.0版本中，该平台拥有一个多目的的工具就是允许你定义并使用你自己的注释类型。这种工具包括声明注释类型的语法，注释声明的语法，读取注释的apis，表示注释的类文件和一个注释处理工具。
注释不直接影响程序的语义，但是它们影响工具和库处理该程序的方法，这样就能够转过去影响运行时程序的语义。注释从源文件，类文件中被读取，或者在运行时反映出来。
典型的应用程序从来不必定义一个注释类型，但这样做也不难。注释类型声明于正常的接口（interface）声明相似。在关键字interface前加个@符号。每一个方法声明定义一个注释类型的元素。方法声明不必有参数或throws语句。返回值被限制为原始的string,class,enums,annotations和以上类型array。方法可以由缺省值。这是一个注释类型声明的例子：
/**
* 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）能够使用的任何地方。根据协定，注视应先于其它修饰成分。注释由一个at符号@跟着注释类型和括号括起来的元素值对列表。这些值必须是编译时的常量。这里有一个带有注释的对应上述注释类型声明的方法声明：
@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 { }
在marker注释中省略括号是可以的，比如：
@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 { ... }
为了把所有的联系起来，我们将建立一个简单的 基于注释的测试框架。首先我们需要一个marker注释类型来指出一个方法是一个测试方法，并且应该被测试工具来执行：
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 { }
注意这个注释类型声明是自注释的。这样的注释被叫做meta-annotations。第一个（@retention(retentionpolicy.runtime)）指出带有这种类型的注释被虚拟机保留，因此它们能够在运行时反映出来。第二个（@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注释类型（上面定义的）注释的方法的方法。这个映射队列来找出是否一个方法有一个被用绿色强调的test注释。如果测试方法启动抛出一个异常，测试则被认为已经失败。并且一个失败报告被打印出来。最后。一个摘要被打印出来显示通过和失败的测试的数量。这是在foo程序上运行这个测试工具的情况：
$ 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
这个小的测试工具示范了注释的功效，也可以被轻松扩展来克服它的限制。
