Java Annotation 高级应用

版权声明：本文可以自由转载，转载时请务必以超链接形式标明文章原始出处和作者信息及本声明
作者:cleverpig(作者的Blog: http://blog.matrix.org.cn/page/cleverpig)
原文: http://www.matrix.org.cn/resource/article/44/44062_Java+Annotation+Apt.html
关键字:java,annotation,apt

前言：
前不久在matrix上先后发表了 《java annotation 入门》、 《java annotation 手册》两篇文章，比较全面的对java annotation的语法、原理、使用三方面进行了阐述。由于《入门》中的简单例程虽然简单明了的说明了annotation用法，但给大家的感觉可能是意犹未见，所以在此行文《java annotation高级应用》，具体实例化解释annotation和annotation processing tool（APT）的使用。望能对各位的有所帮助。

一、摘要：
《java annotation高级应用》具体实例化解释annotation和annotation processing tool（APT）的使用。望能对各位的有所帮助。本文列举了用于演示annotation的BRFW演示框架、演示APT的apt代码实例，并对其进行较为深度的分析，希望大家多多提意见。

二、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的朋友知道，这个功能类似jaxb。

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

4．BRFW源代码分析：
A．Persistent类：
清单1：

package com.bjinfotech.practice.annotation.runtimeframework;

import java.lang.annotation.*;

/** * 用于修饰类的固有类型成员变量的annotation * @author cleverpig * */@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.FIELD)public @interface Persistent {         String value() default "";}

B．Exportable类：
清单2：

package com.bjinfotech.practice.annotation.runtimeframework;

import java.lang.annotation.*;

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

}

C．AddressForTest类：
清单3：

package com.bjinfotech.practice.annotation.runtimeframework;

/** * 用于测试的地址类 * @author cleverpig * */@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．AddressListForTest类：
清单4：

package com.bjinfotech.practice.annotation.runtimeframework;

import java.util.*;

/** * 友人通讯录 * 包含：姓名、年龄、电话、住址（多个）、备注 * @author cleverpig * */@Exportable(name="addresslist",description="address list")public class AddressListForTest {        //友人姓名        @Persistent        private String friendName=null;

        //友人年龄        @Persistent        private int age=0;

        //友人电话        @Persistent        private ArrayList<String> telephone=null;

        //友人住址：家庭、单位        @Persistent        private ArrayList<AddressForTest> AddressForText=null;

        //备注        @Persistent        private String note=null;

        public AddressListForTest(String name,int age,                        ArrayList<String> telephoneList,                         ArrayList<AddressForTest> addressList,                        String note){                this.friendName=name;                this.age=age;                this.telephone=new ArrayList<String>(telephoneList);                this.AddressForText=new ArrayList<AddressForTest>(addressList);                this.note=note;

        }}

E．ExportToXml类：
清单5：

package com.bjinfotech.practice.annotation.runtimeframework;

import java.lang.reflect.Field;import java.util.Collection;import java.util.Iterator;import java.util.Map;import java.util.ArrayList;

