Java Annotation(注解)

[color=#345286] 原文地址：[url]http://iwtxokhtd.iteye.com/blog/359939[/url][/color]

[color=#345286] Annotation(注释)是 JDK5.0 及以后版本引入的。它可以用于创建文档，跟踪代码中的依赖性，甚至执行基本编译时检查。注释是以 [b]@注释名[/b] 在代码中存在的，根据注释参数的个数，我们可以将注释分为：标记注释、单值注释、完整注释三类。它们都不会直接影响到程序的语义，只是作为注释(标识)存在，我们可以通过反射机制编程实现对这些元数据的访问。另外，你可以在编译时选择代码里的注释是否只存在于源代码级，或者它也能在 class 文件中出现。[/color]

[color=#345286] 如果要对于元数据的作用进行分类，目前还没有明确的定义，不过我们可以根据它所起的作用，大致可分为三类：[/color]
[list=1]
[*] [color=#345286]编写文档：通过代码里标识的元数据生成文档[/color]
[*] [color=#345286]代码分析：通过代码里标识的元数据对代码进行分析[/color]
[*] [color=#345286]通过代码里标识的元数据让编译器能实现基本的编译检查[/color]
[/list]
[color=#FF0000] [b][size=medium]● 基本内置注释[/size][/b][/color]
[color=#345286] [b]@Override[/b][/color]
[color=#345286] 不用多说，用来标注方法是覆写父类的方法。[/color]

[color=#345286] [b]@Deprecated[/b][/color]
[color=#345286] @Deprecated 的作用是对不应该在使用的类或方法添加注释，当编程人员使用这些类或方法时，将会在编译时显示提示信息，它与 javadoc 里的 @deprecated 标记有相同的功能，准确的说，它还不如 javadoc @deprecated，因为它不支持参数。[/color]

[color=#345286] [b]@SuppressWarnings[/b][/color]
[color=#345286] @SuppressWarnings 允许你选择性地取消特定代码段(即，类或方法)中的警告。其中的想法是当你看到警告时，你将调查它，如果你确定它不是问题，你就可以添加一个 @SuppressWarnings 注解，以使你不会再看到警告。虽然它听起来似乎会屏蔽潜在的错误，但实际上它将提高代码安全性，因为它将防止你对警告无动于衷 — 你看到的每一个警告都将值得注意。[/color]
[color=#345286] @SuppressWarnings 有如下参数：[/color]
[color=#345286] [b]deprecation[/b]: 使用了过时的类或方法时的警告[/color]
[color=#345286] [b]unchecked[/b]: 执行了未检查的转换时的警告[/color]
[color=#345286] [b]fallthrough[/b]: 当 switch 程序块直接通往下一种情况而没有 Break 时的警告[/color]
[color=#345286] [b]path[/b]: 在类路径、源文件路径等中有不存在的路径时的警告[/color]
[color=#345286] [b]serial[/b]: 当在可序列化的类上缺少 serialVersionUID 定义时的警告[/color]
[color=#345286] [b]finally[/b]: 任何 finally 子句不能正常完成时的警告[/color]
[color=#345286] [b]all[/b]: 关于以上所有情况的警告[/color]

[color=#FF0000] [b][size=medium]● 自定义注释[/size][/b][/color]
[color=#345286] 它类似于新创建一个接口类文件，但为了区分，我们需要将它声明为 @interface，如下例：[/color]

public @interface MyAnnotation {

}

[color=#345286] 使用自定义的注释类型：[/color]
[code]
public class AnnotationTest {
@MyAnnotation
public static void main(String[] args) {

}
}
[/code]
[color=#345286] 为自定义注释添加变量：[/color]
[code]
public @interface MyAnnotation {
String value();
}
[/code]
[code]
public class AnnotationTest {
@MyAnnotation("main method")
public static void main(String[] args) {
saying();
}

@MyAnnotation(value = "say method")
public static void saying() {

}
}
[/code]
[color=#345286] 定义一个枚举类型，然后将参数设置为该枚举类型，并赋予默认值：[/color]

public @interface Greeting {   
    public enum FontColor {
        BLUE,RED,GREEN
    }

    String name();
    FontColor fontColor() default FontColor.RED;
}

[color=#345286] 这里有两种选择，其实变数也就是在赋予默认值的参数上，我们可以选择使用该默认值，也可以重新设置一个值来替换默认值：[/color]

@MyAnnonation("main method")
public static void main(String[] args) {
    saying();   
    sayHelloWithDefaultFontColor();   
    sayHelloWithRedFontColor();   

}

@MyAnnonation("say method")
public static void saying() {

}

// 此时的 fontColor 为默认的 RED
@Greeting(name="defaultfontcolor")
public static void sayHelloWithDefaultFontColor() {   

}

//现在将 fontColor 改为 BLUE
@Greeting(name="notdefault",fontColor=Greeting.FontColor.BLUE)
public static void sayHelloWithRedFontColor() {   

}

[color=#FF0000] [b][size=medium]● 注释的高级应用[/size][/b][/color]
[color=#345286] [b]限制注释的使用范围[/b][/color]
[color=#345286] 用 @Target 指定 ElementType 属性：[/color]

package java.lang.annotation;

public enum ElementType {   
    // 用于类，接口，枚举但不能是注释
    TYPE,
    // 字段上，包括枚举值  
    FIELD,
    // 方法，不包括构造方法
    METHOD,
    // 方法的参数
    PARAMETER,
    // 构造方法
    CONSTRUCTOR,  
    // 本地变量或 catch 语句
    LOCAL_VARIABLE,
    // 注释类型(无数据)
    ANNOTATION_TYPE,
    // Java 包
    PACKAGE
}

[color=#345286] [b]注解保持性策略[/b][/color]

// 限制注解使用范围
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
public @interface Greeting {
    // 使用枚举类型
    public enum FontColor {
        BLUE,RED,GREEN
    }

    String name();
    FontColor fontColor() default FontColor.RED;
}

[color=#345286] 在 Java 编译器编译时，它会识别在源代码里添加的注释是否还会保留，这就是 [b]RetentionPolicy。[/b]下面是 Java 定义的 RetentionPolicy枚举(编译器的处理有三种策略)：[/color]
[list=1]
[*] [color=#345286]将注释保留在编译后的类文件中，并在第一次加载类时读取它[/color]
[*] [color=#345286]将注释保留在编译后的类文件中，但是在运行时忽略它[/color]
[*] [color=#345286]按照规定使用注释，但是并不将它保留到编译后的类文件中[/color]
[/list]

package java.lang.annotation;

public enum RetentionPolicy {   
    // 此类型会被编译器丢弃
    SOURCE,
    // 此类型注释会保留在class文件中，但JVM会忽略它
    CLASS,   
    // 此类型注释会保留在class文件中，JVM会读取它
    RUNTIME 
}

// 让保持性策略为运行时态，即将注解编码到 class 文件中，让虚拟机读取
@Retention(RetentionPolicy.RUNTIME)
public @interface Greeting {
    //使用枚举类型
    public enum FontColor {
        BLUE,RED,GREEN
    };

    String name();
    FontColor fontColor() default FontColor.RED;
}

[color=#345286] [b]文档化功能[/b][/color]
[color=#345286] Java 提供的 Documented 元注释跟 Javadoc 的作用是差不多的，其实它存在的好处是开发人员可以定制 Javadoc 不支持的文档属性，并在开发中应用。它的使用跟前两个也是一样的，简单代码示例如下：[/color]

// 让它定制文档化功能
// 使用此注解时必须设置 RetentionPolicy 为 RUNTIME
@Documented
public @interface Greeting {
    //使用枚举类型
    public enum FontColor{
        BLUE,RED,GREEN
    };

    String name();
    FontColor fontColor() default FontColor.RED;
}

[color=#345286] [b]标注继承[/b][/color]

// 让它允许继承，可作用到子类
@Inherited
public @interface Greeting {
    //使用枚举类型
    public enum FontColor{
        BLUE,RED,GREEN
    };

    String name();
    FontColor fontColor() default FontColor.RED;
}

[color=#FF0000] [b][size=medium]● 读取注解信息[/size][/b][/color]
[color=#345286] 属于重点，在系统中用到注解权限时非常有用，可以精确控制权限的粒度。[/color]

package com.iwtxokhtd.annotation;
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;

//读取注解信息
public class ReadAnnotationInfoTest {
  public static void main(String[] args)throws Exception {
    // 测试 AnnotationTest 类，得到此类的类对象
    Class c=Class.forName("com.iwtxokhtd.annotation.AnnotationTest");
    // 获取该类所有声明的方法
    Method []methods=c.getDeclaredMethods();
    // 声明注解集合
    Annotation[] annotations;
    // 遍历所有的方法得到各方法上面的注解信息
    for (Method method:methods) {
      // 获取每个方法上面所声明的所有注解信息
      annotations=method.getDeclaredAnnotations();
      // 再遍历所有的注解，打印其基本信息
      for (Annotation an:annotations) {
        System.out.println("方法名为："+ method.getName() + " 其上面的注解为：" + 
            an.annotationType().getSimpleName());
        Method []meths=an.annotationType().getDeclaredMethods();
        // 遍历每个注解的所有变量
        for (Method meth:meths) {
          System.out.println("注解的变量名为："+meth.getName());
        }
      }
    }
  }
}