Java Annotation(1)

 

作者：曾巧（numenzq）

 

摘要

Annotation(注释)是J2SE 5.0引入的新功能，它被定义为JSR-175规范。简单地说，它可以用于创建文档，跟踪代码中的依赖性，甚至执行基本编译时检查。本文只会介绍注释的基本概念，以及Java内置注释的使用方法；关于定制注释及其他高级主题将在下一篇文章中讲解。

 

正文

编程的一个最新的趋势，尤其是在Java编程方面，就是使用元数据。直到JSR-175 提案的通过，并在J2SE 5.0上实现，你才有了使用注释的机会，在不断的发展和演进中，基于JSR-181的元数据批注标准，能让我们更轻松的开发和部署Web Service了，不需要被大量的配置文件所烦恼，说得有点远了，转回整体，元数据是可以添加到代码中的修饰符，它可以用于包声明、类型声明、构造函数、方法、字段、参数和变量。J2SE包含内置注释，还支持你自己编写的定制注释。

 

内容

l         注释基本知识

l         元数据的作用

l         基本内置注释

l         概要

 

注释基础知识

    在J2SE 5.0中，注释是以‘@注释名’在代码中存在的，例如：J2SE 5.0内置的注释：@Override、@Deprecated；有的注释还可以添加一些参数值，例如：@SuppressWarnings(value="unchecked")；对于这种只有一个参数，且参数名为value的注释，我们在使用时可以简写为：@SuppressWarnings("unchecked")。

    根据注释参数的个数，我们可以将注释分为：标记注释、单值注释、完整注释三类。它们都不会直接影响到程序的语义，只是作为注释（标识）存在，我们可以通过反射机制编程实现对这些元数据的访问。另外，你可以在编译时选择代码里的注释是否只存在于源代码级，或者它也能在class文件中出现。

 

元数据的作用

如果要对于元数据的作用进行分类，目前还没有明确的定义，不过我们可以根据它所起的作用，大致可分为三类：

l         编写文档：通过代码里标识的元数据生成文档。

l         代码分析：通过代码里标识的元数据对代码进行分析。

l         编译检查：通过代码里标识的元数据让编译器能实现基本的编译检查。

 

基本内置注释

    @Override注释能实现编译时检查，你可以为你的方法添加该注释，以声明该方法是用于覆盖父类中的方法。如果该方法不是覆盖父类的方法，将会在编译时报错。例如我们为某类重写toString()方法却写成了tostring()，并且我们为该方法添加了@Override注释；代码如下：

package com.gelc.annotation.demo.basic;

 

public class OverrideDemo {

 

    // @Override

    public String tostring() {

 

        return super.toString();

    }

}

在编译时，则会提示以下错误信息：

OverrideTest.java:5: 方法未覆盖其父类的方法

        @Override

         ^

1 错误

    就像示例演示的那样，该注释一大好处就是可以在编译时帮我们捕获部分编译错误，但又有多少编程人员愿意为每个覆盖父类的方法添加该注释呢？这个只有靠编程人员自己进行取舍了。

 

    @Deprecated的作用是对不应该在使用的方法添加注释，当编程人员使用这些方法时，将会在编译时显示提示信息，它与javadoc里的@deprecated标记有相同的功能，准确的说，它还不如javadoc @deprecated，因为它不支持参数，使用@Deprecated的示例代码示例如下：

package com.gelc.annotation.demo.basic;

 

public class DeprecatedDemo {

 

    public static void main(String[] args) {

 

        // DeprecatedClass.DeprecatedMethod();

    }

}

 

class DeprecatedClass {

 

    @Deprecated

    public static void DeprecatedMethod() {

        // TODO

    }

}

    编译时，会得到以下提示：

注意：DeprecatedDemo.java 使用或覆盖了已过时的 API。

注意：要了解详细信息，请使用 -Xlint:deprecation 重新编译。

    如果在编译时添加-Xlint:deprecation参数，我们能更清楚的看到该警告的详细信息，如下：

DeprecatedDemo.java:6: 警告：[deprecation] SomeClass 中的 DeprecatedMethod() 已

过时

                SomeClass.DeprecatedMethod();

                         ^

1 警告

    通过上面的示例，你已经掌握到了如何使用@Deprecated，但你理解到@Deprecated与@deprecated的区别了吗？你可以简单的理解为：@Deprecated是为了编译时检查，而@deprecated是为了生成文档的需要，各尽其责。

 

    @SuppressWarnings与前两个注释有所不同，你需要添加一个参数才能正确使用，这些参数值都是已经定义好了的，我们选择性的使用就好了，参数如下：

参数	语义
deprecation	使用了过时的类或方法时的警告
unchecked	执行了未检查的转换时的警告，例如当使用集合时没有用泛型 (Generics) 来指定集合保存的类型
fallthrough	当 Switch 程序块直接通往下一种情况而没有 Break 时的警告
path	在类路径、源文件路径等中有不存在的路径时的警告
serial	当在可序列化的类上缺少 serialVersionUID 定义时的警告
finally	任何 finally 子句不能正常完成时的警告
all	关于以上所有情况的警告

    通过上面的表格，你应该了解到每个参数的用意了，下面我就以一个常用的参数unchecked为例，为你展示如何使用@SuppressWarnings注释，示例代码如下：

package com.gelc.annotation.demo.basic;

 

import java.util.List;

import java.util.ArrayList;

 

public class SuppressWarningsDemo {

 

    public static List cache = new ArrayList();

 

    // @SuppressWarnings(value = "unchecked")

    public void add(String data) {

 

        cache.add(data);

    }

}

    当我们不使用@SuppressWarnings注释时，编译器就会有如下提示：

注意：SuppressWarningsDemo.java 使用了未经检查或不安全的操作。

注意：要了解详细信息，请使用 -Xlint:unchecked 重新编译。

相信你对这个提示相当熟悉了，我就不在这里多说了。下面我们还是来试试使用了@SuppressWarnings(value="unchecked")注释会是什么效果，它会屏蔽编译时的警告信息，这也就是它所要达到的目的。另外，由于@SuppressWarnings注释只有一个参数，并且参数名为value，所以我们可以将上面一句注释简写为@SuppressWarnings("unchecked")。

 

概要

在J2SE 5.0出现三个多年头后的今天，再回头看看它当时引入的这一新特性，虽然它已不是什么新概念了，还是值得我们再次回味的，下面文章中将介绍编程人员如何定制注释。