注解

注解

Java 注解（Annotation）又称 Java 标注，是 JDK5.0 引入的一种注释机制。

Java 语言中的类、方法、变量、参数和包等都可以被标注。和 Javadoc 不同，Java 标注可以通过反射获取标注内容。

 

主要用途

• 编译格式检查
• 反射中解析
• 生成帮助文档
• 跟踪代码依赖

 

架构

每1个Annotation对象，都会有唯一的RetentionPolicy属性。

每 1 个 Annotation 对象，可以有若干个 ElementType 属性。

Annotation实现类：Deprecated, Documented, Inherited, Override 等等，

　　每一个实现类，都 "和 1 个 RetentionPolicy 关联" 并且 " 和 1~n 个 ElementType 关联"。

 

Annotation类

package java.lang.annotation;

public interface Annotation {
    boolean equals(Object obj);

    int hashCode();

    String toString();

    Class<? extends Annotation> annotationType();
}

ElementType类

package java.lang.annotation;

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

    FIELD,              /* 字段声明（包括枚举常量）  */

    METHOD,             /* 方法声明  即该类型Annotation只能用来修饰方法*/

    PARAMETER,          /* 参数声明  */

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

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

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

    PACKAGE;             /* 包声明  */
}

RetentionPolicy类

package java.lang.annotation;

public enum RetentionPolicy {
    SOURCE,            /* Annotation信息仅存在于编译器处理期间，编译器处理完之后就没有该Annotation信息了  */

    CLASS,             /* 编译器将Annotation存储于类对应的.class文件中。默认行为  */

    RUNTIME;            /* 编译器将Annotation存储于class文件中，并且可由JVM读入 */
}

 

 

Java的内置注解

作用在代码的注解（ 定义在java.lang 中）：

• @Override - 检查该方法是否是重写方法。如果发现其父类，或者是引用的接口中并没有该方法时，会报编译错误。
• @Deprecated - 标记过时方法。如果使用该方法，会报编译警告。
• @SuppressWarnings - 指示编译器去忽略注解中声明的警告。
  • 定义在java.lang.SuppressWarnings
  • 三种使用方式：
    • @SuppressWarnings("unchecked") [^ 抑制单类型的警告]
    • @SuppressWarnings("unchecked","rawtypes") [^ 抑制多类型的警告]
    • @SuppressWarnings("all") [^ 抑制所有类型的警告]
  • 参数列表：

    关键字	用途
    all	抑制所有警告
    boxing	抑制装箱、拆箱操作时候的警告
    cast	抑制映射相关的警告
    dep-ann	抑制启用注释的警告
    deprecation	抑制过期方法警告
    fallthrough	抑制确在switch中缺失breaks的警告
    finally	抑制finally模块没有返回的警告
    hiding	抑制相对于隐藏变量的局部变量的警告
    incomplete-switch	忽略没有完整的switch语句
    nls	忽略非nls格式的字符
    null	忽略对null的操作
    rawtypes	使用generics时忽略没有指定相应的类型
    restriction	抑制禁止使用劝阻或禁止引用的警告
    serial	忽略在serializable类中没有声明serialVersionUID变量
    static-access	抑制不正确的静态访问方式警告
    synthetic-access	抑制子类没有按最优方法访问内部类的警告
    unchecked	抑制没有进行类型检查操作的警告
    unqualified-field-access	抑制没有权限访问的域的警告
    unused	抑制没被使用过的代码的警告

作用在其他注解的注解(或者说 元注解)是（ 定义在java.lang.annotation 中）:

• @Retention - 标识这个注解怎么保存，是只在代码中，还是编入class文件中，或者是在运行时可以通过反射访问，即指定 Annotation 的策略属性。
  • 定义 Annotation 时，@Retention 可有可无。
  • 若没有 @Retention，则默认是 RetentionPolicy.CLASS。
• @Documented - 标记这些注解是否包含在用户文档中。
  • 定义 Annotation 时，@Documented 可有可无；
  • 若没有定义，则 Annotation 不会出现在 javadoc 中。
• @Target - 标记这个注解应该是哪种 Java 成员，即指定 Annotation 的类型属性。
  • 定义 Annotation 时，@Target 可有可无。若有 @Target，则该 Annotation 只能用于它所指定的地方；
  • 若没有 @Target，则该 Annotation 可以用于任何地方。
• @Inherited - 标记这个注解是继承于哪个注解类(默认 注解并没有继承于任何子类)，只能被用来标注“Annotation类型”，它所标注的Annotation具有继承性。
  • 子类会继承父类使用的注解中被@Inherited修饰的注解
  • 接口继承关系中，子接口不会继承父接口中的任何注解，不管父接口中使用的注解有没有 被@Inherited修饰
  • 类实现接口时不会继承任何接口中定义的注解

从 Java 7 开始，额外添加了 3 个注解:

• @SafeVarargs - Java 7 开始支持，忽略任何使用参数为泛型变量的方法或构造函数调用产生的警告。
• @FunctionalInterface - Java 8 开始支持，标识一个匿名函数或函数式接口。
• @Repeatable - Java 8 开始支持，标识某注解可以在同一个声明上使用多次。

 

自定义注解

格式：

@interface 自定义注解名{
　　参数
　　方法
}

@interface：

　　使用 @interface 定义注解时，意味着它实现了 java.lang.annotation.Annotation 接口，即该注解就是一个Annotation。

　定义 Annotation 时，@interface 是必须的。

　　注意：

• • 它和我们通常的 implemented 实现接口的方法不同。
  • Annotation 接口的实现细节都由编译器完成。
  • 通过 @interface 定义注解后，该注解不能继承其他的注解或接口。

 

示例

@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface MineAnnotation {
    参数类型 参数名() default 默认值;
}

使用方式：@MineAnnotation

注意：

• 注解中的每一个方法，实际是声明的注解配置参数
  • 方法的名称就是 配置参数的名称
  • 方法的返回值类型，就是配置参数的类型。只能是：基本类型/Class/String/enum
• 可以通过default来声明参数的默认值
• 如果只有一个参数成员，一般参数名为value
• 注解元素必须要有值，我们定义注解元素时，经常使用空字符串、0作为默认值。

 

@Inherited注解使用示例：https://www.runoob.com/w3cnote/java-annotation.html