Java元注解

喜欢ヅ旅行 2024-03-25 15:11 86阅读 0赞

## 一、元注解 ##

### 一、@Documented ###

1、java.lang.annotation.Documented		在生成JavaDoc的时候，会将该注解显示出来。
    
    @Document 是 java 在生成文档，是否显示注解的开关。如果一个注解@B，被@Documented标注，那么被@B修饰的类，生成文档时，会显示@B。如果@B没有被@Documented标注，最终生成的文档中就不会显示@B。

package java.lang.annotation;
    @Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.ANNOTATION_TYPE)
    public @interface Documented {
        
    }

### 二、@Target ###

#### 一、**@Target的用法** ####

1、java.lang.annotation.Target	用于设定注解使用范围
    2、java.lang.annotation.ElementType	Target通过ElementType来指定注解可使用范围的枚举集合

package java.lang.annotation;
    @Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.ANNOTATION_TYPE)
    public @interface Target {
        
        /**
         * Returns an array of the kinds of elements an annotation type
         * can be applied to.
         * @return an array of the kinds of elements an annotation type
         * can be applied to
         * 返回注释可应用于某种元素类型的数组。
         */
        ElementType[] value();
    }

#### 二、**ElementType的用法** ####

ElementType. PACKAGE。它并不是使用在一般的类中，而是用在固定的文件package-info.java中。这里需要强调命名一定是“package-info”。由于package-info.java并不是一个合法的类，使用eclipse创建类的方式会提示不合法，所以需要以创建文件的方式来创建package-info.java。
    	注解只能在ElementType设定的范围内使用，否则将会编译报错。例如：范围只包含ElementType.METHOD ，则表明该注解只能使用在类的方法上，超出使用范围将编译异常。

<table> 
 <thead> 
  <tr> 
   <th>取值</th> 
   <th align="center">注解使用范围</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>TYPE</td> 
   <td align="center">可用于类或者接口上</td> 
  </tr> 
  <tr> 
   <td>FIELD</td> 
   <td align="center">可用于域上</td> 
  </tr> 
  <tr> 
   <td>METHOD</td> 
   <td align="center">可用于方法上</td> 
  </tr> 
  <tr> 
   <td>PARAMETER</td> 
   <td align="center">可用于参数上</td> 
  </tr> 
  <tr> 
   <td>CONSTRUCTOR</td> 
   <td align="center">可用于构造方法上</td> 
  </tr> 
  <tr> 
   <td>LOCAL_VARIABLE</td> 
   <td align="center">可用于局部变量上</td> 
  </tr> 
  <tr> 
   <td>ANNOTATION_TYPE</td> 
   <td align="center">可用于注解类型上（被@interface修饰的类型）</td> 
  </tr> 
  <tr> 
   <td>PACKAGE</td> 
   <td align="center">用于记录java文件的package信息</td> 
  </tr> 
  <tr> 
   <td>TYPE_PARAMETER</td> 
   <td align="center">@since 1.8 可用于泛型参数/类型变量的声明语句中</td> 
  </tr> 
  <tr> 
   <td>TYPE_USE</td> 
   <td align="center">@since 1.8 可用于类型声明和类型参数声明（eg：声明语句、泛型和强制转换语句的类型）</td> 
  </tr> 
 </tbody> 
</table>

package java.lang.annotation;
    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 */
        /** 可用于包上，用于记录Java文件的package信息 */
        PACKAGE,
        /**
         * Type parameter declaration
         * 可用于泛型参数
         * @since 1.8
         */
        TYPE_PARAMETER,
        /**
         * Use of a type
         * 用于类型声明和类型参数声明
         * @since 1.8
         */
        TYPE_USE
    }

### 三、@Retention ###

#### 一、**@Retention的用法** ####

1、java.lang.annotation.Retention	用来标识这个注解将如何保留。
    2、java.lang.annotation.RetentionPolicy 	Retention通过RetentionPolicy来标识这个注解将如何保留。
    
    @Retention修饰注解，用来表示注解的生命周期，生命周期的长短取决于@Retention的属性RetentionPolicy指定的值

package java.lang.annotation;
    @Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.ANNOTATION_TYPE)
    public @interface Retention {
        
        /**
         * Returns the retention policy.
         * @return the retention policy
         * 返回注解的保留策略
         * @return 保留策略
         */
        RetentionPolicy value();
    }

#### 二、**RetentionPolicy的用法** ####

