How to write Android projects based on compile-time annotations

1. Overview

In Android application development, we often choose to use some annotation-based frameworks to improve development efficiency. However, due to the loss of operating efficiency caused by reflection, we prefer compile-time annotation frameworks, such as:

• butterknife saves us from writing code for View initialization and event injection.
• EventBus3 facilitates communication between components.
• fragmentargs easily adds parameter information to fragments and provides creation methods.
• ParcelableGenerator can automatically convert any object into a Parcelable type, making it easier to transfer objects.

There are many similar libraries. Most of these libraries are designed to automatically help us complete the parts that need to be rewritten in daily coding (for example: each View in an Activity needs to be initialized, and each object that implements the Parcelable interface requires a lot of fixed-style code).

[[192267]]

This does not mean that the above frameworks do not use reflection. In fact, some of the above frameworks still have some internal implementations that rely on reflection, but they are very few and generally cached, so relatively speaking, the efficiency impact is very small.

However, when using such projects, errors are sometimes difficult to debug. The main reason is that many users do not understand the internal principles of such frameworks, so when problems arise, they spend a lot of time troubleshooting.

So, it makes sense that at a time when the compile-time annotation framework is so popular, we have reason to learn: how to write a project that uses compile-time annotations

First, it is to understand its principles, so that when we encounter problems using similar frameworks, we can find the correct way to troubleshoot the problems; secondly, if we have good ideas and find that some codes need to be created repeatedly, we can also write a framework ourselves to facilitate our daily coding and improve coding efficiency; it can also be regarded as an improvement of our own technology.

Note: The following IDE is Android Studio.

This article will take writing a View injection framework as a clue and introduce the steps of writing such a framework in detail.

2. Preparation before writing

When writing such a framework, you generally need to create multiple modules, such as the example that this article will implement:

• ioc-annotation is used to store annotations, etc., Java modules
• ioc-compiler is used to write annotation processors, Java modules
• ioc-api is used to provide users with an API. In this case, it is an Android module.
• ioc-sample example, this example is an Android module

In addition to the example, you generally need to create three modules. You can decide the name of the module yourself. The above is a simple reference. Of course, if conditions permit, some developers like to merge the annotation storage and API modules into one module.

For dependencies between modules, since writing annotation processors requires dependencies on related annotations, so:

• ioc-compiler depends on ioc-annotation

In the process of use, we will use annotations and related APIs

• So ioc-sample depends on ioc-api; ioc-api depends on ioc-annotation

3. Implementation of Annotation Module

The annotation module is mainly used to store some annotation classes. In this example, the template Butterknife implements View injection, so this example only needs one annotation class:

 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.FIELD)
 public @interface BindView
 {
 int value();
 }

The retention strategy we set is Class, and the annotation is used on Field. Here we need to pass in an id when using it, and set it directly in the form of value.

When you are writing, analyze how many annotation classes you need and set @Target and @Retention correctly.

4. Implementation of Annotation Processor

After defining the annotation, you can write the annotation processor. This is a bit complicated, but there are rules to follow.

For this module, we generally rely on the annotation module and can use an auto-service library

The dependencies of build.gradle are as follows:

 dependencies {
    compile 'com.google.auto.service:auto-service:1.0-rc2'  
    compile project ( ':ioc-annotation' )
 }

The auto-service library can help us generate META-INF and other information.

(1) Basic code

