一私植、什么是注解
注解可以向編譯器、虛擬機等解釋說明一些事情车酣。舉一個最常見的例子曲稼,當我們在子類當中覆寫父類的aMethod
方法時,在子類的aMethod
上會用@Override
來修飾它湖员,反之贫悄,如果我們給子類的bMethod
用@Override
注解修飾,但是在它的父類當中并沒有這個bMethod
娘摔,那么就會報錯窄坦。這個@Override
就是一種注解,它的作用是告訴編譯器它所注解的方法是重寫父類的方法凳寺,這樣編譯器就會去檢查父類是否存在這個方法鸭津。
注解是用來描述Java
代碼的,它既能被編譯器解析肠缨,也能在運行時被解析曙博。
二、元注解
元注解是描述注解的注解怜瞒,也是我們編寫自定義注解的基礎(chǔ),比如以下代碼中我們使用@Target
元注解來說明MethodInfo
這個注解只能應(yīng)用于對方法進行注解:
@Target(ElementType.METHOD)
public @interface MethodInfo {
//....
}
下面我們來介紹4種元注解般哼,我們可以發(fā)現(xiàn)這四個元注解的定義又借助到了其它的元注解:
2.1 Documented
當一個注解類型被@Documented
元注解所描述時吴汪,那么無論在哪里使用這個注解,都會被Javadoc
工具文檔化蒸眠,我們來看以下它的定義:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
//....
}
- 定義注解時使用
@interface
關(guān)鍵字: -
@Document
表示它本身也會被文檔化漾橙; -
Retention
表示@Documented
這個注解能保留到運行時; -
@ElementType.ANNOTATION_TYPE
表示@Documented
這個注解只能夠被用來描述注解類型楞卡。
2.2 Inherited
表明被修飾的注解類型是自動繼承的霜运,若一個注解被Inherited
元注解修飾,則當用戶在一個類聲明中查詢該注解類型時蒋腮,若發(fā)現(xiàn)這個類聲明不包含這個注解類型淘捡,則會自動在這個類的父類中查詢相應(yīng)的注解類型。
我們需要注意的是池摧,用inherited
修飾的注解焦除,它的這種自動繼承功能,只能對類生效作彤,對方法是不生效的膘魄。也就是說乌逐,如果父類有一個aMethod
方法,并且該方法被注解a
修飾创葡,那么無論這個注解a
是否被Inherited
修飾浙踢,只要我們在子類中覆寫了aMethod
,子類的aMethod
都不會繼承父類aMethod
的注解灿渴,反之洛波,如果我們沒有在子類中覆寫aMethod
,那么通過子類我們依然可以獲得注解a
逻杖。
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
//....
}
2.3 Retention
這個注解表示一個注解類型會被保留到什么時候奋岁,它的原型為:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
RetentionPolicy value();
}
其中,RetentionPolicy.xxx
的取值有:
-
SOURCE
:表示在編譯時這個注解會被移除荸百,不會包含在編譯后產(chǎn)生的class
文件中闻伶。 -
CLASS
:表示這個注解會被包含在class
文件中,但在運行時會被移除够话。 -
RUNTIME
:表示這個注解會被保留到運行時蓝翰,我們可以在運行時通過反射解析這個注解。
2.4 Target
這個注解說明了被修飾的注解的應(yīng)用范圍女嘲,其用法為:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
ElementType[] value();
}
ElementType
是一個枚舉類型畜份,它包括:
-
TYPE
:類、接口欣尼、注解類型或枚舉類型爆雹。 -
PACKAGE
:注解包。 -
PARAMETER
:注解參數(shù)愕鼓。 -
ANNOTATION_TYPE
:注解 注解類型钙态。 -
METHOD
:方法。 -
FIELD
:屬性(包括枚舉常量) -
CONSTRUCTOR
:構(gòu)造器菇晃。 -
LOCAL_VARIABLE
:局部變量册倒。
三、常見注解
3.1 @Override
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {}
告訴編譯器被修飾的方法是重寫的父類中的相同簽名的方法磺送,編譯器會對此做出檢查驻子,若發(fā)現(xiàn)父類中不存在這個方法或是存在的方法簽名不同,則會報錯估灿。
3.2 @Deprecated
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {}
不建議使用這些被修飾的程序元素崇呵。
3.3 @SuppressWarnings
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
String[] value();
}
告訴編譯器忽略指定的警告信息。
四甲捏、自定義注解
在自定義注解前演熟,有一些基礎(chǔ)知識:
- 注解類型是用
@interface
關(guān)鍵字定義的。 - 所有的方法均沒有方法體,且只允許
public
和abstract
這兩種修飾符號芒粹,默認為public
兄纺。 - 注解方法只能返回:原始數(shù)據(jù)類型,
String
化漆,Class
估脆,枚舉類型,注解座云,它們的一維數(shù)組疙赠。
下面是一個例子:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Inherited
public @interface MethodInfo {
String author() default "absfree";
String date();
int version() default 1;
}
五、注解的解析
5.1 編譯時解析
ButterKnife
是解析編譯時注解很經(jīng)典的例子朦拖,因為在Activity/ViewGroup/Fragment
中圃阳,我們有很多的findViewById/setOnClickListener
,這些代碼具有一個特點璧帝,就是重復性很高捍岳,它們僅僅是id
和返回值不同。
這時候睬隶,我們就可以給需要執(zhí)行findViewById
的View
加上注解锣夹,然后在編譯時根據(jù)規(guī)則生成特定的一些類,這些類中的方法會執(zhí)行上面那些重復性的操作苏潜。
下面是網(wǎng)上一個大神寫的模仿ButterKnife
的例子银萍,我們來看一下編譯時解析是如果運用的。
整個項目的結(jié)構(gòu)如下:
-
app
:示例模塊恤左,它和其它3個模塊的關(guān)系為:
-
viewfinder
:android-library
贴唇,它聲明了API
的接口。 -
viewfinder-annotation
:Java-library
飞袋,包含了需要使用到的注解滤蝠。 -
viewfinder-compiler
:Java-library
,包含了注解處理器授嘀。
5.1.1 創(chuàng)建注解
新建一個viewfinder-annotation
的java-library
,它包含了所需要用到的注解锣险,注意到這個注解是保留到編譯時:
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.FIELD)
public @interface BindView {
int id();
}
5.1.2 聲明API
接口
新建一個viewfinder
的android-library
蹄皱,用來提供給外部調(diào)用的接口。
首先新建一個Provider
接口和它的兩個實現(xiàn)類:
public interface Provider {
Context getContext(Object source);
View findView(Object source, int id);
}
public class ActivityProvider implements Provider{
@Override
public Context getContext(Object source) {
return ((Activity) source);
}
@Override
public View findView(Object source, int id) {
return ((Activity) source).findViewById(id);
}
}
public class ViewProvider implements Provider {
@Override
public Context getContext(Object source) {
return ((View) source).getContext();
}
@Override
public View findView(Object source, int id) {
return ((View) source).findViewById(id);
}
}
定義接口Finder
芯肤,后面我們會根據(jù)被@BindView
注解所修飾的變量所在類(host
)來生成不同的Finder
實現(xiàn)類巷折,而這個判斷的過程并不需要使用者去關(guān)心,而是由框架的實現(xiàn)者在編譯器時就處理好的了崖咨。
public interface Finder<T> {
/**
* @param host 持有注解的類
* @param source 調(diào)用方法的所在的類
* @param provider 執(zhí)行方法的類
*/
void inject(T host, Object source, Provider provider);
}
ViewFinder
是ViewFinder
框架的使用者唯一需要關(guān)心的類锻拘,當在Activity/Fragment/View
中調(diào)用了inject
方法時,會經(jīng)過一下幾個過程:
- 獲得調(diào)用
inject
方法所在類的類名xxx
,也就是注解類署拟。 - 獲得屬于該類的
xxx$$Finder
婉宰,調(diào)用xxx$$Finder
的inject
方法。
public class ViewFinder {
private static final ActivityProvider PROVIDER_ACTIVITY = new ActivityProvider();
private static final ViewProvider PROVIDER_VIEW = new ViewProvider();
private static final Map<String, Finder> FINDER_MAP = new HashMap<>(); //由于使用了反射,因此緩存起來.
public static void inject(Activity activity) {
inject(activity, activity, PROVIDER_ACTIVITY);
}
public static void inject(View view) {
inject(view, view);
}
public static void inject(Object host, View view) {
inject(host, view, PROVIDER_VIEW);
}
public static void inject(Object host, Object source, Provider provider) {
String className = host.getClass().getName(); //獲得注解所在類的類名.
try {
Finder finder = FINDER_MAP.get(className); //每個Host類,都會有一個和它關(guān)聯(lián)的Host$$Finder類,它實現(xiàn)了Finder接口.
if (finder == null) {
Class<?> finderClass = Class.forName(className + "$$Finder");
finder = (Finder) finderClass.newInstance();
FINDER_MAP.put(className, finder);
}
//執(zhí)行這個關(guān)聯(lián)類的inject方法.
finder.inject(host, source, provider);
} catch (Exception e) {
throw new RuntimeException("Unable to inject for " + className, e);
}
}
}
那么這上面所有的xxx$$Finder
類推穷,到底是什么時候產(chǎn)生的呢心包,它們的inject
方法里面又做了什么呢,這就需要涉及到下面注解處理器的創(chuàng)建馒铃。
5.1.3 創(chuàng)建注解處理器
創(chuàng)建viewfinder-compiler
(java-library
)蟹腾,在build.gradle
中導入下面需要的類:
apply plugin: 'java'
dependencies {
compile fileTree(dir: 'libs', include: ['*.jar'])
compile project(':viewfinder-annotation')
compile 'com.squareup:javapoet:1.7.0'
compile 'com.google.auto.service:auto-service:1.0-rc2'
}
targetCompatibility = '1.7'
sourceCompatibility = '1.7'
TypeUtil
定義了需要用到的類的包名和類名:
public class TypeUtil {
public static final ClassName ANDROID_VIEW = ClassName.get("android.view", "View");
public static final ClassName ANDROID_ON_LONGCLICK_LISTENER = ClassName.get("android.view", "View", "OnLongClickListener");
public static final ClassName FINDER = ClassName.get("com.example.lizejun.viewfinder", "Finder");
public static final ClassName PROVIDER = ClassName.get("com.example.lizejun.viewfinder.provider", "Provider");
}
每個BindViewField
和注解類中使用了@BindView
修飾的View
是一一對應(yīng)的關(guān)系。
public class BindViewField {
private VariableElement mFieldElement;
private int mResId;
private String mInitValue;
public BindViewField(Element element) throws IllegalArgumentException {
if (element.getKind() != ElementKind.FIELD) { //判斷被注解修飾的是否是變量.
throw new IllegalArgumentException(String.format("Only fields can be annotated with @%s", BindView.class.getSimpleName()));
}
mFieldElement = (VariableElement) element; //獲得被修飾變量.
BindView bindView = mFieldElement.getAnnotation(BindView.class); //獲得被修飾變量的注解.
mResId = bindView.id(); //獲得注解的值.
}
/**
* @return 被修飾變量的名字.
*/
public Name getFieldName() {
return mFieldElement.getSimpleName();
}
/**
* @return 被修飾變量的注解的值,也就是它的id.
*/
public int getResId() {
return mResId;
}
/**
* @return 被修飾變量的注解的值.
*/
public String getInitValue() {
return mInitValue;
}
/**
* @return 被修飾變量的類型.
*/
public TypeMirror getFieldType() {
return mFieldElement.asType();
}
}
AnnotatedClass
封裝了添加被修飾注解element
区宇,通過element
列表生成JavaFile
這兩個過程娃殖,AnnotatedClass
和注解類是一一對應(yīng)的關(guān)系:
public class AnnotatedClass {
public TypeElement mClassElement;
public List<BindViewField> mFields;
public Elements mElementUtils;
public AnnotatedClass(TypeElement classElement, Elements elementUtils) {
this.mClassElement = classElement;
mFields = new ArrayList<>();
this.mElementUtils = elementUtils;
}
public String getFullClassName() {
return mClassElement.getQualifiedName().toString();
}
public void addField(BindViewField bindViewField) {
mFields.add(bindViewField);
}
public JavaFile generateFinder() {
//生成inject方法的參數(shù).
MethodSpec.Builder methodBuilder = MethodSpec
.methodBuilder("inject") //方法名.
.addModifiers(Modifier.PUBLIC) //訪問權(quán)限.
.addAnnotation(Override.class) //注解.
.addParameter(TypeName.get(mClassElement.asType()), "host", Modifier.FINAL) //參數(shù).
.addParameter(TypeName.OBJECT, "source")
.addParameter(TypeUtil.PROVIDER, "provider");
//在inject方法中,生成重復的findViewById(R.id.xxx)的語句.
for (BindViewField field : mFields) {
methodBuilder.addStatement(
"host.$N = ($T)(provider.findView(source, $L))",
field.getFieldName(),
ClassName.get(field.getFieldType()),
field.getResId());
}
//生成Host$$Finder類.
TypeSpec finderClass = TypeSpec
.classBuilder(mClassElement.getSimpleName() + "$$Finder")
.addModifiers(Modifier.PUBLIC)
.addSuperinterface(ParameterizedTypeName.get(TypeUtil.FINDER, TypeName.get(mClassElement.asType())))
.addMethod(methodBuilder.build())
.build();
//獲得包名.
String packageName = mElementUtils.getPackageOf(mClassElement).getQualifiedName().toString();
return JavaFile.builder(packageName, finderClass).build();
}
}
在做完前面所有的準備工作之后,后面的事情就很清楚了:
- 編譯時议谷,系統(tǒng)會調(diào)用所有
AbstractProcessor
子類的process
方法炉爆,也就是調(diào)用我們的ViewFinderProcess
的類。 - 在
ViewFinderProcess
中柿隙,我們獲得工程下所有被@BindView
注解所修飾的View
叶洞。 - 遍歷這些被
@BindView
修飾的View
變量,獲得它們被聲明時所在的類禀崖,首先判斷是否已經(jīng)為所在的類生成了對應(yīng)的AnnotatedClass
衩辟,如果沒有,那么生成一個波附,并將View
封裝成BindViewField
添加進入AnnotatedClass
的列表艺晴,反之添加即可,所有的AnnotatedClass
被保存在一個map
當中掸屡。 - 當遍歷完所有被注解修飾的
View
后封寞,開始遍歷之前生成的AnnotatedClass
,每個AnnotatedClass
會生成一個對應(yīng)的$$Finder
類仅财。 - 如果我們在
n
個類中使用了@BindView
來修飾里面的View
狈究,那么我們最終會得到n
個$$Finder
類,并且無論我們最終有沒有在這n
個類中調(diào)用ViewFinder.inject
方法盏求,都會生成這n
個類抖锥;而如果我們調(diào)用了ViewFinder.inject
,那么最終就會通過反射來實例化它對應(yīng)的$$Finder
類碎罚,通過調(diào)用inject
方法來給被它里面被@BindView
所修飾的View
執(zhí)行findViewById
操作磅废。
@AutoService(Processor.class)
public class ViewFinderProcess extends AbstractProcessor{
private Filer mFiler;
private Elements mElementUtils;
private Messager mMessager;
private Map<String, AnnotatedClass> mAnnotatedClassMap = new HashMap<>();
@Override
public synchronized void init(ProcessingEnvironment processingEnv) {
super.init(processingEnv);
mFiler = processingEnv.getFiler();
mElementUtils = processingEnv.getElementUtils();
mMessager = processingEnv.getMessager();
}
@Override
public Set<String> getSupportedAnnotationTypes() {
Set<String> types = new LinkedHashSet<>();
types.add(BindView.class.getCanonicalName());
return types;
}
@Override
public SourceVersion getSupportedSourceVersion() {
return SourceVersion.latestSupported();
}
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
mAnnotatedClassMap.clear();
try {
processBindView(roundEnv);
} catch (IllegalArgumentException e) {
return true;
}
for (AnnotatedClass annotatedClass : mAnnotatedClassMap.values()) { //遍歷所有要生成$$Finder的類.
try {
annotatedClass.generateFinder().writeTo(mFiler); //一次性生成.
} catch (IOException e) {
return true;
}
}
return true;
}
private void processBindView(RoundEnvironment roundEnv) throws IllegalArgumentException {
for (Element element : roundEnv.getElementsAnnotatedWith(BindView.class)) {
AnnotatedClass annotatedClass = getAnnotatedClass(element);
BindViewField field = new BindViewField(element);
annotatedClass.addField(field);
}
}
private AnnotatedClass getAnnotatedClass(Element element) {
TypeElement classElement = (TypeElement) element.getEnclosingElement();
String fullClassName = classElement.getQualifiedName().toString();
AnnotatedClass annotatedClass = mAnnotatedClassMap.get(fullClassName);
if (annotatedClass == null) {
annotatedClass = new AnnotatedClass(classElement, mElementUtils);
mAnnotatedClassMap.put(fullClassName, annotatedClass);
}
return annotatedClass;
}
}
5.2 運行時解析
首先我們需要定義注解類型,RuntimeMethodInfo
:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Inherited
public @interface RuntimeMethodInfo {
String author() default "tony";
String data();
int version() default 1;
}
之后荆烈,我們再定義一個類RuntimeMethodInfoTest
拯勉,它其中的testRuntimeMethodInfo
方法使用了這個注解,并給它其中的兩個成員變量傳入了值:
public class RuntimeMethodInfoTest {
@RuntimeMethodInfo(data = "1111", version = 2)
public void testRuntimeMethodInfo() {}
}
最后,在程序運行時宫峦,我們動態(tài)獲取注解中傳入的信息:
private void getMethodInfoAnnotation() {
Class cls = RuntimeMethodInfoTest.class;
for (Method method : cls.getMethods()) {
RuntimeMethodInfo runtimeMethodInfo = method.getAnnotation(RuntimeMethodInfo.class);
if (runtimeMethodInfo != null) {
System.out.println("RuntimeMethodInfo author=" + runtimeMethodInfo.author());
System.out.println("RuntimeMethodInfo data=" + runtimeMethodInfo.data());
System.out.println("RuntimeMethodInfo version=" + runtimeMethodInfo.version());
}
}
}
最后得到打印出的結(jié)果為:
參考文檔:
1.http://blog.csdn.net/lemon89/article/details/47836783
2.http://blog.csdn.net/hb707934728/article/details/52213086
3.https://github.com/brucezz/ViewFinder
4.http://www.cnblogs.com/peida/archive/2013/04/24/3036689.html