三种类型生命周期：     SOURCE             <CLASS         <RUNTIME，使用RUNTIME会包含前面两个生命周期,
    	分别对应于：	   Java源文件(.java文件) ---> .class文件 ---> 内存中的字节码。
    注解按生命周期来划分可分为3类：
    1、RetentionPolicy.SOURCE：注解只保留在源文件，当Java文件编译成class文件的时候，注解被遗弃；
    2、RetentionPolicy.CLASS：注解被保留到class文件，但jvm加载class文件时候被遗弃，这是默认的生命周期；
    3、RetentionPolicy.RUNTIME：注解不仅被保存到class文件中，jvm加载class文件之后，仍然存在；
            
    那怎么来选择合适的注解生命周期呢？
    	首先要明确生命周期长度 SOURCE < CLASS < RUNTIME ，所以前者能作用的地方后者一定也能作用。一般如果需要在运行时去动态获取注解信息，那只能用 RUNTIME 注解；如果要 在编译时进行一些预处理操作，比如生成一些辅助代码（如ButterKnife），就用 CLASS注解；如果 只是做一些检查性的操作，比如 @Override 和@SuppressWarnings，则 可选用 SOURCE 注解。
    注：	
    注解@Override用在方法上，当我们想重写一个方法时，在方法上加@Override，当我们方法的名字出错时，编译器就会报错
    注解@Deprecated，用来表示某个类或属性或方法已经过时，不想别人再用时，在属性和方法上用@Deprecated修饰
    注解@SuppressWarnings用来压制程序中出来的警告，比如在没有用泛型或是方法已经过时的时候

<table> 
 <thead> 
  <tr> 
   <th align="center"><strong>取值</strong></th> 
   <th align="center"><strong>描述</strong></th> 
   <th align="center"><strong>作用范围</strong></th> 
   <th><strong>使用场景</strong></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center">RetentionPolicy.SOURCE</td> 
   <td align="center">表示注解只保留在源文件，当java文件编译成class文件，就会消失</td> 
   <td align="center">源文件</td> 
   <td>只是做一些检查性的操作，，比如 @Override 和 @SuppressWarning</td> 
  </tr> 
  <tr> 
   <td align="center">RetentionPolicy.CLASS</td> 
   <td align="center">注解被保留到class文件，但jvm加载class文件时候被遗弃，这是默认的生命周期</td> 
   <td align="center">class文件（默认）</td> 
   <td>要在编译时进行一些预处理操作，比如生成一些辅助代码（如 ButterKnife）</td> 
  </tr> 
  <tr> 
   <td align="center">RetentionPolicy.RUNTIME</td> 
   <td align="center">注解不仅被保存到class文件中，jvm加载class文件之后，仍然存在</td> 
   <td align="center">运行时也存在</td> 
   <td>需要在运行时去动态获取注解信息</td> 
  </tr> 
 </tbody> 
</table>

package java.lang.annotation;
    /**
     * 注解保留策略。
     * 与@Retention元注解一起使用，指定注解要保留多长时间
     */
    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.
         * 注解由编译器记录在类文件中，但在JVM将被忽略。
         */
        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.
         * @see java.lang.reflect.AnnotatedElement
         * 注解由编译器记录在类文件中并且在JVM在运行时保留，因此可以通过反射读取。
         */
        RUNTIME
    }

### 四、@Inherited ###

1、java.lang.annotation.Inherited	该注解作用于某父类时，该注解会被父类的子类继承。

package java.lang.annotation;
    @Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.ANNOTATION_TYPE)
    public @interface Inherited {
        
    }

### 五、@Repeatable ###

1、java.lang.annotation.Repeatable	
    @Repeatable用于声明其它类型注解的元注解，来表示这个声明的注解是可重复的
    @Repeatable的值是另一个注解，其可以通过这个另一个注解的值来包含这个可重复的注解。
        
    注： 
    @Repeatable 所声明的注解，其元注解@Target的使用范围要比@Repeatable的值声明的注解中的@Target的范围要大或相同，否则编译器错误，显示@Repeatable值所声明的注解的元注解@Target不是@Repeatable声明的注解的@Target的子集
    @Repeatable注解声明的注解的元注解@Retention的周期要比@Repeatable的值指向的注解的@Retention得周期要小或相同。
     
    注：
    1、在需要重复使用的注解上修饰 @Repeatable
    2、@Repeatable中的参数为被修饰注解的容器的类对象（class对象）
    3、容器包含一个value方法，返回一个被修饰注解的数组

