Java基础注解

前言

📢📢📢本文主要是对这篇博文进行学习:https://www.cnblogs.com/skywang12345/p/3344137.html

一.理解什么是注解

我们常常在类、方法、字段、参数前看见一种以@开头的标记,这种标记叫做注解,是一种特殊带有相应功能的“注释”。

1.注解的框架图

理解注解之前先来看看注解的框架图(下图),从中我们可以看出：

• 1个Annotation接口关联1个RetentionPolicy类,关联1~n个ElementType类
• 1个Annotation接口具有多个实现类(Deprecated, Documented, Inherited, Override,Retention,Target…)

2.注解框架图的关联类

(1) Annotation接口

从下图的Annotation源码中我们可知:

• Annotation是一个接口,位于java.lang.annotation包下
• Annotation接口有4个抽象方法,equals(Object obj), hashCode(),toString(),annotationType()
• Annotation接口关联1个RetentionPolicy类和1~n个ElementType类。

(2) RetentionPolicy类

从下图的RetentionPolicy源码中我们可知:

• RetentionPolicy是一个枚举类型,位于java.lang.annotation包下
• RetentionPolicy有三种类型,SOURCE,CLASS,RUNTIME
• 1个Annotation接口关联1个RetentionPolicy的类型
• RetentionPolicy可理解为给Annotation指定策略/作用域,这三种策略分别SOURCE,CLASS,RUNTIME

这三种类型的解释如下表所示:

(3) ElementType类

从下图的ElementType源码中我们可知:

• ElementType是一个枚举类型,位于java.lang.annotation包下
• ElementType包含10种类型,分别为: TYPE ,FIELD ,METHOD ,PARAMETER ,CONSTRUCTOR ,LOCAL_VARIABLE ,ANNOTATION_TYPE ,PACKAGE, TYPE_PARAMETER, TYPE_USE
• 1个Annotation接口关联1~n个ElementType的类型
• ElementType可理解为指定Annotation的元素类型

这10种类型的解释如下表所示:

3.Annotation的实现类

(1) Annotation定义

理解了上面的3个类的作用之后，我们接下来可以讲解Annotation实现类的语法定义了。

@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation1 {
}

上面的作用是定义一个Annotation，它的名字是MyAnnotation1。定义了MyAnnotation1之后，我们可以在代码中通过“@MyAnnotation1”来使用它。
其它的，@Documented, @Target, @Retention, @interface注解都是来修饰MyAnnotation1的。下面分别说说它们的含义：

1. @interface

使用@interface定义注解时，意味着它实现了java.lang.annotation.Annotation接口，即该注解就是一个Annotation。定义Annotation时，@interface是必须的。注意：它和我们通常的implemented实现接口的方法不同。Annotation接口的实现细节都由编译器完成。通过@interface定义注解后，该注解不能继承其他的注解或接口。

2. @Documented

类和方法的Annotation在缺省情况下是不出现在javadoc中的。如果使用@Documented修饰该Annotation，则表示它可以出现在javadoc中。定义Annotation时，@Documented可有可无；若没有定义，则Annotation不会出现在javadoc中。

3. @Target(ElementType.TYPE)

前面我们说过，ElementType是Annotation的类型属性。而@Target的作用，就是来指定Annotation的类型属性。@Target(ElementType.TYPE)的意思就是指定该Annotation的类型是ElementType.TYPE。这就意味着，MyAnnotation1是来修饰“类、接口（包括注释类型）或枚举声明”的注解。定义Annotation时，@Target可有可无。若有@Target，则该Annotation只能用于它所指定的地方；若没有@Target，则该Annotation可以用于任何地方。

4. @Retention(RetentionPolicy.RUNTIME)

前面我们说过，RetentionPolicy是Annotation的策略属性，而@Retention的作用，就是指定Annotation的策略属性。@Retention(RetentionPolicy.RUNTIME)的意思就是指定该Annotation的策略是RetentionPolicy.RUNTIME。这就意味着，编译器会将该Annotation信息保留在.class文件中，并且能被虚拟机读取。定义Annotation时，@Retention可有可无。若没有@Retention，则默认是RetentionPolicy.CLASS。

备注:修饰其他注解的注解称为元注解。

注解定义的时候常常还定义一些参数,这些参数一般的数据类型如下:

• 所有基本类型；
• String；
• 枚举类型；
• 基本类型、String、Class以及枚举的数组。

定义参数如下:

@Documented
@Target(ElementType.TYPE) //这个注解可以在类,接口和枚举上使用
@Retention(RetentionPolicy.RUNTIME) // 作用域为运行时
@Inherited // 该注解可继承
@interface Inheritable{
    int type() default 0;
    String level() default "info";
    String value() default "";
}

使用的时候就可以给注解相应参数赋值,这里赋的值都是常量,如下:

备注:注解常常都有一个value参数,该参数表示最常用的参数。

(2) Annotation的实现类

java 常用Annotation的实现类如下表所示：

被@Deprecated注解标注表示不在被建议使用,使用的时候会给出相应的提示信息,如下图:

看看该注解的源码:

• @Documented表示该注解能出现在javadoc中。
• @Retention(RetentionPolicy.RUNTIME)表示指定注解的策略为RetentionPolicy.RUNTIME,这就意味着，编译器会将Deprecated的信息保留在.class文件中，并且能被虚拟机读取。
• @Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE,
  PARAMETER, TYPE})指定注解的参数为CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD,
  PACKAGE, PARAMETER, TYPE,表示该注解可以标注构造方法,字段,局部变量,方法,包,参数,类,接口和枚举。

