Java Annotation基本介绍

这两周接到的任务是同事写前台c++builder展现相片管理系统功能，而我则完成部分后台与数据库java功能实现。

在两种不同的语言之间，可以用xml来传递信息，不过在我们项目中是采用json。

返回JSON需要采用自定义注释标记java对象某些需过滤的字段，先让我非常感谢网上的一位朋友贡献以下的资源：

 

1、Java Annotation基本介绍
 转自：http://numenzq.javaeye.com/blog/153909 
摘要
Annotation(注释)是J2SE 5.0引入的新功能，它被定义为JSR-175规范。简单地说，它可以用于创建文档，跟踪代码中的依赖性，甚至执行基本编译时检查。本文只会介绍注释的基本概念，以及Java内置注释的使用方法；关于定制注释及其他高级主题将在下一篇文章中讲解。
 
正文
编程的一个最新的趋势，尤其是在Java编程方面，就是使用元数据。直到JSR-175 提案的通过，并在J2SE 5.0上实现，你才有了使用注释的机会，在不断的发展和演进中，基于JSR-181的元数据批注标准，能让我们更轻松的开发和部署Web Service了，不需要被大量的配置文件所烦恼，说得有点远了，转回整体，元数据是可以添加到代码中的修饰符，它可以用于包声明、类型声明、构造函数、方法、字段、参数和变量。J2SE包含内置注释，还支持你自己编写的定制注释。
 
内容
l         注释基本知识
l         元数据的作用
l         基本内置注释
l         概要
 
注释基础知识
    在J2SE 5.0中，注释是以‘@注释名’在代码中存在的，例如：J2SE 5.0内置的注释：@Override、@Deprecated；有的注释还可以添加一些参数值，例如：@SuppressWarnings(value="unchecked")；对于这种只有一个参数，且参数名为value的注释，我们在使用时可以简写为：@SuppressWarnings("unchecked")。
    根据注释参数的个数，我们可以将注释分为：标记注释、单值注释、完整注释三类。它们都不会直接影响到程序的语义，只是作为注释（标识）存在，我们可以通过反射机制编程实现对这些元数据的访问。另外，你可以在编译时选择代码里的注释是否只存在于源代码级，或者它也能在class文件中出现。
 
元数据的作用
如果要对于元数据的作用进行分类，目前还没有明确的定义，不过我们可以根据它所起的作用，大致可分为三类：
l         编写文档：通过代码里标识的元数据生成文档。
l         代码分析：通过代码里标识的元数据对代码进行分析。
l         编译检查：通过代码里标识的元数据让编译器能实现基本的编译检查。
 
基本内置注释
    @Override注释能实现编译时检查，你可以为你的方法添加该注释，以声明该方法是用于覆盖父类中的方法。如果该方法不是覆盖父类的方法，将会在编译时报错。例如我们为某类重写toString()方法却写成了tostring()，并且我们为该方法添加了@Override注释；代码如下：
package com.gelc.annotation.demo.basic;
 
public class OverrideDemo {
 
    // @Override
    public String tostring() {
 
        return super.toString();
    }
}
在编译时，则会提示以下错误信息：
OverrideTest.java:5: 方法未覆盖其父类的方法
        @Override
         ^
1 错误
    就像示例演示的那样，该注释一大好处就是可以在编译时帮我们捕获部分编译错误，但又有多少编程人员愿意为每个覆盖父类的方法添加该注释呢？这个只有靠编程人员自己进行取舍了。
 
    @Deprecated的作用是对不应该在使用的方法添加注释，当编程人员使用这些方法时，将会在编译时显示提示信息，它与javadoc里的@deprecated标记有相同的功能，准确的说，它还不如javadoc @deprecated，因为它不支持参数，使用@Deprecated的示例代码示例如下：
package com.gelc.annotation.demo.basic;
 
public class DeprecatedDemo {
 
    public static void main(String[] args) {
 
        // DeprecatedClass.DeprecatedMethod();
    }
}
 
