补：注解（Annotation）

主要内容:

• 注解(Annotation)概述
• 常见的Annotation示例
• 自定义Annotation
• JDK中的元注解
• 利用反射获取注解信息（在反射部分涉及)
• JDK 8中注解的新特性

目录

常见的注解示例

示例一:生成文档相关的注解

示例二:在编译时进行格式检查(JDK内置的三个基本注解)

示例三:跟踪代码依赖性，实现替代配置文件功能

自定义注解：

自定义注解示例

元注解

@Retention

@Target

@Documented

@Inherited

jdk 8中注解的新特性：

可重复注解

在jdk8以前

在jdk8以后

类型注解

---

常见的注解示例

使用Annotation时要在其前面增加@符号,并把Annotation当成一个修饰符使用。用于修饰它支持的程序元素

示例一:生成文档相关的注解

@author：标明开发该类模块的作者，多个作者之间使用,分割

@version：标明该类模块的版本
@see：参考转向，也就是相关主题

@since：从哪个版本开始增加的
@param：对方法中某参数的说明，如果没有参数就不能写
@return对方法返回值的说明，如果方法的返回值类型是void就不能写

@exception：对方法可能抛出的异常进行说明，如果方法没有用throws显式抛出的异常就不能写其中

注意：

@param @return和@exception这三个标记都是只用于方法的。

@param的格式要求:@param形参名形参类型形参说明
@return的格式要求:@return返回值类型返回值说明

@exception的格式要求:exception异常类型异常说明

@param和@exception可以并列多个
 

示例二:在编译时进行格式检查(JDK内置的三个基本注解)

@Override:限定重写父类方法,该注解只能用于方法
@Deprecated:用于表示所修饰的元素(类,方法等)已过时。通常是因为所修饰的结构危险或存在更好的选择
@SuppressWarnings:抑制编译器警告
 

示例三:跟踪代码依赖性，实现替代配置文件功能

Servlet3.o提供了注解(annotation),使得不再需要在web.xml文件中进行Servlet的部署。
 

自定义注解：

参照@SupperWarning

1. 注解声明为:@interface
2. 内部定义成员，通常使用value表示
3. 可以指定成员的默认值，使用default定义
4. 如果自定义注解没有成员，表明是一个标识作用。
    

定义新的Annotation类型使用@interface关键字

自定义注解自动继承了java.lang.annotation.Annotation接口

Annotation的成员变量在 Annotation定义中以无参数方法的形式来声明。其方法名和返回值定义了该成员的名字和类型。我们称为配置参数。类型只能是八种基本数据类型、String类型、class类型、enum类型、Annotation类型、以上所有类型的数组。

可以在定义Annotation的成员变量时为其指定初始值，指定成员变量的初始值可使用default关键字

如果只有一个参数成员，建议使用参数名为value

如果定义的注解含有配置参数，那么使用时必须指定参数值，除非它有默认值。格式是“参数名=参数值”，如果只有一个参数成员，且名称为value，可以省略“value=”

没有成员定义的Annotation称为标记;包含成员变量的 Annotation称为元数据Annotation

注意:自定义注解必须配上注解的信息处理流程才有意义。
 

自定义注解通过都会指明两个元注解: Retention（生命周期）. Target（作用域）
 

自定义注解示例

public @interface MyAnnotation {
    String [] value();
}

指定默认值

public @interface MyAnnotation {
    String [] value() default "hello";
}

@Override 没有成员

public @interface Override {
}

元注解

对现有的注解进行注解的注解 

JDK的元Annotation用于修饰其他Annotation定义
 

JDK5.0提供了4个标准的meta-annotation类型，分别是:

• Retention：指定所修饰的Annotation的生命周期:SOURCE\CLASS（默认行为)\RUNTIME                         只有声明为RUNTIME生命周期的注解，才能通过反射获取。
• Target：用于指定被修饰的Annotation能用于修饰哪些程序元素
• 以下两个使用较少
  • Documented：表示所修饰的注解在被javadoc解析时,保留下来。
  • Inherited：被它修饰的Annotation将具有继承性。
     

