Java 之 Annotation

Annotation 是 Java 5.0 开始引入的新特征。注解是附加在代码中的一些元信息，用于一些工具在编译、运行时进行解析和使用，起到说明、配置的功能。注解不会影响代码的实际逻辑，仅仅起到辅助性的作用。包含在 java.lang.annotation 包中。

1、元注解

元注解是指注解的注解，包括  @Retention @Target @Document @Inherited 四种。

1.1、@Retention

定义注解的保留策略，指示注释类型的注释要保留多久。如果注释类型声明中不存在 Retention 注释，则保留策略默认为 RetentionPolicy.CLASS。

@Retention(RetentionPolicy.SOURCE)
@Retention(RetentionPolicy.CLASS)
@Retention(RetentionPolicy.RUNTIME)

public enum RetentionPolicy {
    /**
     * Annotations are to be discarded by the compiler.
     */
    SOURCE,

    /**
     * Annotations are to be recorded in the class file by the compiler
     * but need not be retained by the VM at run time.  This is the default
     * behavior.
     */
    CLASS,

    /**
     * Annotations are to be recorded in the class file by the compiler and
     * retained by the VM at run time, so they may be read reflectively.
     *
     * @see java.lang.reflect.AnnotatedElement
     */
    RUNTIME
}

1.2、@Target

定义注解的作用目标，指示注释类型所适用的程序元素的种类。如果注释类型声明中不存在Target元注释，则声明的类型可以用在任一程序元素上。如果存在这样的元注释，则编译器强制实施指定的使用限制。

@Target(ElementType.TYPE)
@Target(ElementType.FIELD)
@Target(ElementType.METHOD)
@Target(ElementType.PARAMETER)
@Target(ElementType.CONSTRUCTOR)
@Target(ElementType.LOCAL_VARIABLE)
@Target(ElementType.ANNOTATION_TYPE)
@Target(ElementType.PACKAGE)

public enum ElementType {
    /** Class, interface (including annotation type), or enum declaration */
    TYPE,

    /** Field declaration (includes enum constants) */
    FIELD,

    /** Method declaration */
    METHOD,

    /** Parameter declaration */
    PARAMETER,

    /** Constructor declaration */
    CONSTRUCTOR,

    /** Local variable declaration */
    LOCAL_VARIABLE,

    /** Annotation type declaration */
    ANNOTATION_TYPE,

    /** Package declaration */
    PACKAGE
}

1.3、@Document

说明该注解将被包含在JavaDoc中

1.4、@Inherited

说明子类可以继承父类中的该注解，默认情况下注解并不会被继承到子类中，可以在自定义注解时加上@Inherited注解声明使用继承。

2、自定义注解

2.1. 定义注解

2.1.1 @Handler

import java.lang.annotation.*;

@Inherited
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Handler
{
    String[] value() default {};
}

2.1.2 @SetHandler

import java.lang.annotation.*;

@Inherited
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SetHandler
{
}

2.1.3 @GetHandler

import java.lang.annotation.*;

@Inherited
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface GetHandler
{
}

2.2. 使用注解

import java.util.*;

@Handler("HandlerMethod")
public class HandlerTest
{
    public int setHandler(String method, HashMap<String, String> properties) {
        return 0;
    }

    @SetHandler
    public int setHandler(String method, Map<String, String> properties) {
        return 0;
    }

    @GetHandler
    public String getHandler(String method, Map<String, String> properties) {
        return null;
    }
}

2.3. 处理注解

import java.lang.reflect.*;
import java.util.*;

public class Main
{
    public static void main(String[] args) throws Exception {
        Map<String, String> prop = new HashMap<String, String>();
        prop.put("0", "Property0");
        prop.put("1", "Property0");

        Class clazz = loadClass("HandlerTest");
        doHandler(clazz, "Good luck !!!", prop);
    }

    // load class by name and find annotation
    private static Class loadClass(String name) throws ClassNotFoundException {
        Class clazz = Class.forName(name);
        if (clazz.isAnnotationPresent(Handler.class)) {
            Handler handler = (Handler) clazz.getAnnotation(Handler.class);
            System.out.println("!!! " + clazz + " for " + Arrays.toString(handler.value()));
        }

        return clazz;
    }
    