备注:Retention里的参数只有一个,因为前面我们提到RetentionPolicy和Annotation的关联是1对1Target可以有多个这是因为ElementType和Annotation的关联是1~n对1,接下来就不在做任何注解解释了,你可以直接跳转到对应注解的源码,然后通过上面给出的相应表格查询相应说明。

@Override注解表示该方法覆盖父类中的方法:

运行效果( 子类的getId()覆盖了父类的getId() ):

@Inherited注解只能被用来标注“Annotation类型”，它所标注的Annotation具有继承性。

例子:

下面的isAnnotationPresent()方法可以理解为某个注解是否在该类上,AnnotationStudy类继承AnnotationStudySuper类,在AnnotationStudySuper类上有一个自定义的@Inheritable可继承注解,所以它的子类AnnotationStudy也具有@Inheritable注解,。

import java.lang.annotation.*;

public class AnnotationStudy extends AnnotationStudySuper{
    public AnnotationStudy() {
        super();    // 调用父类的构造函数
            // InheritableSon类是否具有 Inheritable Annotation
        System.out.println("InheritableSon:"+AnnotationStudy.class.isAnnotationPresent(Inheritable.class));
    }

    public static void main(String[] args) {
        AnnotationStudySuper superObj = new AnnotationStudy();
        superObj.getId();
    }

    @Deprecated
    private  void deprecatedMthod() {
        System.out.println("@Deprecated所标注内容，不再被建议使用。");
    }

    @Override
    public void getId() {
        System.out.println("【子类】:获取用户的id");
    }

}

@Inheritable
class AnnotationStudySuper{

    public AnnotationStudySuper() {
        // InheritableBase是否具有 Inheritable Annotation
       System.out.println("InheritableFather:"+AnnotationStudySuper.class.isAnnotationPresent(Inheritable.class));
    }

    public void getId() {
        System.out.println("【父类】:获取用户的id");
    }
}


@Target(ElementType.TYPE) //这个注解可以在类,接口和枚举上使用
@Retention(RetentionPolicy.RUNTIME) // 作用域为运行时
@Inherited // 该注解可继承
@interface Inheritable{

}

运行效果:

现在把@Inherited注解注释掉再次运行:

运行效果:

@SuppressWarnings注解所标注内容产生的警告，编译器会对这些警告保持静默。

使用Date date = new Date(113,8,26);时出现黄色警告,如下图所示:

使用@SuppressWarnings注解

警告取消了!

@SuppressWarnings注解的参数如下图所示:

二.注解的作用

Annotation 是一个辅助类，它在Junit、Struts、Spring等工具框架中被广泛使用。我们在编程中经常会使用到的Annotation作用有：

1. 编译检查
2. 在反射中使用Annotation
3. 根据Annotation生成帮助文档
4. 能够帮忙查看查看代码

1.编译检查

Annotation具有“让编译器进行编译检查的作用”。

例如，@SuppressWarnings, @Deprecated和@Override都具有编译检查作用。

2.在反射中使用Annotation

在反射的Class, Method, Field等函数中，有许多关于Annotation相关的接口。这也意味着，我们可以在反射中解析并使用Annotation。

判断某个注解是否存在于Class、Field、Method或Constructor：

• Class.isAnnotationPresent(Class)
• Field.isAnnotationPresent(Class)
• Method.isAnnotationPresent(Class)
• Constructor.isAnnotationPresent(Class)

例如：

// 判断@Inheritable注解是否存在AnnotationStudySuper类中
boolean annotationPresent = AnnotationStudySuper.class.isAnnotationPresent(Inheritable.class);

使用反射API读取Annotation：

• Class.getAnnotation(Class)
• Field.getAnnotation(Class)
• Method.getAnnotation(Class)
• Constructor.getAnnotation(Class)

例如：

// 获取Person定义的@Report注解:
 Inheritable annotation = AnnotationStudySuper.class.getAnnotation(Inheritable.class);

并且还可以直接通过注解获取相应的参数,如下:

  System.out.println(annotation.level());
  System.out.println(annotation.type());
  System.out.println(annotation.value());

完整代码:

import java.lang.annotation.*;

@Inheritable(value = "10",level = "debug",type = 10)
public class AnnotationStudySuper{

    public static void main(String[] args) {
        // 判断@Inheritable注解是否存在AnnotationStudySuper类中
        boolean annotationPresent = AnnotationStudySuper.class.isAnnotationPresent(Inheritable.class);
        if (annotationPresent) {
            Inheritable annotation = AnnotationStudySuper.class.getAnnotation(Inheritable.class);
            System.out.println("@Inheritable注解是否存在AnnotationStudySuper类中:"+(annotationPresent == true?"是":"不是"));
            if (annotation != null) {
                System.out.println(annotation.level());
                System.out.println(annotation.type());
                System.out.println(annotation.value());
            }
        }
    }
    public AnnotationStudySuper() {
        // InheritableBase是否具有 Inheritable Annotation
        System.out.println("InheritableFather:"+AnnotationStudySuper.class.isAnnotationPresent(Inheritable.class));
    }

    public void getId() {
        System.out.println("【父类】:获取用户的id");
    }


}

@Documented
@Target(ElementType.TYPE) //这个注解可以在类,接口和枚举上使用
@Retention(RetentionPolicy.RUNTIME) // 作用域为运行时
@Inherited // 该注解可继承
@interface Inheritable{
    int type() default 0;
    String level() default "info";
    String value() default "";
}

3.根据Annotation生成帮助文档

通过给Annotation注解加上@Documented标签，能使该Annotation标签出现在javadoc中。

给自定义注解加上@Documented标签

生成javadoc文档:

效果: