Java注解解读-ElementType详解

注解须知前言

Java注解使用是相当频繁，特别是在在框架源码使用，用到类的反射获取方法和属性，用的尤其多，而且即使是编写业务代码时候，也常有使用自定义注解来结合aop来实现减少代码的编写。

接下来我们就来解读一下Java注解。
Java中以前只有4个元注解，Java8后又新增了1个。


在讲解元注解概念之前，我们先建立元数据的概念。 元数据在英语中对应单词 metadata, metadata在wiki中的解释是：

Metadata is data [information] that provides information about other data

为其他数据提供信息的数据

这样元注解就好理解了，元注解 meta annotation用于注解 自定义注解 的注解。

接下来就看看Java中有哪些元注解，如下：

@Target 目标即作用范围
@Retention 保留
@Inherited 遗传，即注解是否可被继承
@Documented 文档，用javadoc命令生成API文档，会又相关信息

---

@Repeatable (java1.8 新增项)
当没有@Repeatable修饰的时候，注解在同一个位置，只能出现一次

接下来就进行注意讲解：

@Target

/*
 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package java.lang.annotation;

/**
 * The constants of this enumerated type provide a simple classification of the
 * syntactic locations where annotations may appear in a Java program. These
 * constants are used in {@link Target java.lang.annotation.Target}
 * meta-annotations to specify where it is legal to write annotations of a
 * given type.
 *
 * 
The syntactic locations where annotations may appear are split into
 * declaration contexts , where annotations apply to declarations, and
 * type contexts , where annotations apply to types used in
 * declarations and expressions.
 *
 * 
The constants {@link #ANNOTATION_TYPE} , {@link #CONSTRUCTOR} , {@link
 * #FIELD} , {@link #LOCAL_VARIABLE} , {@link #METHOD} , {@link #PACKAGE} ,
 * {@link #PARAMETER} , {@link #TYPE} , and {@link #TYPE_PARAMETER} correspond
 * to the declaration contexts in JLS 9.6.4.1.
 *
 * 
For example, an annotation whose type is meta-annotated with
 * {@code @Target(ElementType.FIELD)} may only be written as a modifier for a
 * field declaration.
 *
 * 
The constant {@link #TYPE_USE} corresponds to the 15 type contexts in JLS
 * 4.11, as well as to two declaration contexts: type declarations (including
 * annotation type declarations) and type parameter declarations.
 *
 * 
For example, an annotation whose type is meta-annotated with
 * {@code @Target(ElementType.TYPE_USE)} may be written on the type of a field
 * (or within the type of the field, if it is a nested, parameterized, or array
 * type), and may also appear as a modifier for, say, a class declaration.
 *
 * 
The {@code TYPE_USE} constant includes type declarations and type
 * parameter declarations as a convenience for designers of type checkers which
 * give semantics to annotation types. For example, if the annotation type
 * {@code NonNull} is meta-annotated with
 * {@code @Target(ElementType.TYPE_USE)}, then {@code @NonNull}
 * {@code class C {...}} could be treated by a type checker as indicating that
 * all variables of class {@code C} are non-null, while still allowing
 * variables of other classes to be non-null or not non-null based on whether
 * {@code @NonNull} appears at the variable's declaration.
 *
 * @author  Joshua Bloch
 * @since 1.5
 * @jls 9.6.4.1 @Target
 * @jls 4.1 The Kinds of Types and Values
 */
public enum ElementType {
    /** Class, interface (including annotation type), or enum declaration */
    TYPE,

    /** Field declaration (includes enum constants) */
    FIELD,

    /** Method declaration */
    METHOD,

    /** Formal parameter declaration */
    PARAMETER,

    /** Constructor declaration */
    CONSTRUCTOR,

    /** Local variable declaration */
    LOCAL_VARIABLE,

    /** Annotation type declaration */
    ANNOTATION_TYPE,

    /** Package declaration */
    PACKAGE,

    /**
     * Type parameter declaration
     *
     * @since 1.8
     */
    TYPE_PARAMETER,

    /**
     * Use of a type
     *
     * @since 1.8
     */
    TYPE_USE
}

@Target 表示这个注解能放在什么位置上，是只能放在类上？还是即可以放在方法上，又可以放在属性上。从源码中可见，目标注解的值是一个数组,举个例子：

@Target({METHOD,TYPE})，表示他可以用在方法和类型上（类和接口），但是不能放在属性等其他位置。

可以选择的位置列表如下：

值得注意的是，在Java8中 ElementType 新增两个枚举成员，TYPE_PARAMETER 和 TYPE_USE ，在Java8前注解只能标注在一个声明(如字段、类、方法)上，Java8后，新增的TYPE_PARAMETER可以用于标注类型参数，而TYPE_USE则可以用于标注任意类型(不包括class)。如下所示

ElementType.TYPE：能修饰类、接口或枚举类型
ElementType.FIELD：能修饰成员变量
ElementType.METHOD：能修饰方法
ElementType.PARAMETER：能修饰参数
ElementType.CONSTRUCTOR：能修饰构造器
ElementType.LOCAL_VARIABLE：能修饰局部变量
ElementType.ANNOTATION_TYPE：能修饰注解
ElementType.PACKAGE：能修饰包

@Retention

@Retention 表示生命周期

RetentionPolicy.SOURCE： 注解只在源代码中存在，编译成class之后，就没了。@Override 就是这种注解。
RetentionPolicy.CLASS： 注解在java文件编程成.class文件后，依然存在，但是运行起来后就没了。@Retention的默认值，即当没有显式指定@Retention的时候，就会是这种类型。
RetentionPolicy.RUNTIME： 注解在运行起来之后依然存在，程序可以通过反射获取这些信息

@Inherited

翻译注释即：

指示注释类型是自动继承的。如果注释类型声明中存在继承的元注释，并且用户在类声明中查询该注释类型，并且该类声明没有该类型的注释，则将自动查询该类的超类以获取注释类型。重复此过程，直到找到该类型的注释，或到达类层次结构（对象）的顶部为止。如果没有超类对此类型进行注释，则查询将指示所讨论的类没有此类注释。请注意，如果带注释的类型用于注释除类之外的任何内容，则此元注释类型无效。还要注意，此元注释仅使注释从超类继承；已实现的接口上的注释无效。

@Inherited 表示该注解具有继承性。
即如果一个使用了@Inherited 修饰的annotation 类型被用于一个class，则这个annotation 将被用于该class 的子类。

@Documented

@Documented 如图所示， 在用javadoc命令生成API文档后，文档里会出现该注解说明

@Repeatable

元注解@Repeatable是JDK1.8新加入的，它表示在同一个位置重复相同的注解。在没有该注解前，一般是无法在同一个类型上使用相同的注解的。

//Java8前无法这样使用
@FilterPath("/update")
@FilterPath("/add")
public class A {}

Java8前如果是想实现类似的功能，我们需要在定义@FilterPath注解时定义一个数组元素接收多个值如下：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface FilterPath {
    String [] value();
}

//使用
@FilterPath({"/update","/add"})
public class A { }

@Target({ElementType.TYPE,ElementType.FIELD,ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(FilterPaths.class)//参数指明接收的注解class
public @interface FilterPath {
    String  value();
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface FilterPaths {
    FilterPath[] value();
}

//使用案例
@FilterPath("/update")
@FilterPath("/add")
@FilterPath("/delete")
class AA{ }