Java Annotation注解

Annotation(注解)是JDK5.0及以后版本引入的。它可以用于创建文档，跟踪代码中的依赖性，甚至执行基本编译时检查。从某些方面看，
annotation就像修饰符一样被使用，并应用于包、类 型、构造方法、方法、成员变量、参数、本地变量的声明中，
这些信息被存储在Annotation的“name=value”结构对中。

要注意的是，这里存在着一个基本的规则：Annotation不能影响程序代码的执行，无论增加、删除 Annotation，代码都始终如一的执行。
另外，尽管一些annotation通过java的反射api方法在运行时被访问，而java语言解释器在工作时忽略了这些annotation。


注解的用处大致可分为三类： 
1. 编写文档：通过代码里标识的元数据生成文档
2. 代码分析：通过代码里标识的元数据对代码进行分析
3. 编译检查：通过代码里标识的元数据让编译器能实现基本的编译检查
4. 利用自定义注解，通过反射获取自定义注解完成对程序逻辑上的额外分析功能。


系统内置标准注解：

注解的语法比较简单，除了@符号的使用外，他基本与Java固有的语法一致，JavaSE中内置三个标准注解，定义在java.lang中：
@Override：用于修饰此方法覆盖了父类的方法; 它说明了被标注的方法重载了父类的方法，起到了断言的作用。

@Deprecated：用于修饰已经过时的方法; 当一个类型或者类型成员使用@Deprecated修饰的话，编译器将提示不鼓励使用这个被标注的程序元素

@SuppressWarnnings:用于通知java编译器禁止特定的编译警告。 用于有选择的关闭编译器对类、方法、成员变量、变量初始化的警告。
注解的常见参数值的简单说明：

1.deprecation：使用了不赞成使用的类或方法时的警告；
2.unchecked：执行了未检查的转换时的警告，例如当使用集合时没有用泛型 (Generics) 来指定集合保存的类型; 
3.fallthrough：当 Switch 程序块直接通往下一种情况而没有 Break 时的警告;
4.path：在类路径、源文件路径等中有不存在的路径时的警告; 
5.serial：当在可序列化的类上缺少 serialVersionUID 定义时的警告; 
6.finally：任何 finally 子句不能正常完成时的警告; 
7.all：关于以上所有情况的警告。

---------------------------------------------------------------------------------------------------------------------------------------
自定义注解：
自定义Annotion(注解)是一个特殊类型的接口，程序可以通过反射来获取指定程序元素的Annotion对象，然后通过Annotion对象来获取注解里面的元数据。

实现自定义注解，需要先定义元注解：
Java5.0定义的元注解：
1.@Target,
2.@Retention,
3.@Documented,
4.@Inherited
这些类型和它们所支持的类在java.lang.annotation包中可以找到。下面我们看一下每个元注解的作用和相应分参数的使用说明。
@Target：

@Target说明了Annotation所修饰的对象范围：Annotation可被用于 packages、types（类、接口、枚举、Annotation类型）、类型成员（方法、构造方法、成员变量、枚举值）、
方法参数和本地变量（如循环变量、catch参数）。在Annotation类型的声明中使用了target可更加明晰其修饰的目标。

作用：用于描述注解的使用范围（即：被描述的注解可以用在什么地方）

取值(ElementType)有：

1.CONSTRUCTOR:用于描述构造器
2.FIELD:用于描述域
3.LOCAL_VARIABLE:用于描述局部变量
4.METHOD:用于描述方法
5.PACKAGE:用于描述包
6.PARAMETER:用于描述参数
7.TYPE:用于描述类、接口(包括注解类型) 或enum声明


@Retention定义了该Annotation被保留的时间长短


作用：表示需要在什么级别保存该注释信息，用于描述注解的生命周期（即：被描述的注解在什么范围内有效）

取值（RetentionPoicy）有：

1.SOURCE:在源文件中有效（即源文件保留）
2.CLASS:在class文件中有效（即class保留）
3.RUNTIME:在运行时有效（即运行时保留）

@Documented:

@Documented用于描述其它类型的annotation应该被作为被标注的程序成员的公共API，因此可以被例如javadoc此类的工具文档化。Documented是一个标记注解，没有成员。


@Inherited：

@Inherited 元注解是一个标记注解，@Inherited阐述了某个被标注的类型是被继承的。如果一个使用了@Inherited修饰的annotation类型被用于一个class，
则这个annotation将被用于该class的子类。

使用示例

import java.lang.annotation.*;

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface Column {
    public String name() default "fieldName";
    public String setFuncName() default "setField";
    public String getFuncName() default "getField"; 
    public boolean defaultDBValue() default false;
}


使用@interface自定义注解时，自动继承了java.lang.annotation.Annotation接口，由编译程序自动完成其他细节。
在定义注解时，不能继承其他的注解或接口。@interface用来声明一个注解，其中的每一个方法实际上是声明了一个配置参数。
方法的名称就是参数的名称，返回值类型就是参数的类型（返回值类型只能是基本类型、Class、String、enum）。可以通过default来声明参数的默认值。


Annotation类型里面的参数该怎么设定: 
第一,只能用public或默认(default)这两个访问权修饰.例如,String value();这里把方法设为defaul默认类型；　 　
第二,参数成员只能用基本类型byte,short,char,int,long,float,double,boolean八种基本数据类型和 String,Enum,Class,annotations等数据类型,
以及这一些类型的数组.例如,String value();这里的参数成员就为String;　　
第三,如果只有一个参数成员,最好把参数名称设为"value",后加小括号.例:下面的例子FruitName注解就只有一个参数成员。

注解元素的默认值：

注解元素必须有确定的值，要么在定义注解的默认值中指定，要么在使用注解时指定，非基本类型的注解元素的值不可为null。因此, 使用空字符串或0作为默认值是一种常用的做法。

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


简单的自定义注解和使用注解实例：


@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitColor {

    public enum Color{ BULE,RED,GREEN};
    
    /**
     * 颜色属性
     * @return
     */
    Color fruitColor() default Color.GREEN;

}

package annotation;

import annotation.FruitColor.Color;

public class Apple {
    
    @FruitName("Apple")
    private String appleName;
    
    @FruitColor(fruitColor=Color.RED)
    private String appleColor;
    
    
    
    
    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 displayName(){
        System.out.println("水果的名字是：苹果");
    }
}

具体的代码示例(包括如何获取)：

//FruitColor注解类
package com.helloWorld;

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.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitColor {

    public enum Color{ BULE,RED,GREEN};
    

    Color fruitColor() default Color.GREEN;

}

//FruitName注解类
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitName {
    String value() default "";
}


//Apple 实体Bean类
package com.helloWorld;

import com.helloWorld.FruitColor.Color;

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("水果的名字是：苹果");
    }
}

//FruitProvider注解类
@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 "";
}


//工具类，获取注解内容类
package com.helloWorld;

import java.lang.reflect.Field;

public class FruitInfoUtil {

	 public static void getFruitInfo(Class<?> clazz){
	        
	        String strFruitName=" 水果名称：";
	        String strFruitColor=" 水果颜色：";
	        String strFruitProvicer="供应商信息：";
	        
	        Field[] fields = clazz.getDeclaredFields();
	        
	        for(Field field :fields){
	        	//判断该程序元素上是否包含指定类型的注解，存在则返回true，否则返回false.
	            if(field.isAnnotationPresent(FruitName.class)){
	            	//返回改程序元素上存在的、指定类型的注解，如果该类型注解不存在，则返回null。
	                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 static void main(String[] args) {        
      FruitInfoUtil.getFruitInfo(Apple.class);        
 }