Java深度历险（六）——Java注解——（七）—

在开发Java程序，尤其是Java EE应用的时候，总是免不了与各种配置文件打交道。以Java EE中典型的S(pring)S(truts)H(ibernate)架构来说，Spring、Struts和Hibernate这三个框架都有自己的XML格式的配置文件。这些配置文件需要与Java源代码保存同步，否则的话就可能出现错误。而且这些错误有可能到了运行时刻才被发现。把同一份信息保存在两个地方，总是个坏的主意。理想的情况是在一个地方维护这些信息就好了。其它部分所需的信息则通过自动的方式来生成。JDK
5中引入了源代码中的注解（annotation）这一机制。注解使得Java源代码中不但可以包含功能性的实现代码，还可以添加元数据。注解的功能类似于代码中的注释，所不同的是注解不是提供代码功能的说明，而是实现程序功能的重要组成部分。Java注解已经在很多框架中得到了广泛的使用，用来简化程序中的配置。

使用注解

在一般的Java开发中，最常接触到的可能就是@Override和@SupressWarnings这两个注解了。使用@Override的时候只需要一个简单的声明即可。这种称为标记注解（marker
annotation ），它的出现就代表了某种配置语义。而其它的注解是可以有自己的配置参数的。配置参数以名值对的方式出现。使用 @SupressWarnings的时候需要类似@SupressWarnings({"uncheck", "unused"})这样的语法。在括号里面的是该注解可供配置的值。由于这个注解只有一个配置参数，该参数的名称默认为value，并且可以省略。而花括号则表示是数组类型。在JPA中的@Table注解使用类似@Table(name
= "Customer", schema = "APP")这样的语法。从这里可以看到名值对的用法。在使用注解时候的配置参数的值必须是编译时刻的常量。

从某种角度来说，可以把注解看成是一个XML元素，该元素可以有不同的预定义的属性。而属性的值是可以在声明该元素的时候自行指定的。在代码中使用注解，就相当于把一部分元数据从XML文件移到了代码本身之中，在一个地方管理和维护。

开发注解

在一般的开发中，只需要通过阅读相关的API文档来了解每个注解的配置参数的含义，并在代码中正确使用即可。在有些情况下，可能会需要开发自己的注解。这在库的开发中比较常见。注解的定义有点类似接口。下面的代码给出了一个简单的描述代码分工安排的注解。通过该注解可以在源代码中记录每个类或接口的分工和进度情况。

@Retention(RetentionPolicy.RUNTIME)

@Target(ElementType.TYPE)

public @interface Assignment {

    String assignee();

    int effort();

    double finished() default 0;

}

@interface用来声明一个注解，其中的每一个方法实际上是声明了一个配置参数。方法的名称就是参数的名称，返回值类型就是参数的类型。可以通过default来声明参数的默认值。在这里可以看到@Retention和@Target这样的元注解，用来声明注解本身的行为。@Retention用来声明注解的保留策略，有CLASS、RUNTIME和SOURCE这三种，分别表示注解保存在类文件、JVM运行时刻和源代码中。只有当声明为RUNTIME的时候，才能够在运行时刻通过反射API来获取到注解的信息。@Target用来声明注解可以被添加在哪些类型的元素上，如类型、方法和域等。

处理注解

在程序中添加的注解，可以在编译时刻或是运行时刻来进行处理。在编译时刻处理的时候，是分成多趟来进行的。如果在某趟处理中产生了新的Java源文件，那么就需要另外一趟处理来处理新生成的源文件。如此往复，直到没有新文件被生成为止。在完成处理之后，再对Java代码进行编译。JDK 5中提供了apt工具用来对注解进行处理。apt是一个命令行工具，与之配套的还有一套用来描述程序语义结构的Mirror
API。Mirror API（com.sun.mirror.*）描述的是程序在编译时刻的静态结构。通过Mirror API可以获取到被注解的Java类型元素的信息，从而提供相应的处理逻辑。具体的处理工作交给apt工具来完成。编写注解处理器的核心是AnnotationProcessorFactory和AnnotationProcessor两个接口。后者表示的是注解处理器，而前者则是为某些注解类型创建注解处理器的工厂。