package java.lang.annotation;
    @Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.ANNOTATION_TYPE)
    public @interface Repeatable {
        
        /**
         * Indicates the <em>containing annotation type</em> for the
         * repeatable annotation type.
         * @return the containing annotation type
         */
        Class<? extends Annotation> value();
    }

package java.lang.annotation;
    public interface Annotation {
        
        /**
         * Returns true if the specified object represents an annotation
         * that is logically equivalent to this one.  In other words,
         * returns true if the specified object is an instance of the same
         * annotation type as this instance, all of whose members are equal
         * to the corresponding member of this annotation, as defined below:
         * <ul>
         *    <li>Two corresponding primitive typed members whose values are
         *    <tt>x</tt> and <tt>y</tt> are considered equal if <tt>x == y</tt>,
         *    unless their type is <tt>float</tt> or <tt>double</tt>.
         *
         *    <li>Two corresponding <tt>float</tt> members whose values
         *    are <tt>x</tt> and <tt>y</tt> are considered equal if
         *    <tt>Float.valueOf(x).equals(Float.valueOf(y))</tt>.
         *    (Unlike the <tt>==</tt> operator, NaN is considered equal
         *    to itself, and <tt>0.0f</tt> unequal to <tt>-0.0f</tt>.)
         *
         *    <li>Two corresponding <tt>double</tt> members whose values
         *    are <tt>x</tt> and <tt>y</tt> are considered equal if
         *    <tt>Double.valueOf(x).equals(Double.valueOf(y))</tt>.
         *    (Unlike the <tt>==</tt> operator, NaN is considered equal
         *    to itself, and <tt>0.0</tt> unequal to <tt>-0.0</tt>.)
         *
         *    <li>Two corresponding <tt>String</tt>, <tt>Class</tt>, enum, or
         *    annotation typed members whose values are <tt>x</tt> and <tt>y</tt>
         *    are considered equal if <tt>x.equals(y)</tt>.  (Note that this
         *    definition is recursive for annotation typed members.)
         *
         *    <li>Two corresponding array typed members <tt>x</tt> and <tt>y</tt>
         *    are considered equal if <tt>Arrays.equals(x, y)</tt>, for the
         *    appropriate overloading of {@link java.util.Arrays#equals}.
         * </ul>
         *
         * @return true if the specified object represents an annotation
         *     that is logically equivalent to this one, otherwise false
         */
        boolean equals(Object obj);
    
        /**
         * Returns the hash code of this annotation, as defined below:
         *
         * <p>The hash code of an annotation is the sum of the hash codes
         * of its members (including those with default values), as defined
         * below:
         *
         * The hash code of an annotation member is (127 times the hash code
         * of the member-name as computed by {@link String#hashCode()}) XOR
         * the hash code of the member-value, as defined below:
         *
         * <p>The hash code of a member-value depends on its type:
         * <ul>
         * <li>The hash code of a primitive value <tt><i>v</i></tt> is equal to
         *     <tt><i>WrapperType</i>.valueOf(<i>v</i>).hashCode()</tt>, where
         *     <tt><i>WrapperType</i></tt> is the wrapper type corresponding
         *     to the primitive type of <tt><i>v</i></tt> ({@link Byte},
         *     {@link Character}, {@link Double}, {@link Float}, {@link Integer},
         *     {@link Long}, {@link Short}, or {@link Boolean}).
         *
         * <li>The hash code of a string, enum, class, or annotation member-value
         I     <tt><i>v</i></tt> is computed as by calling
         *     <tt><i>v</i>.hashCode()</tt>.  (In the case of annotation
         *     member values, this is a recursive definition.)
         *
         * <li>The hash code of an array member-value is computed by calling
         *     the appropriate overloading of
         *     {@link java.util.Arrays#hashCode(long[]) Arrays.hashCode}
         *     on the value.  (There is one overloading for each primitive
         *     type, and one for object reference types.)
         * </ul>
         *
         * @return the hash code of this annotation
         */
        int hashCode();
    
        /**
         * Returns a string representation of this annotation.  The details
         * of the representation are implementation-dependent, but the following
         * may be regarded as typical:
         * <pre>
         *   @com.acme.util.Name(first=Alfred, middle=E., last=Neuman)
         * </pre>
         *
         * @return a string representation of this annotation
         */
        String toString();
    
        /**
         * Returns the annotation type of this annotation.
         * @return the annotation type of this annotation
         */
        Class<? extends Annotation> annotationType();
    }