Annotation processors generally inherit from AbstractProcessor. We just said that there are rules to follow because the writing methods of some codes are basically fixed, as follows:

 @AutoService(Processor.class)
 public class IocProcessor extends AbstractProcessor{
 private Filer mFileUtils;
    private Elements mElementUtils;
    private Messager mMessager;
 @Override
 public synchronized void init(ProcessingEnvironment processingEnv){
        super.init(processingEnv);
        mFileUtils = processingEnv.getFiler();
        mElementUtils = processingEnv.getElementUtils();
        mMessager = processingEnv.getMessager();
 }
 @Override
 public   Set <String> getSupportedAnnotationTypes(){
 Set <String> annotationTypes = new LinkedHashSet<String>();
        annotationTypes.add ( BindView.class.getCanonicalName ());
 return annotationTypes;
 }
 @Override
 public SourceVersion getSupportedSourceVersion(){
 return SourceVersion.latestSupported();
 }
 @Override
 public boolean process( Set <? extends TypeElement> annotations, RoundEnvironment roundEnv){
 }

After implementing AbstractProcessor, the process() method must be implemented, which is also the core part of our code writing, which will be introduced later.

We usually implement two methods, getSupportedAnnotationTypes() and getSupportedSourceVersion(). One of these two methods returns the supported annotation types, and the other returns the supported source code version. Refer to the code above, the writing method is basically fixed.

In addition, we will choose to override the init() method, which passes in a parameter processingEnv, which can help us initialize some parent classes:

• Filer mFileUtils; Auxiliary class related to files, generates JavaSourceCode.
• Elements mElementUtils; Auxiliary class related to elements, helping us to obtain some element-related information.
• Messager mMessager; auxiliary class related to logging.

Let's briefly mention Elemnet here. Let's take a look at its several subclasses. According to the comments below, you should have a simple understanding of it.

 Element
 - VariableElement //Generally represents a member variable
 - ExecutableElement //Generally represents a method in a class
 - TypeElement //Generally represents the class
 - PackageElement //Generally represents Package

(2) Implementation of process

The implementation in the process is a bit more complicated. Generally, you can think of it as two major steps:

• Collecting Information
• Generate proxy class (this article calls the class generated during compilation the proxy class)

What does it mean to collect information? It means getting the corresponding Element according to your annotation declaration, and then getting the information we need. This information is definitely prepared for the subsequent generation of JavaFileObject.

For example, in this example, we will generate a proxy class for each class, for example, for MainActivity we will generate a MainActivity$$ViewInjector. If annotations are declared in multiple classes, it corresponds to multiple classes, so here we need:

• A class object, representing all the information generated by the proxy class of a specific class, in this case ProxyInfo
• A collection that stores the above class objects (which will be traversed to generate proxy classes in the future). In this case, it is a Map, and the key is the full path of the class.

It doesn't matter if the description here is a bit vague, it will be easier to understand with the code later.

a. Information Collection

 private Map<String, ProxyInfo> mProxyMap = new HashMap<String, ProxyInfo>();
 @Override
 public boolean process( Set <? extends TypeElement> annotations, RoundEnvironment roundEnv){
 mProxyMap.clear();
 Set <? extends Element> elements = roundEnv.getElementsAnnotatedWith(BindView.class);
 //1. Collect information
 for (Element element : elements){
 // Check element type
        if (!checkAnnotationUseValid(element)){
 return   false ;
 }
 //field type
        VariableElement variableElement = (VariableElement) element;
 //class type
        TypeElement typeElement = (TypeElement) variableElement.getEnclosingElement();//TypeElement
        String qualifiedName = typeElement.getQualifiedName().toString(); 
 
        ProxyInfo proxyInfo = mProxyMap.get(qualifiedName);
        if (proxyInfo == null ){
            proxyInfo = new ProxyInfo(mElementUtils, typeElement);
            mProxyMap.put(qualifiedName, proxyInfo);
 }
        BindView annotation = variableElement.getAnnotation(BindView.class);
 int id = annotation.value();
        proxyInfo.mInjectElements.put(id, variableElement);
 }
 return   true ;
 }

First we call mProxyMap.clear();, because the process may be called multiple times to avoid generating duplicate proxy classes and to avoid exceptions where the class name of the generated class already exists.

Then, we get the elements annotated with @BindView through roundEnv.getElementsAnnotatedWith. The return value here should be a VariableElement collection as we expected, because we use it for member variables.

Next we for loop our elements, first checking if the type is VariableElement.

Then get the corresponding class information TypeElement, and then generate a ProxyInfo object. Here, it is checked through an mProxyMap. The key is qualifiedName, which is the full path of the class. If it is not generated, a new one will be generated. ProxyInfo corresponds to the class one by one.

Next, the VariableElement corresponding to the class and declared by @BindView will be added to ProxyInfo. The key is the id filled in when we declare it, that is, the id of the View.

This completes the collection of information. After collecting the information, you should be able to generate the proxy class.

b. Generate proxy class

 @Override
 public boolean process( Set <? extends TypeElement> annotations, RoundEnvironment roundEnv){
 //...Omit the code for collecting information and try, catch related
 for (String key : mProxyMap.keySet()){
        ProxyInfo proxyInfo = mProxyMap.get( key );
        JavaFileObject sourceFile = mFileUtils.createSourceFile(
                proxyInfo.getProxyClassFullName(), proxyInfo.getTypeElement());
            Writer writer = sourceFile.openWriter();
            writer.write(proxyInfo.generateJavaCode());
 writer.flush();
 writer.close () ;
 }
 return   true ;
 }

You can see that the code for generating the proxy class is very short. It mainly traverses our mProxyMap and then obtains each ProxyInfo. Finally, it creates a file object through mFileUtils.createSourceFile. The class name is proxyInfo.getProxyClassFullName(), and the content written is proxyInfo.generateJavaCode().

It seems that the methods for generating Java code are all in ProxyInfo.

c. Generate Java code

Here we mainly focus on how it generates Java code.

The following mainly looks at the method of generating Java code:

 #ProxyInfo
 // key is id, value is the corresponding member variable
 public Map< Integer , VariableElement> mInjectElements = new HashMap< Integer , VariableElement>(); 
 
 public String generateJavaCode(){
    StringBuilder builder = new StringBuilder();
    builder.append( "package " + mPackageName).append( ";\n\n" );
    builder.append( "import com.zhy.ioc.*;\n" );
    builder.append( "public class " ).append(mProxyClassName).append( " implements " + SUFFIX + "<" + mTypeElement.getQualifiedName() + ">" );
    builder.append( "\n{\n" );
 generateMethod(builder);
    builder.append( "\n}\n" );
 return builder.toString();
 }
 private void generateMethod(StringBuilder builder){
     builder.append( "public void inject(" +mTypeElement.getQualifiedName()+ " host , Object object )" );
    builder.append( "\n{\n" );
 for ( int id : mInjectElements.keySet()){
        VariableElement variableElement = mInjectElements.get(id);
        String name = variableElement.getSimpleName().toString();
        String type = variableElement.asType().toString(); 
 
        builder.append( " if(object instanceof android.app.Activity)" );
        builder.append( "\n{\n" );
        builder.append( "host." + name ).append( " = " );
        builder.append( "(" +type+ ")(((android.app.Activity)object).findViewById(" +id+ "));" );
        builder.append( "\n}\n" ).append( "else" ).append( "\n{\n" );
        builder.append( "host." + name ).append( " = " );
        builder.append( "(" +type+ ")(((android.view.View)object).findViewById(" +id+ "));" );
        builder.append( "\n}\n" );
 }
    builder.append( "\n}\n" );
 }

Here we mainly rely on the collected information to splice the completed proxy class object. It may seem a headache, but I will give you a generated code, which will be a lot easier to compare.

 package com.zhy.ioc_sample;
 import com.zhy.ioc.*;
 public class MainActivity$$ViewInjector implements ViewInjector<com.zhy.ioc_sample.MainActivity>{
 @Override
 public void inject(com.zhy.sample.MainActivity host , Object object ){
        if(object instanceof android.app.Activity){
            host.mTv = (android.widget.TextView)(((android.app.Activity)object).findViewById(2131492945));
 }
 else {
            host.mTv = (android.widget.TextView)(((android. view . View )object).findViewById(2131492945));
 }
 }
 }

It will be much better to look at the above code in this way. In fact, it is based on the collected member variables (declared by @BindView), and then generates Java code according to the specific requirements we want to achieve.

Please note that the generated code implements an interface ViewInjector, which is used to unify the types of all proxy class objects. When the time comes, we need to force the proxy class object to be of this interface type and call its method. The interface is generic, and the main purpose is to pass in the actual class object, such as MainActivity, because the code we are generating in the proxy class is actually the actual class. Member variables are accessed in the form of member variables, so member variables annotated at compile time are generally not allowed to be modified with the private modifier (some are allowed, but getter and setter access methods need to be provided).

Here we use a completely spliced ​​approach to write Java code. You can also use some open source libraries to generate code through the Java API, such as javapoet.

 A Java API for generating .java source files.

At this point we have completed the generation of the proxy class. The writing method of any annotation processor here basically follows the steps of collecting information and generating proxy classes.

5. Implementation of API module

After we have the proxy class, we usually provide an API for users to access. For example, the access entry in this example is

 //Activity
 Ioc.inject(Activity);
 //In Fragment, get the ViewHolder
 Ioc.inject(this, view);

Imitating butterknife, the first parameter is the host object, and the second parameter is the object that actually calls findViewById; of course, in Actiivty, the two parameters are the same.

How is an API generally written?

In fact, it is very simple. As long as you understand its principle, this API does two things:

• Find the proxy class we generated according to the passed in host: for example MainActivity->MainActity$$ViewInjector.
• Force conversion to a unified interface and call the methods provided by the interface.

These two things should not be complicated. The first thing is to concatenate the proxy class name, then generate the object by reflection, and the second thing is to force the call.

 public class Ioc{
 public   static void inject(Activity activity){
        inject(activity, activity);
 }
 public   static void inject(Object host, Object root){
        Class<?> clazz = host.getClass();
        String proxyClassFullName = clazz.getName()+ "$$ViewInjector" ;
 //Omit try, catch related code
        Class<?> proxyClazz = Class.forName(proxyClassFullName);
        ViewInjector viewInjector = (com.zhy.ioc.ViewInjector) proxyClazz.newInstance();
        viewInjector.inject(host,root);
 }
 }
 public interface ViewInjector<T>{
    void inject(T t , Object object);
 }

The code is very simple. It concatenates the full path of the proxy class, generates an instance through newInstance, and then forcibly calls the inject method of the proxy class.

Here, the generated proxy class is generally cached, for example, it is stored in a Map and not regenerated, so we will not do it here.

In this way, we have completed the writing of a compile-time annotation framework.

VI. Conclusion

This article describes how to write a project based on compile-time annotations through specific examples. The main steps are: project structure division, annotation module implementation, annotation processor writing, and API module writing. Through the study of this text, you should be able to understand the operating principles of such frameworks based on compile-time annotations, and how to write such a framework yourself.