一、为什么使用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/tutorial/java/javaOO/annotations.html * http://java.sun.com/j2se/1.5.0/docs/guide/language/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。 前言: 前不久在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: 涉及以上2方面的深入内容,作者将在后文《Java Annotation高级应用》中谈到。 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
telephone=null; //友人住址:家庭、单位 @Persistent private ArrayList
AddressForText=null; //备注 @Persistent private String note=null; public AddressListForTest(String name,int age, ArrayList
telephoneList, ArrayList
addressList, String note){ this.friendName=name; this.age=age; this.telephone=new ArrayList
(telephoneList); this.AddressForText=new ArrayList
(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()+"
"); } //处理成员变量中类型为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
学习tapestry5前预先了解JDK5.0 annotation
最新推荐文章于 2020-01-16 16:11:18 发布