/** * 将具有Exportable Annotation的对象转换为xml格式文本  * @author cleverpig * */public class ExportToXml {        /**         * 返回对象的成员变量的值（字符串类型）         * @param field 对象的成员变量         * @param fieldTypeClass 对象的类型         * @param obj 对象         * @return 对象的成员变量的值（字符串类型）         */        private String getFieldValue(Field field,Class fieldTypeClass,Object obj){                String value=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=getFieldValue(field,typeClass,obj);

                        //如果获得成员变量的值，则输出                        if (value!=null){                                System.out.println(getIndent()+"<"+name+">/n"                                                +getIndent()+"/t"+value+"/n"+getIndent()+"</"+name+">");                        }                        //处理成员变量中类型为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<Object> cyclicChecker=new ArrayList<Object>();

        /**         * 返回缩进字符串         * @return         */        private String getIndent(){                String s="";                for(int i=0;i<levelDepth;i++){                        s+="/t";                }                return s;        }        /**         * 输出对象，如果对象类型为Collection和Map类型，则需要递归调用exportObject进行处理         * @param obj         * @throws Exception         */        public void exportObject(Object obj) throws Exception{                Exportable exportable=null;                String elementName=null;

                //循环引用现象处理                if (cyclicChecker.contains(obj)){                        return;                }

                cyclicChecker.add(obj);

                //首先处理Collection和Map类型                if (obj instanceof Collection){                        for(Iterator i=((Collection)obj).iterator();i.hasNext();){                                exportObject(i.next());                        }                }                else if (obj instanceof Map){                        for(Iterator i=((Map)obj).keySet().iterator();i.hasNext();){                                exportObject(i.next());                        }                }                else{

                        exportable=obj.getClass().getAnnotation(Exportable.class);                        //如果obj已经被Exportable Annotation修饰过了（注意annotation是具有继承性的），                        //则使用其name作为输出xml的元素name                        if (exportable!=null){                                if (exportable.value().length()>0){                                        elementName=exportable.value();                                }                                else{                                        elementName=exportable.name();                                }                        }                        //未被修饰或者Exportable Annotation的值为空字符串，                        //则使用类名作为输出xml的元素name                        if (exportable==null||elementName.length()==0){                                elementName=obj.getClass().getSimpleName();                        }                        //输出xml元素头                        System.out.println(getIndent()+"<"+elementName+">");                        levelDepth++;                        //如果没有被修饰，则直接输出其toString()作为元素值                        if (exportable==null){                                System.out.println(getIndent()+obj.toString());                        }                        //否则将对象的成员变量导出为xml                        else{                                exportFields(obj);                        }                        levelDepth--;                        //输出xml元素结尾                        System.out.println(getIndent()+"</"+elementName+">");

                }                cyclicChecker.remove(obj);        }

        public static void main(String[] argv){                try{                        AddressForTest ad=new AddressForTest("China","Beijing",                                        "Beijing","winnerStreet","10");

                        ExportToXml test=new ExportToXml();

                        ArrayList<String> telephoneList=new ArrayList<String>();                        telephoneList.add("66608888");                        telephoneList.add("66608889");

                        ArrayList<AddressForTest> adList=new ArrayList<AddressForTest>();                        adList.add(ad);

                        AddressListForTest adl=new AddressListForTest("coolBoy",                                        18,telephoneList,adList,"some words");

                        test.exportObject(adl);                }                catch(Exception ex){                        ex.printStackTrace();                }        }}

在ExportToXml类之前的类比较简单，这里必须说明一下ExportToXml类：此类的核心函数是exportObject和exportFields方法，前者输出对象的xml信息，后者输出对象成员变量的信息。由于对象类型和成员类型的多样性，所以采取了以下的逻辑：

在exportObject方法中，当对象类型为Collection和Map类型时，则需要递归调用exportObject进行处理；
而如果对象类型不是Collection和Map类型的话，将判断对象类是否被Exportable annotation修饰过：
如果没有被修饰，则直接输出<对象类名>对象.toString()</对象类名>作为xml绑定结果的一部分；
如果被修饰过，则需要调用exportFields方法对对象的成员变量进行xml绑定。

在exportFields方法中，首先取出对象的所有成员，然后获得被Persisitent annotation修饰的成员。在其后的一句：field.setAccessible(true)是很重要的，因为bean类定义中的成员访问修饰都是private，所以为了避免java虚拟机检查对私有成员的访问权限，加上这一句是必需的。接着后面的语句便是输出<成员名>成员值</成员名>这样的xml结构。像在exportObject方法中一般，仍然需要判断成员类型是否为Collection和Map类型，如果为上述两种类型之一，则要在exportFields中再次调用exportObject来处理这个成员。

在main方法中，本人编写了一段演示代码：建立了一个由单个友人地址类（AddressForTest）组成的ArrayList作为通讯录类（AddressForTest）的成员的通讯录对象，并且输出这个对象的xml绑定，运行结果如下：

