第三节 自定义Annotation

第三节 自定义Annotation
使用过spring框架，ejb框架，cxf，junit2等支持Annotation技术的框架的人都会很清楚，其中除了jdk自带的一些Annotation以外，我们还可以自己定义很多Annotation帮助我们进行框架的搭建，这一小节我们将逐步的进行自定义Annotation的说明。
Ok，开始我们的第一个Annotation程序之旅吧。
一：Quick Start
定义Annotation的时候和定义接口的方式很类似，只不过再interface前面加了@，我感觉在这一点sun公司确实有一些吝啬，为何不开辟一个新的类型标识符呢，呵呵，当然这样的抱怨也是无关紧要的，只要能达到目的即可。牢骚也不不多发了，直接上codes。

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. public @interface UserdefinedAnnotation {  
4.       
5. }  

代码很简单，没有任何的结构，只是一个空的Annotation，接下来演示一下如何对其进行使用。

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. public class UseAnnotation {  
4.       
5.     @UserdefinedAnnotation  
6.     public static void main(String[] args) {  
7.         System.out.println("hello");  
8.     }  
9. }  

上述的代码简单到再也不能简单，甚至简单到说明不了任何问题，只是从它上面可以看得出来我们如何自定一个Annotation，并且如何的使用它，我们并没有给自定义Annotation中添加任何的属性，甚至没有指定其保持力(Retention)，可继承性(Inherited)，标注对象（Target）等，再接下来的描述中我们会逐步进行说明。
二：Annotation属性值
Annotation属性值大致有以下三种：
● 基本类型
● 数组类型
● 枚举类型
我们在下面的文字中将会一个个的进行演示和说明。
1：基本串类型

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. public @interface UserdefinedAnnotation {  
4.     int value();  
5.     String name();  
6.     String address();  
7. }  

上面是一个自定义的annotation，可能稍微有一些复杂，只不过是为了更多的说明一下问题，可以看出来在定义属性的时候有点像interface定义方法一样，每一个属性名称之后需要加上括号，接下来看看如何使用。

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2. public class UseAnnotation {  
3.       
4. @UserdefinedAnnotation(value=123,name="wangwenjun",address="火星")  
5.     public static void main(String[] args) {  
6.         System.out.println("hello");  
7.     }  
8. }  

如果在使用UserdefinedAnnotation时候不给相关的属性赋值，会出现错误。
需要说明的一点事如果一个annotation中只有一个属性名字叫value，我没在使用的时候可以给出属性名也可以省略。

Java代码  

1. public @interface UserdefinedAnnotation {  
2.     int value();  
3. }  
4. package com.wangwenjun.annatation.userdefined;  
5.   
6. public class UseAnnotation {  
7.       
8.     @UserdefinedAnnotation(value=123)  
9.     public static void main(String[] args) {  
10.         System.out.println("hello");  
11.     }  
12. }  

也可以写成如下的形式

Java代码  

1. @UserdefinedAnnotation(123)  
2.     public static void main(String[] args) {  
3.         System.out.println("hello");  
4. }  

直接对其进行了省略。如果定义的属性名字不叫value，那么属性名字是不可以省略的哦！那是因为value属性名是annotation默认的一个属性名，这一点很重要的哦，千万不能忽略。
2：数组类型
我们在自定义annotation中定义一个数组类型的属性，代码如下：

Java代码  

1. public @interface UserdefinedAnnotation {  
2.     int[] value();  
3. }  

我们如何使用呢，代码如下：

Java代码  

1. public class UseAnnotation {  
2.       
3.     @UserdefinedAnnotation({123})  
4.     public static void main(String[] args) {  
5.         System.out.println("hello");  
6.     }  
7. }  

