Java Annotation Introduction

Java Annotation Introduction

Java Annotation 是 JDK1.5 引入的新特性,其实就是代码里的一些标记,它并不会影响代码本身代表的意思,但一些开发工具或部署工具会对其进行解析并处理。这些工具或程序可以生成根据它一些新的代码，或者 xml 文件等等。

1. Annotation 的类型及定义方式
Annotation 有三种方式:

a)Marker - 只有名称，没有元素
Example:
public @interface MyAnnotation {
}

Usage:
@MyAnnotation
public void mymethod() { .... }

b)Single-Element - 只有一个元素,使用的时候可以有两种方式，效果是一样的,如下

Example:
public @interface MyAnnotation
{
String doSomething();
}

Usage1:
@MyAnnotation ("What to do")
public void mymethod() { .... }

Usage2:
@MyAnnotation (doSomething="What to do")
public void mymethod() { .... }

c)multi-value - 有多个数据元素，只有一种使用方式，就是 data=value

Example:
public @interface MyAnnotation {
String doSomething();
int count();
String date();
}

Usage:
@MyAnnotation (doSomething="What to do", count=1, date="09-09-2005")
public void mymethod() { .... }

2. 定义 Annotation 的一些规则
a) 必须以 @interface 开始，再加上名字,如 public @interface MyAnnotation{}
b) 方法不能有任何参数
c) 方法也不能抛出异常
d) 方法的返回类型只能是 primitives,String,Class,enum ,以及 array of the above types

3. JDK5 有两种 Annotation
1) Simple Annotation
这是 JDK5 本身提供的几个标记，你可以用他们来标记自己的代码，但不能用它们来定义新的标记,目前只有三个这样的标记
a) Override - 这个标记标记的方法必须是对父类的方法的重写,否则编译器会报错
b) Deprecated - 表明方法过时，如果使用了该标记标记的方法，则编译会产生警告
c) Suppresswarnings - 该标记指向的类或方法不产生警告信息,该标记标记的元素会影响该元素的所有子元素

如下例，则调用 doSomeTestNow() 时，不会产生 deprecation 警告
public class TestAnnotations {
public static void main(String arg[]) throws Exception {
new TestAnnotations().doSomeTestNow();
}

@SuppressWarnings({"deprecation"})
public void doSomeTestNow() {
Test_Deprecated t2 = new Test_Deprecated();
t2.doSomething();
}
}



2) Meta Annotation
这些标记是JDK提供的用来定义自己的标记的,有四种类型：
1) Target - 表明该标记应该应用到类的哪种元素上,有以下几种:

@Target(ElementType.TYPE)—can be applied to any element of a class
@Target(ElementType.FIELD)—can be applied to a field or property
@Target(ElementType.METHOD)—can be applied to a method level annotation
@Target(ElementType.PARAMETER)—can be applied to the parameters of a method
@Target(ElementType.CONSTRUCTOR)—can be applied to constructors
@Target(ElementType.LOCAL_VARIABLE)—can be applied to local variables
@Target(ElementType.ANNOTATION_TYPE)—indicates that the declared type itself is an annotation type

如：
@Target(ElementType.METHOD)
public @interface Test_Target {
public String doTestTarget();
}

2) Retention - 表明该标记应该保持在哪里及保持多长时间,有三种类型

RetentionPolicy.SOURCE—Annotations with this type will be by retained only at the source level and will be ignored by the compiler
RetentionPolicy.CLASS—Annotations with this type will be by retained by the compiler at compile time, but will be ignored by the VM
RetentionPolicy.RUNTIME—Annotations with this type will be retained by the VM so they can be read only at run-time

3) Documented - 表明 JavaDoc 工具生成文档时,这个标记会出现在生成的文档上
4) Inherited - 表明这个标记标记的类会自动继承该标记本身代表的类

如：
@Inherited
public @interface myParentObject {
boolean isInherited() default true;
String doSomething() default "Do what?";
}

//这个类会自动继承 isInherited,及doSomething 方法
@myParentObject
public Class myChildObject { }

From: http://www.developer.com/java/other/article.php/10936_3556176_1