How to build an Android compile-time annotation framework

In Android Studio, click File -> New -> Module in the upper left corner of the menu and select Java Module. Why Java Module? As mentioned earlier, this library only involves the annotations used, so the Java type library can meet all our needs, there is no need to use android Library, otherwise it will involve extra resource files, which will make our library size larger. Permissions4m – Annotation Module screenshot below:

The first four annotations can be grouped into the following categories: callback for custom permission secondary request, callback for permission rejection, callback for permission pass, and callback for permission secondary request. PermissionsGranted PermissionsGranted PermissionsGranted

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
public @interface PermissionsGranted {
    int[] value();
}
Copy the code

Although I mentioned earlier that I wanted you to have a little bit of annotation background, I would like to point out that we need to use @Retention(retentionPolicy.class) annotations and @target (elementType.method) to mark our annotation interface. The former preserves information about the interface only until the.class period, while the latter indicates that the object that the interface decorates is a method. What does int[] value() mean? It means that if we use @permissionsgranted annotations like this, it’s not ok

@PermissionsGranted()
public void grant() {
}
Copy the code

Instead, it should be used like this:

@PermissionsGranted({1, 2})
public void grant(int code) {
}
Copy the code

or

@PermissionsGranted(1)
public void granted() {
}
Copy the code

So the simple thing is that we need to restrict the interface to passing in an integer array, so why do we need to pass in an integer array? The @permissionsgranted annotation supports callbacks for any permission request. The @permissionsgranted annotation supports callbacks for any permission request. @permissionsgranted the @permissionSgranted annotation takes an integer value as the argument to the method. The possible value of this parameter is the value of the array.

