java中注解（Annotation）及注解的作用_如何在java的api文档中查找某个注解的作用呢?-CSDN博客

文章目录

1、什么是java注解

注解，顾名思义，就是对某一事物添加注释说明，其会存放一些信息，这些信息可能对以后某个时段来说是很有用处的。
Java注解又叫java标注，java提供了一套机制，使得我们可以对包、类、方法、域、参数、变量等添加标注(即附上某些信息)，且在以后某个时段通过反射将标注的信息提取出来以供使用。

2、通过反射访问注解

程序通过反射获取了某个类的对象之后，程序就可以调用该对象的如下四个方法来访问注解信息：

方法1： T getAnnotation(Class annotationClass)：返回该程序元素上存在的、指定类型的注解，如果该类型注解不存在，则返回null
方法2：Annotation[] getAnnotations()：返回该程序元素上存在的所有注解
方法3：boolean is AnnotationPresent(Class<?extends Annotation> annotationClass)：判断该程序元素上是否包含指定类型的注解，存在，则返回true；否则，返回false
方法4：Annotation[] getDeclaredAnnotations()：返回直接存在于此元素上的所有注解。与其他方法不同的是，该方法将忽略继承的注释。如果没有注解直接存在于此元素上，则返回长度为零的一个数组，该方法的调用者可以随意修改返回的数组，可是，这不会对其他调用者返回的数组产生任何影响。

3、自定义Java注解

3.1 为什么要自定义注解

Java从1.5版本以后默认内置三个注解：

@Override：只能用在方法之上，用来告诉别人这一个方法是重写父类的
@Deprecated：建议别人不要使用旧的API的时候用的，编译的时候会产生警告信息，可以设定在程序里的所有的元素上
@SuppressWarnings：这一个类型可以暂时把一些警告信息关闭

但是，仅仅这三个标注是不能满足我们开发时一些需求的。所以java允许我们自定义注解来使用。

3.2 如何自定义注解

自定义步骤大致分为两步：

通过@interface关键字(注意，不是interface，是@interace)声明注解名称，以及注解的成员属性或者叫做注解的参数
使用java内置的四个元注解对自定义注解的功能和范围进行一些限制

3.3 什么是元注解

元注解，就是定义注解的注解，也就是说这些元注解的作用就是专门用来约束其它注解的注解。请区别上面那三个注解，他们也是通过元注解定义而来的。元注解主要有四个@Target,@Retention,@Documented,@Inherited

元注解有：@Target,@Retention,@Documented,@Inherited 

@Target 表示该注解用于什么地方，可能的 ElemenetType 参数包括： 
	ElemenetType.CONSTRUCTOR 构造器声明 
	ElemenetType.FIELD 域声明（包括 enum 实例） 
	ElemenetType.LOCAL_VARIABLE 局部变量声明 
	ElemenetType.METHOD 方法声明 
	ElemenetType.PACKAGE 包声明 
	ElemenetType.PARAMETER 参数声明 
	ElemenetType.TYPE 类，接口（包括注解类型）或enum声明 
 
@Retention 表示在什么级别保存该注解信息。可选的 RetentionPolicy 参数包括： 
	RetentionPolicy.SOURCE 注解将被编译器丢弃 
	RetentionPolicy.CLASS 注解在class文件中可用，但会被VM丢弃 
	RetentionPolicy.RUNTIME VM将在运行期也保留注释，因此可以通过反射机制读取注解的信息。 
 
@Documented 将此注解包含在 javadoc 中 
 
@Inherited 允许子类继承父类中的注解

3.4 自定义及使用注解示例

文件架构：
自定义一个类级别的注解Description

package annotation_;

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;

@Target(ElementType.TYPE)//这个标注应用于类
@Retention(RetentionPolicy.RUNTIME)//标注会一直保留到运行时
@Documented	//将此注解包含在javadoc中
public @interface Description{
    String value();
}

再定义个方法级别的注解Name

package annotation_;

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;

//注意这里的@Target与@Description里的参数成员不同
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Name{
   String originate();
   String community();
}

然后使用以上两个注解

package annotation_;

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;

@Description(value="javaeye,做最棒的软件开发交流社区")
public class JavaEyer {
      @Name(originate="创始人:robbin",community="javaEye")
      public String getName()
      {
                return null;
      }
     
      @Name(originate="创始人:江南白衣",community="springside")
      public String getName2()
      {
                return "借用两位的id一用,写这一个例子,请见谅!";
      }
}

注意：注解“@Description(value=“javaeye,做最棒的软件开发交流社区”)”，可以写成“@Description(“javaeye,做最棒的软件开发交流社区”)”，这两种方式的结果是一样的。因为Description注解定义的时候其参数(或者说属性)为value，而value比较特殊，它在被指定参数的时候可以不用显示的写出来。当然如果定义的参数名不是value而是其它的，比如des，那么使用注解的时候，必须显式地写出参数名，然后再赋值：@Description(Des=”xxx”)

提取出注解的信息

package annotation_;

