下面进一步深入分析Java注解的机制。


一、为什么使用Annotation：

在JAVA应用中，我们常遇到一些需要使用模版代码。例如，为了编写一个JAX-RPC web service，我们必须提供一对接口和实现作为模版代码。如果使用annotation对远程访问的方法代码进行修饰的话，这个模版就能够使用工具自动生成。
另外，一些API需要使用与程序代码同时维护的附属文件。例如，JavaBeans需要一个BeanInfo Class与一个Bean同时使用/维护，而EJB则同样需要一个部署描述符。此时在程序中使用annotation来维护这些附属文件的信息将十分便利而且减少了错误。

二、Annotation工作方式：

在5.0版之前的Java平台已经具有了一些ad hocannotation机制。比如，使用transient修饰符来标识一个成员变量在序列化子系统中应被忽略。而@deprecated这个javadoc tag也是一个ad hocannotation用来说明一个方法已过时。从Java5.0版发布以来， 5.0平台提供了一个正式的annotation功能：允许开发者定义、使用自己的annoatation类型。此功能由一个定义annotation类型的语法和一个描述annotation声明的语法，读取annotaion的API，一个使用annotation修饰的class文件，一个annotation处理工具（apt）组成。
annotation并不直接影响代码语义，但是它能够工作的方式被看作类似程序的工具或者类库，它会反过来对正在运行的程序语义有所影响。annotation可以从源文件、class文件或者以在运行时反射的多种方式被读取。
当然annotation在某种程度上使javadoc tag更加完整。一般情况下，如果这个标记对java文档产生影响或者用于生成java文档的话，它应该作为一个javadoc tag；否则将作为一个annotation。

三、Annotation使用方法：

1、类型声明方式：
通常，应用程序并不是必须定义annotation类型，但是定义annotation类型并非难事。Annotation类型声明于一般的接口声明极为类似，区别只在于它在interface关键字前面使用“@”符号。
annotation类型的每个方法声明定义了一个annotation类型成员，但方法声明不必有参数或者异常声明；方法返回值的类型被限制在以下的范围：primitives、String、Class、enums、annotation和前面类型的数组；方法可以有默认值。
下面是一个简单的annotation类型声明：
清单1：

/** * Describes the Request-For-Enhancement(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。
2、修饰方法的annotation声明方式：
annotation是一种修饰符，能够如其它修饰符（如public、static、final）一般使用。习惯用法是annotaions用在其它的修饰符前面。annotations由“@+annotation类型+带有括号的成员-值列表”组成。这些成员的值必须是编译时常量（即在运行时不变）。
A：下面是一个使用了RequestForEnhancement annotation的方法声明：
清单2:

@RequestForEnhancement( id= 2868724, synopsis = "Enable time-travel", engineer = "Mr. Peabody", date= "4/1/3007" ) public static void travelThroughTime(Date destination) { ... }

B：当声明一个没有成员的annotation类型声明时，可使用以下方式：
清单3:

/** * Indicates that the specification of the annotated API element * is preliminary and subject to change. */ public @interface Preliminary { }

作为上面没有成员的annotation类型声明的简写方式：
清单4:

@Preliminary public class TimeTravel { ... }

C： 如果在annotations中只有唯一一个成员，则该成员应命名为value：
清单5:

/** * Associates a copyright notice with the annotated API element. */ public @interface Copyright { String value(); }

更为方便的是对于具有唯一成员且成员名为value的annotation（如上文），在其使用时可以忽略掉成员名和赋值号（=）：
清单6:

@Copyright("2002 Yoyodyne Propulsion Systems") public class OscillationOverthruster { ... }

D：下面是一个复杂的Annotataion类型声明，其成员是Annotation类型的数组

import java.lang.annotation.*; /** * Reviews annotation类型只有一个成员， * 由Review annotation组成的数组 */ @Retention(RetentionPolicy.RUNTIME) public @interface Reviews { Review[] value(); }/** * Review annotation类型有3个成员： * 枚举类型成员grade * 表示Review名称的字符串类型成员Reviewer * 具有默认值的字符串类型成员Comment。 */ public @interface Review { // 内嵌的枚举类型 public static enum Grade { EXCELLENT, SATISFACTORY, UNSATISFACTORY }; // 下面的方法定义了annotation的成员 Grade grade(); String reviewer(); String comment() default ""; }

Reviews annotation类型只有一个成员，但是这个成员的类型是复杂的：由Review annotation组成的数组。Review annotation类型有3个成员：枚举类型成员grade、表示Review名称的字符串类型成员Reviewer、具有默认值的字符串类型成员Comment。
Annotation类型的成员不能是generic。只有返回值类型是Class的方法可以在annotation类型中使用generic，因为此方法能够用类转换将各种类型转换为Class。
最后，我们来定义一个annotation方法用于罗列出类运行中所有的unchecked异常（这种情况不一定是错误）。这个annotation类型将一个数组作为了唯一的成员。数组中的每个元素都是异常类。为了加强对未检查的异常（此类异常都是在运行时抛出）进行报告，我们可以在代码中对异常的类型进行限制：

public @interface UncheckedExceptions { Class[] value(); }

3、一个使用实例：
结合上面所讲的，我们在这里建立一个简单的基于annotation测试框架。首先我们需要一个annotation类型来表示某个方法是一个应该被测试工具运行的测试方法。
清单7:

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 { }

值得注意的是annotaion类型声明是可以标注自己的，这样的annotation被称为“meta-annotations”。
在上面的代码中，@Retention(RetentionPolicy.RUNTIME)这个meta-annotation表示了此类型的annotation将被虚拟机保留使其能够在运行时通过反射被读取。而@Target(ElementType.METHOD)表示此类型的annotation只能用于修饰方法声明。
下面是一个简单的程序，其中部分方法被上面的annotation所标注：
清单8:

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); } }

