Annotation annotation

1. The working principle of Annotation:

The annotation function is provided in JDK5.0, allowing developers to define and use their own annotation types. This functionality consists of a syntax that defines an annotation type and a syntax that describes an annotation declaration, an API for reading annotations, a class file decorated with annotations, and an annotation processing tool.

Annotation does not directly affect the semantics of the code, but it can be seen as a tool or class library for the program. It in turn has an impact on the running program semantics.

Annotation can be read from source files, class files, or at runtime through reflection mechanisms in various ways.

2. @Override annotation:

java.lang
Annotation Type Override
@Target(value=METHOD)
@Retention(value=SOURCE)
public @interface Override

Indicates that a method declaration intends to override another method declaration in the superclass. The compiler generates an error message if a method is annotated with this annotation type but does not override the superclass method.

The @Override annotation indicates that the subclass should override the corresponding method of the superclass.

Override is a Marker annotation, which is used to identify the Annotation. The Annotation name itself represents the information to be given to the tool program.

Here is an example using the @Override annotation:

class A {
    private String id;
    A(String id){
        this.id = id;
    }
    @Override
    public String toString() {
        return id;
    }
}

3. @Deprecated annotation:

java.lang
Annotation Type Deprecated
@Documented
@Retention(value=RUNTIME)
public @interface Deprecated

用 @Deprecated 注释的程序元素，不鼓励程序员使用这样的元素，通常是因为它很危险或存在更好的选择。在使用不被赞成的程序元素或在不被赞成的代码中执行重写时，编译器会发出警告。

@Deprecated注解表示方法是不被建议使用的。

Deprecated是一个Marker annotation。

下面是一个使用@Deprecated注解的例子：

class A {
    private String id;
    A(String id){
        this.id = id;
    }
    @Deprecated
    public void execute(){
        System.out.println(id);
    }
    public static void main(String[] args) {
        A a = new A("a123");
        a.execute();
    }
}

4、@SuppressWarnings注解：

java.lang
注释类型 SuppressWarnings
@Target(value={TYPE,FIELD,METHOD,PARAMETER,CONSTRUCTOR,LOCAL_VARIABLE})
@Retention(value=SOURCE)
public @interface SuppressWarnings

指示应该在注释元素（以及包含在该注释元素中的所有程序元素）中取消显示指定的编译器警告。注意，在给定元素中取消显示的警告集是所有包含元素中取消显示的警告的超集。例如，如果注释一个类来取消显示某个警告，同时注释一个方法来取消显示另一个警告，那么将在此方法中同时取消显示这两个警告。

根据风格不同，程序员应该始终在最里层的嵌套元素上使用此注释，在那里使用才有效。如果要在特定的方法中取消显示某个警告，则应该注释该方法而不是注释它的类。

@SuppressWarnings注解表示抑制警告。

下面是一个使用@SuppressWarnings注解的例子：

@SuppressWarnings("unchecked")
public static void main(String[] args) {
    List list = new ArrayList();
    list.add("abc");
}

5、自定义注解：

使用@interface自定义注解时，自动继承了java.lang.annotation.Annotation接口，由编译程序自动完成其他细节。在定义注解时，不能继承其他的注解或接口。

自定义最简单的注解：

public @interface MyAnnotation {

}

使用自定义注解：

public class AnnotationTest2 {

    @MyAnnotation
    public void execute(){
        System.out.println("method");
    }
}

5.1、添加变量：

public @interface MyAnnotation {

    String value1();
}

使用自定义注解：

public class AnnotationTest2 {

    @MyAnnotation(value1="abc")
    public void execute(){
        System.out.println("method");
    }
}

当注解中使用的属性名为value时，对其赋值时可以不指定属性的名称而直接写上属性值接口；除了value意外的变量名都需要使用name=value的方式赋值。

5.2、添加默认值：

public @interface MyAnnotation {

    String value1() default "abc";
}

5.3、多变量使用枚举：

public @interface MyAnnotation {

    String value1() default "abc";
    MyEnum value2() default MyEnum.Sunny;
}
enum MyEnum{
    Sunny,Rainy
}

使用自定义注解：

public class AnnotationTest2 {

