用Java内置注解来限定自定义注解的技巧

在定义Java注解时，还可以使用JDK类库的一些内置注解来进行相关的限定。这些内置注解主要包括@Target、@Rentention、@Documented和@Inherited。下面以定义@MyAnnotation注解为例，分别介绍这些内置注解的用法。

1．@Target注解

@Target注解用来指定@MyAnnotation注解所适用的目标，即@MyAnnotation注解可以为源代码中的哪些内容做注解。

@Target注解有一个用于设定目标的value成员，其可选值由java.lang.annotation.ElementType类的静态常量来表示，表1列出了这些常量表示的目标。

表1 ElementType类的常量

例如以下@MyAnnotation注解的适用目标为ElementType.TYPE，即可以为Java类和接口做注解；@MyField注解的适用目标为ElementType.FIELD，即可以为成员变量做注解：

@Target({ElementType.TYPE})          //适用于类和接口
@interface MyAnnotation{}

@Target({ElementType.FIELD})          //适用于成员变量
@interface MyField{}

以下Sample类在声明时使用了@MyAnnotation注解，它的var成员变量使用了@MyField注解：

@MyAnnotation
public class Sample{
  @MyField
  String var;
}

2．@Retention注解

@Retention注解用来指定@MyAnnotaion注解的有效范围。@Retention注解的value成员用于设定有效范围，其可选值由java.lang.annotation.RetentionPolicy类的静态常量来表示，表2列出了这些常量表示的有效范围。

表2 RetentionPolicy类的常量

3．@Documented注解

@Documented注解是标识性注解，指定@MyAnnotaion注解包含的元数据信息会加入到JavaDoc文档中。

例如以下@MyAnnotation注解在声明时使用了@Documented注解：

@Documented   
@Target({ElementType.TYPE})       
@interface MyAnnotation{String value();}

以下Sample类在声明时使用了@MyAnnotation注解：

@MyAnnotation("这是一个范例")
public class Sample{}

用javadoc命令为Sample类生成JavaDoc文档时，@MyAnnotation注解包含的元数据信息会加入到JavaDoc文档中。

4．@Inherited注解

@Inherited注解是标识性注解，指定@MyAnnotation注解可以被继承。假定在声明@MyAnnotation注解时使用了@Inherited注解，在声明Sample类时使用了@MyAnnotation注解，那么Sample类的子类也会继承@MyAnnotation注解，即相当于Sample类的子类在声明时也使用了@MyAnnotation注解。

Sample类的子类继承@MyAnnotation注解

下面再举例解释这些内置注解的用法。例程1定义了@Programmer注解，它会加入到JavaDoc文档中，适用于对类和接口做注解，有效范围是程序运行时。

例程1 Programmer.java

import java.lang.annotation.*;
@Documented
@Target({ElementType.TYPE})            //适用于类和接口
@Retention(RetentionPolicy.RUNTIME)  //有效范围是运行时
public @interface Programmer{
  String name();                         //程序员姓名
  String company();                     //程序员所在单位
}

例程2定义了@ConstructorNote注解，它适用于对构造方法做注解，有效范围是程序运行时。

例程2 ConstructorNote.java

import java.lang.annotation.*;
@Target(ElementType.CONSTRUCTOR)      //适用于构造方法
@Retention(RetentionPolicy.RUNTIME)  //有效范围是运行时
public @interface ConstructorNote{
  String value() default "默认构造方法";
}

例程3定义了@Common注解，它适用于对成员变量、成员方法和参数做注解，有效范围是程序运行时。

例程3 Common.java

import java.lang.annotation.*;
//适用于成员变量、成员方法和参数
@Target({ElementType.FIELD,ElementType.METHOD,
           ElementType.PARAMETER}) 
@Retention(RetentionPolicy.RUNTIME)  //有效范围是运行时
public @interface Common{
  Class type() default void.class;	
  String description();
}

以上@Target注解的成员的值是一个数组，该数组包含了ElementType类的多个常量。

相关阅读：

孙卫琴书友会：《Java面向对象编程》导读-在Java类中使用自定义注解

上文参考孙卫琴的经典Java书籍《Java面向对象编程》