清单6：

<addresslist>        <friendName>                coolBoy        </friendName>        <age>                18        </age>        <String>                66608888        </String>        <String>                66608889        </String>        <address>                <country>                        China                </country>                <province>                        Beijing                </province>                <city>                        Beijing                </city>                <street>                        winnerStreet                </street>                <doorplate>                        10                </doorplate>        </address>        <note>                some words        </note></addresslist>

三、APT实例分析：
1．何谓APT？
根据sun官方的解释，APT（annotation processing tool）是一个命令行工具，它对源代码文件进行检测找出其中的annotation后，使用annotation processors来处理annotation。而annotation processors使用了一套反射API并具备对JSR175规范的支持。
annotation processors处理annotation的基本过程如下：首先，APT运行annotation processors根据提供的源文件中的annotation生成源代码文件和其它的文件（文件具体内容由annotation processors的编写者决定），接着APT将生成的源代码文件和提供的源文件进行编译生成类文件。
简单的和前面所讲的annotation实例BRFW相比，APT就像一个在编译时处理annotation的javac。而且从sun开发者的blog中看到，java1.6 beta版中已将APT的功能写入到了javac中，这样只要执行带有特定参数的javac就能达到APT的功能。

2．为何使用APT？
使用APT主要目的是简化开发者的工作量，因为APT可以在编译程序源代码的同时，生成一些附属文件（比如源文件、类文件、程序发布描述文字等），这些附属文件的内容也都是与源代码相关的。换句话说，使用APT就是代替了传统的对代码信息和附属文件的维护工作。使用过hibernate或者beehive等软件的朋友可能深有体会。APT可以在编译生成代码类的同时将相关的文件写好，比如在使用beehive时，在代码中使用annotation声明了许多struct要用到的配置信息，而在编译后，这些信息会被APT以struct配置文件的方式存放。

3．如何定义processor？
A．APT工作过程：
从整个过程来讲，首先APT检测在源代码文件中哪些annotation存在。然后APT将查找我们编写的annotation processor factories类，并且要求factories类提供处理源文件中所涉及的annotation的annotation processor。接下来，一个合适的annotation processors将被执行，如果在processors生成源代码文件时，该文件中含有annotation，则APT将重复上面的过程直到没有新文件生成。

B．编写annotation processors：
编写一个annotation processors需要使用java1.5 lib目录中的tools.jar提供的以下4个包：
com.sun.mirror.apt: 和APT交互的接口；
com.sun.mirror.declaration: 用于模式化类成员、类方法、类声明的接口；
com.sun.mirror.type: 用于模式化源代码中类型的接口；
com.sun.mirror.util: 提供了用于处理类型和声明的一些工具。

每个processor实现了在com.sun.mirror.apt包中的AnnotationProcessor接口，这个接口有一个名为“process”的方法，该方法是在APT调用processor时将被用到的。一个processor可以处理一种或者多种annotation类型。
一个processor实例被其相应的工厂返回，此工厂为AnnotationProcessorFactory接口的实现。APT将调用工厂类的getProcessorFor方法来获得processor。在调用过程中，APT将提供给工厂类一个AnnotationProcessorEnvironment 类型的processor环境类对象，在这个环境对象中，processor将找到其执行所需要的每件东西，包括对所操作的程序结构的参考，与APT通讯并合作一同完成新文件的建立和警告/错误信息的传输。

提供工厂类有两个方式：通过APT的“-factory”命令行参数提供，或者让工厂类在APT的发现过程中被自动定位（关于发现过程详细介绍请看 http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html）。前者对于一个已知的factory来讲是一种主动而又简单的方式；而后者则是需要在jar文件的META-INF/services目录中提供一个特定的发现路径：
在包含factory类的jar文件中作以下的操作：在META-INF/services目录中建立一个名为com.sun.mirror.apt.AnnotationProcessorFactory 的UTF-8编码文件，在文件中写入所有要使用到的factory类全名，每个类为一个单独行。