import java.lang.reflect.Method;
import java.util.HashSet;
import java.util.Set;

public class TestAnnotation {
        /**
         * author lighter
         * 说明:具体关天Annotation的API的用法请参见javaDoc文档
         */
      public static void main(String[] args) throws Exception {
      String CLASS_NAME = "annotation_.JavaEyer";
      Class test = Class.forName(CLASS_NAME);
      
      boolean flag = test.isAnnotationPresent(Description.class);
       if(flag)
       {
                Description des = (Description)test.getAnnotation(Description.class);
                System.out.println("描述:"+des.value());
                System.out.println("-----------------");
       }
      
       Method[] method = test.getMethods();
       //把JavaEyer这个类中有利用到@Name的全部方法保存到Set中去
       Set<Method> set = new HashSet<Method>();
       for(int i=0;i<method.length;i++)
       {
                boolean otherFlag = method[i].isAnnotationPresent(Name.class);
                if(otherFlag) set.add(method[i]);
       }
       for(Method m: set)
       {
                Name name = m.getAnnotation(Name.class);
                System.out.println(name.originate());
                System.out.println("创建的社区:"+name.community());
       }
    }
}

注意：所有自定义的Annotation（如Description和Name）会自动继承java.lang.annotation这一个接口，所以不能再去继承别的类或是接口。最重要的一点，Annotation类型里的参数设定:

第一，只能用public或默认(default)这两个访问权修饰，例如String value()，这里被设为defaul默认类型
第二，参数成员只能用基本类型byte,short,char,int,long,float,double,boolean八种基本数据类型和String,Enum,Class,annotations等数据类型，以及这一些类型的数组，例如String value()，这里的参数类型就为String

运行结果，如下图：

3.4 自定义及使用注解示例 2

/***********注解声明***************/

/**
 * 水果名称注解
 * @author peida
 *
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitName {
    String value() default "";
}

/**
 * 水果颜色注解
 * @author peida
 *
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitColor {
    /**
     * 颜色枚举
     * @author peida
     *
     */
    public enum Color{ BULE,RED,GREEN};
    
    /**
     * 颜色属性
     * @return
     */
    Color fruitColor() default Color.GREEN;

}

/**
 * 水果供应者注解
 * @author peida
 *
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitProvider {
    /**
     * 供应商编号
     * @return
     */
    public int id() default -1;
    
    /**
     * 供应商名称
     * @return
     */
    public String name() default "";
    
    /**
     * 供应商地址
     * @return
     */
    public String address() default "";
}

/***********注解使用***************/

public class Apple {
    
    @FruitName("Apple")
    private String appleName;
    
    @FruitColor(fruitColor=Color.RED)
    private String appleColor;
    
    @FruitProvider(id=1,name="陕西红富士集团",address="陕西省西安市延安路89号红富士大厦")
    private String appleProvider;
    
    public void setAppleColor(String appleColor) {
        this.appleColor = appleColor;
    }
    public String getAppleColor() {
        return appleColor;
    }
    
    public void setAppleName(String appleName) {
        this.appleName = appleName;
    }
    public String getAppleName() {
        return appleName;
    }
    
    public void setAppleProvider(String appleProvider) {
        this.appleProvider = appleProvider;
    }
    public String getAppleProvider() {
        return appleProvider;
    }
    
    public void displayName(){
        System.out.println("水果的名字是：苹果");
    }
}

/***********注解处理器***************/

public class FruitInfoUtil {
    public static void getFruitInfo(Class<?> clazz){
        
        String strFruitName=" 水果名称：";
        String strFruitColor=" 水果颜色：";
        String strFruitProvicer="供应商信息：";
        
        Field[] fields = clazz.getDeclaredFields();
        
        for(Field field :fields){
            if(field.isAnnotationPresent(FruitName.class)){
                FruitName fruitName = (FruitName) field.getAnnotation(FruitName.class);
                strFruitName=strFruitName+fruitName.value();
                System.out.println(strFruitName);
            }
            else if(field.isAnnotationPresent(FruitColor.class)){
                FruitColor fruitColor= (FruitColor) field.getAnnotation(FruitColor.class);
                strFruitColor=strFruitColor+fruitColor.fruitColor().toString();
                System.out.println(strFruitColor);
            }
            else if(field.isAnnotationPresent(FruitProvider.class)){
                FruitProvider fruitProvider= (FruitProvider) field.getAnnotation(FruitProvider.class);
                strFruitProvicer=" 供应商编号："+fruitProvider.id()+" 供应商名称："+fruitProvider.name()+" 供应商地址："+fruitProvider.address();
                System.out.println(strFruitProvicer);
            }
        }
    }
}

/***********输出结果***************/
public class FruitRun {

    /**
     * @param args
     */
    public static void main(String[] args) {
        
        FruitInfoUtil.getFruitInfo(Apple.class);
        
    }

}

====================================
 水果名称：Apple
 水果颜色：RED
 供应商编号：1 供应商名称：陕西红富士集团 供应商地址：陕西省西安市延安路89号红富士大厦