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