@Retention

只能用于修饰一个Annotation定义,用于指定该Annotation的生命周期, @Rentention包含一个RetentionPolicy类型的成员变量,使用
@Rentention时必须为该value成员变量指定值:

• RetentionPolicy.SOURCE:在源文件中有效（即源文件保留），编译器直接丢弃这种策略的注释
• RetentionPolicy.CLASS:在class文件中有效(即class保留)，当运行Java程序时,JVM不会保留注解。这是默认值
• RetentionPolicy.RUNTIME:在运行时有效（即运行时保留），当运行Java程序时,JVM会保留注释。程序可以通过反射获取该注释。
   

例如@SuppressWarnings()源码中

@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
    /**
     * The set of warnings that are to be suppressed by the compiler in the
     * annotated element.  Duplicate names are permitted.  The second and
     * successive occurrences of a name are ignored.  The presence of
     * unrecognized warning names is not an error: Compilers must
     * ignore any warning names they do not recognize.  They are, however,
     * free to emit a warning if an annotation contains an unrecognized
     * warning name.
     *
     * 
 The string {@code "unchecked"} is used to suppress
     * unchecked warnings. Compiler vendors should document the
     * additional warning names they support in conjunction with this
     * annotation type. They are encouraged to cooperate to ensure
     * that the same names work across multiple compilers.
     * @return the set of warnings to be suppressed
     */
    String[] value();
}

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,

    /**
     * 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
     */
    RUNTIME
}

@Target

用于修饰Annotation定义,用于指定被修饰的Annotation能用于修饰哪些程序元素。@Target也包含一个名为value的成员变量。
 

取值		取值
CONSTRUCTOR	用于描述构造器	PACKAGE	用于描述包
FLELD	用于描述域	PARAMETRE	用于描述参数
LOCAL_VARIABLE	用于描述局部变量	TYPE	用于描述类、接口（包括注解类型）或enum声明
METHOD	用于描述方法

@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();
}

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
}

@Documented

用于指定被该元Annotation修饰的Annotation类将被javadoc工具提取成文档。默认情况下，javadoc是不包括注解的。

定义为Documented的注解必须设置Retention值为RUNTIME。

@Inherited

被它修饰的Annotation将具有继承性。如果某个类使用了被@lnherited修饰的Annotation,则其子类将自动具有该注解。

• 比如:如果把标有@Inherited注解的自定义的注解标注在类级别上，子类则可以继承父类类级别的注解
• 实际应用中，使用较少
   

jdk 8中注解的新特性： 可重复注解

@MyAnnotation(value = "hello")
@MyAnnotation(value = "hi")
class Person {
    private String name;
    private int  age;}

直接这样写会报错

解决办法：

在jdk8以前

1.将注解里的值声明为注解类型的数组

public @interface MyAnnotations {
        MyAnnotation[] value();
}

2.将两个注解放入

@MyAnnotations({@MyAnnotation(value = "hello"),@MyAnnotation(value = "hi")})
class Person {
    private String name;
    private int  age;}

在jdk8以后

在MyAnnotation上声明@Repeatable，成员值为MyAnnotations.class

MyAnnotation的@Target和@Retention@Inherited必须和MyAnnotations相同。

@Repeatable(MyAnnotations.class)
public @interface MyAnnotation {
    String [] value() default "hello";
}
public @interface MyAnnotations {
        MyAnnotation[] value();
}
@MyAnnotation(value = "hello")
@MyAnnotation(value = "hi")
class Person {
    private String name;
    private int  age;
}

类型注解
 

JDK1.8之后，关于元注解@Target的参数类型ElementType枚举值多了两 个

• TYPE_PARAMETER
• TYPE_USE

在Java 8之前，注解只能是在声明的地方所使用，Java8开始，注解可以应用在任何地方。

• ElementType.TYPE_PARAMETER表示该注解能写在类型变量的声明语句中（如:泛型声明）
• ElementType.TYPE_USE表示该注解能邹在使用类型的任何语句中。