Java注解学习二：自定义注解

一.注解术语

     http://zy19982004.iteye.com/blog/1979039里把注解里的术语罗列了一遍，未做深入解读。本文用一个例子来强化注解术语。

 

二.代码

 

package com.jyz.study.jdk.annotation;

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;

/**
 * 1.演示四种元注解的用法
 * @Target
 * @Retention
 * @Document
 * @Inherited
 * 
 * @author [e-mail]
 *
 */
@JyzTargetType
@JyzRetentionRuntime
@JyzDocument
@JyzInherited
public class MetaAnnotation {
	@JyzTargetField
	private String info;
	
	@JyzTargetConstructor
	public MetaAnnotation(@JyzTargetParamter String info) {
		this.info = info;
	}
	
	@JyzTargetMethod
	public void test(){
		@JyzTargetLocalVariable
		String infoInner = "sa";
	}
}

@Target(ElementType.TYPE) @interface JyzTargetType{} 						//接口、类、枚举、注解
@Target(ElementType.FIELD) @interface JyzTargetField{}						//字段、枚举的常量
@Target(ElementType.METHOD) @interface JyzTargetMethod{}					//方法
@Target(ElementType.PARAMETER) @interface JyzTargetParamter{}				//方法参数
@Target(ElementType.CONSTRUCTOR) @interface JyzTargetConstructor{}			//构造函数
@Target(ElementType.LOCAL_VARIABLE) @interface JyzTargetLocalVariable{}		//局部变量
@Target(ElementType.ANNOTATION_TYPE) @interface JyzTargetAnnotationType{}	//注解
@Target(ElementType.PACKAGE) @Retention(RetentionPolicy.RUNTIME) @interface JyzTargetPackage{public String version() default "";}	//包 
@JyzTargetAnnotationType @interface JyzTargetAll{}													

@Retention(RetentionPolicy.SOURCE) @interface JyzRetentionSource{}
@Retention(RetentionPolicy.CLASS) @interface JyzRetentionClass{}
@Retention(RetentionPolicy.RUNTIME) @interface JyzRetentionRuntime{}

@Documented @interface JyzDocument{}

@Inherited @interface JyzInherited{}

 

 

 

三.代码解释

1. Java内置了四种元注解。或许你要问了，这四种元注解又是哪里来的呢？我们来看看这三种元注解，得到的答案是每一种元注解又是建立在四个元注解的基础之上的。有点自己定义自己的意思。

   package java.lang.annotation;
   
   @Documented
   @Retention(RetentionPolicy.RUNTIME)
   @Target(ElementType.ANNOTATION_TYPE)
   public @interface Target {
       ElementType[] value();
   }
   
   @Documented
   @Retention(RetentionPolicy.RUNTIME)
   @Target(ElementType.ANNOTATION_TYPE)
   public @interface Retention {
       RetentionPolicy value();
   }
   
   
   @Documented
   @Retention(RetentionPolicy.RUNTIME)
   @Target(ElementType.ANNOTATION_TYPE)
   public @interface Documented {
   }
   
   @Documented
   @Retention(RetentionPolicy.RUNTIME)
   @Target(ElementType.ANNOTATION_TYPE)
   public @interface Inherited {
   }

    
2. 什么时候使用这四个元注解？仅仅在你需要定义自己的注解类时，如代码里的Jyz*这些类都是自定义的注解类。
3. 什么时候使用自定义注解类或Java内置的几个标准注解类？当然是在普通Java类(指的是不是注解类的类如MetaAnnotation，有时候我也叫它被注解类)里使用。需要记住的是，普通Java类里并不能直接使用元注解，如果你在MetaAnnotation上面加上@Documented，肯定编译报错。
4. @Target的八种参数，前六种很好理解，该用什么地方就用什么地方。PACKAGE包的声明会在下文http://zy19982004.iteye.com/blog/1979308单独讲解。于是就是剩下一个ANNOTATION_TYPE了，这个代表了自定义的注解只能用在注解上，看看四个元注解便知，看看

   @JyzTargetAnnotationType @interface JyzTargetAll{}		

    也是这个意思。在自定义的注解类里@Target未指定任何参数的话，代表八种都包括，在代码合适的地方我都能使用@JyzTargetAll。
5. @Inherited的作用也在下文说http://zy19982004.iteye.com/blog/1979520。
6. @Documented：如果Java普通类里使用@JyzDocumented，则普通Java类的Javadoc里保留@JyzDocumented。

 

四.使用总结

1. 使用四种元注解定义自己的注解类
1. @Target(ElementType.?)就根据需要定义吧，不太同意定义成@JyzTargetAll。
2. 除非你能保证你的注解类永远被使用在不需要反射的类上，但这个似乎不太可能，所以你最好@Retention(RetentionPolicy.RUNTIME)。
3. 至于@Documented也加上吧，对jvm来说完全没什么负担。
4. 也建议加上@Inherited，尽管你觉得现在是不需要的，指不定两个被注解类就存在继承关系。
2. 为注解类定义需要的属性(上面的Jyz*这些注解类主要是为了演示元注解的使用，并未加上任何元素)，并设置默认值。
3. 普通Java类里合适的地方使用合适的注解类，并为需要赋值的元素赋值，不赋值将使用默认值。为元素赋值的方式为名-值对，如@JyzTargetPackage(version="1.0") 。如果恰好只需要为一个元素赋值，而这个元素定义为value()，无需使用名值对，只需在括号内给出value元素所需的值即可，如@JyzTargetPackage("1.0") 。