转自: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!