class DeprecatedClass {
 
    @Deprecated
    public static void DeprecatedMethod() {
        // TODO
    }
}
    编译时，会得到以下提示：
注意：DeprecatedDemo.java 使用或覆盖了已过时的 API。
注意：要了解详细信息，请使用 -Xlint:deprecation 重新编译。
    如果在编译时添加-Xlint:deprecation参数，我们能更清楚的看到该警告的详细信息，如下：
DeprecatedDemo.java:6: 警告：[deprecation] SomeClass 中的 DeprecatedMethod() 已
过时
                SomeClass.DeprecatedMethod();
                         ^
1 警告
    通过上面的示例，你已经掌握到了如何使用@Deprecated，但你理解到@Deprecated与@deprecated的区别了吗？你可以简单的理解为：@Deprecated是为了编译时检查，而@deprecated是为了生成文档的需要，各尽其责。
 
    @SuppressWarnings与前两个注释有所不同，你需要添加一个参数才能正确使用，这些参数值都是已经定义好了的，我们选择性的使用就好了，参数如下：
 
参数 语义   
deprecation 使用了过时的类或方法时的警告   
unchecked 执行了未检查的转换时的警告，例如当使用集合时没有用泛型 (Generics) 来指定集合保存的类型   
fallthrough 当 Switch 程序块直接通往下一种情况而没有 Break 时的警告   
path 在类路径、源文件路径等中有不存在的路径时的警告   
serial 当在可序列化的类上缺少 serialVersionUID 定义时的警告   
finally 任何 finally 子句不能正常完成时的警告   
all 关于以上所有情况的警告 
    通过上面的表格，你应该了解到每个参数的用意了，下面我就以一个常用的参数unchecked为例，为你展示如何使用@SuppressWarnings注释，示例代码如下：
package com.gelc.annotation.demo.basic;
 
import java.util.List;
import java.util.ArrayList;
 
public class SuppressWarningsDemo {
 
    public static List cache = new ArrayList();
 
    // @SuppressWarnings(value = "unchecked")
    public void add(String data) {
 
        cache.add(data);
    }
}
    当我们不使用@SuppressWarnings注释时，编译器就会有如下提示：
注意：SuppressWarningsDemo.java 使用了未经检查或不安全的操作。
注意：要了解详细信息，请使用 -Xlint:unchecked 重新编译。
相信你对这个提示相当熟悉了，我就不在这里多说了。下面我们还是来试试使用了@SuppressWarnings(value="unchecked")注释会是什么效果，它会屏蔽编译时的警告信息，这也就是它所要达到的目的。另外，由于@SuppressWarnings注释只有一个参数，并且参数名为value，所以我们可以将上面一句注释简写为@SuppressWarnings("unchecked")。

2、Java Annotation进阶——自定义注释
摘要
在前一篇文章中，已经向你介绍了Annotation的基本概念、作用、Java内置注释等，本文将向你展示在J2SE 5.0或更高版本中Annotation(注释)更强大的一面：自定义注释，开发人员可以根据需求编写特定功能的注释。通过对本文的学习，我们将了解到如何创建注释，使用自定义注释等知识。
 
内容
        定制注释类型
        使用定制的注释类型
        添加变量
        为变量赋默认值
        概要
 
定制注释类型
    好的，让我们创建一个自己的注释类型（annotation type）吧。它类似于新创建一个接口类文件，但为了区分，我们需要将它声明为@interface,如下例：
public @interface NewAnnotation {
 
}
 
使用定制的注释类型
    我们已经成功地创建好一个注释类型NewAnnotation，现在让我们来尝试使用它吧，如果你还记得本文的第一部分，那你应该知道他是一个标记注释，使用也很容易，如下例：
public class AnnotationTest {
 
    @NewAnnotation
    public static void main(String[] args) {
   
    }
}
 