    // find annotated method and perform
    private static void doHandler(Class clazz, String arg, Map<String, String> prop)
            throws IllegalAccessException, InstantiationException {
        Object object = clazz.newInstance();
        for (Method method : clazz.getMethods()) {
            if (method.isAnnotationPresent(SetHandler.class)) {
                invoke(object, method, arg, prop);
            } else if (method.isAnnotationPresent(GetHandler.class)) {
                invoke(object, method, arg, prop);
            }
        }
    }

    // invoke method
    private static Object invoke(Object object, Method method, String arg, Map<String, String> properties) {
        Class<?>[] type = method.getParameterTypes();
        Map<String, String> prop = null;
        Class clazz0 = type[1];
        Object retval = null;

        if (properties != null) {
            Class clazz1 = properties.getClass();

            if (clazz0 == clazz1) {
                System.out.println("!!! " + clazz0 + " == " + clazz1);
            } else if (clazz1.isAssignableFrom(clazz0)) {
                System.out.println("!!! " + clazz0 + " <= " + clazz1);
            } else if (clazz0.isAssignableFrom(clazz1)) {
                System.out.println("!!! " + clazz0 + " => " + clazz1);
            } else {
                System.out.println("!!! " + clazz0 + " != " + clazz1);
            }

            try {
                if (clazz0.isAssignableFrom(clazz1)) {
                    prop = (Map<String, String>) clazz1.newInstance();
                } else {
                    prop = (Map<String, String>) clazz0.newInstance();
                }
            } catch (Exception e) {
                e.printStackTrace();
            }

            if (prop != null) {
                for (Map.Entry<String, String> entry : properties.entrySet()) {
                    prop.put(entry.getKey(), entry.getValue());
                }
            }
        }

        try {
            retval = method.invoke(object, new Object[]{arg, prop});
        } catch (Exception e) {
            e.printStackTrace();
        }

        return retval;
    }
}

3. 注解处理器

如上面的例子中 @SetHandler 和 @GetHandler 被用来注解方法，但是怎么样来保证被注解的方法有一个统一的声明原型呢。这里可以让Java的编译器来帮忙在编译阶段检查被注解的方法的原型，需要客制化一个注解处理器的插件来让Java编译器处理。为Java的编译器写插件就需要将注解处理器继承自 javax.annotation.processing.AbstractProcessor 且实现一些必要的方法来让其协同工作。
怎么样让编译器找到和使用插件呢？这里必须提供一个jar文件，将注解处理器打包在此jar中，并且还需要打包一个特定的文件 javax.annotation.processing.Processor 到 META-INF/services 路径下，其内容是注解处理器的合法的全名列表。

import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.*;
import javax.lang.model.type.*;
import java.util.*;

public class MyProcessor extends AbstractProcessor
{
    private static final String OBJ_TYPE = "java.lang.Object";
    private static final String STR_TYPE = "java.lang.String";
    private static final String MAP_TYPE = "java.util.Map<?,?>";

    @Override
    public synchronized void init(ProcessingEnvironment processingEnv) {
        super.init(processingEnv);
    }

