Java 注解
Java的注解是个很神奇的东西，它既可以帮你生成代码，又可以结合反射来在运行时获得注解标识的对象，进行逻辑处理，它能帮助我们完成很多很多不可能完成的任务，这回我们就来一起来了解下它。
一、什么可以被注解修饰
Java中的类、方法、变量、参数、包都可以被注解，在java8中注解可以被运用到任何地方。比如：
myString = (@NonNull String) str; class UnmodifiableList<T> implements @Readonly List<@Readonly T> { ... } new @Interned MyObject();
需要注意的是，类型注解只是语法而不是语义，并不会影响java的编译时间，加载时间，以及运行时间。在Java8没有普及的情况下，本文仅仅讨论在jdk1.7中可被用于实践的注解方案。
二、注解的类型
2.1 引子
我们先从我们最熟悉的@Override说起
/** * Annotation type used to mark methods that override a method declaration in a * superclass. Compilers produce an error if a method annotated with @Override * does not actually override a method in a superclass. * * @since 1.5 */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.SOURCE) public @interface Override { }
我们注意到了@Target和@Retention这两个注解，这两个家伙就是专门用来修饰注解的注解，看起来吊吊的，但在实际开发中我们都不会去用到他们，所以我们不是很熟悉。但今天我们已经开始学习注解了，姑且就和他们打个招呼吧，先照猫画虎写一个自己的注解，注解的名字叫做classInfo：
@Target(ElementType.TYPE) @Retention(RetentionPolicy.CLASS) public @interface ClassInfo { String value() default "default"; }
先不管这个注解有什么用，我们就看这个注解类的标识，其实上面两行标识就是起一个说明作用，和他们一样的还有@Document等。
@Documented 是否会保存到 Javadoc 文档中
@Retention 保留时间，可选值 SOURCE（源码时），CLASS（编译时），RUNTIME（运行时），默认为 CLASS。
如果值为 SOURCE 大都为 Mark Annotation，这类 Annotation 大都用来校验，比如 Override, Deprecated, SuppressWarnings
@Target 来指定这个注解可以修饰哪些元素，如 TYPE, METHOD, CONSTRUCTOR, FIELD, PARAMETER 等，未标注则表示可修饰所有类型
@Inherited 是否可以被继承，默认为 false
2.2 详细说明
我们来详细说说看:
@Documented 这个东西如果加在了注解上面，就会在生成java doc时有相关注解的文档，在小项目开发过程中，这个注解意义不大，可以忽略。
@Retention 它里面的值都是以RetentionPolicy开头的，来看看源码是怎么写的：
public enum RetentionPolicy { /** * Annotation is only available in the source code. */ SOURCE, /** * Annotation is available in the source code and in the class file, but not * at runtime. This is the default policy. */ CLASS, /** * Annotation is available in the source code, the class file and is * available at runtime. */ RUNTIME }
- 如果是SOURCE，注解保留范围为源代码，在编译时将会被编译器丢弃。这类 Annotation 大都用来校验，比如 Override, Deprecated, SuppressWarnings。
- 如果是CLASS，这个注解保留范围是源代码和类文件中，但并非作用于运行时，所以JVM不会识别此。如果你在自定义注解时，不写@Retention，默认就是CLASS的。这类的注解和SOURCE的注解都可以配合AbstractProcessor进行使用，用于在编译时进行自动处理一些事物或者生成一些文件。
- 如果是RUNTIME，这个注解的保留范围是源代码、类文件和运行时，这类的注解一般会和反射配合使用。可以在运行时通过反射查看被这个注解标识的方法，然后得到被标识的元素，接着进行处理。
final Method[] allMethods = clazz.getDeclaredMethods(); for (Method method : allMethods) { // 根据注解来解析函数 Subscriber annotation = method.getAnnotation(Subscriber.class);
｝
上面这段代码会遍历这个类中被标识了@Subscriber的方法。但如果我们把@Subscriber设定为@Retention(RetentionPolicy.CLASS)，这时这个注解就不会被保留到运行时的代码中了，因此我们用反射就获取不到，就会报出如下错误。
@Target 指定注解可以被标识于哪种Java元素上，指定类型（ElementType）如下：
ElementType.ANNOTATION_TYPE注释类型声明。ElementType.CONSTRUCTOR构造方法声明。ElementType.FIELD字段声明（包括枚举常量）。ElementType.LOCAL_VARIABLE局部变量声明。ElementType.METHOD方法声明。ElementType.PACKAGE包声明。ElementType.PARAMETER参数声明。ElementType.TYPE类、接口（包括注释类型）或枚举声明。
这个注解标识仅仅做个标识，没有任何代码逻辑，它的目的是避免使用者随便标识注解，从而造成处理注解时出现错误。
三、自定义编译时注解
3.1 编译时注解
所谓编译时注解就是在你写代码时，就能产生作用的注解，一旦程序运行成apk，你的注解就没用了，所以它的生命周期在于你写代码到编译的过程之间。我们先来看看一个Android特有的注解方式，这种注解方式属于特殊的编译时注解。
public static final int VANILLA = 0; public static final int CHOCOLATE = 1; public static final int STRAWBERRY = 2; @IntDef({VANILLA, CHOCOLATE, STRAWBERRY}) public @interface Flavour { }
首先我们定义了三个常量，然后定义了一个注解 @Flavour，在这个注解上用@IntDef标识了这个注解的作用。说明用@Flavour标识的变量，必须是0,1,2这三个int类型值，是不是很像枚举类型呢？其实它就是为了替代枚举而出现的（Android中枚举的效率稍低）。在使用的时候，我们只需要像如下标识，编译器就会自动进行判断，从而提升代码质量。
@Flavour public int getFlavour() { return flavour; } public void setFlavour(@Flavour int flavour) { this.flavour = flavour; }
如果在使用的时候传入了错误的值（不是0,1,2），编译器自动会提示警告：
好了，上面仅仅是小试牛刀，现在我们开始真正写一个编译时注解。
我希望有个注解可以帮助我们自动生成网络请求的代码，之前我们的网络请求代码是这样的：
public Observable post041(String create_time, String user_name) { HashMap<String, String> map = new HashMap<>(); map.put("create_time", create_time); map.put("user_name", user_name); map.put("name", "kale"); map.put("user", "aaaa3"); return (Observable) mHttpRequest.doPost("http://image.baidu.com", map, null); }
这种代码就是模板式代码，注解最适合干掉这样的代码了。高兴之余，先分析下需求，拆分可变部分和不可变部分是主要需求，我们的可变部分在于定义url，请求的参数，其中包含默认的请求参数还有从外部传入的请求参数，还有进行json解析的model类、是get请求还是post请求。
分析完毕，分分钟定义一个注解：
@Documented @Retention(RetentionPolicy.SOURCE) @Target(ElementType.METHOD) public @interface HttpPost { String url(); Class<?> model() default HttpProcessor.class; }
这个注解中包含两个方法，一个是url，这个是必须传入的（使用者不写就会报错）。如果你这个请求没有解析的model，那么就不用传入model对象，所以这里给一个默认的model对象。这个注解我希望出现在java doc里面，所以加上了@documented。这个注解标识的是java中的method，所以写了method，而且我希望它仅仅是在编译时有效，所以用了source。
现在定义好了，开始使用：
@HttpPost(url = "http://image.baidu.com?user=aaaa3&name=kale", model = String.class) Observable post041(String create_time, String user_name);
将url写入注解中，并且定义好model（如果不需要json解析，可以不定义），如果是必须传的参数，就和url写到一起，把需要从外部得到的注解写到方法的参数中。现在两行代码写了一个网络请求，是不是很简单呢？现在api、请求方法体、解析model的聚合度变得很高了。注意哦，现在调用这个方法其实根本不起作用，因为我们还没有去解析这个注解呢，下面来说说怎么解析。
3.2 建立解析编译时注解类
首先在as中建立一个java的lib，然后在这个lib中开始写解析类。我建立了HttpProcessor这个类，这个类继承了AbstractProcessor这个类，它会强制你实现process这个方法，这样HttpProcessor就有了解析注解的能力了。
public class HttpProcessor extends AbstractProcessor{ @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { return false; } }
接着，我在头部定义一些配置代码：
@SupportedAnnotationTypes({"kale.net.http.annotation.HttpPost"})
@SupportedSourceVersion(SourceVersion.RELEASE_7)
public class HttpProcessor extends AbstractProcessor {
上面两行代码定义了这个类能处理的注解类，并且标识了基于的java版本。写完了之后千万不要忘记了把这个注解处理类注册到项目中，注册的方法就是在resource/META-INF/services中建立一个javax.annotation.processing.Processor文件，在里面写上这个注解处理类的全名。如果你有多个注解处理类，请用回车分割。
3.2 解析注解
我们为了方便首先在init时定义好一个工具类，以后会用到。
private Elements elementUtils; @Override public synchronized void init(ProcessingEnvironment processingEnv) { super.init(processingEnv); elementUtils = processingEnv.getElementUtils(); }
然后，在process方法中开始处理传入的注解对象。需要注意的是，这个process方法会被调用多次，调用次数取决于你这个注解处理类能处理的注解个数。
@SupportedAnnotationTypes({"kale.net.http.annotation.HttpPost"})
@SupportedSourceVersion(SourceVersion.RELEASE_7)
public class HttpProcessor01 extends AbstractProcessor{
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
// 传入当前注解处理器可以处理的注解元素
for (TypeElement te : annotations) {
// 找到被标识了可处理的注解的元素
for (Element e : roundEnv.getElementsAnnotatedWith(te)) {
if (e.getKind() == ElementKind.INTERFACE) {
// 如果是接口
TypeElement ele = (TypeElement) e;
// ……
} else if (e.getKind() == ElementKind.METHOD) {
// 如果是方法
ExecutableElement method = (ExecutableElement) e;
// ……
}
}
}
return true;
}
}
代码有些复杂，我分布讲解：
@Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { // 传入当前注解处理器可以处理的注解元素 for (TypeElement te : annotations) { // 找到被标识了可处理的注解的元素 for (Element e : roundEnv.getElementsAnnotatedWith(te)) {
在这个for循环中，我们可以利用 e.getKind() 这个方法来判断注解标识的是什么对象，如果是方法就采用方法的处理逻辑，如果标识的是类就采用类的处理逻辑，如果是接口就用接口的，根据需要进行处理即可。
if (e.getKind() == ElementKind.METHOD) { // 如果是方法 ExecutableElement method = (ExecutableElement) e; if (method.getAnnotation(HttpPost.class) != null) { handlerHttp(mStringBuilder, e, method, true); ｝ }
进入if块后，我首先将e进行了强制转换，为啥要强制转换呢，因为e是标识被@httpPost标识的元素对象，但目前程序不知道它是什么类型的。我们通过之前的判断，知道它现在是方法对象，所以在这里就强转了。那么如果是接口改强转成什么呢？如果是类应该强转什么呢？来看下面的说明：
package com.example; // PackageElement
public class Foo { // TypeElement
private int a; // VariableElement
private Foo other; // VariableElement
public Foo () {} // ExecuteableElement
public void setA ( // ExecuteableElement
int newA // TypeElement
) {}
}
如果注解标识到了类中，就强转为TypeElement；
如果标识的是变量，就强转VariableElement；
如果标识内部类或者方法，强转ExecuteableElement；
如果标识方法中的参数，就强转为TypeElement。
说明：这里的每个强转后的对象都有自己好用的api，我就不详细说明了，大家可以在用的时候进行测试。
现在我们必须换个角度来看源代码，它只是结构化的文本，他不是可运行的。你可以想象它就像你将要去解析的XML文件一样（或者是编译器中抽象的语法树）。就像XML解释器一样，有一些类似DOM的元素。你可以从一个元素导航到它的父或者子元素上。
举例来说，假如你有一个代表public class Foo类的TypeElement元素，你可以遍历它的孩子，如下：
TypeElement fooClass = ... ; for (Element e : fooClass.getEnclosedElements()){ // iterate over children Element parent = e.getEnclosingElement(); // parent == fooClass }
正如你所见，Element代表的是源代码。TypeElement代表的是源代码中的类型元素，例如类。然而，TypeElement并不包含类本身的信息。你可以从TypeElement中获取类的名字，但是你获取不到类的信息，例如它的父类。这种信息需要通过TypeMirror获取。你可以通过调用elements.asType()获取元素的TypeMirror。
好，现在我们回过头来扩充上面的那段代码：
@Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { // 传入当前注解处理器可以处理的注解元素 for (TypeElement te : annotations) { // 找到被标识了可处理的注解的元素 for (Element e : roundEnv.getElementsAnnotatedWith(te)) { if (e.getKind() == ElementKind.INTERFACE) { // 如果是接口 TypeElement ele = (TypeElement) e; if (ele.getAnnotation(ApiInterface.class) != null) { String interFaceName = ele.getQualifiedName().toString(); mStringBuilder = createClsBlock(interFaceName, mStringBuilder); } else { fatalError("Should use " + ApiInterface.class.getName()); } } else if (e.getKind() == ElementKind.METHOD) { // 如果是方法 ExecutableElement method = (ExecutableElement) e; if (method.getAnnotation(HttpPost.class) != null) { handlerHttp(mStringBuilder, e, method, true); } else { handlerHttp(mStringBuilder, e, method, false); } } } } mStringBuilder.append("\n}"); createClassFile(PACKAGE_NAME, CLASS_NAME, mStringBuilder.toString()); return true; }
如果是被标识为@HttpPost的方法体，那么就开始进入handlerHttp（…）中了。这个方法的代码和注解其实没啥关系了，就是做些字符串的拼接，拼接完毕后生成一个类文件。
public void handlerHttp(StringBuilder sb, Element ele, ExecutableElement method, boolean isPost) { String url; String modelName; if (isPost) { HttpPost httpPost = ele.getAnnotation(HttpPost.class); url = httpPost.url(); try { modelName = httpPost.model().getName(); } catch (MirroredTypeException ex) { modelName = ex.getTypeMirror().toString(); } } else { HttpGet httpGet = ele.getAnnotation(HttpGet.class); url = httpGet.url(); try { modelName = httpGet.model().getName(); } catch (MirroredTypeException ex) { modelName = ex.getTypeMirror().toString(); } } if (url.equals("")) { fatalError("Url is null"); return; } log("Working on method: " + method.getSimpleName()); Map<String, String> defaultParams = UrlUtil.getParams(url); List<String> customParams = getCustomParams(method); if (modelName.equals(HttpProcessor.class.getName())) { modelName = null; } if (modelName != null && modelName.contains("<any?>")) { modelName = modelName.replace("<any?>", UrlUtil.url2packageName(url)); } url = UrlUtil.getRealUrl(url); if (isPost) { sb.append(createPostMethodBlock(method.getSimpleName().toString(), url, defaultParams, customParams, modelName)); } else { sb.append(createGetMethodBlock(method.getSimpleName().toString(), url, defaultParams, customParams, modelName)); } log("Parse method: " + method.getSimpleName() + " completed"); }
3.3 生成文件的方法
还记得我们在init中产生的工具类么，现在我们需要靠它来生成文件了。传入类包名、类名和类内部的信息就行。
private void createClassFile(String PACKAGE_NAME, String clsName, String content) { //PackageElement pkgElement = elementUtils.getPackageElement(""); TypeElement pkgElement = elementUtils.getTypeElement(PACKAGE_NAME); OutputStreamWriter osw = null; try { JavaFileObject fileObject = processingEnv.getFiler().createSourceFile(PACKAGE_NAME + "." + clsName, pkgElement); OutputStream os = fileObject.openOutputStream(); osw = new OutputStreamWriter(os, Charset.forName("UTF-8")); osw.write(content, 0, content.length()); } catch (IOException e) { e.printStackTrace(); //fatalError(e.getMessage()); } finally { try { if (osw != null) { osw.flush(); osw.close(); } } catch (IOException e) { e.printStackTrace(); fatalError(e.getMessage()); } } }
3.4 打log的方法
注解中的log有个自己的api，封装一下就是这样了：
private void log(String msg) { if (processingEnv.getOptions().containsKey("debug")) { processingEnv.getMessager().printMessage(Diagnostic.Kind.NOTE, TAG + msg); } } private void fatalError(String msg) { processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, TAG + " FATAL ERROR: " + msg); }
关于详细的代码可以参考：https://github.com/tianzhijiexian/HttpAnnotation
关于用编译时注解写工厂方法的代码：http://www.codeceo.com/article/java-annotation-processor.html
类似的用注解写网络框架的文章：http://segmentfault.com/a/1190000002785541
四、运行时注解
有时候一些注解会配合反射进行调用，比如事件总线。
/** * 事件接收函数的注解类,运用在函数上 * * @author mrsimple */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface Subscriber { /** * 事件的tag,类似于BroadcastReceiver中的Action,事件的标识符 */ String tag(); }
这种注解必须把生命周期写到Runtime，否则反射就获取不到它了。写好了后，就可以通过反射来得到它标记的元素，从而进行处理：
public void registerMethods(Object subscriber) { Class<?> clazz = subscriber.getClass(); // 查找类中符合要求的注册方法,直到Object类 while (clazz != null && !isSystemCls(clazz.getName())) { final Method[] allMethods = clazz.getDeclaredMethods(); for (Method method : allMethods) { // 根据注解来解析函数 Subscriber annotation = method.getAnnotation(Subscriber.class); if (annotation != null) { String tag = annotation.tag(); // 获取方法的tag if (!TextUtils.isEmpty(tag)) { SubscriberBean bean = new SubscriberBean(); bean.setSubscriber(subscriber); bean.setMethod(method); if (subscriberMap.containsKey(tag)) { // 如果已经有这个tag了，那么说明已经有人注册了，所以可以直接添加到注册列表中 subscriberMap.get(tag).add(bean); } else { // 如果之前没有这个tag，那么建立新的注册列表 List<SubscriberBean> list = new ArrayList<>(); list.add(bean); subscriberMap.put(tag, list); } } } } // end for // 获取父类,以继续查找父类中符合要求的方法 clazz = clazz.getSuperclass(); } }
如果想用注解干掉findviewById也是可以的。先定义一个注入的注解：
@Target(ElementType.FIELD) @Retention(RetentionPolicy.RUNTIME) public @interface InjectView { //id就是控件id，在某一个控件上使用注解标注其id int id() default -1; }
在activity中进行反射查找，找到了后利用注解自动调用findviewById即可：
public class MainActivity extends Activity { public static final String TAG=MainActivity; //标注TextView的id @InjectView(id=R.id.tv_img) private TextView mText; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); try { autoInjectAllField(this); } catch (IllegalAccessException e) { } catch (IllegalArgumentException e) { } if(mText!=null) mText.setText(Hello Gavin); } public void autoInjectAllField(Activity activity) throws IllegalAccessException, IllegalArgumentException { //得到Activity对应的Class Class clazz=this.getClass(); //得到该Activity的所有字段 Field []fields=clazz.getDeclaredFields(); Log.v(TAG, fields size-->+fields.length); for(Field field :fields) { //判断字段是否标注InjectView if(field.isAnnotationPresent(InjectView.class)) { Log.v(TAG, is injectView); //如果标注了，就获得它的id InjectView inject=field.getAnnotation(InjectView.class); int id=inject.id(); Log.v(TAG, id--->+id); if(id>0) { //反射访问私有成员，必须加上这句 field.setAccessible(true); //然后对这个属性赋值 field.set(activity, activity.findViewById(id)); } } } } }
如果你活学活用了这一特性，那么你完全可以用它做任何事情。假如你厌倦了在Android程序中打出一个完整的静态限定常量，比如：
public class CrimeActivity { public static final String ACTION_VIEW_CRIME = “com.bignerdranch.android.criminalintent.CrimeActivity.ACTION_VIEW_CRIME”; }
你完全可以使用一个运行时注解来帮你做这些事情。首先，创建一个注解类：
@Retention(RetentionPolicy.RUNTIME) @Target( { ElementType.FIELD }) public @interface ServiceConstant { }
一旦定义了注解，我们接着就要写些代码来寻找并自动填充带注解的字段：
public static void populateConstants(Class<?> klass) { String packageName = klass.getPackage().getName(); for (Field field : klass.getDeclaredFields()) { if (Modifier.isStatic(field.getModifiers()) && field.isAnnotationPresent(ServiceConstant.class)) { String value = packageName + "." + field.getName(); try { field.set(null, value); Log.i(TAG, "Setup service constant: " + value + ""); } catch (IllegalAccessException iae) { Log.e(TAG, "Unable to setup constant for field " + field.getName() + " in class " + klass.getName()); } } } }
哈哈，现在我们就可以用注解自动赋值常量了：
public class CrimeActivity { @ServiceConstant public static final String ACTION_VIEW_CRIME; static { ServiceUtils.populateConstants(CrimeActivity.class); }
得到className的小技巧：
try { modelName = httpPost.model().getName(); } catch (MirroredTypeException ex) { modelName = ex.getTypeMirror().toString(); }
参考自：
http://www.trinea.cn/android/java-annotation-android-open-source-analysis/
http://blog.zenfery.cc/archives/78.html
http://www.race604.com/annotation-processing/
http://www.2cto.com/kf/201405/302998.html
http://objccn.io/issue-11-6/
http://www.codeceo.com/article/java-annotation-processor.html
