学习随笔——自定义注解

致谢：参考博客（写的非常清晰，这篇就是我自己的笔记。）

一、简单了解

1. 注解是一种元数据形式。即注解是属于java的一种数据类型，和类、接口、数组、枚举类似。
2. 注解用来修饰，类、方法、变量、参数、包。
3. 注解不会对所修饰的代码产生直接的影响。

其实简单来说注解就是一个标记，定义一个标记。在需要的位置打上标记（类、方法、变量、参数、包）。然后程序在编译时或运行时可以检测到这些标记从而执行一些特殊操作。

二、自定义一个注解

自定义一个注解十分简单，就像定义一个类，一个接口一样但又有所不同。
例如定义一个新的注解。

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface TestAnnotation {
    String log() default "";
    int num();
}

这段代码会在下面做详细解释。

三、基本语法

注解类型的声明部分：

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

public @interface TestAnnotation {
}

注解类型的实现部分：

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

public @interface TestAnnotation {
    String log() default "";
    int num();
}

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

1. 访问修饰符必须为public，不写默认为public；
2. 该元素的类型只能是基本数据类型、String、Class、枚举类型、注解类型（体现了注解的嵌套效果）以及上述类型的一位数组；
3. 该元素的名称一般定义为名词，如果注解中只有一个元素，请把名字起为value（后面使用会带来便利操作）；
4. ()不是定义方法参数的地方，也不能在括号中定义任何参数，仅仅只是一个特殊的语法；
5. default代表默认值，值必须和第2点定义的类型一致；
6. 如果没有默认值，代表后续使用注解时必须给该类型元素赋值。

四、常用的元注解

元注解，简单总结就是修饰注解类型的注解。有些注解放在类上面，有些注解放在方法上面，有些注解放在属性上面等等。这些注解的特性，就是由元注解来进行控制的

@Target

@Target注解，是专门用来限定某个自定义注解能够被应用在哪些Java元素上面的。它使用一个枚举类型定义如下：

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

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

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

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

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

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

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

    /** 包的声明 */
    PACKAGE
}

注解TestAnnotation被限制只能在放法上添加。

@Target(ElementType.METHOD)
public @interface TestAnnotation {
    String log() default "";
    int num();
}

@Retention

@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
}

详解：

1. 如果一个注解被定义为RetentionPolicy.SOURCE，则它将被限定在Java源文件中，那么这个注解即不会参与编译也不会在运行期起任何作用，这个注解就和一个注释是一样的效果，只能被阅读Java文件的人看到；
2. 如果一个注解被定义为RetentionPolicy.CLASS，则它将被编译到Class文件中，那么编译器可以在编译时根据注解做一些处理动作，但是运行时JVM（Java虚拟机）会忽略它，我们在运行期也不能读取到；
3. 如果一个注解被定义为RetentionPolicy.RUNTIME，那么这个注解可以在运行期的加载阶段被加载到Class对象中。那么在程序运行阶段，我们可以通过反射得到这个注解，并通过判断是否有这个注解或这个注解中属性的值，从而执行不同的程序代码段。我们实际开发中的自定义注解几乎都是使用的RetentionPolicy.RUNTIME；
4. 在默认的情况下，自定义注解是使用的RetentionPolicy.CLASS。

@Documented

@Documented注解，是被用来指定自定义注解是否能随着被定义的java文件生成到JavaDoc文档当中。

@Inherited

@Inherited注解，是指定某个自定义注解如果写在了父类的声明部分，那么子类的声明部分也能自动拥有该注解。@Inherited注解只对那些@Target被定义为ElementType.TYPE的自定义注解起作用。

五、测试

定义一个简单的测试类，并添加上注解

public class TestClass {

    @TestAnnotation(log = "添加注解了", num = 1)
    public void test() {
        for (int i = 0; i < 5; i++) {
            System.out.println("Hello Annotation >>>>" + i );
        }
    }
}

搞个main方法测试一下

public class Test4 {

    public static void main(String[] args) {
        TestAnnotation annotation;
        try {
            Class testClass = Class.forName("POJO.TestClass");
            Method testMethod = testClass.getMethod("test");
            annotation = testMethod.getAnnotation(TestAnnotation.class);
            if (annotation == null) {
                System.out.println("此方法上没有添加：" + TestAnnotation.class.getName() + "注解");
            } else {
                System.out.println(annotation.log());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

另外：

1. 如果我们要获得的注解是配置在方法上的，那么我们要从Method对象上获取；如果是配置在属性上，就需要从该属性对应的Field对象上去获取，如果是配置在类型上，需要从Class对象上去获取。总之在谁身上，就从谁身上去获取！
2. isAnnotationPresent(Class<? extends Annotation> annotationClass)方法是专门判断该元素上是否配置有某个指定的注解；
3. getAnnotation(Class<A> annotationClass)方法是获取该元素上指定的注解。之后再调用该注解的注解类型元素方法就可以获得配置时的值数据；
4. 反射对象上还有一个方法getAnnotations()，该方法可以获得该对象身上配置的所有的注解。它会返回给我们一个注解数组，需要注意的是该数组的类型是Annotation类型，这个Annotation是一个来自于java.lang.annotation包的接口。