Java&Android 基礎知識梳理(1) 註解

澤毛發表於2017-12-21

一、什麼是註解

註解可以向編譯器、虛擬機器等解釋說明一些事情。舉一個最常見的例子，當我們在子類當中覆寫父類的aMethod方法時，在子類的aMethod上會用@Override來修飾它，反之，如果我們給子類的bMethod用@Override註解修飾，但是在它的父類當中並沒有這個bMethod，那麼就會報錯。這個@Override就是一種註解，它的作用是告訴編譯器它所註解的方法是重寫父類的方法，這樣編譯器就會去檢查父類是否存在這個方法。註解是用來描述Java程式碼的，它既能被編譯器解析，也能在執行時被解析。

二、元註解

元註解是描述註解的註解，也是我們編寫自定義註解的基礎，比如以下程式碼中我們使用@Target元註解來說明MethodInfo這個註解只能應用於對方法進行註解：

@Target(ElementType.METHOD)
public @interface MethodInfo {
    //....
}
複製程式碼

下面我們來介紹4種元註解，我們可以發現這四個元註解的定義又藉助到了其它的元註解：

2.1 `Documented`

當一個註解型別被@Documented元註解所描述時，那麼無論在哪裡使用這個註解，都會被Javadoc工具文件化，我們來看以下它的定義：

@Documented 
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
    //....
}
複製程式碼

定義註解時使用@interface關鍵字：
@Document表示它本身也會被文件化；
Retention表示@Documented這個註解能保留到執行時；
@ElementType.ANNOTATION_TYPE表示@Documented這個註解只能夠被用來描述註解型別。

2.2 `Inherited`

表明被修飾的註解型別是自動繼承的，若一個註解被Inherited元註解修飾，則當使用者在一個類宣告中查詢該註解型別時，若發現這個類宣告不包含這個註解型別，則會自動在這個類的父類中查詢相應的註解型別。我們需要注意的是，用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：表示在編譯時這個註解會被移除，不會包含在編譯後產生的class檔案中。
CLASS：表示這個註解會被包含在class檔案中，但在執行時會被移除。
RUNTIME：表示這個註解會被保留到執行時，我們可以在執行時通過反射解析這個註解。

2.4 `Target`

這個註解說明了被修飾的註解的應用範圍，其用法為：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target { 
    ElementType[] value();
}
複製程式碼

ElementType是一個列舉型別，它包括：

TYPE：類、介面、註解型別或列舉型別。
PACKAGE：註解包。
PARAMETER：註解引數。
ANNOTATION_TYPE：註解註解型別。
METHOD：方法。
FIELD：屬性（包括列舉常量）
CONSTRUCTOR：構造器。
LOCAL_VARIABLE：區域性變數。

三、常見註解

3.1 `@Override`

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {}
複製程式碼

告訴編譯器被修飾的方法是重寫的父類中的相同簽名的方法，編譯器會對此做出檢查，若發現父類中不存在這個方法或是存在的方法簽名不同，則會報錯。

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();
}
複製程式碼

告訴編譯器忽略指定的警告資訊。

四、自定義註解

在自定義註解前，有一些基礎知識：

註解型別是用@interface關鍵字定義的。
所有的方法均沒有方法體，且只允許public和abstract這兩種修飾符號，預設為public。
註解方法只能返回：原始資料型別，String，Class，列舉型別，註解，它們的一維陣列。

下面是一個例子：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Inherited
public @interface MethodInfo { 
  String author() default "absfree"; 
  String date(); 
  int version() default 1;
}
複製程式碼

五、註解的解析

5.1 編譯時解析

ButterKnife是解析編譯時註解很經典的例子，因為在Activity/ViewGroup/Fragment中，我們有很多的findViewById/setOnClickListener，這些程式碼具有一個特點，就是重複性很高，它們僅僅是id和返回值不同。這時候，我們就可以給需要執行findViewById的View加上註解，然後在編譯時根據規則生成特定的一些類，這些類中的方法會執行上面那些重複性的操作。

下面是網上一個大神寫的模仿ButterKnife的例子，我們來看一下編譯時解析是如果運用的。

整個專案的結構如下：

app：示例模組，它和其它3個模組的關係為：
viewfinder：android-library，它宣告瞭API的介面。
viewfinder-annotation：Java-library，包含了需要使用到的註解。
viewfinder-compiler：Java-library，包含了註解處理器。

5.1.1 建立註解

新建一個viewfinder-annotation的java-library，它包含了所需要用到的註解，注意到這個註解是保留到編譯時：

@Retention(RetentionPolicy.CLASS)
@Target(ElementType.FIELD)
public @interface BindView {
    int id();
}
複製程式碼

5.1.2 宣告`API`介面

新建一個viewfinder的android-library，用來提供給外部呼叫的介面。首先新建一個Provider介面和它的兩個實現類：

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，後面我們會根據被@BindView註解所修飾的變數所在類（host）來生成不同的Finder實現類，而這個判斷的過程並不需要使用者去關心，而是由框架的實現者在編譯器時就處理好的了。

public interface Finder<T> {

    /**
     * @param host 持有註解的類
     * @param source 呼叫方法的所在的類
     * @param provider 執行方法的類
     */
    void inject(T host, Object source, Provider provider);

}
複製程式碼

ViewFinder是ViewFinder框架的使用者唯一需要關心的類，當在Activity/Fragment/View中呼叫了inject方法時，會經過一下幾個過程：

