Java step by step(3): Annotation
About Annotation
Java 5引入了Annotation, 这极大减轻了开发的负担，不用写很多的代码，只需要在代码中加入一些"tag"就可以了，这个很符合声明式编程(declarative programming)的思想。
当然有个问题还是要问的，虽然作为使用annotation的开发者来说，不用考虑Annotation最后究竟会被怎样执行，只要在需要使用Annotation的地方tag一下就可以，但是很显然这个只是把问题处理地点转移了而已，终归是需要有人来处理的，不然，这个Annotation就没有任何意义了。
可以想见，很多JDK提供的annotation, JVM或者编译器肯定是要负责解释处理这些anntation的。如果使用一些framework提供的annotation, 自然这些framework会提供解释执行这些annotation的代码实现，否则JVM怎么可能知道如何去解释这些tag呢。那么究竟如何去识别代码中哪些地方使用了annotation呢，很容易想到可以运用reflection来实现。
所以，annotation看起来很神秘，其实只是借助了reflection，将相关的代码实现处理逻辑封闭在一个地方，从而使得运用这些annoation的代码不需要重复实现这些功能，从而简化了工作量。
The Rules of Defining Java Annotation Types
// MyAnnotation.java
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface MyAnnotation {
public String doSomething() default "do something";
public String date();
}
上面是一个简单的Annotation定义，Annotation的定义很特别，很像interface,不过需要在interface前面加个@符号。另外annotation中定义的method (attribute) 不能是private的，不能接受参数，不能有throws语句，返回值的类型必须是如下几种之一：
1）primitives
2) String
3) Class
4) Enum
5) Array of the above types
Java Annotation Types
Java 支持两种Annotation类型：
1） 简单类型：这种annotation只能用于其它code，不能用于annotation 类型。
2）Meta Annotation: 这种annotation是用于annotation type的，也就是annotation of annotation.
Out-of-the-box Simple Annotation Types in JDK
JDK提供了3个简单类型的annotations, 包括：
1) Override
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}
可以看到Override只能用于method, 而且retention级别是SOURCE。这个Annotation的好处在于可以帮助我们快速发现问题，如果把toString写成了toString1，编译器会给出错误提示，这样就不要等到运行的时候发现出错了。
2) Deprecated
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Deprecated {
}
如果一个方法或者变量被标示成Deprecated，那就意味着该方法或者变量是不应该被使用的，否则的话，编译器会报出警告信息。
3) Suppresswarnings
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
/**
* The set of warnings that are to be suppressed by the compiler in the
* annotated element. Duplicate names are permitted. The second and
* successive occurrences of a name are ignored. The presence of
* unrecognized warning names is <i>not</i> an error: Compilers must
* ignore any warning names they do not recognize. They are, however,
* free to emit a warning if an annotation contains an unrecognized
* warning name.
*
* <p>Compiler vendors should document the warning names they support in
* conjunction with this annotation type. They are encouraged to cooperate
* to ensure that the same names work across multiple compilers.
*/
String[] value();
}
这个Annotation是让编译器忽略某些warning信息。
Out-of-the-box Meta Annotation Types in JDK
JDK提供了如下4种Meta Annotation Types:
1) Target
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
ElementType[] value();
}
这个Annotation用来标示定义的annotation类型可以用在哪些类型的元素上，包括如下几种....
-- @Target(ElementType.TYPE)
-- @Target(ElementType.FIELD) : public attributes of the class
-- @Target(ElementType.METHOD)
-- @Target(ElementType.PARAMETER)
-- @Target(ElementType.CONSTRUCTOR)
-- @Target(ElementType.LOCAL_VARIABLE)
-- @Target(ElementType.ANNOTATION_TYPE)
2) Retention
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
RetentionPolicy value();
}
这个Annotation表示定义的annotation会retention的时间，有如下三种值：
-- RententionPolicy.SOURCE: retained at the source level, ignored by the compiler
-- RententionPolicy.CLASS: retained by the compiler, ignored by the VM
-- RententionPolicy.RUNTIME: retained by the VM, can be read only at run-time.
3) Documented
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
}
表示定义的annotation type应该被javadoc加入到生成的document中的。
4) Inherited
/**
* Indicates that an annotation type is automatically inherited. If
* an Inherited meta-annotation is present on an annotation type
* declaration, and the user queries the annotation type on a class
* declaration, and the class declaration has no annotation for this type,
* then the class's superclass will automatically be queried for the
* annotation type. This process will be repeated until an annotation for this
* type is found, or the top of the class hierarchy (Object)
* is reached. If no superclass has an annotation for this type, then
* the query will indicate that the class in question has no such annotation.
*
* <p>Note that this meta-annotation type has no effect if the annotated
* type is used to annotate anything other than a class. Note also
* that this meta-annotation only causes annotations to be inherited
* from superclasses; annotations on implemented interfaces have no
* effect.
*
* @author Joshua Bloch
* @since 1.5
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
}
A Simple Example
定义一个简单的Annotation Type -- MyAnnoation
// MyAnnotation.java
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface MyAnnotation {
public String doSomething() default "do something";
public String date();
}
通过Reflection来获取annotation定义的field...
// MainTest.java
public class MainTest {
@MyAnnotation(doSomething = "Test Annotation", date = "2011-08-01")
public String annotationTest;
public void testAnnotation() {
Class aClass = MainTest.class;
try {
Field aField = aClass.getField("annotationTest");
MyAnnotation myAnnotation = aField.getAnnotation(MyAnnotation.class);
annotationTest = myAnnotation.doSomething() + " on " + myAnnotation.date();
System.out.println(this.annotationTest);
} catch (SecurityException e) {
// TODO Auto-generated catch block
e.printStackTrace();
} catch (NoSuchFieldException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
}
/**
* @param args
*/
public static void main(String[] args) {
new MainTest().testAnnotation();
}
}
--------------------------------------
Regards,
FangwenYu
