自定义 Java Annotation及应用

转载：http://denger.iteye.com/blog/805649

作为一个Javaer 我想对于 Java Annotation（注解或元数据）并已不是什么新鲜的东西了，在现在流行的SSH、JUnit等框架中早也已经广泛使用，然而在我们实际开发中对于自定义 Annotation 的场景和需求也并不见得多，大多数都还是以使用为主。

1. 基本语法

 1 package org.denger.annotation.example;
 2 
 3 import java.lang.annotation.ElementType;
 4 import java.lang.annotation.Target;
 5 // The @Bind tag.
 6 @Target(ElementType.METHOD)
 7 @Retention(RetentionPolicy.RUNTIME)
 8 public @interface Bind {
 9     public String name();
10 
11     public int time() default 0;
12 }

以上是一个用于Method级的简单的@Bind注解类，比较有点象接口的结构，事实上，与其它任何Java接口一样，注解也将会编译成class文件。

 1 package org.denger.annotation.example;
 2 /**
 3  * Use the @Bind tag.
 4  */
 5 public class BindCase {
 6 
 7     @Bind(name="case", time=1)
 8     public void method(){
 9         // do something..
10     }
11 
12     public void method1(){
13         // do something..
14     }
15 
16     @Bind(name="case1", time=20)
17     public void method2(){
18         // do something..
19     }
20 }

编写注解处理器：
在 JASE 1.5扩展了了反射机制的API，为我们提供了相应的注解处理器的API，另外还可以通过外部工具 apt 来解析带有注解的Java Code.

 1 public class BindCaseTracker{
 2     
 3     private static Logger logger = Logger.getLogger(BindCaseTracker.class);
 4     
 5     public static void printBindCase(Class<?> bindClass){
 6         assert bindClass != null;
 7         for (Method method : bindClass.getDeclaredMethods()){
 8             Bind bind = method.getAnnotation(Bind.class);
 9             if (bind == null) continue; // Not found annotation.
10 
11             logger.debug(String.format("Found [%s] Bind Case : %s-%d", method
12                     .getName(), bind.name(), bind.time()));
13         }
14     }
15 
16     public static void main(String[] args) {
17         BindCaseTracker.printBindCase(BindCase.class);
18     }
19 }  /* Output:
20 [DEBUG] 11-08 14:15 Found [method] Bind Case : case-1
21 [DEBUG] 11-08 14:15 Found [method2] Bind Case : case1-20
22 *///~

2. 元注解
     在J2SE中内置了三种常用标准注解(Override, Deprecated, SuppressWarnings)以及四种元注解：
     @Target: 表示该注解可以用于什么地方。可用ElementType枚举类型主要有：
               TYPE : 类、接口或enum声明
               FIELD: 域(属性)声明
               METHOD: 方法声明
               PARAMETER: 参数声明
               CONSTRUCTOR: 构造方法声明
               LOCAL_VARIABLE:局部变量声明
               ANNOTATION_TYPE:注释类型声明
               PACKAGE: 包声明
     @Retention: 表示需要在什么级别保存该注解信息。可用RetentionPolicy枚举类型主要有：
              SOURCE: 注解将被编译器丢弃。
              CLASS : 注解在class文件中可能。但会被VM丢弃。
              RUNTIME: VM将在运行时也保存注解(如果需要通过反射读取注解，则使用该值)。
     @Documented: 将此注解包含在Javadoc中。
     @Inherited: 允许子类继承父类中的注解。

3. 使用技巧
           a. 如果希望定义的注解用于多种 ElementType 的话可以写成：

1 import static java.lang.annotation.ElementType
2 @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })

b. 在声明注解中的方法时可通过 default 来指定默认值。
c. 在声明注解中的方法返回类型可结合泛型使用，如：

1 Class<? extends Payload>[] payload() default {};

d. 可在注解类中定义嵌套注解，如：

 1 import static java.lang.annotation.ElementType
 2 
 3 @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
 4 @Retention(RUNTIME)
 5 @Documented
 6 public @interface NotNull {
 7     String message() default "{javax.validation.constraints.NotNull.message}";
 8 
 9     @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
10     @Retention(RUNTIME)
11     @Documented
12     @interface List {
13         NotNull[] value();
14     }
15 }

1 @NotNull.List(value = { @NotNull })
2 protected List<?> list;

e. 在JASE中提供了很少的内置注解，不过JBoss提供了一个 validation-api 的类库，提供常用验证注解。有兴趣的朋友可以下载看看，其 maven 依赖为：

1 <dependency>
2   <groupId>javax.validation</groupId>
3   <artifactId>validation-api</artifactId>
4   <version>1.0</version>
5 </dependency>