摘要
本文针对java初学者或者annotation初次使用者全面地说明了annotation的使用方法定义方式分类初学者可以通过以上的说明制作简单的annotation程序但是对于一些高级的annotation应用（例如使用自定义annotation生成javabean映射xml文件）还需要进一步的研究和探讨涉及到深入annotation的内容作者将在后文《Java Annotation高级应用》中谈到
同时annotation运行存在两种方式运行时编译时上文中讨论的都是在运行时的annotation应用但在编译时的annotation应用还没有涉及
一为什么使用Annotation
在JAVA应用中我们常遇到一些需要使用模版代码例如为了编写一个JAXRPC web service我们必须提供一对接口和实现作为模版代码如果使用annotation对远程访问的方法代码进行修饰的话这个模版就能够使用工具自动生成
另外一些API需要使用与程序代码同时维护的附属文件例如JavaBeans需要一个BeanInfo Class与一个Bean同时使用/维护而EJB则同样需要一个部署描述符此时在程序中使用annotation来维护这些附属文件的信息将十分便利而且减少了错误
二Annotation工作方式
在版之前的Java平台已经具有了一些ad hoc annotation机制比如使用transient修饰符来标识一个成员变量在序列化子系统中应被忽略而@deprecated这个javadoc tag也是一个ad hoc annotation用来说明一个方法已过时从Java版发布以来平台提供了一个正式的annotation功能允许开发者定义使用自己的annoatation类型此功能由一个定义annotation类型的语法和一个描述annotation声明的语法读取annotaion的API一个使用annotation修饰的class文件一个annotation处理工具（apt）组成
annotation并不直接影响代码语义但是它能够工作的方式被看作类似程序的工具或者类库它会反过来对正在运行的程序语义有所影响annotation可以从源文件class文件或者以在运行时反射的多种方式被读取
当然annotation在某种程度上使javadoc tag更加完整一般情况下如果这个标记对java文档产生影响或者用于生成java文档的话它应该作为一个javadoc tag否则将作为一个annotation
三Annotation使用方法
类型声明方式
通常应用程序并不是必须定义annotation类型但是定义annotation类型并非难事Annotation类型声明于一般的接口声明极为类似区别只在于它在interface关键字前面使用@符号
annotation类型的每个方法声明定义了一个annotation类型成员但方法声明不必有参数或者异常声明方法返回值的类型被限制在以下的范围primitivesStringClassenumsannotation和前面类型的数组方法可以有默认值
下面是一个简单的annotation类型声明
清单
/**
* Describes the RequestForEnhancement(RFE) that led
* to the presence of the annotated API element
*/
public @interface RequestForEnhancement {
intid();
String synopsis();
String engineer() default [unassigned];
String date();default [unimplemented];
}
代码中只定义了一个annotation类型RequestForEnhancement
修饰方法的annotation声明方式
annotation是一种修饰符能够如其它修饰符（如publicstaticfinal）一般使用习惯用法是annotaions用在其它的修饰符前面annotations由@+annotation类型+带有括号的成员值列表组成这些成员的值必须是编译时常量（即在运行时不变）
A下面是一个使用了RequestForEnhancement annotation的方法声明
清单
@RequestForEnhancement(
id =
synopsis = Enable timetravel
engineer = Mr Peabody
date = //
)
public static void travelThroughTime(Date destination) { }
B当声明一个没有成员的annotation类型声明时可使用以下方式
清单
/**
* Indicates that the specification of the annotated API element
* is preliminary and subject to change
*/
public @interface Preliminary { }
作为上面没有成员的annotation类型声明的简写方式
清单
@Preliminary public class TimeTravel { }
C如果在annotations中只有唯一一个成员则该成员应命名为value
清单
/**
* Associates a copyright notice with the annotated API element
*/
public @interface Copyright {
String value();
}
更为方便的是对于具有唯一成员且成员名为value的annotation（如上文）在其使用时可以忽略掉成员名和赋值号（=）
清单
@Copyright( Yoyodyne Propulsion Systems)
public class OscillationOverthruster { }
一个使用实例
结合上面所讲的我们在这里建立一个简单的基于annotation测试框架首先我们需要一个annotation类型来表示某个方法是一个应该被测试工具运行的测试方法
清单
import javalangannotation*;
/**
* Indicates that the annotated method is a test method
* This annotation should be used only on parameterless static methods
*/
@Retention(RetentionPolicyRUNTIME)
@Target(ElementTypeMETHOD)
public @interface Test { }
值得注意的是annotaion类型声明是可以标注自己的这样的annotation被称为metaannotations
在上面的代码中@Retention（RetentionPolicyRUNTIME）这个metaannotation表示了此类型的annotation将被虚拟机保留使其能够在运行时通过反射被读取而@Target（ElementTypeMETHOD）表示此类型的annotation只能用于修饰方法声明
下面是一个简单的程序其中部分方法被上面的annotation所标注
清单
public class Foo {
@Test public static void m() { }
public static void m() { }
@Test public static void m() {
throw new RuntimeException(Boom);
}
public static void m() { }
@Test public static void m() { }
public static void m() { }
@Test public static void m() {
throw new RuntimeException(Crash);
}
public static void m() { }
}
Here is the testing tool:
import javalangreflect*;
public class RunTests {
public static void main(String[] args) throws Exception {
int passed = failed = ;
for (Method m : ClassforName(args[])getMethods()) {
if (misAnnotationPresent(Testclass)) {
try {
minvoke(null);
passed++;
} catch (Throwable ex) {
Systemoutprintf(Test %s failed: %s %n m exgetCause());
failed++;
}
}
}
Systemoutprintf(Passed: %d Failed %d%n passed failed);
}
}
这个程序从命令行参数中取出类名并且遍历此类的所有方法尝试调用其中被上面的测试annotation类型标注过的方法在此过程中为了找出哪些方法被annotation类型标注过需要使用反射的方式执行此查询如果在调用方法时抛出异常此方法被认为已经失败并打印一个失败报告最后打印运行通过/失败的方法数量
下面文字表示了如何运行这个基于annotation的测试工具
清单
$ java RunTests Foo
Test public static void Foom() failed: javalangRuntimeException: Boom
Test public static void Foom() failed: javalangRuntimeException: Crash
Passed: Failed
四Annotation分类
根据annotation的使用方法和用途主要分为以下几类
内建Annotation——Java版在java语法中经常用到的内建Annotation
@Deprecated用于修饰已经过时的方法
@Override用于修饰此方法覆盖了父类的方法（而非重载）
@SuppressWarnings用于通知java编译器禁止特定的编译警告
下面代码展示了内建Annotation类型的用法
清单
package combjinfotechpracticeannotation;
/**
* 演示如何使用java内建的annotation
* 参考资料
* ml
* /docs/guide/language/l
*
* @author cleverpig
*
*/
import javautilList;
public class UsingBuiltInAnnotation {
//食物类
class Food{}
//干草类
class Hay extends Food{}
//动物类
class Animal{
Food getFood(){
return null;
}
//使用Annotation声明Deprecated方法
@Deprecated
void deprecatedMethod(){
}
}
//马类继承动物类
class Horse extends Animal{
//使用Annotation声明覆盖方法
@Override
Hay getFood(){
return new Hay();
}
//使用Annotation声明禁止警告
@SuppressWarnings({deprecationunchecked})
void callDeprecatedMethod(List horseGroup){
Animal an=new Animal();
andeprecatedMethod();
horseGroupadd(an);
}
}
}
开发者自定义Annotation由开发者自定义Annotation类型
下面是一个使用annotation进行方法测试的sample
AnnotationDefineForTestFunction类型定义如下
清单
package combjinfotechpracticeannotation;
import javalangannotation*;
/**
* 定义annotation
* @author cleverpig
*
*/
//加载在VM中在运行时进行映射
@Retention(RetentionPolicyRUNTIME)
//限定此annotation只能标示方法
@Target(ElementTypeMETHOD)
public @interface AnnotationDefineForTestFunction{}
测试annotation的代码如下
清单
package combjinfotechpracticeannotation;
import javalangreflect*;
/**
* 一个实例程序应用前面定义的AnnotationAnnotationDefineForTestFunction
* @author cleverpig
*
*/
public class UsingAnnotation {
@AnnotationDefineForTestFunction public static void method(){}
public static void method(){}
@AnnotationDefineForTestFunction public static void method(){
throw new RuntimeException(method);
}
public static void method(){
throw new RuntimeException(method);
}
public static void main(String[] argv) throws Exception{
int passed = failed = ;
//被检测的类名
String className=combjinfotechpracticeannotationUsingAnnotation;
//逐个检查此类的方法当其方法使用annotation声明时调用此方法
for (Method m : ClassforName(className)getMethods()) {
if (misAnnotationPresent(AnnotationDefineForTestFunctionclass)) {
try {
minvoke(null);
passed++;
} catch (Throwable ex) {
Systemoutprintf(测试 %s 失败: %s %n m exgetCause());
failed++;
}
}
}
Systemoutprintf(测试结果通过: %d 失败 %d%n passed failed);
}
}
使用第三方开发的Annotation类型
这也是开发人员所常常用到的一种方式比如我们在使用Hibernate时就可以利用Annotation生成数据表映射配置文件而不必使用Xdoclet
五总结
前面的文字说明了annotation的使用方法定义方式分类初学者可以通过以上的说明制作简单的annotation程序但是对于一些高级的annotation应用（例如使用自定义annotation生成javabean映射xml文件）还需要进一步的研究和探讨
同时annotation运行存在两种方式运行时编译时上文中讨论的都是在运行时的annotation应用但在编译时的annotation应用还没有涉及因为编译时的annotation要使用annotation processing tool
