Tiger 中的注释，第 2 部分: 定制注释

文档选项 将此页作为电子邮件发送 最新推荐 Java 应用开发源动力 － 下载免费软件，快速启动开发 级别: 初级 Brett McLaughlin, 作者/编者, O‘Reilly Media, Inc 2004 年 9 月 01 日 本系列文章的 第 1 部分介绍了注释 —— J2SE 5.0 中新的元数据工具，并重点讨论了 Tiger 的基本内置注释。一个更强大的相关特性是支持编写自己的注释。本文中，Brett McLauglin 说明了如何创建定制注释，如何用自己的注释注解文档，并进一步定制代码。 本系列的第一篇文章 介绍了什么是元数据，元数据的重要性，以及如何使用 J2SE 5.0（也叫做 Tiger）的基本内置注释。如果习惯了这些概念，您可能已经在想，Java 5 提供的三种标准注释也并不是特别健壮，能使用的只有 Deprecated 、 SuppressWarnings 和 Override 而已。所幸的是，Tiger 还允许定义自己的注释类型。在本文中，我将通过一些示例引导您掌握这个相对简单的过程。您还将了解如何对自己的注释进行注解，以及这样做的一些好处。我要感谢 O‘Reilly Media, Inc.，他们非常慷慨地允许我在本文中使用我关于 Tiger 的书籍的“注释”一章中的代码示例（请参阅 参考资料）。 定义自己的注释类型 通过添加了一个小小的语法（Tiger 添加了大量的语法结构），Java 语言支持一种新的类型 —— 注释类型（annotation type）。注释类型看起来很像普通的类，但是有一些特有的性质。最明显的一点是，可以在类中以符号（ @ ）的形式注释其他 Java 代码。我将一步一步地介绍这个过程。 @interface 声明 定义新的注释类型与创建接口有很多类似之处，只不过 interface 关键字之前要有一个 @ 符号。清单 1 中给出的是一个最简单的注释类型的示例： 清单 1. 非常简单的注释类型 package com.oreilly.tiger.ch06; /** * Marker annotation to indicate that a method or class * is still in progress. */ public @interface InProgress { } 清单 1 的含义非常明显。如果编译这个注释类型，并确信其位于类路径中，那么您就可以在自己的源代码方法中使用它，以指出某个方法或类仍在处理中，如清单 2 所示： 清单 2. 使用定制的注释类型 @com.oreilly.tiger.ch06.InProgress public void calculateInterest(float amount, float rate) { // Need to finish this method later } 清单 1 所示注释类型的使用方法和内置注释类型的使用方法完全相同，只不过要同时使用名称和所在的包来指示定制注释。当然，一般的 Java 规则仍然适用，您可以导入该注释类型，直接使用 @InProgress 引用它。 不要漏掉本系列的另一部分 一定要阅读本系列文章的“ 第 1 部分”，其中介绍了 Java 5.0 中的注释。 添加成员 上面所示的基本用法还远远不够健壮。您一定还记得“第 1 部分”中曾经提到的，注释类型可以有成员变量（请参阅 参考资料）。这一点非常有用，尤其是准备将注释作为更加复杂的元数据，而不仅仅将它作为原始文档使用的时候。代码分析工具喜欢加工大量的信息，定制注释可以提供这类信息。 注释类型中的数据成员被设置成使用有限的信息进行工作。定义数据成员后不需要分别定义访问和修改的方法。相反，只需要定义一个方法，以成员的名称命名它。数据类型应该是该方法返回值的类型。清单 3 是一个具体的示例，它澄清了一些比较含糊的要求： 清单 3. 向注释类型添加成员 package com.oreilly.tiger.ch06; /** * Annotation type to indicate a task still needs to be * completed. */ public @interface TODO { String value(); } 尽管清单 3 看起来很奇怪，但这是注释类型所要求的格式。清单 3 定义了一个名为 value 的字符串，该注释类型能够接受它。然后，就可以像清单 4 中那样使用注释类型： 清单 4. 使用带有成员值的注释类型 @com.oreilly.tiger.ch06.InProgress @TODO("Figure out the amount of interest per month") public void calculateInterest(float amount, float rate) { // Need to finish this method later } 这里同样没有多少花样。清单 4 假设已经引入了 com.oreilly.tiger.ch06.TODO ，因此源代码中的注释 不 需要包名作前缀。此外，需要注意的是，清单 4 中采用了简写的方法：将值 （"Figure out the amount of interest per month"） 直接提供给注释，没有指定成员变量名。清单 4 和清单 5 是等价的，后者没有采用简写形式： 清单 5. 清单 4 的“加长”版 @com.oreilly.tiger.ch06.InProgress @TODO(value="Figure out the amount of interest per month") public void calculateInterest(float amount, float rate) { // Need to finish this method later } 当然作为编码人员，我们都不愿意跟这种“加长”版搅在一起。不过要注意，只有当注释类型只有 一个 成员变量，而且变量名为 value 时，才能使用简写形式。如果不符合这个条件，那么就无法利用这种特性。 设置默认值 迄今为止，您已经有了一个很好的起点，但是要做得完美，还有很长的一段路要走。您可能已经想到，下一步就要为注释设置某个默认值。如果您希望用户指定某些值，但是只有这些值与默认值不同的时候才需要指定其他的值，那么设置默认值就是一种很好的办法。清单 6 用另一个定制注释 —— 来自 清单 4 的 TODO 注释类型的一个全功能版本，示范了这个概念及其实现： 清单 6. 带有默认值的注释类型 package com.oreilly.tiger.ch06; public @interface GroupTODO { public enum Severity { CRITICAL, IMPORTANT, TRIVIAL, DOCUMENTATION }; Severity severity() default Severity.IMPORTANT; String item(); String assignedTo(); String dateAssigned(); } 清单 6 中的 GroupTODO 注释类型中添加了几个新的变量。因为该注释类型的成员变量不是一个，所以将一个变量命名为 value 没有任何意义。只要成员变量多于一个，就应该尽可能准确地为其命名。因为不可能从 清单 5所示的简写形式中获益，所以您需要创建虽然稍微有点冗长，但是更容易理解的注释类型。 清单 6 中出现的另一个新特性是注释类型定义了自己的枚举（枚举，即 enumeration，通常也称为 enums，是 Java 5 的另一个新特性。它并没有多么地不同凡响，对注释类型更是如此）。然后，清单 6 使用新定义的枚举作为一个成员变量的类型。 最后，再回到我们的主题 —— 默认值。建立默认值的过程非常琐碎，需要在成员声明的后面添加关键字 default ，然后提供默认值。正如您所料，默认值的类型必须与成员变量声明的类型完全相同。同样，这也不是什么火箭科学，只不过是词法上的变异。清单 7 给出了一个具体应用中的 GroupTODO 注释，其中 没有 指定 severity 成员： 清单 7. 使用默认值 @com.oreilly.tiger.ch06.InProgress @GroupTODO( item="Figure out the amount of interest per month", assignedTo="Brett McLaughlin", dateAssigned="08/04/2004" ) public void calculateInterest(float amount, float rate) { // Need to finish this method later } 清单 8 中使用了同一个注释，但这一次给出了 severity 的值： 清单 8. 改写默认值 @com.oreilly.tiger.ch06.InProgress @GroupTODO( severity=GroupTODO.Severity.DOCUMENTATION, item="Need to explain how this rather unusual method works", assignedTo="Jon Stevens", dateAssigned="07/30/2004" ) public void reallyConfusingMethod(int codePoint) { // Really weird code implementation } 回页首 对注释的注释 结束关于注释的讨论之前（至少在本系列文章中），我想简要地讨论一下注释的注释。第 1 部分中所接触的预定义注释类型都有预定义的目的。但是在编写自己的注释类型时，注释类型的目的并不总是显而易见的。除了基本的文档外，可能还要针对某个特定的成员类型或者一组成员类型编写类型。这就要求您为注释类型提供某种元数据，以便编译器保证按照预期的目的使用注释。 当然，首先想到的就是 Java 语言选择的元数据形式 —— 注释。您可以使用 4 种预定义的注释类型（称为 元注释）对您的注释进行注释。我将对这 4 种类型分别进行介绍。 指定目标 最明显的元注释就是允许何种程序元素具有定义的注释类型。毫不奇怪，这种元注释被称为 Target 。但是在了解如何使用 Target 之前，您还需要认识另一个类，该类被称为 ElementType ，它实际上是一个枚举。这个枚举定义了注释类型可应用的不同程序元素。清单 9 给出了完整的 ElementType 枚举： 清单 9. ElementType 枚举 package java.lang.annotation; public enum ElementType { TYPE, // Class, interface, or enum (but not annotation) FIELD, // Field (including enumerated values) METHOD, // Method (does not include constructors) PARAMETER, // Method parameter CONSTRUCTOR, // Constructor LOCAL_VARIABLE, // Local variable or catch clause ANNOTATION_TYPE, // Annotation Types (meta-annotations) PACKAGE // Java package } 清单 9 中的枚举值意义很明确，您自己可以分析其应用的目标（通过后面的注解）。使用 Target 元注释时，至少要提供这些枚举值中的一个并指出注释的注释可以应用的程序元素。清单 10 说明了 Target 的用法： 清单 10. 使用 Target 元注释 package com.oreilly.tiger.ch06; import java.lang.annotation.ElementType; import java.lang.annotation.Target; /** * Annotation type to indicate a task still needs to be completed */ @Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.ANNOTATION_TYPE}) public @interface TODO { String value(); } 现在，Java 编译器将把 TODO 应用于类型、方法、构造函数和其他注释类型。这样有助于避免他人误用您的注释类型（或者最好的地方是， 您自己也不会因为疲惫而误用它）。 设置保持性