注意1：其中123外面的大括号是可以被省略的，因为只有一个元素，如果里面有一个以上的元素的话，花括号是不能被省略的哦。比如{123，234}。
注意2：其中属性名value我们在使用的时候进行了省略，那是因为他叫value，如果是其他名字我们就不可以进行省略了必须是@UserdefinedAnnotation（属性名={123,234}）这样的格式。
3：枚举类型
自从jdk5.0以后，java引进了枚举类型，我个人比较喜欢这样的方式尤其在进行业务逻辑判断的if或者switch子句中使用很方便，而且还不容易出错，大多时候都是作为一个函数的形式参数而存在，关于枚举类型的使用请查看相应的doc文档。
我们定义一个enum类型

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. public enum DateEnum {  
4.     Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday  
5. }  
6. 然后在定义一个annotation  
7. package com.wangwenjun.annatation.userdefined;  
8.   
9. public @interface UserdefinedAnnotation {  
10.     DateEnum week();  
11. }  

可以看出annotation中的属性类型为enum类型的，接下来我们看看他如何来使用

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. public class UseAnnotation {  
4.       
5.     @UserdefinedAnnotation(week=DateEnum.Sunday)  
6.     public static void main(String[] args) {  
7.         System.out.println("hello");  
8.     }  
9. }  

在使用上也是很方便的，直接用来进行相关的引用，这样再应用的过程中就不会出现错误。
4：默认值
有时候我们在使用annotation的时候某一些属性值是会被经常使用到的，或者说他会有一个默认值给我们直接进行使用，那么我们在定义annotation的时候就可以为属性直接给出默认值，下面进行一下简单的示例。

Java代码  

1. public @interface UserdefinedAnnotation {  
2.     String name() default "zhangsan";  
3. }  

在使用的时候我们可以不进行指定

Java代码  

1. public class UseAnnotation {  
2.       
3.     @UserdefinedAnnotation()  
4.     public static void main(String[] args) {  
5.         System.out.println("hello");  
6.     }  
7. }  

当然我们也可以自己对其进行重新的设置，其中数组和枚举类型的默认值基本上类似，就不多做赘述了，自己进行测试即可。
5：注意
● Annotation是不可以继承其他接口的，这一点是需要进行注意，这也是annotation的一个规定吧。
● Annotation也是存在包结构的，在使用的时候直接进行导入即可。
● Annotation类型的类型只支持原声数据类型，枚举类型和Class类型的一维数组，其他的类型或者用户自定义的类都是不可以作为annotation的类型，我查看过文档并且进行过测试。
三：Retention标记
Retention标记是告知编译器如何来处理我们自定义的annotation，指示注释类型的注释要保留多久。如果注释类型声明中不存在 Retention 注释，则保留策略默认为 RetentionPolicy.CLASS。
查看他的源代码，会发现他有一个属性value，类型为RetentionPolicy，RetentionPolicy是一个枚举类型。其中有三个类型的值分别代表不同的意思。
CLASS 编译器将把注释记录在类文件中，但在运行时 VM 不需要保留注释。

RUNTIME 编译器将把注释记录在类文件中，在运行时 VM 将保留注释，因此可以反射性地读取。
SOURCE 编译器要丢弃的注释

下面是一段简短的定义代码示例。

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. import java.lang.annotation.Retention;  
4. import java.lang.annotation.RetentionPolicy;  
5.   
6. @Retention(RetentionPolicy.RUNTIME)  
7. public @interface UserdefinedAnnotation {  
8.     String name() default "zhangsan";  
9. }  

从上面的实例中我们自定义的annotation是一个runntime范围的annotation，也就是说他会保持在源文件中并且也会在运行时由JVM自动调用。
我们先对它有一个感性的认识，知道有这么一个东西，在后面的文章中我会以一个示例对其进行详细的说明（会涉及到反射的相关东西）。其实Retention的名字翻译过来就是“保持力”的意思，说明的很清楚，就是我的annotation存放在哪些地方，也就是说我的annotation他的影响力到底在哪。
四：AnnotatedElement
在jdk5.0以后java反射包增加了这样一个接口，主要是用来对annotation进行操作的，其中AccessibleObject, Class, Constructor, Field, Method, Package都对其进行了实现继承。总共有以下四个方法：
<T extends Annotation>
T
getAnnotation(Class<T> annotationType)
          如果存在该元素的指定类型的注释，则返回这些注释，否则返回 null。
Annotation[]
getAnnotations()
          返回此元素上存在的所有注释。
Annotation[]
getDeclaredAnnotations()
          返回直接存在于此元素上的所有注释。