    @Override
    public Set<String> getSupportedAnnotationTypes() {
        Set<String> types = new LinkedHashSet<String>();
        types.add(SetHandler.class.getCanonicalName());
        types.add(GetHandler.class.getCanonicalName());
        return types;
    }

    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latestSupported();
    }

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        for (TypeElement annotation : annotations) {
            for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) {
                TypeElement enclosingElement = (TypeElement) element.getEnclosingElement();

                if (!(element instanceof ExecutableElement) || element.getKind() != ElementKind.METHOD) {
                    error(element, "@%s.%s annotation must be on a method.",
                        enclosingElement.getQualifiedName(), element.toString());
                    return false;
                }

                Set<Modifier> modifiers = element.getModifiers();
                if (modifiers.contains(Modifier.PRIVATE)
                    || modifiers.contains(Modifier.STATIC)
                    || modifiers.contains(Modifier.PROTECTED)) {
                    error(element, "@%s.%s method must not be protected, private or static.",
                        enclosingElement.getQualifiedName(), element.toString());
                    return false;
                }

                ExecutableElement executableElement = (ExecutableElement) element;
                List<? extends VariableElement> parameters = executableElement.getParameters();
                if (parameters.size() != 2) {
                    error(element, "@%s.%s methods must have 2 parameters.",
                        enclosingElement.getQualifiedName(), element.toString());
                    return false;
                }

                VariableElement parameter0 = parameters.get(0);
                TypeMirror typeMirror0 = parameter0.asType();
                if (!isSubtypeOfType(typeMirror0, STR_TYPE)) {
                    error(element, "The 1st parameter of methods @%s.%s must be 'String'.",
                        enclosingElement.getQualifiedName(), element.toString());
                    return false;
                }

                VariableElement parameter1 = parameters.get(1);
                TypeMirror typeMirror1 = parameter1.asType();
                if (!isSubtypeOfType(typeMirror1, MAP_TYPE, STR_TYPE, STR_TYPE)) {
                    error(element, "The 2nd parameter of methods @%s.%s should assignable from 'Map<String, String>'.",
                        enclosingElement.getQualifiedName(), element.toString());
                    return false;
                }
            }
        }

        for (Element element : roundEnv.getElementsAnnotatedWith(SetHandler.class)) {
            TypeElement enclosingElement = (TypeElement) element.getEnclosingElement();
            ExecutableElement executableElement = (ExecutableElement) element;
            TypeMirror returnType = executableElement.getReturnType();
            if (!isSubtypeOfType(returnType, "int")) {
                error(element, "@%s.%s methods must have a 'int' return type.",
                    enclosingElement.getQualifiedName(), element.toString());
                return false;
            }
        }

        for (Element element : roundEnv.getElementsAnnotatedWith(GetHandler.class)) {
            TypeElement enclosingElement = (TypeElement) element.getEnclosingElement();
            ExecutableElement executableElement = (ExecutableElement) element;
            TypeMirror returnType = executableElement.getReturnType();
            if (!isSubtypeOfType(returnType, OBJ_TYPE)) {
                error(element, "@%s.%s methods should have a 'Object' return type.",
                    enclosingElement.getQualifiedName(), element.toString());
                return false;
            }
        }

        return true;
    }

    private boolean isSubtypeOfType(TypeMirror typeMirror, String otherType, String... genericTypes) {
        if (otherType.equals(typeMirror.toString())) {
            return true;
        }
        if (typeMirror.getKind() != TypeKind.DECLARED) {
            return false;
        }

        DeclaredType declaredType = (DeclaredType) typeMirror;
        List<? extends TypeMirror> typeArguments = declaredType.getTypeArguments();
        if (typeArguments.size() > 0) {
            StringBuilder typeString = new StringBuilder(declaredType.asElement().toString());
            typeString.append('<');
            for (int i = 0; i < typeArguments.size(); i++) {
                if (i > 0) {
                    typeString.append(',');
                }
                typeString.append('?');
                if (genericTypes != null && genericTypes.length > i) {
                    if (!isSubtypeOfType(typeArguments.get(i), genericTypes[i])) {
                        return false;
                    }
                }
            }

            typeString.append('>');
            if (typeString.toString().equals(otherType)) {
                return true;
            }
        }

        Element element = declaredType.asElement();
        if (!(element instanceof TypeElement)) {
            return false;
        }

        TypeElement typeElement = (TypeElement) element;
        TypeMirror superType = typeElement.getSuperclass();
        if (isSubtypeOfType(superType, otherType)) {
            return true;
        }

        for (TypeMirror interfaceType : typeElement.getInterfaces()) {
            if (isSubtypeOfType(interfaceType, otherType)) {
                return true;
            }
        }

        return false;
    }

    private void error(Element element, String message, Object... args) {
        if (args.length > 0) {
            message = String.format(message, args);
        }

        processingEnv.getMessager().printMessage(javax.tools.Diagnostic.Kind.ERROR, message, element);
    }
}

4. 注解应用实例

• butterknife