这个程序从命令行参数中取出类名，并且遍历此类的所有方法，尝试调用其中被上面的测试annotation类型标注过的方法。在此过程中为了找出哪些方法被annotation类型标注过，需要使用反射的方式执行此查询。如果在调用方法时抛出异常，此方法被认为已经失败，并打印一个失败报告。最后，打印运行通过/失败的方法数量。
下面文字表示了如何运行这个基于annotation的测试工具：
清单9:

$ 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

注解在很多框架、类库中有广泛的应用。如JUnit测试框架, Spring, Hibernate, EJB等等。这也是开发人员所常常用到的一种方式。

【深入理解Java注解(2)（高级应用）】上面的介绍说明了annotation的使用方法、定义方式、分类。初学者可以通过以上的说明制作简单的annotation程序，但是对于一些高级的annotation应用（例如使用自定义annotation生成javabean映射xml文件）还需要进一步的研究和探讨。同时，annotation运行存在两种方式：运行时、编译时。上文中讨论的都是在运行时的annotation应用，但在编译时的annotation应用还没有涉及，因为编译时的annotation要使用annotation processing tool(APT)。
annotation本身使用时十分简便。例如一个本地变量可以被一个以NonNull命名的annotation类型所标注，来作为对这个本地变量不能被赋予null值的断言。而我们可以编写与之配套的一个annotation代码分析工具，使用它来对具有前面变量的代码进行解析，并且尝试验证这个断言。当然这些代码并不必自己编写。在JDK安装后，在JDK/bin目录中可以找到名为“apt”的工具，它提供了处理annotation的框架：它启动后扫描源代码中的annotation，并调用我们定义好的annotation处理器完成我们所要完成的工作（比如验证前面例子中的断言）。说到这里，annotation的强大功能似乎可以替代XDoclet这类的工具了，随着我们的深入，大家会更加坚信这一点。
注：详细描述请参看JSR 250规范 http://www.jcp.org/aboutJava/communityprocess/pfd/jsr250/



四、annotation实例分析

1．BRFW（Beaninfo Runtime FrameWork）定义：
本人编写的一个annotation功能演示框架。顾名思义，BRFW就是在运行时取得bean信息的框架。
2．BRFW的功能：
A．源代码级annotation：在bean的源代码中使用annotation定义bean的信息；
B．运行时获取bean数据：在运行时分析bean class中的annotation，并将当前bean class中field信息取出，功能类似xdoclet；
C．运行时bean数据的xml绑定：将获得的bean数据构造为xml文件格式展现。熟悉j2ee的朋友知道，这个功能类似JAXP。
3．BRFW框架：
BRFW主要包含以下几个类：
A．Persistent类：定义了用于修饰类的固有成员变量的annotation。
B．Exportable类：定义了用于修饰Class的类型的annotation。
C．ExportToXml类：核心类，用于完成BRFW的主要功能：将具有Exportable Annotation的bean对象转换为xml格式文本。
D．AddressForTest类：被A和B修饰过的用于测试目的的地址bean类。其中包含了地址定义所必需的信息：国家、省级、城市、街道、门牌等。
E．ContactBookForTest类：被A和B修饰过的友人通讯录bean类。其中包含了通讯录所必备的信息：友人姓名、年龄、电话、住址（成员为AddressForTest类型的ArrayList）、备注。需要说明的是电话这个bean成员变量是由字符串类型组成的ArrayList类型。由于朋友的住址可能不唯一，故这里的住址为由AddressForTest类型组成的ArrayList。
从上面的列表中，可以发现A、B用于修饰bean类和其类成员；C主要用于取出bean类的数据并将其作xml绑定，代码中使用了E作为测试类；E中可能包含着多个D。
在了解了这个简单框架后，我们来看一下BRFW的代码吧！
4．BRFW源代码分析：
A．Persistent类：