    @MyAnnotation(value1="a", value2=MyEnum.Sunny)
    public void execute(){
        System.out.println("method");
    }
}

5.4、数组变量：

public @interface MyAnnotation {

    String[] value1() default "abc";
}

使用自定义注解：

public class AnnotationTest2 {

    @MyAnnotation(value1={"a","b"})
    public void execute(){
        System.out.println("method");
    }
}

6、设置注解的作用范围：

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Retention

指示注释类型的注释要保留多久。如果注释类型声明中不存在 Retention 注释，则保留策略默认为 RetentionPolicy.CLASS。

只有元注释类型直接用于注释时，Target 元注释才有效。如果元注释类型用作另一种注释类型的成员，则无效。

public enum RetentionPolicy
extends Enum<RetentionPolicy>

注释保留策略。此枚举类型的常量描述保留注释的不同策略。它们与 Retention 元注释类型一起使用，以指定保留多长的注释。

CLASS
编译器将把注释记录在类文件中，但在运行时 VM 不需要保留注释。
RUNTIME
编译器将把注释记录在类文件中，在运行时 VM 将保留注释，因此可以反射性地读取。
SOURCE
编译器要丢弃的注释。

@Retention注解可以在定义注解时为编译程序提供注解的保留策略。

属于CLASS保留策略的注解有@SuppressWarnings，该注解信息不会存储于.class文件。

6.1、在自定义注解中的使用例子：

@Retention(RetentionPolicy.CLASS)
public @interface MyAnnotation {

    String[] value1() default "abc";
}

7、使用反射读取RUNTIME保留策略的Annotation信息的例子：

java.lang.reflect
        接口 AnnotatedElement
所有已知实现类：
        AccessibleObject, Class, Constructor, Field, Method, Package

表示目前正在此 VM 中运行的程序的一个已注释元素。该接口允许反射性地读取注释。由此接口中的方法返回的所有注释都是不可变并且可序列化的。调用者可以修改已赋值数组枚举成员的访问器返回的数组；这不会对其他调用者返回的数组产生任何影响。

如果此接口中的方法返回的注释（直接或间接地）包含一个已赋值的 Class 成员，该成员引用了一个在此 VM 中不可访问的类，则试图通过在返回的注释上调用相关的类返回的方法来读取该类，将导致一个 TypeNotPresentException。

isAnnotationPresent
boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)

如果指定类型的注释存在于此元素上，则返回 true，否则返回 false。此方法主要是为了便于访问标记注释而设计的。

参数：

annotationClass - 对应于注释类型的 Class 对象

如果指定注释类型的注释存在于此对象上，则返回 true，否则返回 false

抛出：

NullPointerException - 如果给定的注释类为 null

从以下版本开始：

1.5

getAnnotation
<T extends Annotation> T getAnnotation(Class<T> annotationClass)

如果存在该元素的指定类型的注释，则返回这些注释，否则返回 null。

参数：

annotationClass - 对应于注释类型的 Class 对象

如果该元素的指定注释类型的注释存在于此对象上，则返回这些注释，否则返回 null

抛出：

NullPointerException - 如果给定的注释类为 null

从以下版本开始：

1.5

getAnnotations
Annotation[] getAnnotations()

返回此元素上存在的所有注释。（如果此元素没有注释，则返回长度为零的数组。）该方法的调用者可以随意修改返回的数组；这不会对其他调用者返回的数组产生任何影响。

此元素上存在的所有注释

从以下版本开始：

1.5

getDeclaredAnnotations
Annotation[] getDeclaredAnnotations()

返回直接存在于此元素上的所有注释。与此接口中的其他方法不同，该方法将忽略继承的注释。（如果没有注释直接存在于此元素上，则返回长度为零的一个数组。）该方法的调用者可以随意修改返回的数组；这不会对其他调用者返回的数组产生任何影响。

直接存在于此元素上的所有注释

从以下版本开始：

1.5

下面是使用反射读取RUNTIME保留策略的Annotation信息的例子：

自定义注解：

@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation {

    String[] value1() default "abc";
}

使用自定义注解：

public class AnnotationTest2 {

    @MyAnnotation(value1={"a","b"})
    @Deprecated
    public void execute(){
        System.out.println("method");
    }
}