獲得呼叫inject方法所在類的類名xxx，也就是註解類。
獲得屬於該類的xxx$$Finder，呼叫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類,都會有一個和它關聯的Host$$Finder類,它實現了Finder介面.
            if (finder == null) {
                Class<?> finderClass = Class.forName(className + "$$Finder");
                finder = (Finder) finderClass.newInstance();
                FINDER_MAP.put(className, finder);
            }
            //執行這個關聯類的inject方法.
            finder.inject(host, source, provider);
        } catch (Exception e) {
            throw new RuntimeException("Unable to inject for " + className, e);
        }
    }
}
複製程式碼

那麼這上面所有的xxx$$Finder類，到底是什麼時候產生的呢，它們的inject方法裡面又做了什麼呢，這就需要涉及到下面註解處理器的建立。

5.1.3 建立註解處理器

建立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是一一對應的關係。

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和註解類是一一對應的關係：

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方法的引數.
        MethodSpec.Builder methodBuilder = MethodSpec
                .methodBuilder("inject") //方法名.
                .addModifiers(Modifier.PUBLIC) //訪問許可權.
                .addAnnotation(Override.class) //註解.
                .addParameter(TypeName.get(mClassElement.asType()), "host", Modifier.FINAL) //引數.
                .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();

    }
}
複製程式碼

在做完前面所有的準備工作之後，後面的事情就很清楚了：

編譯時，系統會呼叫所有AbstractProcessor子類的process方法，也就是呼叫我們的ViewFinderProcess的類。
在ViewFinderProcess中，我們獲得工程下所有被@BindView註解所修飾的View。
遍歷這些被@BindView修飾的View變數，獲得它們被宣告時所在的類，首先判斷是否已經為所在的類生成了對應的AnnotatedClass，如果沒有，那麼生成一個，並將View封裝成BindViewField新增進入AnnotatedClass的列表，反之新增即可，所有的AnnotatedClass被儲存在一個map當中。
當遍歷完所有被註解修飾的View後，開始遍歷之前生成的AnnotatedClass，每個AnnotatedClass會生成一個對應的$$Finder類。
如果我們在n個類中使用了@BindView來修飾裡面的View，那麼我們最終會得到n個$$Finder類，並且無論我們最終有沒有在這n個類中呼叫ViewFinder.inject方法，都會生成這n個類；而如果我們呼叫了ViewFinder.inject，那麼最終就會通過反射來例項化它對應的$$Finder類，通過呼叫inject方法來給被它裡面被@BindView所修飾的View執行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() {}
}
複製程式碼

最後，在程式執行時，我們動態獲取註解中傳入的資訊：

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());
            }
        }
}
複製程式碼

最後得到列印出的結果為：

參考文件：

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

Java&Android 基礎知識梳理(8) 容器類
2017-12-21
JavaAndroid
Java&Android 基礎知識梳理(2) 序列化
2017-12-21
JavaAndroid
Java&Android 基礎知識梳理(10) - SparseArray 原始碼解析
2018-01-25
JavaAndroid原始碼
Java&Android 基礎知識梳理(9) - LruCache 原始碼解析
2018-01-23
JavaAndroid原始碼
Java&Android 基礎知識梳理(3) 記憶體區域
2017-12-21
JavaAndroid記憶體
Java&Android 基礎知識梳理(7) Android 虛擬機器
2017-12-21
JavaAndroid虛擬機
Java&Android 基礎知識梳理(11) - 淺拷貝 Vs 深拷貝
2018-01-30
JavaAndroid
Java&Android 基礎知識梳理(5) 類載入&物件例項化
2017-12-21
JavaAndroid物件
Java&Android 基礎知識梳理(6) 位元組輸入輸出流
2017-12-21
JavaAndroid
Kotlin 知識梳理(1) Kotlin 基礎
2017-12-21
Kotlin
Canvas&Paint 知識梳理(1) Canvas 基礎
2017-12-21
CanvasAI
Docker容器學習梳理 - 基礎知識（1）
2016-03-08
Docker
js基礎知識梳理
2019-02-17
JS
kafka基礎知識梳理
2021-06-22
Kafka
MongoDB基礎知識梳理
2023-03-29
MongoDB
Java基礎知識點梳理
2020-02-12
Java
Java&Android 基礎知識梳理(4) 垃圾收集器與記憶體分配策略
2017-12-21
JavaAndroid記憶體
Java基礎知識整理之註解
2019-01-19
Java
Python基礎知識點梳理
2020-02-08
Python
基礎知識梳理~資料庫
2019-12-14
資料庫
基礎知識梳理~ES6 解構賦值
2019-12-14
賦值
1、基礎知識
2024-09-27
Java註解知識梳理與簡單使用
2019-05-15
Java
圖片基礎知識梳理(1) ImageView 的 ScaleType 屬性解析
2017-12-21
View
RxJava 知識梳理(3) RxJava2 基礎知識小結
2017-12-21
RxJava
機器學習基礎知識梳理，新手必備！（附連結）
2019-04-24
機器學習
多執行緒基礎知識點梳理
2023-05-17
執行緒
Docker容器學習梳理 - 基礎知識（2）
2017-03-14
Docker
Docker容器學習梳理–基礎知識（2）
2017-11-27
Docker
PHP 基礎知識-1
2019-03-25
PHP
DDD基礎知識1
2018-10-24
機器學習基礎知識1
2020-10-24
機器學習
1.基礎知識
2024-07-15
DS #1 基礎知識
2024-08-15
nginx應用總結（1）-- 基礎知識和應用配置梳理
2016-11-23
Nginx
【Android】註解框架（二）基礎知識（Java註解）& 執行時註解框架
2017-12-23
Android框架Java
【Android】註解框架（一）基礎知識Java 反射
2017-12-23
Android框架Java反射
超全面的Linux基礎知識的梳理
2021-09-09
Linux

Java&Android 基礎知識梳理(1) 註解

一、什麼是註解

二、元註解

2.1 Documented

2.2 Inherited

2.3 Retention

2.4 Target