Still using enumerations? I gave up on them a long time ago! (Android annotations explained)

Preface: Use Support Annotations to optimize code

This article explains how to use Support Annotations to optimize code, such as using Android's unique magic variable annotations to replace Enum and other functions. Don't think that reflection will affect performance when you see the use of annotations. Today we will learn about Android Support Annotations to optimize our code, increase readability, and eliminate more errors in the bud.

Support Annotations Introduction:

The Android support library continues to introduce new annotation libraries, which contain many useful meta-annotations that you can use to modify your code and help you find bugs. The support library itself also uses these annotations, so as a user of the support library, Android Studio has already verified your code based on these annotations and marked potential problems.

How to introduce Support Annotations:

Annotations are not included by default; they are packaged as a separate library. If you use the appcompat library, Support Annotations will be automatically imported because appcompat uses Support Annotations. If not, you need to add the following configuration in build.gradle:

 dependencies {
    compile 'com.android.support:support-annotations:23.4.0'  
 }

If you have already imported appcompat v7, there may be no need to reference support-annotations again, because appcompat includes a reference to it by default.

Support Annotations Category:

Typedef annotation: IntDef / StringDef (Android-specific magic variable annotation instead of Enum)

Enum in Android Enum is a complete class in Java. Each value in the enumeration is an object in the enumeration class. So when we use it, the enumeration value will consume more memory than the integer constant. When we use enumeration in Android applications, if our program itself consumes a lot of memory, or it is a game application. Then we can use constants instead of enumeration. But after using constants instead, we can't limit the value. So what's a good way?

Of course, there are some handy annotation helpers in the Android support annotation library that we can use to solve our previous problem (at compile time).

IntDef and StringDef are two magic variable annotations. Use these two to replace the Enum used before. It will help us select the function of the variable like Enum when compiling the code. @IntDef is very similar to "typedef". You can create another annotation and then use @IntDef to specify a list of integer constant values ​​you expect. Then you can modify your API with this defined annotation. Next, let's use IntDef to replace Enum.

 public class MainActivity extends Activity {
 public   static final int SUNDAY = 0;
 public   static final int MONDAY = 1;
 {... omitted} 
 
    @IntDef({SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY})
    @Retention(RetentionPolicy.SOURCE)
 public @interface WeekDays {
 } 
 
 @WeekDays
 int currentDay = SUNDAY; 
 
 @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main); 
 
        setCurrentDay(WEDNESDAY); 
 
        @WeekDays int today = getCurrentDay();
 switch (today) {
 case SUNDAY:
 break;
 case MONDAY:
 break;
 {... omitted}
 default :
 break;
 }
 } 
 
 /**
 * Parameters can only be integers within the declared range, otherwise the compilation will fail
 * @param currentDay
 */
 public void setCurrentDay(@WeekDays int currentDay) {
        this.currentDay = currentDay;
 } 
 
 @WeekDays
 public   int getCurrentDay() {
 return currentDay;
 }
 }

illustrate:

1. Declare some necessary int constants
2. Declare an annotation as WeekDays
3. Use @IntDef to modify WeekDays, and set the parameter to the collection to be enumerated
4. Use @Retention(RetentionPolicy.SOURCE) to specify that the annotation only exists in the source code and is not added to the class file.

Only the specified type must be passed in when calling. If the passed type is incorrect, the compilation will fail.

We can also specify integer values ​​as flags, which means that these integer values ​​can be ANDed or ORed using '|' or '&'. If we define @Flavour as a flag like this:

 @IntDef(flag = true , value = {SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY})
 public @interface Flavour {
 }

Then you can call it as follows:

 setCurrentDay(SUNDAY & WEDNESDAY);

The usage of @StringDef is basically the same as @IntDef, but it is only for String type.

How is it? It is quite simple to use. If you are just looking for a way to replace Enum for the title, you can jump to the end of the article and click "Like" to leave. If you want to know more about the powerful functions of annotations, then continue reading the following content!

Nullness Annotation

The @Nullable annotation can be used to indicate that a specific parameter or return value can be null.

The @NonNull annotation can be used to indicate that a parameter cannot be null.

Resource Type Annotation

Resources are passed as integer values ​​in Android. This means that code that wants to get a drawable as a parameter can easily be passed a string type resource, because their resource ids are all integers, and the compiler has difficulty distinguishing them. The Resource Type annotation can provide type checking under such conditions, for example:

If the type is specified incorrectly, the compilation will fail.

Common Resource Type annotations are used to specify an integer parameter, member variable, or method to check the corresponding resource type.

• AnimatorRes : animator resource type
• AnimRes: anim resource type
• AnyRes: any resource type
• ArrayRes: array resource type
• AttrRes: attr resource type
• BoolRes: boolean resource type
• ColorRes: color resource type
• DimenRes: dimen resource type.
• DrawableRes: drawable resource type.
• FractionRes: fraction resource type
• IdRes: id resource type
• IntegerRes: integer resource type
• InterpolatorRes: interpolator resource type
• LayoutRes: layout resource type
• MenuRes: menu resource type
• PluralsRes: plurals resource type
• RawRes: raw resource type
• StringRes: string resource type
• StyleableRes: styleable resource type
• StyleRes: style resource type
• TransitionRes: transition resource type
• XmlRes: xml resource type