读取注解中的信息：

public static void main(String[] args) throws SecurityException, NoSuchMethodException, IllegalArgumentException, IllegalAccessException, InvocationTargetException {
    AnnotationTest2 annotationTest2 = new AnnotationTest2();
    //获取AnnotationTest2的Class实例
    Class<AnnotationTest2> c = AnnotationTest2.class;
    //获取需要处理的方法Method实例
    Method method = c.getMethod("execute", new Class[]{});
    //判断该方法是否包含MyAnnotation注解
    if(method.isAnnotationPresent(MyAnnotation.class)){
        //获取该方法的MyAnnotation注解实例
        MyAnnotation myAnnotation = method.getAnnotation(MyAnnotation.class);
        //执行该方法
        method.invoke(annotationTest2, new Object[]{});
        //获取myAnnotation
        String[] value1 = myAnnotation.value1();
        System.out.println(value1[0]);
    }
    //获取方法上的所有注解
    Annotation[] annotations = method.getAnnotations();
    for(Annotation annotation : annotations){
        System.out.println(annotation);
    }
}

8、限定注解的使用：

限定注解使用@Target。

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Target

指示注释类型所适用的程序元素的种类。如果注释类型声明中不存在 Target 元注释，则声明的类型可以用在任一程序元素上。如果存在这样的元注释，则编译器强制实施指定的使用限制。例如，此元注释指示该声明类型是其自身，即元注释类型。它只能用在注释类型声明上：

@Target(ElementType.ANNOTATION_TYPE)
    public @interface MetaAnnotationType {
        ...
    }

此元注释指示该声明类型只可作为复杂注释类型声明中的成员类型使用。它不能直接用于注释：

@Target({}) 
    public @interface MemberType {
        ...
    }

这是一个编译时错误，它表明一个 ElementType 常量在 Target 注释中出现了不只一次。例如，以下元注释是非法的：

@Target({ElementType.FIELD, ElementType.METHOD, ElementType.FIELD})
    public @interface Bogus {
        ...
    }

public enum ElementType
extends Enum<ElementType>

程序元素类型。此枚举类型的常量提供了 Java 程序中声明的元素的简单分类。

这些常量与 Target 元注释类型一起使用，以指定在什么情况下使用注释类型是合法的。

ANNOTATION_TYPE
注释类型声明
CONSTRUCTOR
构造方法声明
FIELD
字段声明（包括枚举常量）
LOCAL_VARIABLE
局部变量声明
METHOD
方法声明
PACKAGE
包声明
PARAMETER
参数声明
TYPE
类、接口（包括注释类型）或枚举声明

注解的使用限定的例子：

@Target(ElementType.METHOD)
public @interface MyAnnotation {

    String[] value1() default "abc";
}

9、在帮助文档中加入注解：

要想在制作JavaDoc文件的同时将注解信息加入到API文件中，可以使用java.lang.annotation.Documented。

在自定义注解中声明构建注解文档：

@Documented
public @interface MyAnnotation {

    String[] value1() default "abc";
}

使用自定义注解：

public class AnnotationTest2 {

    @MyAnnotation(value1={"a","b"})
    public void execute(){
        System.out.println("method");
    }
}

10、在注解中使用继承：

默认情况下注解并不会被继承到子类中，可以在自定义注解时加上java.lang.annotation.Inherited注解声明使用继承。

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Inherited

指示注释类型被自动继承。如果在注释类型声明中存在 Inherited 元注释，并且用户在某一类声明中查询该注释类型，同时该类声明中没有此类型的注释，则将在该类的超类中自动查询该注释类型。此过程会重复进行，直到找到此类型的注释或到达了该类层次结构的顶层 (Object) 为止。如果没有超类具有该类型的注释，则查询将指示当前类没有这样的注释。

注意，如果使用注释类型注释类以外的任何事物，此元注释类型都是无效的。还要注意，此元注释仅促成从超类继承注释；对已实现接口的注释无效。

除了文章中有特别说明，均为IT宅原创文章，转载请以链接形式注明出处。
本文链接： http://www.itzhai.com/java-based-notebook-annotation-annotation-introduction-and-use-custom-annotations.html

Annotation annotation

Guess you like