以上面的注解Assignment为例，当每个开发人员都在源代码中更新进度的话，就可以通过一个注解处理器来生成一个项目整体进度的报告。首先是注解处理器工厂的实现。

public class AssignmentApf implements AnnotationProcessorFactory {

    public AnnotationProcessor getProcessorFor(Set<AnnotationTypeDeclaration> atds,? AnnotationProcessorEnvironment env) {

        if (atds.isEmpty()) {

           return AnnotationProcessors.NO_OP;

        }

        return new AssignmentAp(env); //返回注解处理器

    }

    public Collection<String> supportedAnnotationTypes() {

        return Collections.unmodifiableList(Arrays.asList("annotation.Assignment"));

    }

    public Collection<String> supportedOptions() {

        return Collections.emptySet();

    }

}

AnnotationProcessorFactory接口有三个方法：getProcessorFor是根据注解的类型来返回特定的注解处理器；supportedAnnotationTypes是返回该工厂生成的注解处理器所能支持的注解类型；supportedOptions用来表示所支持的附加选项。在运行apt命令行工具的时候，可以通过-A来传递额外的参数给注解处理器，如-Averbose=true。当工厂通过 supportedOptions方法声明了所能识别的附加选项之后，注解处理器就可以在运行时刻通过AnnotationProcessorEnvironment的getOptions方法获取到选项的实际值。注解处理器本身的基本实现如下所示。

public class AssignmentAp implements AnnotationProcessor {

    private AnnotationProcessorEnvironment env;

    private AnnotationTypeDeclaration assignmentDeclaration;

    public AssignmentAp(AnnotationProcessorEnvironment env) {

        this.env = env;

        assignmentDeclaration = (AnnotationTypeDeclaration) env.getTypeDeclaration("annotation.Assignment");

    }

    public void process() {

        Collection<Declaration> declarations = env.getDeclarationsAnnotatedWith(assignmentDeclaration);

        for (Declaration declaration : declarations) {

           processAssignmentAnnotations(declaration);

        }

    }

    private void processAssignmentAnnotations(Declaration declaration) {

        Collection<AnnotationMirror> annotations = declaration.getAnnotationMirrors();

        for (AnnotationMirror mirror : annotations) {

            if (mirror.getAnnotationType().getDeclaration().equals(assignmentDeclaration)) {

                Map<AnnotationTypeElementDeclaration, AnnotationValue> values = mirror.getElementValues();

                String assignee = (String) getAnnotationValue(values, "assignee"); //获取注解的值

            }

        }

    }

}

注解处理器的处理逻辑都在process方法中完成。通过一个声明（Declaration）的getAnnotationMirrors方法就可以获取到该声明上所添加的注解的实际值。得到这些值之后，处理起来就不难了。

