文章目录

  • 3.6 Java注释
  • 3.6.1 Annotation 的定义
  • 3.6.2 基本Annotation
  • 1、@Override
  • 2、@Deprecated
  • 3、@SuppressWarning
  • 4、@SafeVarargs
  • 3.6.3 Annotation的用途
  • 1.生成文档
  • 2.检查格式
  • 3.替代配置文件
  • 3.6.4 Java文档生成器


3.6 Java注释

Java注释( Annotation)是JDK 5后增加的特性，现在越来越流行并且广为使用，通过在代码中不改变原有逻辑的前提下，增加一些特殊的标记(即Annotation)来实现，这些标记可以在编译、类加载.运行时通过Java反射机制获取，然后把标记提供的信息自动注射到程序中，程序做出相应的处理。这样，可使代码运行中动态地完成系统的一-些处理工作，从而省去之前诸多的配置和冗余代码。

3.6.1 Annotation 的定义

  • Annotation分为Java系统默认提供和程序员自定义的两类。自定义新的Annotation类型使用@interface关键字来实现, Annotation的定义方式与接口的定义方式类似，格式如下:
public @interface Test{}
  • 然后就可以在程序中使用该Annotation了，Annotation 使用时如同public、 final 等语法限定符一一样，用于修饰包、类型、构造方法、成员方法、数据成员、参数等，JDK8又扩展了注释的范围，几乎可以为任何程序元素添加注释:局部变量、接口及其实现类，甚
    至是方法中抛出的异常。使用时采用@+Annotation的类型名称就可以直接使用，通常把Annotation 另放一行，并放在所有修饰符之前。例如:
@test
public class MyAnnotation{
}

Annotation定义中可以定义成员变量，成员变量采用无参的方法形式来声明，例如：

public class Test{
    @MyAnnotation(name="Tom",age = 20)
    public void func(){
    }
}
  • 当Annotation修饰了类、方法等程序元素后，Annotation 并不会自己生效，必须由程序员提供相应的代码提取并处理信息。Java 提供了两个类java.lang.annotation和java.lang.reflect 配合使用来完成Annotation的提取，为了获取注释信息，必须采用反射机制。
  • 其中java.lang.annotation类中的java.lang.annotation.Annotation接口提供的主要方法annotationType()，用于返回该注释的java.lang.Class。
  • java.lang.reflect 类的java.lang.reflect.AnnotatedElement接口提供了三个主要方法:
  • isAnnotationPresent() :判断该程序元素上是否存在指定类型的注释,如果存在，则返回true,否则返回false。
  • getAnnotation(): 返回该程序元素上存在的指定类型的注释,如果该注释不存在，则返回null。
  • Annotation[] getAnnotations():返回该程序元素上存在的所有注释。
    名
  • 在信息提取过程中，程序通过反射机制获取某个类的AnnotatedElement对象，然后调用该对象的isAnnotationPresent( )、getAnnotation( )等方法来访问注释信息。

3.6.2 基本Annotation

Annotation的类型由JDK默认提供，JDK默认提供的Annotation如下：

1、@Override

  • 作用于子类中的方法，检验被@Override修饰的子类方法，如果不存在对应的被重写的父类方法，则报错，举例如下：
public class AnnotationOverrideTest{
    @Override
    public String toString(){
        ......
    }
}

这里的@Override让编译器检查toString()方法是否覆盖了基类的方法

2、@Deprecated

  • 用于表示某个类或者方法等已经被弃用，如果使用被@Deprecated修饰的类或者方法等，编译器会发出警告，该方法名称上会被画上一条横线

3、@SuppressWarning

  • 抑制编译器警告。表示被@SuppressWarning修饰的类以及该类中的方法取消显示指定的编译器警告。常见的为@SuppressWarning(value = "unchecked")

4、@SafeVarargs

  • 这是JDK7专门为抑制“堆污染”警告提供的

3.6.3 Annotation的用途

Annotation在Java中主要用于以下几个方面:

1.生成文档

通过@Documented来标注是否需要在Javadoc中出现，@Documented会被Javadoc具提取生成文档，这是最常见也是Java最早提供的注释，常用的还有@see、@param、@author 等。

2.检查格式

使编译器提供更多的代码错误检验，如@Override、@SuppressWarning 等。

3.替代配置文件

  • 采用注释方式取代配置文件的目的是减少配置文件的数量，在J2EE应用程序中，各种架构如SSH (Spring+Struts+Hibernate)大都采用这种配置。
  • 编程中自己定义Annotation的情形并不多，通常Annotation用在项目设计、J2EE 应用程序及架构中，不希望程序中有过多的配置文件时。例如，若在J2EE的Servlet中采用资源注释@resource的方式，不需要Servlet程序主动读取资源，Tomcat 启动时会把web.xml配置的信息主动注射到servlet中。但是也需要注意过多地使用Annotation会导致代码的可读性差。

3.6.4 Java文档生成器

  • Javadoc是用于提取注释的工具，能从Java源文件中读取格式为/**...**/的注释，并能识别注释中用@标识的一些特殊变量，产生HTML格式的类说明文档。Javadoc 不但能对一个Java源文件生成注释文档，而且能对目录和包生成交叉链接的HTML格式的类说明文
    档，十分方便。
  • Javadoc可以为类、接口、方法、变量添加注释，但只能为public 和protected成员进行文档注释，private 及包内访问权限成员的注释会被忽略，生成的文档为HTML文件，可通过浏览器查看。
  • Javadoc的每个注释由Javadoc标签和描述性文本组成。描述性文本不但可以用普通文本，还可以使用HTML文本。Javadoc标签一般以@为前缀，有的也以{@为前缀，以}结束，如{@value }。
    例如:
/**
 * @author yjq
 * @version 1.0
 * @date 2021/8/11 22:17
 */
  • Javadoc 常用标签及说明如表3-9所示。