Web开发教程2－Java Annotation

本篇文章我们要学习另一个非常重要的预备知识：Java Annotation。Java Annotation是Sun公司自JDK 1.5版本以来推出的一个新的语言特性，中文可以将其翻译成Java标记。什么是标记特性呢？如果您使用Java编写过一些程序，那么您可能已经接触过这一特性了。比如JavaDoc语法中使用的@return，@param这些就是Java标记。又比如说，大家经常用到的用来抑制Java编译器警告信息的@SuppressWarning标记，以及标识某方法或某类过期的@Deprecated标记。从Java 1.5版本开始，用户可以自已制作各种标记。

使用标记的好处是什么呢？最大的好处就是这一特性使得代码之间的耦合度变得非常之低。那么Annotation到底如何制作，如何使用？下面我们来亲自动手做一个自己的Annotation来玩玩看。
实例

我们来做一个图书数据管理的项目。在这个项目中，有图书类Book，每一本书都有自己的书名bookname。除书名外，图书还有附加的版权信息Copyright，但是出于设计角度考虑，版权这个属性由出版社定义，它与书本身的关系不大，因此不想做成Book的一个属性信息。因此把Copyright独立设计成一个类，然后嵌入到Book类中去。如果使用传统的方法，那么Copyright类将成为Book的一个私有成员：
1 public class Book {
2 ...
3 private Copyright copyright;
4 ...
5 }

但是在这里，我们将使用另外一种实现方法，使用新的Annotation特性，让Copyright成为Book的一个标记。首先要做的工作便是制作Copyright这个标记类：
01 import java.lang.annotation.ElementType;
02 import java.lang.annotation.Retention;
03 import java.lang.annotation.RetentionPolicy;
04 import java.lang.annotation.Target;
05
06 @Target(ElementType.TYPE)
07 @Retention(RetentionPolicy.RUNTIME)
08 public @interface Copyright {
09 String value();
10 }

这里面有很多未接触过的语法。我们来仔细看一下：首先，定义Annotation类有点类似于定义Java接口类interface，但和一般的接口类比起来，interface前面多了一个@。这样就声明了Copyright是一个Annotation类。另外，String value()这个写法是@interface中一个比较独特的地方。它实际上定义的不并是标记类的一个方法，而是标记类的一个属性。您随后就会看到，在Book类别中，我们是如何使用这个属性的：
1 @Copyright(value = "All Rights Resvered")
2 public class Book
3 ...

除了声明比较奇怪，还有两行比较陌生的代码：@Target及@Retention，这两个本身就是Java提供的标记，它们定义了我们的标记类Copyright的一些属性。下面进行详细说明。

@Target指定此标记的作用域。一共有四种类型：

TYPE－说明此标记可以用在Class、Interface、Enum、Annotation之上
FIELD－可用于类的属性之上
METHOD－用于函数
PARAMETER－用于函数的参数
CONSTRUCTOR－用于构造方法
PACKAGE－用于包

什么叫做作用域呢？很简单，就是指这个标记类可以用来给代码的什么类型的元素来使用。拿@Deprecated这个比较常用的Java固有标记来举例，我们既可以把一个类标记为过期：
1 @Deprecated
2 public class SomeClazz {...}

也可以把一个函数标记为已过期：
1 public class SomeClazz {
2
3 @Deprecated
4 public void someMethod();
5 ...
6 }

还可以把参数、属性，构造方法等所有的元素标记为@Deprecated。因此，我们说@Deprecated这个标记作用域是TYPE+FIELD+METHOD+PARAMETER+CONSTRUCTOR+PACKAGE，即全域有效。对于我们自己制作的这个Copyright来讲，它的作用域就小很多了。因为我们仅希望Copyright能够给Book作标记，而Book是一个类，因此我们指定Copyright的作用域是TYPE。这样，当我们制作的@Copyright被用到TYPE以外的地方时，编译器就会报错。

另一个@Retention标记，它的作用是指定我们所制作的标记的生命周期。

SOURCE－代表此标记的仅在代码编译前存活。比如@Deprecated，仅在编译前提供一些提示信息。在编译时，这些标记并不会编译到class文件中。
CLASS－与CLASS不同，这类标记会编译到class文件中，但不会成为程序的一部分，也不可以通过代码在运行时调用到。
RUNTIME－这类标记将成为代码的一部分，并会在实际运行时起到作用。Copyright标记就是RUNTIME类型的。

有些标记不参与代码逻辑，仅仅是给编程序的人提供一个输写便笺的地方，或者控制编译器的一些行为，如抑制编译器警告输出的@SuppressWarning标记。这类标记有一个特点，就是把它们从代码中去掉以后，代码还是照用不误，不会对运行时的行为产生任何影响。SOURCE及CLASS类型的标记就属于这一类。而有的标记本身就是代码的一部分，参与代码的执行过程，并且在代码中对标记的属性还有调用。这类标记不是可有可无，而是代码逻辑的组成部分，RUNTIME类型的标记就属于这一种。对于我们的Copyright标记，由于在代码执行的过程中需要获取到每本书的版权信息，因此把Copyright标记为RUNTIME类型。随后您将会看到标记中版权数据的调用演示。

接下来制作图书的类别：
01 @Copyright(value = "All Rights Resvered")
02 public class Book {
03 private String bookname;
04
05 public String getBookname() {
06 return bookname;
07 }
08
09 public void setBookname(String bookname) {
10 this.bookname = bookname;
11 }
12 }

