Java Annotation基本介绍

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

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

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

1、Java Annotation基本介绍
转自：http://numenzq.iteye.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枚举：
编译器的处理有三种策略：
豛~ 将注释保留在编译后的类文件中，并在第一次加载类时读取它
豛~ 将注释保留在编译后的类文件中，但是在运行时忽略它
豛~ 按照规定使用注释，但是并不将它保留到编译后的类文件中
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());
}
}
}
}