Annotation 深度剖析(一)

 一.  Annotation  接口(interface) 所有 annotation 类型 都要扩展的公共接口。 

 二. 枚举类型  

1. ElementType  程序元素类型  枚举类  通常是与 @target 元注释类型一起使用,指定什么情况使用注释是合法的

public enum ElementType 

  extends Enum<ElementType>

    枚举常量

    (a). ANNOTATION_TYPE    //注释类型声明    

       (b).CONSTRUCTOR          //构造方法声明

       (c).LOCAL_VARIABLE      //局部变量声明

     (d).PACKAGE                  //包声明

     (e).PARAMETER            //参数类型声明

     (d).TYPE                      //类型,接口(包括注释类型)或者枚举声明

2.RetentionPolicy   enum 枚举类 (保存策略)

     (a).SOURCE    编译器要丢弃的注释 ,即保存在源代码期间,javadoc 后会被丢弃

     (b).CLASS     编译器将把注释记录在类文件中,但在运行时 VM 不需要保留注释。这是默认的行为。

       (c). RUNTIME  编译器将把注释记录在类文件中,在运行时 VM 将保留注释,因此可以反射性地读取。

 三 注释类型

     (a).Documented 指示某一类型的注释将通过 javadoc 和类似的默认工具进行文档化。应使用此类型来注释这些文档的声明:其注释会影响由其客户端注释的元素的使用。如果类型声明是用Documented 来注释的,则其注释将成为注释元素的公共API 的一部分。 (根据这段话的意识来理解,@Document  如果标记了@Document 来注解,如果导出Api 文档的话,会把注解的 转为 注解 的API) 源代码如下:

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
}

    (b).Inherited  指示注释类型会被自动继承指示注释类型被自动继承。如果在注释类型声明中存在 Inherited 元注释,并且用户在某一类声明中查询该注释类型,同时该类声明中没有此类型的注释,则将在该类的超类中自动查询该注释类型。此过程会重复进行,直到找到此类型的注释或到达了该类层次结构的顶层 (Object) 为止。如果没有超类具有该类型的注释,则查询将指示当前类没有这样的注释。(如果一个使用了@Inherited修饰的annotation类型被用于一个class,则这个annotation将被用于该class的子类。可以理解有穿透性)源代码如下:

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
}

    (c).Retention    指示注释类型的注释要保留多久。如果注释类型声明中不存在 Retention 注释,则保留策略默认为 RetentionPolicy.CLASS。只有元注释类型直接用于注释时,Target 元注释才有效。如果元注释类型用作另一种注释类型的成员,则无效。(指注释保存时间,分为三种 :源代码,运行中,编译后)

四。注解  

      (a).AnnotationTypeMismatchException 若某个注释的类型在对该注释进行编译(或序列化)后发生了更改,而程序试图访问该注释的元素时,抛出此异常。(运行时异常) 源代码如下:

public class AnnotationTypeMismatchException extends RuntimeException {
    private static final long serialVersionUID = 8125925355765570191L;

    /**
     * The <tt>Method</tt> object for the annotation element.
     */
    private final Method element;

    /**
     * The (erroneous) type of data found in the annotation.  This string
     * may, but is not required to, contain the value as well.  The exact
     * format of the string is unspecified.
     */
    private final String foundType;

    /**
     * Constructs an AnnotationTypeMismatchException for the specified
     * annotation type element and found data type.
     *
     * @param element the <tt>Method</tt> object for the annotation element
     * @param foundType the (erroneous) type of data found in the annotation.
     *        This string may, but is not required to, contain the value
     *        as well.  The exact format of the string is unspecified.
     */
    public AnnotationTypeMismatchException(Method element, String foundType) {
        super("Incorrectly typed data found for annotation element " + element
              + " (Found data of type " + foundType + ")");
        this.element = element;
        this.foundType = foundType;
    }

    /**
     * Returns the <tt>Method</tt> object for the incorrectly typed element.
     *
     * @return the <tt>Method</tt> object for the incorrectly typed element
     */
    public Method element() {
        return this.element;
    }

    /**
     * Returns the type of data found in the incorrectly typed element.
     * The returned string may, but is not required to, contain the value
     * as well.  The exact format of the string is unspecified.
     *
     * @return the type of data found in the incorrectly typed element
     */
    public String foundType() {
        return this.foundType;
    }
}

    (b).IncompleteAnnotationException  若某个注释在编译(或序列化)后将某个注释类型添加到其类型定义中,而程序试图该注释类型的元素时,抛出此异常。如果新元素有默认值,则不抛出此异常。源码如下

public class IncompleteAnnotationException extends RuntimeException {
    private static final long serialVersionUID = 8445097402741811912L;

    private Class<? extends Annotation> annotationType;
    private String elementName;

    /**
     * Constructs an IncompleteAnnotationException to indicate that
     * the named element was missing from the specified annotation type.
     *
     * @param annotationType the Class object for the annotation type
     * @param elementName the name of the missing element
     * @throws NullPointerException if either parameter is {@code null}
     */
    public IncompleteAnnotationException(
            Class<? extends Annotation> annotationType,
            String elementName) {
        super(annotationType.getName() + " missing element " +
              elementName.toString());

        this.annotationType = annotationType;
        this.elementName = elementName;
    }

    /**
     * Returns the Class object for the annotation type with the
     * missing element.
     *
     * @return the Class object for the annotation type with the
     *     missing element
     */
    public Class<? extends Annotation> annotationType() {
        return annotationType;
    }

    /**
     * Returns the name of the missing element.
     *
     * @return the name of the missing element
     */
    public String elementName() {
        return elementName;
    }
}

(c).AnnotationFormatError  错误 

       构造一个指示指定注释类型中缺少指定元素的 IncompleteAnnotationException。

       参数:

  annotationType - 注释类型的 Class 对象

  elementName - 缺少元素的名称

    

   

猜你喜欢

转载自blog.csdn.net/qq_38233650/article/details/86212355