这个Java类非常简单，无需过多解释。值得一提的是我们对Book类使用了Copyright这个标记，声明Book类别的Copyright为All rights reserved。下面制作一个UseBook类，看看标记是否生效：
01 import java.lang.annotation.Annotation;
02
03 public class UseBook {
04
05 public static void main(String[] args) {
06 Book b = new Book();
07 b.setBookname("J2EE Tutorial");
08 for (Annotation anno : b.getClass().getAnnotations()) {
09 System.out.println(anno.annotationType().toString());
10 if (anno.annotationType().equals(Copyright.class)) {
11 Copyright c = (Copyright) anno;
12 System.out.println("The Copyright of " + b.getBookname() + ": "
13 + c.value());
14 }
15 }
16 }
17 }

由于我们定义Copyright的Retention类别为RUNTIME，因此在程序的逻辑中应该能够通过Java所提供Clazz.getAnnotations()方法取到Book中的Copyright信息。运行这个代码得到：
1 interface Copyright
2 The Copyright of J2EE Tutorial: All Rights Resvered.

为了进一步说明@Retention的功用，再分别做一个RetentionPolicy.RUNTIME及一个RetentionPolicy.CLASS的标记。其中一个叫做Version，标记Book的版本。另一个叫做TempNote，用于做一些临时的标记说明：
01 import java.lang.annotation.ElementType;
02 import java.lang.annotation.Retention;
03 import java.lang.annotation.RetentionPolicy;
04 import java.lang.annotation.Target;
05
06 @Target(ElementType.TYPE)
07 @Retention(RetentionPolicy.CLASS)
08 public @interface Version {
09 String value();
10 }
01 import java.lang.annotation.ElementType;
02 import java.lang.annotation.Retention;
03 import java.lang.annotation.RetentionPolicy;
04 import java.lang.annotation.Target;
05
06 @Target(ElementType.TYPE)
07 @Retention(RetentionPolicy.SOURCE)
08 public @interface TempNote {
09 String value();
10 }

然后做一个新版本的Book，应用所有的这些标记：
01 @TempNote("This is just a note and won't compile in to source code.")
02 @Version("First Draft")
03 @Copyright(value = "All Rights Resvered.")
04 public class BookV2 {
05 private String bookname;
06
07 public String getBookname() {
08 return bookname;
09 }
10
11 public void setBookname(String bookname) {
12 this.bookname = bookname;
13 }
14 }

接下来在UseBook中使用新的Book：
01 import java.lang.annotation.Annotation;
02
03 public class UseBookV2 {
04
05 public static void main(String[] args) {
06 BookV2 b = new BookV2();
07 b.setBookname("J2EE Tutorial");
08 for (Annotation anno : b.getClass().getAnnotations()) {
09 System.out.println(anno.annotationType().toString());
10 if (anno.annotationType().equals(Copyright.class)) {
11 Copyright c = (Copyright) anno;
12 System.out.println("The Copyright of " + b.getBookname() + ": "
13 + c.value());
14 }
15 }
16 }
17 }

运行结果如下：
1 interface Copyright
2 The Copyright of J2EE Tutorial: All Rights Resvered.

可以看到，系统在运行过程中仅取到了RUNTIME类型的Copyright标记，SOURCE类型的@TempNote及CLASS类型的@Version在运行时都不生效，不参与程序逻辑。

细心的读者可能还不满足：我们把Copyright标记作用于Book类别，这样不是所有的Book类别的实例只能具有同一个Copyright的值了吗？这样如果我们有两本书，一本书的Copyright是All Rights Resevred，另一本是GNU Public License，这样的标记方式就不能够满足我们的编码需要了。因此，我们要做一个新的Copyright，与原来的不同，它的作用域从ElementType.TYPE变成了ElementType.FIELD：
01 import java.lang.annotation.ElementType;
02 import java.lang.annotation.Retention;
03 import java.lang.annotation.RetentionPolicy;
04 import java.lang.annotation.Target;
05
06 @Target(ElementType.FIELD)
07 @Retention(RetentionPolicy.RUNTIME)
08 public @interface CopyrightV2 {
09 String value();
10 }

这样，这个标记就可以用Book实例了。我们还是用例子来进行清晰地说明：
01 import java.lang.annotation.Annotation;
02 import java.lang.reflect.Field;
03
04 public class UseBookV3 {
05
06 @CopyrightV2(value = "All Rights Reserved")
07 private Book book;
08
09 @CopyrightV2(value = "GNU Public License")
10 private Book book2;
11
12 public static void main(String[] args) {
13
14 UseBookV3 ub = new UseBookV3();
15
16 for (Field field : ub.getClass().getDeclaredFields()) {
17 System.out.println("fields found.");
18 for (Annotation anno : field.getAnnotations()) {
19 System.out.println(anno.annotationType().toString());
20 if (anno.annotationType().equals(CopyrightV2.class)) {
21 CopyrightV2 c = (CopyrightV2) anno;
22 System.out.println("value: " + c.value());
23 }
24 }
25 }
26 }
27 }

在这个例子中，我们在UseBookV3类中定义了两个Book的实例：book及book2。由于CopyrightV2的作用域FIELD恰恰是用来标记类中的成员，因此我们分别对book和book2进行了各自独立的标记声明。然后在主程序中，从UseBookV3的实例ub中取得类中的所有变量，java提供的getDeclaredFields()方法可以实现这一目的。当系统找到ub的两个成员book及book2后，把它们所包含的标记及其值打印出来，程序具体输出如下：
1 fields found.
2 interface CopyrightV2
3 value: All Rights Reserved
4
5 fields found.
6 interface CopyrightV2
7 value: GNU Public License
小结

我们这次学习了标记的概念，并亲身体会了标记的制作过程及使用方法。使用这一特性，我们将类与类之间的耦合度大大降低，为系统设计达到OCP的标准提供了强有力的工具。在后续的文章中，我们将大量使用Java的这一语言特性。掌握了以上的标记基本知识，在后续的学习当中将会感觉到非常轻松。