package beaninfoframework; import java.lang.annotation.*; /** * 用于修饰类的成员变量的annotation * @author jackzhou */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.FIELD) public @interface Persistent { String value() default ""; }

B．Exportable类：

package beaninfoframework; import java.lang.annotation.*; /** * 用于修饰类类型的annotation * @author jackzhou */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface Exportable { // 名称 String name() default ""; // 描述 String description() default ""; // 省略name和description后，用来保存name值 String value() default ""; }

C．AddressForTest类：

package beaninfoframework; /** * 用于测试的地址类 * @author jackzhou */ @Exportable("address") public class AddressForTest {//国家@Persistent private String country = null; //省级 @Persistent private String province = null; //城市 @Persistent private String city = null; //街道 @Persistent private String street = null; //门牌 @Persistent private String doorplate = null; public AddressForTest(String country, String province, String city, String street, String doorplate) { this.country = country; this.province = province; this.city = city; this.street = street; this.doorplate = doorplate; } }

D．ContactBookForTest类：

package beaninfoframework; import java.util.ArrayList; /** * 用于测试的友人通讯录类 * 包含：姓名、年龄、电话、住址（多个）、备注 * @author jackzhou */ @Exportable(name = "contactbook", description = "contact book") public class ContactBookForTest {//友人姓名 @Persistent private String friendName = null; //友人年龄 @Persistent private int age = 0; //友人电话 @Persistent private ArrayList telephones = null; //友人住址：家庭、单位 @Persistent private ArrayList AddressForText = null; //备注 @Persistent private String note = null; public ContactBookForTest(String name, int age, ArrayList telephoneList, ArrayList addressList, String note) { this.friendName = name; this.age = age; this.telephones = new ArrayList<>(telephoneList); this.AddressForText = new ArrayList<>(addressList); this.note = note; } }

E．ExportToXml类：

package beaninfoframework; import java.lang.reflect.Field; import java.util.ArrayList; import java.util.Collection; import java.util.Iterator; import java.util.Map; /** * 将具有Exportable Annotation的对象转换为xml格式文本 * @author jackzhou */ public class ExportToXml {/** * 返回对象的成员变量的值（字符串类型） * @param field 对象的成员变量 * @param fieldTypeClass 对象的类型 * @param obj 对象 * @return 对象的成员变量的值（字符串类型） */ private String getFieldValue(Field field, Class fieldTypeClass, Object obj) { String value = https://www.it610.com/article/null; try { if (fieldTypeClass == String.class) { value = (String) field.get(obj); } else if (fieldTypeClass == int.class) { value = Integer.toString(field.getInt(obj)); } else if (fieldTypeClass == long.class) { value = Long.toString(field.getLong(obj)); } else if (fieldTypeClass == short.class) { value = Short.toString(field.getShort(obj)); } else if (fieldTypeClass == float.class) { value = Float.toString(field.getFloat(obj)); } else if (fieldTypeClass == double.class) { value = Double.toString(field.getDouble(obj)); } else if (fieldTypeClass == byte.class) { value = Byte.toString(field.getByte(obj)); } else if (fieldTypeClass == char.class) { value = Character.toString(field.getChar(obj)); } else if (fieldTypeClass == boolean.class) { value = Boolean.toString(field.getBoolean(obj)); } } catch (Exception ex) { ex.printStackTrace(); value = null; } return value; }/** * 输出对象的字段，当对象的字段为Collection或者Map类型时， * 要调用exportObject方法继续处理 * @param obj 被处理的对象 * @throws Exception */ public void exportFields(Object obj) throws Exception { Exportable exportable = obj.getClass().getAnnotation(Exportable.class); if (exportable != null) { if (exportable.value().length()> 0) { //System.out.println("Class annotation Name:"+exportable.value()); } else { //System.out.println("Class annotation Name:"+exportable.name()); } } else { //System.out.println(obj.getClass()+"类不是使用Exportable标注过的"); }//取出对象的成员变量 Field[] fields = obj.getClass().getDeclaredFields(); for (Field field : fields) { //获得成员变量的标注 Persistent fieldAnnotation = field.getAnnotation(Persistent.class); if (fieldAnnotation == null) { continue; } //重要:避免java虚拟机检查对私有成员的访问权限 field.setAccessible(true); Class typeClass = field.getType(); String name = field.getName(); String value = https://www.it610.com/article/getFieldValue(field, typeClass, obj); //如果获得成员变量的值，则输出 if (value != null) { System.out.println(getIndent() +"<" + name + ">\n" + getIndent() + "\t" + value + "\n" + getIndent() + ""); } //处理成员变量中类型为Collection或Map else if ((field.get(obj) instanceof Collection) || (field.get(obj) instanceof Map)) { exportObject(field.get(obj)); } else { exportObject(field.get(obj)); } } }//缩进深度 int levelDepth = 0; //防止循环引用的检查者，循环引用现象如：a包含b，而b又包含a Collection