4．一个简单的APT实例分析：
A．实例构成：
Review类：定义Review Annotation；
ReviewProcessorFactory类：生成ReviewProcessor的工厂类；
ReviewProcessor类：定义处理Review annotation的Processor；
ReviewDeclarationVisitor类：定义Review annotation声明访问者，ReviewProcessor将要使用之对Class进行访问。
runapt.bat：定义了使用自定义的ReviewProcessor对Review类源代码文件进行处理的APT命令行。

B．Review类：
清单7：

package com.bjinfotech.practice.annotation.apt;

/** * 定义Review Annotation * @author cleverpig * */public @interface Review {        public static enum TypeEnum{EXCELLENT,NICE,NORMAL,BAD};        TypeEnum type();        String name() default "Review";}

C．ReviewProcessorFactory类：
清单8：

package com.bjinfotech.practice.annotation.apt;

import java.util.Collection;import java.util.Set;import java.util.Arrays;import com.sun.mirror.apt.*;import com.sun.mirror.declaration.AnnotationTypeDeclaration;import com.sun.mirror.apt.AnnotationProcessorEnvironment;//请注意为了方便，使用了静态importimport static java.util.Collections.unmodifiableCollection;import static java.util.Collections.emptySet;

/** * 生成ReviewProcessor的工厂类 * @author cleverpig * */public class ReviewProcessorFactory implements AnnotationProcessorFactory{        /**         * 获得针对某个（些）类型声明定义的Processor         * @param atds 类型声明集合         * @param env processor环境         */        public AnnotationProcessor getProcessorFor(                        Set<AnnotationTypeDeclaration> atds,                         AnnotationProcessorEnvironment env){                return new ReviewProcessor(env);        }        /**         * 定义processor所支持的annotation类型         * @return processor所支持的annotation类型的集合         */        public Collection<String>         supportedAnnotationTypes(){                //“*”表示支持所有的annotation类型                //当然也可以修改为“foo.bar.*”、“foo.bar.Baz”，来对所支持的类型进行修饰            return unmodifiableCollection(Arrays.asList("*"));    }

        /**         * 定义processor支持的选项         * @return processor支持选项的集合         */        public Collection<String>         supportedOptions(){                //返回空集合            return emptySet();    }

        public static void main(String[] argv){                System.out.println("ok");        }}

D．ReviewProcessor类：
清单9：

package com.bjinfotech.practice.annotation.apt;

import com.sun.mirror.apt.AnnotationProcessor;import com.sun.mirror.apt.AnnotationProcessorEnvironment;import com.sun.mirror.declaration.TypeDeclaration;import com.sun.mirror.util.DeclarationVisitors;import com.sun.mirror.util.DeclarationVisitor;

/** * 定义Review annotation的Processor * @author cleverpig * */public class ReviewProcessor implements AnnotationProcessor{        //Processor所工作的环境        AnnotationProcessorEnvironment env=null;

        /**         * 构造方法         * @param env 传入processor环境         */        public ReviewProcessor(AnnotationProcessorEnvironment env){                this.env=env;        }

        /**         * 处理方法：查询processor环境中的类型声明，         */        public void process(){                //查询processor环境中的类型声明                for(TypeDeclaration type:env.getSpecifiedTypeDeclarations()){                        //返回对类进行扫描、访问其声明时使用的DeclarationVisitor，                        //传入参数：new ReviewDeclarationVisitor()，为扫描开始前进行的对类声明的处理                        //        DeclarationVisitors.NO_OP，表示在扫描完成时进行的对类声明不做任何处理                        DeclarationVisitor visitor=DeclarationVisitors.getDeclarationScanner(                                        new ReviewDeclarationVisitor(),DeclarationVisitors.NO_OP);                        //应用DeclarationVisitor到类型                        type.accept(visitor);                }        }}

E．ReviewDeclarationVisitor类：
清单10：

package com.bjinfotech.practice.annotation.apt;

import com.sun.mirror.util.*;import com.sun.mirror.declaration.*;

/** * 定义Review annotation声明访问者 * @author cleverpig * */public class ReviewDeclarationVisitor extends SimpleDeclarationVisitor{        /**         * 定义访问类声明的方法：打印类声明的全名         * @param cd 类声明对象         */        public void visitClassDeclaration(ClassDeclaration cd){                System.out.println("获取Class声明:"+cd.getQualifiedName());        }

        public void visitAnnotationTypeDeclaration(AnnotationTypeDeclaration atd){                System.out.println("获取Annotation类型声明:"+atd.getSimpleName());        }

        public void visitAnnotationTypeElementDeclaration(AnnotationTypeElementDeclaration aed){                System.out.println("获取Annotation类型元素声明:"+aed.getSimpleName());        }}

F．runapt.bat文件内容如下：
清单11：

E:rem 项目根目录set PROJECT_ROOT=E:/eclipse3.1RC3/workspace/tigerFeaturePracticerem 包目录路径set PACKAGEPATH=com/bjinfotech/practice/annotation/aptrem 运行根路径set RUN_ROOT=%PROJECT_ROOT%/buildrem 源文件所在目录路径set SRC_ROOT=%PROJECT_ROOT%/testrem 设置Classpathset CLASSPATH=.;%JAVA_HOME%;%JAVA_HOME%/lib/tools.jar;%RUN_ROOT%

cd %SRC_ROOT%/%PACKAGEPATH%apt -nocompile -factory com.bjinfotech.practice.annotation.apt.ReviewProcessorFactory  ./*.java

四、参考资源：
http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
作者的Blog: http://blog.matrix.org.cn/page/cleverpig

五、源代码下载：
[ 下载文件]

发表于 @ 2006年04月11日 13:45:00 | 评论 (0)

 Java Annotation入门

版权声明：本文可以自由转载，转载时请务必以超链接形式标明文章原始出处和作者信息及本声明
作者:cleverpig(作者的Blog:
http://blog.matrix.org.cn/page/cleverpig
)
原文:[http://www.matrix.org.cn/resourc ... ava+Annotation.html]http://www.matrix.org.cn/resource/article/44/44048_Java+Annotation.html[/url]
关键字:Java,annotation,标注
摘要：
本文针对java初学者或者annotation初次使用者全面地说明了annotation的使用方法、定义方式、分类。初学者可以通过以上的说明制作简单的annotation程序，但是对于一些高级的annotation应用（例如使用自定义annotation生成javabean映射xml文件）还需要进一步的研究和探讨。涉及到深入annotation的内容，作者将在后文《Java Annotation高级应用》中谈到。
同时，annotation运行存在两种方式：运行时、编译时。上文中讨论的都是在运行时的annotation应用，但在编译时的annotation应用还没有涉及，
一、为什么使用Annotation：
在JAVA应用中，我们常遇到一些需要使用模版代码。例如，为了编写一个JAX-RPC web service，我们必须提供一对接口和实现作为模版代码。如果使用annotation对远程访问的方法代码进行修饰的话，这个模版就能够使用工具自动生成。
另外，一些API需要使用与程序代码同时维护的附属文件。例如，JavaBeans需要一个BeanInfo Class与一个Bean同时使用/维护，而EJB则同样需要一个部署描述符。此时在程序中使用annotation来维护这些附属文件的信息将十分便利而且减少了错误。
二、Annotation工作方式：
在5.0版之前的Java平台已经具有了一些ad hoc annotation机制。比如，使用transient修饰符来标识一个成员变量在序列化子系统中应被忽略。而@deprecated这个javadoc tag也是一个ad hoc annotation用来说明一个方法已过时。从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 {
        int    id();
        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 { ... }
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() { }
    }
Here is the testing tool:
    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
四、Annotation分类：
根据annotation的使用方法和用途主要分为以下几类：
1。内建Annotation——Java5.0版在java语法中经常用到的内建Annotation：
@Deprecated用于修饰已经过时的方法；
@Override用于修饰此方法覆盖了父类的方法（而非重载）；
@SuppressWarnings用于通知java编译器禁止特定的编译警告。
下面代码展示了内建Annotation类型的用法：
清单10:
package com.bjinfotech.practice.annotation;
/**
* 演示如何使用java5内建的annotation
* 参考资料：
* http://java.sun.com/docs/books/t ... OO/annotations.html
* http://java.sun.com/j2se/1.5.0/d ... ge/annotations.html
* http://mindprod.com/jgloss/annotations.html
* @author cleverpig
*
*/
import java.util.List;
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({"deprecation","unchecked"})
                void callDeprecatedMethod(List horseGroup){
                        Animal an=new Animal();
                        an.deprecatedMethod();
                        horseGroup.add(an);
                }
        }
}
2。开发者自定义Annotation：由开发者自定义Annotation类型。
下面是一个使用annotation进行方法测试的sample：
AnnotationDefineForTestFunction类型定义如下：
清单11:
package com.bjinfotech.practice.annotation;
import java.lang.annotation.*;
/**
* 定义annotation
* @author cleverpig
*
*/
//加载在VM中，在运行时进行映射
@Retention(RetentionPolicy.RUNTIME)
//限定此annotation只能标示方法
@Target(ElementType.METHOD)
public @interface AnnotationDefineForTestFunction{}
测试annotation的代码如下：
清单12:
package com.bjinfotech.practice.annotation;
import java.lang.reflect.*;
/**
* 一个实例程序应用前面定义的Annotation：AnnotationDefineForTestFunction
* @author cleverpig
*
*/
public class UsingAnnotation {
        @AnnotationDefineForTestFunction public static void method01(){}
        
        public static void method02(){}
        
        @AnnotationDefineForTestFunction public static void method03(){
                throw new RuntimeException("method03");
        }
        
        public static void method04(){
                throw new RuntimeException("method04");
        }
        
        public static void main(String[] argv) throws Exception{
                int passed = 0, failed = 0;
                //被检测的类名
                String className="com.bjinfotech.practice.annotation.UsingAnnotation";
                //逐个检查此类的方法，当其方法使用annotation声明时调用此方法
            for (Method m : Class.forName(className).getMethods()) {
               if (m.isAnnotationPresent(AnnotationDefineForTestFunction.class)) {
                  try {
                     m.invoke(null);
                     passed++;
                  } catch (Throwable ex) {
                     System.out.printf("测试 %s 失败: %s %n", m, ex.getCause());
                     failed++;
                  }
               }
            }
            System.out.printf("测试结果： 通过: %d, 失败： %d%n", passed, failed);
        }
}
3。使用第三方开发的Annotation类型
这也是开发人员所常常用到的一种方式。比如我们在使用Hibernate3.0时就可以利用Annotation生成数据表映射配置文件，而不必使用Xdoclet。
五、总结：
1。前面的文字说明了annotation的使用方法、定义方式、分类。初学者可以通过以上的说明制作简单的annotation程序，但是对于一些高级的annotation应用（例如使用自定义annotation生成javabean映射xml文件）还需要进一步的研究和探讨。
2。同时，annotation运行存在两种方式：运行时、编译时。上文中讨论的都是在运行时的annotation应用，但在编译时的annotation应用还没有涉及，因为编译时的annotation要使用annotation processing tool。
涉及以上2方面的深入内容，作者将在后文《Java Annotation高级应用》中谈到。
六、参考资源：
·Matrix-Java开发者社区:
http://www.matrix.org.cn
·
http://java.sun.com/docs/books/tutorial/java/javaOO/annotations.html
·
http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
·
http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
·
http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
·作者的Blog:
http://blog.matrix.org.cn/page/cleverpig