添加变量
    J2SE 5.0里，我们了解到内置注释@SuppressWarnings()是可以使用参数的，那么自定义注释能不能定义参数个数和类型呢？答案是当然可以，但参数类型只允许为基本类型、String、Class、枚举类型等，并且参数不能为空。我们来扩展NewAnnotation，为之添加一个String类型的参数，示例代码如下：
public @interface NewAnnotation {
 
    String value();
}
    使用该注释的代码如下：正如你所看到的，该注释的使用有两种写法，这也是在之前的文章里所提到过的。如果你忘了这是怎么回事，那就再去翻翻吧。
public class AnnotationTest {
 
    @NewAnnotation("Just a Test.")
    public static void main(String[] args) {
        sayHello();
    }
   
    @NewAnnotation(value="Hello NUMEN.")
    public static void sayHello() {
        // do something
    }
}
 
为变量赋默认值
    我们对Java自定义注释的了解正在不断的增多，不过我们还需要更过，在该条目里我们将了解到如何为变量设置默认值，我们再对NewAnnotaion进行修改，看看它会变成什么样子，不仅参数多了几个，连类名也变了。但还是很容易理解的，我们先定义一个枚举类型，然后将参数设置为该枚举类型，并赋予默认值。
public @interface Greeting {
 
    public enum FontColor {RED, GREEN, BLUE};
 
    String name();
 
    String content();
   
    FontColor fontColor() default FontColor.BLUE;
}
    我们还是来看看如何使用吧，这里有两种选择，其实变数也就是在赋予默认值的参数上，我们可以选择使用该默认值，也可以重新设置一个值来替换默认值，如下例：
public class AnnotationTest {
 
    @NewAnnotation("Just a Test.")
    public static void main(String[] args) {
       
        sayHello();
        sayHelloWithDefaultFontColor();
        sayHelloWithRedFontColor();
    }
   
    @NewAnnotation("Hello NUMEN.")
    public static void sayHello() {
       
    }
   
    @Greeting(name="NUMEN", content="Hello")
    public static void sayHelloWithDefaultFontColor() {
        // do something
    }
   
    @Greeting(name="NUMEN", content="Hello", fontColor=Greeting.FontColor.RED )
    public static void sayHelloWithRedFontColor() {
        // do something
    }
}

 

3、Java Annotation进阶——自定义注释限制范围
摘要
在之前的文章中，我们已经了解了Annotation的基本概念，Java的内置Annotation和如何定制自己的Annotation；在这里我们将学习Annotation的另一个特性：元注释，它可以使我们更好的定制我们的注释。
 
内容
         限定注释使用范围
         注释保持性策略
         文档化功能
         标注继承
         概要
 
限定注释使用范围
    当我们的自定义注释不断的增多也比较复杂时，就会导致有些开发人员使用错误，主要表现在不该使用该注释的地方使用。为此，Java提供了一个ElementType枚举类型来控制每个注释的使用范围，比如说某些注释只能用于普通方法，而不能用于构造函数等。下面是Java定义的ElementType枚举：
package java.lang.annotation;
 
public enum ElementType {
  TYPE,         // Class, interface, or enum (but not annotation)
  FIELD,        // Field (including enumerated values)
  METHOD,       // Method (does not include constructors)
  PARAMETER,        // Method parameter
  CONSTRUCTOR,      // Constructor
  LOCAL_VARIABLE,   // Local variable or catch clause
  ANNOTATION_TYPE,  // Annotation Types (meta-annotations)
  PACKAGE       // Java package
}
    下面我们来修改Greeting注释，为之添加限定范围的语句，这里我们称它为目标（Target）使用方法也很简单，如下：
package com.gelc.annotation.demo.customize;
 
@Target( { ElementType.METHOD, ElementType.CONSTRUCTOR })
public @interface Greeting {
 
    public enum FontColor {
        RED, GREEN, BLUE
    };
 
    String name();
 
    String content();
 
    FontColor fontColor() default FontColor.BLUE;
}
正如上面代码所展示的，我们只允许Greeting注释标注在普通方法和构造函数上，使用在包申明、类名等时，会提示错误信息。
 
