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这个标记类：

 

 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类别中，我们是如何使用这个属性的：

view source

print ?

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固有标记来举例，我们既可以把一个类标记为过期：

view source

print ?

1	@Deprecated

2	public class SomeClazz {...}

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

view source

print ?

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类型。随后您将会看到标记中版权数据的调用演示。

 

接下来制作图书的类别：

 

@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信息。运行这个代码得到：

1	interface Copyright

2	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());  

             }  

         }  

     }  

 } 

运行结果如下：

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的这一语言特性。掌握了以上的标记基本知识，在后续的学习当中将会感觉到非常轻松