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的一个私有成员：

public class Book {
...
private Copyright copyright;
...
}

但是在这里，我们将使用另外一种实现方法，使用新的Annotation特性，让Copyright成为Book的一个标记。首先要做的工作便是制作Copyright这个标记类：

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Copyright {
	String value();
}

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

@Copyright(value = "All Rights Resvered")
public class Book
...

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

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

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

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

@Deprecated
public class SomeClazz {...}

也可以把一个函数标记为已过期：

public class SomeClazz {

@Deprecated
public void someMethod();
...
}

还可以把参数、属性，构造方法等所有的元素标记为@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类型。随后你将会看到标记中版权数据的调用演示。

接下来制作图书的类别：

@Copyright(value = "All Rights Resvered")
public class Book {
	private String bookname;

	public String getBookname() {
		return bookname;
	}

	public void setBookname(String bookname) {
		this.bookname = bookname;
	}
}

这个Java类非常简单，无需过多解释。值得一提的是我们对Book类使用了Copyright这个标记，声明Book类别的Copyright为All rights reserved。下面制作一个UseBook类，看看标记是否生效：

import java.lang.annotation.Annotation;

public class UseBook {

	public static void main(String[] args) {
		Book b = new Book();
		b.setBookname("J2EE Tutorial");
		for (Annotation anno : b.getClass().getAnnotations()) {
			System.out.println(anno.annotationType().toString());
			if (anno.annotationType().equals(Copyright.class)) {
				Copyright c = (Copyright) anno;
				System.out.println("The Copyright of " + b.getBookname() + ": "
						+ c.value());
			}
		}
	}
}

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

interface Copyright
The Copyright of J2EE Tutorial: All Rights Resvered.

为了进一步说明@Retention的功用，再分别做一个RetentionPolicy.RUNTIME及一个RetentionPolicy.CLASS的标记。其中一个叫做Version，标记Book的版本。另一个叫做TempNote，用于做一些临时的标记说明：

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface Version {
	String value();
}

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface TempNote {
	String value();
}

然后做一个新版本的Book，应用所有的这些标记：

@TempNote("This is just a note and won't compile in to source code.")
@Version("First Draft")
@Copyright(value = "All Rights Resvered.")
public class BookV2 {
	private String bookname;

	public String getBookname() {
		return bookname;
	}

	public void setBookname(String bookname) {
		this.bookname = bookname;
	}
}

接下来在UseBook中使用新的Book：

import java.lang.annotation.Annotation;

public class UseBookV2 {

	public static void main(String[] args) {
		BookV2 b = new BookV2();
		b.setBookname("J2EE Tutorial");
		for (Annotation anno : b.getClass().getAnnotations()) {
			System.out.println(anno.annotationType().toString());
			if (anno.annotationType().equals(Copyright.class)) {
				Copyright c = (Copyright) anno;
				System.out.println("The Copyright of " + b.getBookname() + ": "
						+ c.value());
			}
		}
	}
}

运行结果如下：

interface Copyright
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：

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface CopyrightV2 {
	String value();
}

这样，这个标记就可以用Book实例了。我们还是用例子来进行清晰地说明：

import java.lang.annotation.Annotation;
import java.lang.reflect.Field;

public class UseBookV3 {

	@CopyrightV2(value = "All Rights Reserved")
	private Book book;

	@CopyrightV2(value = "GNU Public License")
	private Book book2;

	public static void main(String[] args) {

		UseBookV3 ub = new UseBookV3();

		for (Field field : ub.getClass().getDeclaredFields()) {
			System.out.println("fields found.");
			for (Annotation anno : field.getAnnotations()) {
				System.out.println(anno.annotationType().toString());
				if (anno.annotationType().equals(CopyrightV2.class)) {
					CopyrightV2 c = (CopyrightV2) anno;
					System.out.println("value: " + c.value());
				}
			}
		}
	}
}

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

fields found.
interface CopyrightV2
value: All Rights Reserved

fields found.
interface CopyrightV2
value: GNU Public License

小结
我们这次学习了标记的概念，并亲身体会了标记的制作过程及使用方法。使用这一特性，我们将类与类之间的耦合度大大降低，为系统设计达到OCP的标准提供了强有力的工具。