• 丰搜首页
• 文档中心
• 视频中心
• 丰搜贴吧
• 问题集锦
• 更多功能

选择显示字体大小

• 最大
• 较大
• 标准

java annotation入门

java annotation入门
作者：cleverpig




版权声明：本文可以自由转载，转载时请务必以超链接形式标明文章原始出处和作者信息及本声明
作者:cleverpig(作者的blog:http://blog.matrix.org.cn/page/cleverpig)
原文:[http://www.matrix.org.cn/resource/article/44/44048_java+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/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。

涉及以上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

 

关键字 本文所属关键字

相关 与本文相关文章

分类 所有文章关键字导航

标准 网站致力的规范