The above basically covers all resource types, but sometimes you need to set the color value through RGB color integer. In this case, you can use the @ColorInt annotation to indicate that you expect an integer value representing the color. If you use it incorrectly, the compilation will also fail.

Threading Annotation

For example, if we are dealing with time-consuming operations in our project, we need to specify that they should be executed in the working sub-thread. We can use the Threading annotation. If they are not executed in the specified thread, they will not compile.

Several Threading Annotations

• @UiThread UI thread
• @MainThread Main thread
• @WorkerThread child thread
• @BinderThread binds the thread

Value Constraints annotations: @Size, @IntRange, @FloatRange

In the actual development process, we may sometimes need to set a value range. In this case, we can use the value range annotation to constrain it.

For example, we set a percentage with a value range of 0-100.

For data, collections, and strings, you can use the @Size annotation parameter to limit the size of the collection (when the parameter is a string, you can limit the length of the string).

A few examples

• The collection cannot be empty: @Size(min=1)
• The string *** can only have 23 characters: @Size(max=23)
• Arrays can only have 2 elements: @Size(2)
• The size of the array must be a multiple of 2 (for example, the x/y coordinate array of the position obtained in the graphics API: @Size(multiple=2)

Permissions annotation: @RequiresPermission

Sometimes our method calls require the caller to have specified permissions, then we can use

@RequiresPermission annotation,

 @RequiresPermission(Manifest.permission.SET_WALLPAPER)
 public abstract void setWallpaper(Bitmap bitmap) throws IOException;

In addition to the single usage method above, the official also provides the following usage scenarios

(1) If you need at least one of the permissions in the set, you can use the anyOf attribute

 @RequiresPermission(anyOf = {
    Manifest.permission.ACCESS_COARSE_LOCATION,
    Manifest.permission.ACCESS_FINE_LOCATION})
 public abstract Location getLastKnownLocation(String provider);

(2) If you need multiple permissions at the same time, you can use the allOf attribute

 @RequiresPermission(allOf = {
    Manifest.permission.READ_HISTORY_BOOKMARKS,
    Manifest.permission.WRITE_HISTORY_BOOKMARKS})
 public   static final void updateVisitedHistory(ContentResolver cr, String url, boolean real );

(3) For permissions on intents, you can directly mark the permission requirements on the defined intent constant string fields (they are usually already marked with the @SdkConstant annotation)

 @RequiresPermission(android.Manifest.permission.BLUETOOTH)
 public   static final String ACTION_REQUEST_DISCOVERABLE =
 "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE" ;

(4) For permissions on content providers, you may need to separately annotate read and write permissions, so you can annotate each permission requirement with @Read or @Write

 @RequiresPermission. Read (@RequiresPermission(READ_HISTORY_BOOKMARKS))
 @RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS))
 public   static final Uri BOOKMARKS_URI = Uri.parse( "content://browser/bookmarks" );

Overriding Methods Annotation: @CallSuper

If your API allows users to override your methods, but you need your own methods (parent methods) to be called when overriding, you can use the @CallSuper annotation.

For example: Activity's onCreate function

 @CallSuper
 protected void onCreate(@Nullable Bundle savedInstanceState)

After using this, when the overridden method does not call the parent method, the tool will give a mark prompt

Return Values ​​Annotation: @CheckResult

If your method returns a value and you expect the caller to do something with that value, you can annotate the method with the @CheckResult annotation.

This function is rarely used in actual use, except in special circumstances, such as processing a data in a project. This processing is time-consuming. We hope that the caller of this function will be prompted that it is not used when the processing result is not needed, and delete the call as appropriate.

Keep Annotation

Keep: Indicates that a method should be retained when being obfuscated.

When compiling and generating APK on Android, we usually need to set minifyEnabled to true to achieve the following two effects:

• Obfuscated code
• Delete unused code

But for some purposes, we need not to confuse some code or delete some code. In addition to configuring complex Proguard files, we can also use the @Keep annotation.

 @Keep
 public   static   int getBitmapWidth(Bitmap bitmap) {
 return bitmap.getWidth();
 }

Other notes

VisibleForTesting: You can annotate a class, method, or variable to indicate that it has looser visibility so that it can have wider visibility and make the code testable.

IntelliJ Annotations

 dependencies {
    compile 'com.intellij:annotations:12.0'  
 }

Conclusion

After consulting materials and blogs, I systematically studied and summarized the content of Support Annotations. Using Support Annotations in coding can improve code readability and check some errors when loading classes. It will not affect performance because the life cycle of annotations in Support Annotations is all RetentionPolicy.class. You can try to use it in future coding.