注解的简介
简介
Annotations, a form of metadata, provide data about a program that is not part of the program itself. Annotations have no direct effect on the operation of the code they annotate.
注释是元数据的一种形式,为程序的元素(类、方法、变量)提供一些说明,但是不会对程序本身造成影响。
- Annotation 类似一种修饰符,用于修饰包、类型、构造方法、方法、成语变量、参数的声明语句。
- Annotation 是一个接口。通过反射来访问annotation信息。根据获取的信息来决定如何使用注解信息来做一些事情。
- Annotation 不会对程序造成影响。
- Java预言解析器在工作的时候默认是忽略这些annotation,所以在JVM中"不起作用",只有通过配套的工具才能对这些注解进行访问和处理。
Annotation的使用
- Annotation的声明需要通过@interface这个关键字。会继承Annotation接口。
- Annotation的方法必须声明为无参数、无异常。方法名代表成员变量名,方法的返回值代表了成员变量的类型。而且返回值类型必须为基本数据类型、Class类型、枚举类型、String类型、Annotation类型或者由前面任意一种类型组成的一维数组。方法后面可以使用default和一个默认数值来声明一个成员变量的默认值,null不能作为成员变量的默认值。
- 注解中如果只有一个默认属性,可以直接使用value()函数,一个属性也没有的则表示该Annotation为Mark Annotation。
例如:
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Test {
String value();
}
直接使用@Test("demo"),等同于@Test(value="demo")
添加默认值:
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface TestDefault {
public String description() default "demo";
}
Annotation的作用
很多使用作为一种辅助途径,应用在软件框架或工具中。这些工具类可以根据不同的Annotation心采取不同的处理,具有"让编译器进行编译检查的功能"
具体可分为以下三种作用:
- 标记,告诉编译器一些信息(RetentionPolicy.SOURCE)
- 运行时动态处理,如通过反射的信息获取注解信息进行操作(RetentionPolicy.RUNTIME)
- 编译时动态处理,如生成代码或XML(RetentionPolicy.CLASS)
分类
标准的Annotation
从1.5开始就自带三张标准的Annotation类型:
- Override
它是一种marker类型的Annotation,用来标注方法,说明被它标注的方法是重载了父类中的方法。如果我们使用了该注解到一个没有覆盖父类方法的方法时,编译器就会提示一个编译错误的警告。 - Deprecated
它也是一种marker类型的Annotation。当方法或者变量使用该注解时,编译器就会提示该方法已经废弃。 - SuppressWarnings
它不是marker类型的Annotation。用户告诉编译器不要再对该类、方法或者成员变量进行警告提示。
元Annotation
元Annotation是指用来定义Annotation的Annotation - @Retention
保留时间,可为RetentionPolicy.SOURCE(源码时)、RetentionPolicy.CLASS(编译时)、RetentionPolicy.RUNTIME(运行时),默认为CLASS。如果值为RetentionPolicy.SOURCE那大多都是Mark Annotation,例如:Override、Deprecated。SOURCE表示仅存在于源码中,在class文件中不会包含。CLASS表示会在class文件中存在,但是运行时无法获取。RUNTIME表示会在class文件中存在,并且在运行时可以通过反射获取。 - @Target
用来标记可进行修饰哪些元素,例如ElementType.TYPE、ElementType.METHOD、ElementType.CONSTRUCTOR、ElementType.FIELD、ElementType.PARAMETER等,如果未指定则默认为可修饰所有。 - @Inherited
子类是否可以继承父类中的该注解。它所标注的Annotation将具有继承性。 - @Documented
是否会保存到javadoc文档中。
自定义Annotation
在Android的获取控件中都需要findViewById()来获取,通过注解的来获取到Id的值进行绑定例如:
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ViewInject{
int viewId();
}
注解声明完后,可以定义一些控件来使用:
@ViewInject(viewId = R.id.test)
private TextView test;
Annotation解析
- 当Java源代码被编译时,编译器的一个插件annotation处理器则会处理这些annotation。
处理器可以产生报告信息,或者创建附加的Java源文件或资源。
如果annotation本身被加上了RententionPolicy的运行时类,
则Java编译器则会将annotation的元数据存储到class文件中。然后Java虚拟机或其他的程序可以查找这些元数据并做相应的处理。 - 除了annotation处理器可以处理annotation外,我们也可以使用反射来处理annotation。Java SE 5有一个名为AnnotatedElement的接口,
Java的反射对象类Class,Constructor,Field,Method以及Package都实现了这个接口。
这个接口用来表示当前运行在Java虚拟机中的被加上了annotation的程序元素。
通过这个接口可以使用反射读取annotation。AnnotatedElement接口可以访问被加上RUNTIME标记的annotation,
相应的方法有getAnnotation,getAnnotations,isAnnotationPresent。
由于Annotation类型被编译和存储在二进制文件中就像class一样,
所以可以像查询普通的Java对象一样查询这些方法返回的Annotation。
运行时Annotation解析
该类是指@Retention为RUNTIME的Annotation。
该类型的解析其实本质的使用反射。反射执行的效率是很低的
如果不是必要,应当尽量减少反射的使用,因为它会大大拖累你应用的执行效率。
例如:
public static void viewInject(Activity activity){
Class<? extends Activity> obj=activity.getClass();
Field[] fields=obj.getDeclaredFields();//获取声明的字段
for (Field field :fields){
ViewInject viewInject=field.getAnnotation(ViewInject.class);
if(viewInject!=null){
int viewId=viewInject.viewId();
if(viewId!=-1){
try {
Method method=obj.getMethod("findViewById",int.class);
Object view=method.invoke(activity,viewId);
field.setAccessible(true);//设置属性可以访问
field.set(activity,view);
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
}
在Android的开发中使用ButterKnife他也是使用到了注解
//声明的保留时期为编译时期
@Retention(CLASS) @Target(FIELD)
public @interface BindView {
/** View ID to which the field will be bound. */
@IdRes int value();
}
使用的是编译类型的注解,这样就不会通过反射来获取数值,不会影响性能。
编译类型注解的过程:
编译类型注解的解析
- 该类型注解值是@Retention为CLASS的Annotation,由APT(Annotaion Processing Tool)自动进行解析。是在编译时注入,所以不会像反射一样影响效率问题。
- 根据sun官方的解释,APT(annotation processing tool)是一个命令行工具,
它对源代码文件进行检测找出其中的annotation后,使用annotation processors来处理annotation。
而annotation processors使用了一套反射API并具备对JSR175规范的支持。 - annotation processors处理annotation的基本过程如下:
- APT运行annotation processors根据提供的源文件中的annotation生成源代码文件和其它的文件(文件具体内容由annotation processors的编写者决定)
- 接着APT将生成的源代码文件和提供的源文件进行编译生成类文件。
- APT在编译时自动查找所有继承自AbstractProcessor的类,然后调用他们的process方法去处理,这样就拥有了在编译过程中执行代码的能力
- 所以我们需要完成的工作:
- 自定义类继承AbstractProcessor,重写process方法。
- 注册处理器,让APT能够检测的到。
- 但是在Android Studio死活提示找不到AbstractProcessor类,这是因为注解是javase中javax包里面的,android.jar默认是不包含的,所以会编译报错.
解决方法就是新建一个Module,在选择类型时将该Module的类型选为Java Library。
然后在该Module中创建就好了Processor就好了,完美解决 - Android Studio中创建一个Android工程。
- 新建一个Module,然后选择Java Library类型,并且让app依赖该module
- 在annotations的module中创建注解类
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
public @interface AnnotationTest {
String value() default "";
}
- 创建自定义的Processor类
@SupportedAnnotationTypes("com.example.AnnotationTest")
@SupportedSourceVersion(SourceVersion.RELEASE_7)
public class TestProcessor extends AbstractProcessor {
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
System.out.println("process");
for (TypeElement te : annotations) {
for (Element element : roundEnv.getElementsAnnotatedWith(te)) {
AnnotationTest annotation = element.getAnnotation(AnnotationTest.class);
String value = annotation.value();
System.out.println("type : " + value);
}
}
return true;
}
}
注意:@SupportedAnnotationTypes("com.charon.AnnotationTest")来指定要处理的注解类。
@SupportedSourceVersion(SourceVersion.RELEASE_7)指定编译的版本。这种通过注解指定编译版本和类型的方式是从Java 1.7才有的。
对于之前的版本都是通过重写AbstractProcessor中的方法来指定的。
- 注册处理器
我们自定义了Processor那如何才能让其生效呢?就是在annotations的java同级目录新建resources/META-INF/services/javax.annotation.processing.Processor文件
然后在javax.annotation.processing.Processor文件中指定自定义的处理器,如:
com.example.TestProcessor
- 在app中进行使用
进行Build会在控制台看到输出的信息。
上面只是一个简单的例子,如果你想用编译时注解去做一些更高级的事情,例如自动生成一些代码,那你可能就会用到如下几个类库:
- 以前使用android-apt,Gradle plugin 2.2提供annotationProcessor来代替了android-apt,还是建议使用官方的
As of the Android Gradle plugin version 2.2, all functionality that was previously provided by android-apt is now available in the Android plugin. This means that android-apt is officially obsolete
Here are the steps to migrate:
Make sure you are on the Android Gradle 2.2 plugin or newer.
Remove the android-apt plugin from your build scripts
Change all apt, androidTestApt and testApt dependencies to their new format:
dependencies {
compile 'com.google.dagger:dagger:2.0'
annotationProcessor 'com.google.dagger:dagger-compiler:2.0'
}
-
Google Auto的作用:
Google Auto的主要作用是注解Processor类,并对其生成META-INF的配置信息,
可以让你不用去写META-INF这些配置文件,只要在自定义的Processor上面加上@AutoService(Processor.class) -
Square javapoet的作用:
javapoet:A Java API for generating .java source files.可以更方便的生成代码,它可以帮助我们通过类调用的形式来生成代码。
自定义编译时注解
在自定义注解时,一般来说可能会建三个modules:
- app module:写一些使用注解的android应用逻辑。
- api module:定义一些可以在app中使用的注解。它会被app以及compiler使用。
- compiler module:定义Processor该module不会被包含到应用中,它只会在构建过程中被使用。在编译的过程中它会生成一些java文件,而这些java文件会被打包进apk中。
我们可以在该module中使用auto以及javapoet。
开始进行配置: - compiler module中配置auto以及javapoet
dependencies {
compile fileTree(include: ['*.jar'], dir: 'libs')
//Google Auto的主要作用是注解Processor类,并对其生成META-INF的配置信息,
//可以让你不用去写META-INF这些配置文件,只要在自定义的Processor上面加上@AutoService(Processor.class)
compile 'com.google.auto.service:auto-service:1.0-rc2'
//可以更方便的生成代码,它可以帮助我们通过类调用的形式来生成代码。
compile 'com.squareup:javapoet:1.7.0'
compile project(':apimodule')
}
- app module中gradle配置:
compile project(':compilermodule')
annotationProcessor project(':compilermodule')
- 在api module 中创建一个注解
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
public @interface Factory {
String id();
Class type();
}
- 在compiler module中自定义一个Processor
@AutoService(Processor.class)
public class MyProcessor extends AbstractProcessor {
//初始化操作的方法,RoundEnvironment会提供很多有用的工具类Elements、Types和Filer等。
@Override
public synchronized void init(ProcessingEnvironment processingEnv) {
super.init(processingEnv);
}
//这相当于每个处理器的主函数main()。在该方法中去扫描、评估、处理以及生成Java文件。
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
System.out.println("Hello Wolrd,Custom Processor");
return false;
}
//这里你必须指定,该注解器是注册给哪个注解的
@Override
public Set<String> getSupportedAnnotationTypes() {
return super.getSupportedAnnotationTypes();
}
//用来指定你使用的java版本。通常这里会直接放回SourceVersion.latestSupported()
@Override
public SourceVersion getSupportedSourceVersion() {
return SourceVersion.latestSupported();
}
}
从jdk 1.7开始,可以使用如下注解来代替getSupporedAnnotationTypes()和getSupportedSourceVersion()方法:
@SupportedSourceVersion(SourceVersion.latestSupported())
@SupportedAnnotationTypes({
// 合法注解全名的集合
})