boolean isAnnotationPresent(Class<? extends Annotation> annotationType)
          如果指定类型的注释存在于此元素上，则返回 true，否则返回 false。
在接下来的章节中我们会进行说明。
五：Target 标记
在我们之前的实例中我们定义的annotation可以放在一个类的任何位置，那么我们是否可以对annotation的位置进行设置呢，答案是可以的，这就是我们所要说的的Target 标记，他里面也有一个枚举类型的属性value，其中枚举类型为ElementType，有很多自定义的属性，如下所示：

ANNOTATION_TYPE
          注释类型声明
CONSTRUCTOR
          构造方法声明
FIELD
          字段声明（包括枚举常量）
LOCAL_VARIABLE
          局部变量声明
METHOD
          方法声明
PACKAGE
          包声明
PARAMETER
          参数声明
TYPE
          类、接口（包括注释类型）或枚举声明
上面的列表已经讲述的很清楚了，我们就不再进行说明了，直接来一个小程序进行演示吧，还是先来一个annotation，假设我们的annotation只能放在方法的前面

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. import java.lang.annotation.ElementType;  
4. import java.lang.annotation.Target;  
5.   
6. @Target(ElementType.METHOD)  
7. public @interface UserdefinedAnnotation {  
8.     String name() default "zhangsan";  
9. }  
10. package com.wangwenjun.annatation.userdefined;  
11. public class UseAnnotation {  
12.       
13.     @UserdefinedAnnotation()  
14.     public static void main(String[] args) {  
15.         System.out.println("hello");  
16.     }  
17. }  

我们的annotation只能放在main方法上面放在其他的位置会出现错误。
六：Documented 标记
这个annotation非常简单，也非常容易理解，使用过javadoc命令的人都会很清楚，我们可以用javadoc命令将方法，类，变量等前面的注释转换成文档，在默认的情况下javadoc命令不会将我们的annotation生成再doc中去的，所以使用该标记就是告诉jdk让它也将annotation生成到doc中去，比如：

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. import java.lang.annotation.Documented;  
4. import java.lang.annotation.ElementType;  
5. import java.lang.annotation.Target;  
6.   
7. @Target(ElementType.METHOD)  
8. @Documented  
9. public @interface UserdefinedAnnotation {  
10.     String name() default "zhangsan";  
11. }  

七：Inherited标记
该标记的意思就是说，比如有一个类A，在他上面有一个标记annotation，那么A的子类B是否不用再次标记annotation就可以继承得到呢？答案是肯定的，我们做一个简单的演示，首先我们有一个annotation

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. import java.lang.annotation.Documented;  
4. import java.lang.annotation.ElementType;  
5. import java.lang.annotation.Inherited;  
6. import java.lang.annotation.Retention;  
7. import java.lang.annotation.RetentionPolicy;  
8. import java.lang.annotation.Target;  
9.   
10. @Documented  
11. @Target(ElementType.TYPE)  
12. @Retention(RetentionPolicy.RUNTIME)  
13. @Inherited  
14. public @interface UserdefinedAnnotation {  
15.     String name() default "zhangsan";  
16. }  

接着定义一个父类
package com.wangwenjun.annatation.userdefined;

@UserdefinedAnnotation
public class ParentClass {

}
父类什么都没有干，只是一个空的类，并且有UserdefinedAnnotation的标记，然后我们写一个继承他的子类。

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. public class ChildClass extends ParentClass{  
4.       
5. }  

我们准备工作都已经做完了，现在就是利用反射机制进行一下简短的测试

Java代码  

1. package com.wangwenjun.annatation.userdefined;  
2.   
3. public class TestInherited {  
4.     public static void main(String[] args) {  
5.         Class<ChildClass> clazz = ChildClass.class;  
6.         boolean isExist=clazz.isAnnotationPresent(UserdefinedAnnotation.class);  
7.         if(isExist){  
8.             System.out.println("子类继承了父类的annotation");  
9.         }else{  
10.             System.out.println("子类没有继承父类的annotation");  
11.         }  
12.     }  
13. }  

打印结果为：子类继承了父类的annotation。可以看到子类果然继承了父类的annotation标记。