annotation.md

Annotation

Annotation 目前已經越來越普遍使用了。這裡介紹 Android Support Library 所提供的 Annotation。
其他有很多 Library 有使用 Annotaion，例如 EventBus, ButterKnife...這裡就不敘述囉。

Explain

這些 Android Support Library 提供的註解，主要是 compile 前，先依據 Anotation 的設定檢查不合理的地方，一旦有錯誤，會直接在 Android Studio 上提醒你。所以並不是在 Compile Time or Running Time 的時候進行檢查

Setup

現在新的Project都會自帶com.android.support:appcompat，所以已經有包含 Annotations Library，如果你沒有引入，可以新增以下dependency

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

Type

以下列舉一些種類

Type	Note	Example
Resources	用在 Resource ID	@ColorRes, @IdRes, @LayoutRes, @MenuRes, ...
Null	此變數可否為 Null	@NonNull, @Nullable
Value	用來指定array的size，或是 int/float的 range	@Size, @IntRange, @FloatRange
Definition / Enum	用來指定該method只吃哪些 instance value。需要一些設定，請參照下面的範例	@IntDef, @StringDef
RGB	限制為Color Type	@ColorInt
Override	用來指定該method需要call super	@CallSuper
Return Value	指定使用該method的人要檢查/使用 return value	@CheckResult
Thread	指定該 method 要跑在什麼 Thread	@UIThread, @MainThread, @WorkerThread, @BinderThread
Proguard	防止混淆	@Keep

#Example

Null Type

  ...
  @Nullable
  public Item getItem(){
    ...
    return null;
  }
  ...
  public void setItem(@NonNull String name){
    ...
  }
  

Resource Type

  public setTitle(@StringRes int resId){
  
  }
  
  public setBackground(@DrawableRes int resId){
  
  }

Value Type

  public void setArray(@Size(2) int[] intArray){
    
  }
  
  public void setDatas(@Size(max=10) String[] stringArray){
  
  }
  
  public void setValues(@Size(multiple = 3) float[] floatArray){
      // array長度要為 3 的倍數
  }
  
  ...
  
  public void setScrore(@IntRange(from=60, to=100) int score){
  }

> *** Definition Type / Enum type***

你可以自訂特定的 int/string type，然後宣告 method argument 為該 custom type。有點像 Enum。跟Enum不同的是，該變數實際上依然是 int type，所以雖然實際實用上跟 Enum 無異，但是會比較節省資源。

  public static final int SHAPE_SQUARE = 0;
  public static final int SHAPE_TRIANGLE = 1;

  @IntDef({SHAPE_SQUARE, SHAPE_TRIANGLE})
  @Retention(RetentionPolicy.SOURCE)
  public @interface ShapeType{}
  
  ...
  
 protected @ShapeType int getShapeType(){
 }
 
 protected void setShapeType(@ShapeType int shapeType){
 }

*** Override Type***

  class MyObject{
    @CallSuper
    public void doSomething(){
    }
  }
  
  ...
  
  class ChildObject extends MyObject{
    @Override
    public void doSomething(){
          super.doSomething(); // must call
    }
  }

> *** Return Value***

確認你是否有使用 method 的回傳值

  public @CheckResult String trim(String s) { return s.trim(); }
  ...
  s.trim(); // this is probably an error
  s = s.trim(); // ok
 

> *** Thread Type ***

此方法可以用在 AsyncTask 之類的 method

  new AsyncTask<Void, Void, Void>() {
        @Override
        protected Void doInBackground(Void... params) {
            doSomething(); // correct
            updateViews(); //error
            return null;
        }
      
        @Override
        protected void onPostExecute(Void result) {
           updateViews();  // correct
       }
    };

  @UiThread
  public void updateViews() {
   
  }
  
  @@WorkerThread
  public void doSomething(){
  }

> ***Proguard***

  @Keep
  public static void doSomethging(Bitmap bitmap) {
      // this method wouldn't be confused
  }