Annotation【转】

一、Annotation的工做原理：

JDK5.0中提供了注解的功能，容许开发者定义和使用本身的注解类型。该功能由一个定义注解类型的语法和描述一个注解声明的语法，读取注解的API，一个使用注解修饰的class文件和一个注解处理工具组成。

Annotation并不直接影响代码的语义，可是他能够被看作是程序的工具或者类库。它会反过来对正在运行的程序语义有所影响。

Annotation能够冲源文件、class文件或者在运行时经过反射机制多种方式被读取。

二、@Override注解：

java.lang
注释类型 Override
@Target(value=METHOD)
@Retention(value=SOURCE)
public @interface Override

表示一个方法声明打算重写超类中的另外一个方法声明。若是方法利用此注释类型进行注解但没有重写超类方法，则编译器会生成一条错误消息。

@Override注解表示子类要重写父类的对应方法。

Override是一个Marker annotation，用于标识的Annotation，Annotation名称自己表示了要给工具程序的信息。

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

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

三、@Deprecated注解：

java.lang
注释类型 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();
    }
}

四、@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");
}

五、自定义注解：

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

自定义最简单的注解：

public @interface MyAnnotation {

}

使用自定义注解：

public class AnnotationTest2 {

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

5.一、添加变量：

public @interface MyAnnotation {

    String value1();
}

使用自定义注解：

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

  
  
  
  
public class AnnotationTest2 {

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

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

5.二、添加默认值：

public @interface MyAnnotation {

    String value1() default "abc";
}

5.三、多变量使用枚举：

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.四、数组变量：

public @interface MyAnnotation {

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

使用自定义注解：

public class AnnotationTest2 {

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

六、设置注解的做用范围：

@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.一、在自定义注解中的使用例子：

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

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

七、使用反射读取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);
    }
}

八、限定注解的使用：

限定注解使用@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";
}

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

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

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

@Documented
public @interface MyAnnotation {

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

使用自定义注解：

@Documented
public @interface MyAnnotation {

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

十、在注解中使用继承：

默认状况下注解并不会被继承到子类中，能够在自定义注解时加上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, Java, 注解