【Java--自定义注解】

什么是注解？

 ▪ Annontation是Java5开始引入的新特征，中文名称注解。
▪ 它提供了一种安全的类似注释的机制，用来将任何的信息戒元数据（metadata）与程序元素（类、方法、成员变量等）进行关联。
▪ 为程序的元素（类、方法、成员变量）加上更直观更明了的说明，这些说明信息是与程序的业务逻辑无关，并且供指定的工具和框架使用。
▪ Annontation像一种修饰符一样，应用于包、类型、构造方法、方法、成员变量、参数及本地变量的声明语句中。
▪ Java注解是附加在代码中的一些元信息，用于一些工具在编译、运行时进行解析和使用，起到说明、配置的功能。
▪ 注解不会也不能影响代码的实际逻辑，仅仅起到辅助性的作用。包含在
java.lang.annotation 包中。

An annotation is a form of metadata, that can be added to Java source
code. Classes, methods, variables, parameters and packages may be
annotated. Annotations have no direct effect on the operation of the
code they annotate.

翻译：

注解是一种能被添加到java代码中的元数据，类、方法、变量、参数和包都可以用注解来修饰。注解对于它所修饰的代码并没有直接的影响。

注解的作用
▪ 生成文档。这是最常见的，也是java 最早提供的注解。常用的有
@param @return 等
▪ 跟踪代码依赖性，实现替代配置文件功能。
▪ 在编译时进行格式检查。如@override 放在方法前，如果你这个
方法并不是覆盖了超类方法，则编译时就能检查出。

注解的使用范围
注解又许多用法，其中有：为编译器提供信息 - 注解能被编译器检测到错误或抑制警告。编译时和部署时的处理 - 软件工具能处理注解信息从而生成代码，XML文件等等。运行时的处理 - 有些注解在运行时能被检测到。

*内置注解*
▪ @Override：定义在java.lang.Override中，此注释叧适用于修饰方法，表示一个方法声明打算重写超类中的另一个方法声明
▪ @Deprecated：定义在java.lang.Deprecated中，此注释可以
修饰方法、属性、类，表示不鼓励程序员使用这样的元素，通常是因为它很危险戒者存在更好的选择
▪ @SuppressWarnings：定义在java.lang.SuppressWarnings中，
用来抑制编写编译时的警告信息

元注解

▪ 元注解的作用是负责注解其他注解，java中定义了四个标准的meta-annotation类型，他们被用来提供对其他annotation类型作说明
▪ 这些类型和它们所支持的类在java.lang.annotation包中
– @Target：用来描述注解的使用范围（注解可以用在什么地方）
– @Retention：表示需要在什么级别保存该注释信息，描述注解的生命周期
▪ Source < Class < Runtime
– @Document：说明该注解将被包含在javadoc中
– @Inherited：说明子类可以继承父类中的该注解

自定义注解

	▪ 使用@interfac自定义注解时，自动继承了java.lang.annotation.Annotation接口
▪ 使用规则：
– @interface用来声明一个注解，格式：public @interface 注解名{}
– 其中的每一个方法实际上是声明了一个配置参数
– 方法的名称就是参数的名称
– 返回值类型就是参数的类型（返回值只能是基本类型，Class,String,enum）
– 可以头盖骨default来声明参数的默认值
– 如果叧有一个参数成员，一般参数名为value
– 注解元素必须要有值，我们定义注解元素时，经常使用空字符串，0作为默认值

如何自定义注解
注解其实就是一种标记，可以在程序代码中的关键节点（类、方法、变量、参数、包）上打上这些标记，然后程序在编译时或运行时可以检测到这些标记从而执行一些特殊操作。因此可以得出自定义注解使用的基本流程：

第一步，定义注解——相当于定义标记；
第二步，配置注解——把标记打在需要用到的程序代码中；
第三步，解析注解——在编译期或运行时检测到标记，并进行特殊操作。
2.1 基本语法
注解类型的声明部分：

注解在Java中，与类、接口、枚举类似，因此其声明语法基本一致，只是所使用的关键字有所不同@interface。在底层实现上，所有定义的注解都会自动继承java.lang.annotation.Annotation接口。

public @interface CherryAnnotation {
}

注解类型的实现部分：

根据我们在自定义类的经验，在类的实现部分无非就是书写构造、属性或方法。但是，在自定义注解中，其实现部分只能定义一个东西：注解类型元素（annotation type element）。咱们来看看其语法：

public @interface CherryAnnotation {
	public String name();
	int age();
	int[] array();
}

它与接口中定义抽象方法的语法并不相同，咱们看看下面这个：

public @interface CherryAnnotation {
	public String name();
	int age() default 18;
	int[] array();
}

注解里面定义的是：注解类型元素！

定义注解类型元素时需要注意如下几点：

访问修饰符必须为public，不写默认为public；

该元素的类型只能是基本数据类型、String、Class、枚举类型、注解类（体现了注解的嵌套效果）以及上述类型的一位数组；

该元素的名称一般定义为名词，如果注解中只有一个元素，请把名字起为 value（后面使用会带来便利操作）；

()不是定义方法参数的地方，也不能在括号中定义任何参数，仅仅只是一个特殊的语法；

default代表默认值，值必须和第2点定义的类型一致；

如果没有默认值，代表后续使用注解时必须给该类型元素赋值。

可以看出，注解类型元素的语法非常奇怪，即又有属性的特征（可以赋值）,又有方法的特征（打上了一对括号）。但是这么设计是有道理的，我们在后面的章节中可以看到：注解在定义好了以后，使用的时候操作元素类型像在操作属性，解析的时候操作元素类型像在操作方法。
@Target

public enum ElementType {
    /** 类，接口（包括注解类型）或枚举的声明 */
    TYPE,

    /** 属性的声明 */
    FIELD,

    /** 方法的声明 */
    METHOD,

    /** 方法形式参数声明 */
    PARAMETER,

    /** 构造方法的声明 */
    CONSTRUCTOR,

    /** 局部变量声明 */
    LOCAL_VARIABLE,

    /** 注解类型声明 */
    ANNOTATION_TYPE,

    /** 包的声明 */
    PACKAGE
}

//@CherryAnnotation被限定只能使用在类、接口或方法上面
@Target(value = {ElementType.TYPE,ElementType.METHOD})
public @interface CherryAnnotation {
    String name();
    int age() default 18;
    int[] array();
}

@Retention
翻译为持久力、保持力。即用来修饰自定义注解的生命力。
注解的生命周期有三个阶段：
1、Java源文件阶段；
2、编译到class文件阶段；
3、运行期阶段。同样使用了RetentionPolicy枚举类型定义了三个阶段：

public enum RetentionPolicy {
    /**
     * Annotations are to be discarded by the compiler.
     * （注解将被编译器忽略掉）
     */
    SOURCE,

    /**
     * Annotations are to be recorded in the class file by the compiler
     * but need not be retained by the VM at run time.  This is the default
     * behavior.
     * （注解将被编译器记录在class文件中，但在运行时不会被虚拟机保留，这是一个默认的行为）
     */
    CLASS,

    /**
     * Annotations are to be recorded in the class file by the compiler and
     * retained by the VM at run time, so they may be read reflectively.
     * （注解将被编译器记录在class文件中，而且在运行时会被虚拟机保留，因此它们能通过反射被读取到）
     * @see java.lang.reflect.AnnotatedElement
     */
    RUNTIME
}