注释保持性策略
    在Java编译器编译时，它会识别在源代码里添加的注释是否还会保留，这就是RetentionPolicy。下面是Java定义的RetentionPolicy枚举：
编译器的处理有三种策略：
RUNTIME       将注释保留在编译后的类文件中，并在第一次加载类时读取它
CLASS           将注释保留在编译后的类文件中，但是在运行时忽略它
SOURCE        按照规定使用注释，但是并不将它保留到编译后的类文件中
package java.lang.annotation;
 
public enum RetentionPolicy {
  SOURCE,       // Annotation is discarded by the compiler
  CLASS,        // Annotation is stored in the class file, but ignored by the VM
  RUNTIME       // Annotation is stored in the class file and read by the VM
}
    RetentionPolicy的使用方法与ElementType类似，简单代码示例如下：
package com.gelc.annotation.demo.customize;
 
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
 
@Retention(RetentionPolicy.RUNTIME)
@Target( { ElementType.METHOD, ElementType.CONSTRUCTOR })
public @interface Greeting {
 
    public enum FontColor {
        RED, GREEN, BLUE
    };
 
    String name();
 
    String content();
 
    FontColor fontColor() default FontColor.BLUE;
}
 
文档化功能
    Java提供的Documented元注释跟Javadoc的作用是差不多的，其实它存在的好处是开发人员可以定制Javadoc不支持的文档属性，并在开发中应用。它的使用跟前两个也是一样的，简单代码示例如下：
package com.gelc.annotation.demo.customize;
 
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
 
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target( { ElementType.METHOD, ElementType.CONSTRUCTOR })
public @interface Greeting {
 
    public enum FontColor {
        RED, GREEN, BLUE
    };
 
    String name();
 
    String content();
 
    FontColor fontColor() default FontColor.BLUE;
}
 
值得大家注意的是，如果你要使用@Documented元注释，你就得为该注释设置RetentionPolicy.RUNTIME保持性策略。为什么这样做，应该比较容易理解，这里就不提了。
 
标注继承
继承应该是Java提供的最复杂的一个元注释了，它的作用是控制注释是否会影响到子类，简单代码示例如下：
package com.gelc.annotation.demo.customize;
 
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
 
@Inherited
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target( { ElementType.METHOD, ElementType.CONSTRUCTOR })
public @interface Greeting {
 
    public enum FontColor {
        RED, GREEN, BLUE
    };
 
    String name();
 
    String content();
 
    FontColor fontColor() default FontColor.BLUE;
}

 

4、Java Annotation进阶——读取注释信息
摘要
本文是该系列文章中的最后一篇文章，作为收尾，本文主要讲解如何通过Java反射来获得我们想要的注释信息，如果你对反射比较熟悉，那你应该能轻而易举的读取到想要的注释信息。
 
读取注释信息
    当我们想读取某个注释信息时，我们是在运行时通过反射来实现的，如果你对元注释还有点印象，那你应该记得我们需要将保持性策略设置为RUNTIME，也就是说只有注释标记了@Retention(RetentionPolicy.RUNTIME)的，我们才能通过反射来获得相关信息，下面的例子我们将沿用前面几篇文章中出现的代码，并实现读取AnnotationTest类所有方法标记的注释并打印到控制台。好了，我们来看看是如何实现的吧：
package com.gelc.annotation.demo.reflect;
 
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
 
public class AnnotationIntro {
 
    public static void main(String[] args) throws Exception {
 
        Method[] methods = Class.forName(
                "com.gelc.annotation.demo.customize.AnnotationTest")
                .getDeclaredMethods();
        Annotation[] annotations;
 
        for (Method method : methods) {
            annotations = method.getAnnotations();
            for (Annotation annotation : annotations) {
                System.out.println(method.getName() + " : "
                        + annotation.annotationType().getName());
            }
        }
    }
}