@PermissionsGranted({1, 2}) public void grant(int code) { switch (code) { case 1: break; case 2: break; case 3: // nerver break; default: break; }}Copy the code

If you’re still confused here, don’t worry, I’ll come back to this later. Specific source view: permissions4m – an annotation jokermonn/permissions4m/permissions4m – the annotation. The source code for the Permissions4m-Annotation Module is very simple

AnnotationProcessor inherits AbstractProcessor, in fact, it needs to complete two things, one is to obtain the information we need, and the other is to command ProxyInfo to generate the corresponding proxy class code, the first set of routines are as follows:

1. Constructor

private Elements mUtils;
private Filer mFiler;

@Override
public synchronized void init(ProcessingEnvironment processingEnv) {
    super.init(processingEnv);
    mUtils = processingEnv.getElementUtils();
    mFiler = processingEnv.getFiler();
}
Copy the code

MUtils can help us get information about classes that use annotations, class packages, method information, and so on, so mUtils is a very powerful and essential tool class for getting information. MFiler is the class that generates Java files, which is the utility class that we will use later to generate proxy classes.

2. Overwrite method

@Override
public Set<String> getSupportedAnnotationTypes() {
    Set<String> set = new HashSet<>(5);
    set.add(PermissionsGranted.class.getCanonicalName());
    set.add(PermissionsDenied.class.getCanonicalName());
    set.add(PermissionsRationale.class.getCanonicalName());
    set.add(PermissionsCustomRationale.class.getCanonicalName());
    set.add(PermissionsRequestSync.class.getCanonicalName());

    return set;
}

@Override
public SourceVersion getSupportedSourceVersion() {
    return SourceVersion.latestSupported();
}
Copy the code

GetSupportedAnnotationTypes () of what you need to deal with annotations getCanonicalName () Set and returns can be, And getSupportedSourceVersion (). You only need to return to the SourceVersion latestSupported (); Can.

3. Class header annotations

@AutoService(Processor.class)
public class AnnotationProcessor extends AbstractProcessor {
}
Copy the code

A set of conventions that annotate the current class with @autoService (processor.class).

4. Overwrite the process (Set

As mentioned earlier, the core method is process(), and the real logical business code in the annotator only needs to be written in this method. The source of the process method in permissions4m-Processor is as follows:

First, the handler does nothing when the method returns false and skips the current first loop, similar to continue; , and should return true if you want the processor to process it. The method is divided into two parts. The first part is to extract relevant information needed by the proxy class and stuff it to ProxyInfo. The second part is to use mFiler + ProxyInfo to generate the proxy class we need. Is it so easy? The good news is that part 2 is a set piece that doesn’t need to be flexible. The other good news is that the source code for Part 1 isn’t really that hard. The first is to create a HashMap, key/value pair for String – ProxyInfo, practical significance is to use the full path to the class notes – ProxyInfo, such as “com. Joker. Test. MainActivity” – ProxyInfo,” Com. Joker. Test. – ProxyInfo SecondActivity “, mentioned earlier, this method will be circular calls for many times, so to avoid a repeat of the proxy class, avoid the class name of the generated classes is abnormal. , we need to do map.clear() at the beginning. IsAnnotatedWithMethod (RoundEnvironment roundEnv, Class
clazz);

private boolean isAnnotatedWithMethod(RoundEnvironment roundEnv, Class<? extends Annotation> clazz) {
    Set<? extends Element> elements = roundEnv.getElementsAnnotatedWith(clazz);
    for (Element element : elements) {
        if (isValid(element)) {
            return false;
        }
        ExecutableElement method = (ExecutableElement) element;
        TypeElement typeElement = (TypeElement) method.getEnclosingElement();
        String typeName = typeElement.getQualifiedName().toString();
        ProxyInfo info = map.get(typeName);
        if (info == null) {
            info = new ProxyInfo(mUtils, typeElement);
            map.put(typeName, info);
        }

        Annotation annotation = method.getAnnotation(clazz);
        String methodName = method.getSimpleName().toString();
        if (annotation instanceof PermissionsGranted) {
            int[] value = ((PermissionsGranted) annotation).value();
            if (value.length > 1) {
                info.grantedMap.put(methodName, value);
            } else {
                info.singleGrantMap.put(value[0], methodName);
            }
        }
    }

    return true;
}
Copy the code

ExecutableElement Method = (ExecutableElement) Element; As we started parsing, we were able to ensure that annotations could be used as we wanted (methods must be annotated, public, and non-abstract), so we forced Element to be an ExecutableElement type. To represent it as a method, then we pass getEnclosingElement(); GetQualifiedName ().toString(). This function gets the current class type. TypeElement has a handy method called getQualifiedName().toString() that prints the name of a TypeElement. That’s the class name. If we find that ProxyInfo is empty, we can put a new ProxyInfo to map. To make a new ProxyInfo, we need two parameters, one is mUtils. We will most likely need to use it in ProxyInfo to get more information), one is TypeElement (our generated proxy class needs to be in the same package as it, and we also need the type of this class, For example, our TypeElement can be an Activity or Fragment, and we need to invoke different permission application apis for each type. Here are about the same, the last thing we need is the parameter annotation, we definitely will need to use it, and get the way is simple, the above code already very clear, do extends the author here, need to suggest that the author for each annotation provides two map, This is because there is a difference between the function generated when there is only one argument and when there are multiple arguments, which will be extended later.

Before writing the proxy class, I want you to consider from the overall point of view, we said earlier, API Module is actually called the proxy class method to complete, so certainly said that the proxy class must have a fixed method for API Module to call, so how to have a fixed method? The answer is the interface, and this part of the knowledge is involved in permissions4m-lib. But an interface is very easy to understand, the author is here to release the source of the interface –

public interface PermissionsProxy<T> {
    void rationale(T object, int code);

    void denied(T object, int code);

    void granted(T object, int code);

    boolean customRationale(T object, int code);

    void startSyncRequestPermissionsMethod(T object);
}
Copy the code

The first method is called when the permission is rejected, the third method is called when the permission is approved, and the fourth method refers to whether the custom second request dialog box is used. If so, it will be passed to the method modified by @permissionSrationale. If not, Then transferred to @ PermissionsCustomRationale the modification method, and finally a method is invoked when applying for more permissions synchronization API. The first parameter passed in the method is a generic type, which can only be an Activity or Fragment type, since only an Activity or Fragment can apply for permissions in Android.

This is the only Android in three module module, the Android Studio, select the File | New | module, and then select the Android library to create. Why use Android Library? Because Permissions4M-API is a developer-oriented library and involves activities and Fragment classes, you must use the Android Library. Jokermonn/permissions4m/permissions4m – API structure is as follows:

The Permissions4M interface is an interface exposed to the developer, which exposes the following methods:

• syncRequestPermissions(Activity activity)
• syncRequestPermissions(android.app.Fragment fragment)
• syncRequestPermissions(android.support.v4.app.Fragment fragment)

Apply for multiple permissions synchronously, source code is as follows:

The code is basically the same. If the current version of the application is lower than Android 6.0, nothing is done. Otherwise, initProxy() is called, passing the class as an argument to the function:

Source code is very simple, first get the className of the incoming class, in the splice into the name of the proxy class, and then use reflection to instantiate the proxy class. Let’s look again at the third step in syncRequestPermissions(), the syncRequest() method —

Be clear at a glance, is actually call the proxy class startSyncRequestPermissionsMethod (). Let’s clean up the process again – make sure the current mobile version is greater than 6.0 -> instantiate the proxy class -> invoke the proxy class’s multiple permission synchronization request methods

In fact, not only for the syncRequestPermissions() method, but also for requestPermission(), a common permission request method that permissions4m exposes to developers

The key point is the request method

Although the code looks a bit much, but if the reader has done Android 6.0 dynamic permission adaptation experience, for this code should be more familiar, I take the Activity for example, First is to call ContextCompat. CheckSelfPermission ((Activity) object, permission)! = PackageManager. PERMISSION_GRANTED) method to check whether the permission has been granted, if has been granted, then call the proxy class granted () method. If has not been awarded, then through the (object) (Activity). ShouldShowRequestPermissionRationale (permission) method determine whether the application should display the corresponding message, if you don’t show, You should direct call ActivityCompat. RequestPermissions ((Activity) object, new String [] {permission}, requestCode); Request permission, or else display information. In the module that displays the information, we need to determine whether the developer has customized the callback method for the secondary permission request. If not, we need to go to the normal secondary callback method and display the @permissionSrationale annotation modification method. Then is called ActivityCompat. RequestPermissions ((Activity) object, new String [] {permission}, requestCode); Apply for permission.

In plain English, the Activity permission request process is handled by Permissions4M, which calls the corresponding proxy method.