在创建好注解处理器之后，就可以通过apt命令行工具来对源代码中的注解进行处理。命令的运行格式是apt -classpath bin -factory annotation.apt.AssignmentApf src/annotation/work/*.java，即通过-factory来指定注解处理器工厂类的名称。实际上，apt工具在完成处理之后，会自动调用javac来编译处理完成后的源代码。

JDK 5中的apt工具的不足之处在于它是Oracle提供的私有实现。在JDK 6中，通过JSR 269把自定义注解处理器这一功能进行了规范化，有了新的javax.annotation.processing这个新的API。对Mirror
API也进行了更新，形成了新的javax.lang.model包。注解处理器的使用也进行了简化，不需要再单独运行apt这样的命令行工具，Java编译器本身就可以完成对注解的处理。对于同样的功能，如果用JSR
269的做法，只需要一个类就可以了。

@SupportedSourceVersion(SourceVersion.RELEASE_6)

@SupportedAnnotationTypes("annotation.Assignment")

public class AssignmentProcess extends AbstractProcessor {

    private TypeElement assignmentElement;

    public synchronized void init(ProcessingEnvironment processingEnv) {

        super.init(processingEnv);

        Elements elementUtils = processingEnv.getElementUtils();

        assignmentElement = elementUtils.getTypeElement("annotation.Assignment");

    }

    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {

        Set<? extends Element> elements = roundEnv.getElementsAnnotatedWith(assignmentElement);

        for (Element element : elements) {

            processAssignment(element);

        }

    }

    private void processAssignment(Element element) {

        List<? extends AnnotationMirror> annotations = element.getAnnotationMirrors();

        for (AnnotationMirror mirror : annotations) {

            if (mirror.getAnnotationType().asElement().equals(assignmentElement)) {

                Map<? extends ExecutableElement, ? extends AnnotationValue> values = mirror.getElementValues();

                String assignee = (String) getAnnotationValue(values, "assignee"); //获取注解的值

            }

        }

    }

}

仔细比较上面两段代码，可以发现它们的基本结构是类似的。不同之处在于JDK 6中通过元注解@SupportedAnnotationTypes来声明所支持的注解类型。另外描述程序静态结构的javax.lang.model包使用了不同的类型名称。使用的时候也更加简单，只需要通过javac
-processor annotation.pap.AssignmentProcess Demo1.java这样的方式即可。

上面介绍的这两种做法都是在编译时刻进行处理的。而有些时候则需要在运行时刻来完成对注解的处理。这个时候就需要用到Java的反射API。反射API提供了在运行时刻读取注解信息的支持。不过前提是注解的保留策略声明的是运行时。Java反射API的AnnotatedElement接口提供了获取类、方法和域上的注解的实用方法。比如获取到一个Class类对象之后，通过getAnnotation方法就可以获取到该类上添加的指定注解类型的注解。

实例分析

下面通过一个具体的实例来分析说明在实践中如何来使用和处理注解。假定有一个公司的雇员信息系统，从访问控制的角度出发，对雇员的工资的更新只能由具有特定角色的用户才能完成。考虑到访问控制需求的普遍性，可以定义一个注解来让开发人员方便的在代码中声明访问控制权限。

@Retention(RetentionPolicy.RUNTIME)

@Target(ElementType.METHOD)

public @interface RequiredRoles {

    String[] value();

}

下一步则是如何对注解进行处理，这里使用的Java的反射API并结合动态代理。下面是动态代理中的InvocationHandler接口的实现。

public class AccessInvocationHandler<T> implements InvocationHandler {

    final T accessObj;

    public AccessInvocationHandler(T accessObj) {

        this.accessObj = accessObj;

    }

    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {

        RequiredRoles annotation = method.getAnnotation(RequiredRoles.class); //通过反射API获取注解

        if (annotation != null) {

            String[] roles = annotation.value();

            String role = AccessControl.getCurrentRole();

            if (!Arrays.asList(roles).contains(role)) {

                throw new AccessControlException("The user is not allowed to invoke this method.");

            }

        }

        return method.invoke(accessObj, args);

    }

}

在具体使用的时候，首先要通过Proxy.newProxyInstance方法创建一个EmployeeGateway的接口的代理类，使用该代理类来完成实际的操作。

参考资料

JDK 5和JDK
6中的apt工具说明文档
Pluggable Annotation Processing
API
APT: Compile-Time Annotation Processing with Java

在上一篇文章中介绍Java注解的时候，多次提到了Java的反射API。与javax.lang.model不同的是，通过反射API可以获取程序在运行时刻的内部结构。反射API中提供的动态代理也是非常强大的功能，可以原生实现AOP中
的方法拦截功能。正如英文单词reflection的含义一样，使用反射API的时候就好像在看一个Java类在水中的倒影一样。知道了Java类的内部结构之后，就可以与它进行交互，包括创建新的对象和调用对象中的方法等。这种交互方式与直接在源代码中使用的效果是相同的，但是又额外提供了运行时刻的灵活性。使用反射的一个最大的弊端是性能比较差。相同的操作，用反射API所需的时间大概比直接的使用要慢一两个数量级。不过现在的JVM实现中，反射操作的性能已经有了很大的提升。在灵活性与性能之间，总是需要进行权衡的。应用可以在适当的时机来使用反射API。

基本用法

Java 反射API的第一个主要作用是获取程序在运行时刻的内部结构。这对于程序的检查工具和调试器来说，是非常实用的功能。只需要短短的十几行代码，就可以遍历出来一个Java类的内部结构，包括其中的构造方法、声明的域和定义的方法等。这不得不说是一个很强大的能力。只要有了java.lang.Class类的对象，就可以通过其中的方法来获取到该类中的构造方法、域和方法。对应的方法分别是getConstructor、getField和getMethod。这三个方法还有相应的getDeclaredXXX版本，区别在于getDeclaredXXX版本的方法只会获取该类自身所声明的元素，而不会考虑继承下来的。Constructor、Field和Method这三个类分别表示类中的构造方法、域和方法。这些类中的方法可以获取到所对应结构的元数据。

反射API的另外一个作用是在运行时刻对一个Java对象进行操作。这些操作包括动态创建一个Java类的对象，获取某个域的值以及调用某个方法。在Java源代码中编写的对类和对象的操作，都可以在运行时刻通过反射API来实现。考虑下面一个简单的Java类。
```
class MyClass {

    public int count;

    public MyClass(int start) {

        count = start;

    }

    public void increase(int step) {

        count = count + step;

    }

} 
```
使用一般做法和反射API都非常简单。
```
MyClass myClass = new MyClass(0); //一般做法

myClass.increase(2);

System.out.println("Normal -> " + myClass.count);

try {

    Constructor constructor = MyClass.class.getConstructor(int.class); //获取构造方法
    MyClass myClassReflect = constructor.newInstance(10); //创建对象
    Method method = MyClass.class.getMethod("increase", int.class);  //获取方法
    method.invoke(myClassReflect, 5); //调用方法
    Field field = MyClass.class.getField("count"); //获取域
    System.out.println("Reflect -> " + field.getInt(myClassReflect)); //获取域的值
} catch (Exception e) { 
    e.printStackTrace();
} 
```
由于数组的特殊性，Array类提供了一系列的静态方法用来创建数组和对数组中的元素进行访问和操作。
```
Object array = Array.newInstance(String.class, 10); //等价于 new String[10]

Array.set(array, 0, "Hello");  //等价于array[0] = "Hello"

Array.set(array, 1, "World");  //等价于array[1] = "World"

System.out.println(Array.get(array, 0));  //等价于array[0]
```
使用Java反射API的时候可以绕过Java默认的访问控制检查，比如可以直接获取到对象的私有域的值或是调用私有方法。只需要在获取到Constructor、Field和Method类的对象之后，调用setAccessible方法并设为true即可。有了这种机制，就可以很方便的在运行时刻获取到程序的内部状态。

处理泛型

Java 5中引入了泛型的概念之后，Java反射API也做了相应的修改，以提供对泛型的支持。由于类型擦除机制的存在，泛型类中的类型参数等信息，在运行时刻是不存在的。JVM看到的都是原始类型。对此，Java 5对Java类文件的格式做了修订，添加了Signature属性，用来包含不在JVM类型系统中的类型信息。比如以java.util.List接口为例，在其类文件中的Signature属性的声明是<E:Ljava/lang/Object;>Ljava/lang/Object;Ljava/util/Collection<TE;>;;
，这就说明List接口有一个类型参数E。在运行时刻，JVM会读取Signature属性的内容并提供给反射API来使用。

比如在代码中声明了一个域是List<String>类型的，虽然在运行时刻其类型会变成原始类型List，但是仍然可以通过反射来获取到所用的实际的类型参数。
```
Field field = Pair.class.getDeclaredField("myList"); //myList的类型是List

Type type = field.getGenericType();

if (type instanceof ParameterizedType) {

    ParameterizedType paramType = (ParameterizedType) type;

    Type[] actualTypes = paramType.getActualTypeArguments();

    for (Type aType : actualTypes) {

        if (aType instanceof Class) {

            Class clz = (Class) aType;

            System.out.println(clz.getName()); //输出java.lang.String

        }

    }

}  
```
动态代理

熟悉设计模式的人对于代理模式可能都不陌生。代理对象和被代理对象一般实现相同的接口，调用者与代理对象进行交互。代理的存在对于调用者来说是透明的，调用者看到的只是接口。代理对象则可以封装一些内部的处理逻辑，如访问控制、远程通信、日志、缓存等。比如一个对象访问代理就可以在普通的访问机制之上添加缓存的支持。这种模式在RMI和EJB中都得到了广泛的使用。传统的代理模式的实现，需要在源代码中添加一些附加的类。这些类一般是手写或是通过工具来自动生成。JDK
5引入的动态代理机制，允许开发人员在运行时刻动态的创建出代理类及其对象。在运行时刻，可以动态创建出一个实现了多个接口的代理类。每个代理类的对象都会关联一个表示内部处理逻辑的InvocationHandler接
口的实现。当使用者调用了代理对象所代理的接口中的方法的时候，这个调用的信息会被传递给InvocationHandler的invoke方法。在 invoke方法的参数中可以获取到代理对象、方法对应的Method对象和调用的实际参数。invoke方法的返回值被返回给使用者。这种做法实际上相当于对方法调用进行了拦截。熟悉AOP的人对这种使用模式应该不陌生。但是这种方式不需要依赖AspectJ等AOP框架。

下面的代码用来代理一个实现了List接口的对象。所实现的功能也非常简单，那就是禁止使用List接口中的add方法。如果在getList中传入一个实现List接口的对象，那么返回的实际就是一个代理对象，尝试在该对象上调用add方法就会抛出来异常。
```
public List getList(final List list) {

    return (List) Proxy.newProxyInstance(DummyProxy.class.getClassLoader(), new Class[] { List.class },

        new InvocationHandler() {

            public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {

                if ("add".equals(method.getName())) {

                    throw new UnsupportedOperationException();

                }

                else {

                    return method.invoke(list, args);

                }

            }

        });

 }
```
这里的实际流程是，当代理对象的add方法被调用的时候，InvocationHandler中的invoke方法会被调用。参数method就包含了调用的基本信息。因为方法名称是add，所以会抛出相关的异常。如果调用的是其它方法的话，则执行原来的逻辑。

使用案例

Java 反射API的存在，为Java语言添加了一定程度上的动态性，可以实现某些动态语言中的功能。比如在JavaScript的代码中，可以通过 obj["set" + propName]()来根据变量propName的值找到对应的方法进行调用。虽然在Java源代码中不能这么写，但是通过反射API同样可以实现类似的功能。这对于处理某些遗留代码来说是有帮助的。比如所需要使用的类有多个版本，每个版本所提供的方法名称和参数不尽相同。而调用代码又必须与这些不同的版本都能协同工作，就可以通过反射API来依次检查实际的类中是否包含某个方法来选择性的调用。

Java 反射API实际上定义了一种相对于编译时刻而言更加松散的契约。如果被调用的Java对象中并不包含某个方法，而在调用者代码中进行引用的话，在编译时刻就会出现错误。而反射API则可以把这样的检查推迟到运行时刻来完成。通过把Java中的字节代码增强、类加载器和反射API结合起来，可以处理一些对灵活性要求很高的场景。

在有些情况下，可能会需要从远端加载一个Java类来执行。比如一个客户端Java程序可以通过网络从服务器端下载Java类来执行，从而可以实现自动更新的机制。当代码逻辑需要更新的时候，只需要部署一个新的Java类到服务器端即可。一般的做法是通过自定义类加载器下载了类字节代码之后，定义出 Class类的对象，再通过newInstance方法就可以创建出实例了。不过这种做法要求客户端和服务器端都具有某个接口的定义，从服务器端下载的是这个接口的实现。这样的话才能在客户端进行所需的类型转换，并通过接口来使用这个对象实例。如果希望客户端和服务器端采用更加松散的契约的话，使用反射API就可以了。两者之间的契约只需要在方法的名称和参数这个级别就足够了。服务器端Java类并不需要实现特定的接口，可以是一般的Java类。

动态代理的使用场景就更加广泛了。需要使用AOP中的方法拦截功能的地方都可以用到动态代理。Spring框架的AOP实现默认也使用动态代理。不过JDK中的动态代理只支持对接口的代理，不能对一个普通的Java类提供代理。不过这种实现在大部分的时候已经够用了。

参考资料
- Classworking toolkit: Reflecting generics
- D?ecorating with dynamic proxies