注释 向 Java 代码中添加元数据

注释，J2SE 5.0 (Tiger) 中的新功能，将非常需要的元数据工具引入核心 Java 语言。该系列文章分为两部分，在这第 1 部分中，作者 Brett McLaughlin 解释了元数据如此有用的原因，向您介绍了 Java 语言中的注释，并研究了 Tiger 的内置注释。

编程的一个最新的趋势，尤其是在 Java 编程方面，是使用 元数据 。简单地说，元数据就是 关于 数据的数据。元数据可以用于创建文档，跟踪代码中的依赖性，甚至执行基本编译时检查。许多元数据工具，如 XDoclet（请参阅 参考资料 ），将这些功能添加到核心 Java 语言中，暂时成为 Java 编程功能的一部分。

直到可以使用 J2SE 5.0（也叫做 Tiger，现在是第二个 beta 版本），核心 Java 语言才最接近具有 Javadoc 方法的元数据工具。您使用特殊的标签集合来标记代码，并执行 javadoc 命令来将这些标签转化成格式化的 HTML 页面，该页面说明标签所附加到的类。然而，Javadoc 是有缺陷的元数据工具，因为除了生成文档之外，您没有固定、实用、标准化的方式来将数据用于其他用途。HTML 代码经常混入到 Javadoc 输出中这一事实甚至更进一步降低了其用于任何其他目的的价值。

Tiger 通过名为 注释 的新功能将一个更通用的元数据工 具合并到核心 Java 语言中。注释是可以添加到代码中的修饰符，可以用于包声明、类型声明、构造函数、方法、字段、参数和变量。Tiger 包含内置注释，还支持您自己编写的定制注释。本文将概述元数据的优点并向您介绍 Tiger 的内置注释。本系列文章的 第 2 部分 将研究定制注释。我要感谢 O'Reilly Media, Inc.，他们非常慷慨地 允许我在本文中使用我关于 Tiger 的书籍的“注释”一章中的代码示例（请参阅 参考资料 ）。

元数据的价值

不要漏掉本系列的另一部分 一定要阅读本系列的“ 第 2 部分 ”，该部分研究了定制注释。

编译器检查

JSR 175 JSR 175， Java 编程语言的元数据工具 ，为将元数据合并到核心 Java 语言中提供了正式理由和说明（请参阅 参考资料 ）。根据 JSR，注释“不直接影响程序的语义。然而，开发和部署工具可以读取这些注释，并以某种形式处理这些注释，可能生成其他 Java 编程语言源文件、XML 文档或要与包含注释的程序一起使用的其他构件。”

代码分析

在 更复杂的情况下，代码分析工具可以执行所有种类的额外任务。示例 du jour 是 Enterprise JavaBean (EJB) 组件。甚至简单 EJB 系统中的依赖性和复杂性都非常令人吃惊。您具有了 home 接口和远程接口，以及本地接口和本地 home 接口，还有一个实现类。保持所有这些类同步非常困难。但是，元数据可以提供这个问题的解决放案。好的工具（还是要提一下 XDoclet）可以管理所有这些依赖性，并确保无“代码级”连接、但有“逻辑级”捆绑的类保持同步。元数据在这里确实可以发挥它的作用。

回页首

注释的基本知识

注释或注释类型？ 是否对什么是注释与什么是注释类型感到迷惑？了解这个的最简单方法就是对比所熟悉的 Java 语言概念来想。可以定义一个类（例如 Person ），则在 JVM 中将总是仅有该类的一个版本（假设没有进行麻烦的类路径设置）。然而，在任何给定时间，可能会使用该类的 10 个或 20 个 实例 。仍然是只有一个 Person 类，但是它以不同的方式使用多次。注释类型和注释也是这样。注释类型类似于类，注释类似于该类的实例。

注释分为三个基本种类：

• 标记注释 没有变量。注释显示简单，由名称标识，没有提供其他数据。例如， @MarkerAnnotation 是标记注释。它不包含数据，仅有注释名称。
  
  
• 单一值注释 与标记注释类似，但提供一段数据。因为仅提供很少的一点数据，所以可以使用快捷语法（假设注释类型接受此语法）： @SingleValueAnnotation("my data") 。除了 @ 标记外，这应该与普通的 Java 方法调用很像。
  
  
• 完整注释 有多个数据成员。因此，必须使用更完整的语法（注释不再像普通的 Java 方法）： @FullAnnotation(var1="data value 1", var2="data value 2", var3="data value 3") 。

除了通过默认语法向注释提供值外，还可以在需要传送多个值时使用名称-值对。还可以通过花括号为注释变量提供值数组。清单 1 显示了注释中的值数组的示例。

            @TODOItems({    // Curly braces indicate an array of values is being supplied
            

              @TODO(
            

                severity=TODO.CRITICAL,
            

                item="Add functionality to calculate the mean of the student's grades",
            

                assignedTo="Brett McLaughlin"
            

              ),
            

              @TODO(
            

                severity=TODO.IMPOTANT,
            

                item="Print usage message to screen if no command-line flags specified",
            

                assignedTo="Brett McLaughlin"
            

              ),
            

              @TODO(
            

                severity=TODO.LOW,
            

                item="Roll a new website page with this class's new features",
            

                assignedTo="Jason Hunter"
            

              )
            

            })
            

          

