java 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和前面类型的数组；方法可以有默认值。

/** * 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。

 

说明：一个annotation类型是一个annotation特有的名称，连同所有的默认值与相关信息一起。

常用的内建的Annotation有：
@Deprecated用于修饰已经过时的方法；
@Override用于修饰此方法覆盖了父类的方法（而非重载）；
@SuppressWarnings用于通知java编译器禁止特定的编译警告。

2。修饰方法的annotation声明方式：
annotation 是一种修饰符，能够如其它修饰符（如public、static、final）一般使用。习惯用法是annotaions用在其它的修饰符前面。 annotations由“@+annotation类型+带有括号的成员-值列表”组成。这些成员的值必须是编译时常量（即在运行时不变）。

A：下面是一个使用了RequestForEnhancement annotation的方法声明：
 

@RequestForEnhancement(    
    id       = 2868724,       
    synopsis = "Enable time-travel",       
    engineer = "Mr. Peabody",        
    date     = "4/1/3007"   
 )    

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("2002 Yoyodyne Propulsion Systems")    
public class OscillationOverthruster { ... }

  

3。一个使用实例：

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所标注：

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的测试工具：

    $ 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