A Look At Android Support Annotations

转自：http://anupcowkur.com/posts/a-look-at-android-support-annotations/

注：非常棒的IDEA IDE辅助功能

The Android tools team introduced some cool annotations you can use in your projects in version 19.1 of the Android support library. The support library itself uses these annotations and dogfooding is always a good sign, So let’s dig in, Shall we?

Adding them to our project is easy with gradle :

compile 'com.android.support:support-annotations:20.0.0'

There are basically three types of annotations that we can use :

• Nullness annotations
• Resource type annotations
• IntDef and StringDef annotations

We’re gonna see what each one does and how you can use it in your project with code samples.

Nullness Annotations

The @NonNull annotation indicates that a given parameter cannot be null.

In the sample code below, we have a parameter name whose value is null and it is being passed to a function sayHello which expects a non-null string:

public class MainActivity extends ActionBarActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        String name = null;

        sayHello(name);
    }


    void sayHello(@NonNull String s) {
        Toast.makeText(this, "Hello " + s, Toast.LENGTH_LONG).show();
    }

}

The IDE will notice this since we have a @NonNull annotation on the parameterString s and show us a warning:

If we assign a value to name however - let’s say String name = "Our Lord Duarte", the warning will disappear.

The @Nullable annotation indicates that a parameter or return value can be null. Suppose we have a User class with a field name accessed using User#getName, we can write the following code :

public class MainActivity extends ActionBarActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        User user = new User("Our Lord Duarte");

        Toast.makeText(this, "Hello " + getName(user), Toast.LENGTH_LONG).show();
    }

    @Nullable
    String getName(@NonNull User user) {
        return user.getName();
    }

}

Since the return value of userName is marked with a @Nullable, calling

Toast.makeText(this, "Hello " + getName(user), Toast.LENGTH_LONG).show();

without checking for null can lead to a potential crash.

Resource Type Annotations

Ever passed the wrong resource integer to a method that will happy take any int value? Resource Type annotations are here to help you with exactly that. In the code below, we have function sayHello which expects a string resource id denoted by the@StringRes annotation :

public class MainActivity extends ActionBarActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        sayHello(R.style.AppTheme);
    }


    void sayHello(@StringRes int id) {
        Toast.makeText(this, "Hello " + getString(id), Toast.LENGTH_LONG).show();
    }

}

Since we are passing in a style resource to it, the IDE will show us a warning :

Once again, if we replace the offending statement with a string resource like so :

sayHello(R.string.name);

the warning will disappear.

IntDef and StringDef Annotations

The last type of annotations we are gonna look at are based on Intellij’s “Magic Constant” inspection (we don’t need to worry about how this exactly works for our purposes but follow the link if you are curious).

Many times, we use integer constants as replacements for enumerated types. For example, let’s say we have a IceCreamFlavourManager class, which has 3 modes of operation: VANILLA, CHOCOLATE and STRAWBERRY. We can define a new annotation ourselves called @Flavour and specify the values it can take using @IntDef:

public class IceCreamFlavourManager {

    private int flavour;

    public static final int VANILLA = 0;
    public static final int CHOCOLATE = 1;
    public static final int STRAWBERRY = 2;

    @IntDef({VANILLA, CHOCOLATE, STRAWBERRY})
    public @interface Flavour {
    }

    @Flavour
    public int getFlavour() {
        return flavour;
    }

    public void setFlavour(@Flavour int flavour) {
        this.flavour = flavour;
    }

}

Then when we call IceCreamFlavourManager#setFlavour with a wrong integer value, the IDE shows us an error:

It even suggests what we can use as valid arguments:

We can also specify that the integer can be a flag, meaning that values can be combined using '|', '&' and other opeators. If we make @Flavour into a flag like this :

@IntDef(flag = true, value = {VANILLA, CHOCOLATE, STRAWBERRY})
    public @interface Flavour {
    }

we can then call :

iceCreamFlavourManager.setFlavour(IceCreamFlavourManager.VANILLA & IceCreamFlavourManager
                .CHOCOLATE);

@StringDef is basically @IntDef for strings.

For more info such as the new types of annotations that are planned to be included in the future, how these annotations depend upon and interact with Intellij’s own annotations etc, you can check out the tools site.

Thanks for reading. Annotate away!