清单 1 中的示例并没有乍一看那样复杂。 TODOItems 注释类型有一个具有值的变量。这里提供的值比较复杂，但 TODOItems 的使用实际与单一值注释类型相符，只是这里的单一值是数组而已。该数组包含三个 TODO 注释，其中每个注释都是多值的。逗号分隔每个注释内的值，以及单个数组内的值。非常容易，是吧？

但是我讲的可能超前了些。 TODOItems 和 TODO 是 定制注释 ， 是本系列文章第 2 部分中的主题。但是我想让您看到，即使复杂注释（清单 1 几乎是最复杂的注释）也不是非常令人害怕的。当提到 Java 语言的标准注释类型时，将很少看到如此复杂的情况。正如将在下面三个部分了解到的，Tiger 的基本注释类型的使用都极其简单。

回页首

Override 注释

            package com.oreilly.tiger.ch06;
            

            public class OverrideTester {
            

              public OverrideTester() { }
            

              @Override
            

              public String toString() {
            

                return super.toString() + " [Override Tester Implementation]";
            

              }
            

              @Override
            

              public int hashCode() {
            

                return toString().hashCode();
            

              }
            

            }
            

          

清单 2 应该很容易理解。 @Override 注释对两个方法进行了注释 — toString() 和 hashCode() ，来指明它们覆盖 OverrideTester 类的超类 ( java.lang.Object ) 中的方法的版本。开始这可能看起来没什么作用，但它实际上是非常好的功能。如果不覆盖这些方法，根本 无法 编译此类。该注释还确保当您将 toString() 弄乱时，至少还有某种指示，即应该确保 hashCode() 仍旧匹配。

当编码到很晚且输错了某些东西时，此注释类型真的可以发挥很大的作用，如清单 3 中所示。

            package com.oreilly.tiger.ch06;
            

            public class OverrideTester {
            

              public OverrideTester() { }
            

              @Override
            

              public String toString() {
            

                return super.toString() + " [Override Tester Implementation]";
            

              }
            

              @Override
            

            public int hasCode() {
            

                return toString().hashCode();
            

              }
            

            }
            

          

在清单 3 中， hashCode() 错误地输入为 hasCode() 。注释指明 hasCode() 应该覆盖方法。但是在编译中， javac 将发现超类 ( java.lang.Object ) 没有名为 hasCode() 的方法可以覆盖。因此，编译器将报错，如图 1 中所示。

图 1. 来自 Override 注释的编译器警告

缺少的功能 在单一值注释类型中，如果 Deprecated 允许包含错误类型消息将更好。然后，当用户使用声明为过时的方法时，编译器可以打印消息。该消息可以指明使用方法的结果如何重要，说明何时将停止方法，甚至建议备用方法。可能 J2SE 的下一版本（“Mustang”，他们这样命名）将提供这种功能。

这个便捷的小功能将帮助快速捕获打字稿。

回页首

Deprecated 注释

            package com.oreilly.tiger.ch06;
            

            public class DeprecatedClass {
            

              @Deprecated public void doSomething() {
            

                // some code
            

              }
            

              public void doSomethingElse() {
            

                // This method presumably does what doSomething() does, but better
            

              }
            

            }
            

          

单独编译此类时，不会发生任何不同。但是如果通过覆盖或调用来使用声明为过时的方法，编译器将处理注释，发现不应该使用该方法，并发出错误消息，如图 2 中所示。

图 2. 来自 Deprecated 注释的编译器警告

注意需要开启编译器警告，就像是必须向 Java 编译器指明想要普通的声明为过时警告。可以使用下列两个标记之一和 javac 命令： -deprecated 或新的 -Xlint:deprecated 标记。

回页首

SuppressWarnings 注释

SupressWarnings 可以解决这个问题。 SupressWarnings 与 Override 和 Deprecated 不同， 是 具有变量的 — 所以您将单一注释类型与该变量一起使用。可以以值数组来提供变量，其中每个值指明要阻止的一种特定警告类型。请看清单 5 中的示例，这是 Tiger 中通常会产生错误的一些代码。

            public void nonGenericsMethod() {
            

              List wordList = new ArrayList();    // no typing information on the List
            

              wordList.add("foo");                // causes error on list addition
            

            }
            

          

图 3 显示了清单 5 中代码的编译结果。

图 3. 来自非标准代码的编译器警告

清单 6 通过使用 SuppressWarnings 注释消除了这种问题。

            @SuppressWarings(value={"unchecked"})
            

            public void nonGenericsMethod() {
            

              List wordList = new ArrayList();    // no typing information on the List
            

              wordList.add("foo");                // causes error on list addition
            

            }
            

          

非常简单，是吧？仅需要找到警告类型（图 3 中显示为“unchecked”），并将其传送到 SuppressWarnings 中。

SuppressWarnings 中变量的值采用数组，使您可以在同一注释中阻止多个警告。例如， @SuppressWarnings(value={"unchecked", "fallthrough"}) 使用两个值的数组。此功能为处理错误提供了非常灵活的方法，无需进行大量的工作。

注释 向 Java 代码中添加元数据