Skip to content

Most visited

Recently visited

navigation

Memperbaiki Pemeriksaan Kode dengan Anotasi

Penggunaan alat pemeriksaan kode seperti Lint bisa membantu Anda menemukan masalah dan memperbaiki kode Anda, namun alat pemeriksaan hanya bisa menyimpulkan sejauh itu. ID sumber daya Android, misalnya, menggunakan int untuk mengidentifikasi string, grafik, warna, dan tipe sumber daya lainnya sehingga alat pemeriksaan tidak bisa membedakan kapan Anda telah menetapkan sumber daya string apabila Anda seharusnya telah menetapkan warna. Situasi ini berarti bahwa aplikasi Anda mungkin salah merender atau sama sekali gagal berjalan, bahkan jika Anda menggunakan pemeriksaan kode.

Anotasi memungkinkan Anda untuk menyediakan petunjuk untuk alat pemeriksaan kode seperti Lint, guna membantu mendeteksi masalah kode yang lebih samar. Anotasi ditambahkan sebagai tag metadata yang Anda lampirkan ke variabel, parameter, dan nilai kembalian untuk memeriksa nilai kembalian metode, meneruskan parameter, variabel lokal, dan bidang. Saat digunakan dengan alat pemeriksaan kode, anotasi bisa membantu Anda mendeteksi masalah, seperti pengecualian pointer kosong dan konflik tipe sumber daya.

Android mendukung berbagai anotasi melalui Pustaka Dukungan Anotasi. Anda bisa mengakses pustaka melalui paket android.support.annotation.

Menambahkan Anotasi ke Proyek Anda

Untuk mengaktifkan anotasi di proyek Anda, tambahkan dependensi support-annotations ke pustaka atau aplikasi. Setiap anotasi yang ditambahkan kemudian diperiksa saat Anda menjalankan pemeriksaan kode atau tugas lint.

Menambahkan Dependensi Pustaka Anotasi Dukungan

Pustaka Anotasi Dukungan merupakan bagian dari Android Support Repository. Untuk menambahkan anotasi ke proyek Anda, Anda harus mengunduh repositori dukungan dan menambahkan dependensi support-annotations ke file build.gradle Anda.

  1. Buka SDK Manager dengan mengeklik SDK Manager di bilah alat atau memilih Tools > Android > SDK Manager.
  2. Klik tab SDK Tools.
  3. Luaskan Support Repository dan pilih kotak centang Android Support Repository .
  4. Klik OK.
  5. Lanjutkan melalui wizard untuk memasang paket.
  6. Tambahkan dependensi support-annotations ke proyek Anda dengan menempatkan baris berikut di blok dependencies file build.gradle Anda:
     dependencies { compile 'com.android.support:support-annotations:24.2.0' } 
    Versi pustaka yang Anda unduh mungkin lebih tinggi sehingga pastikan nilai yang Anda tetapkan di sini cocok dengan versi dari langkah 3.
  7. Di bilah alat atau notifikasi sinkronisasi yang muncul, klik Sync Now.

Jika Anda menggunakan anotasi di modul pustaka Anda sendiri, anotasi disertakan sebagai bagian dari artifak Android Archive (AAR) dalam format XML di file annotations.zip. Penambahan dependensi support-annotations tidak memberlakukan dependensi untuk pengguna hilir mana pun dari pustaka Anda.

Jika Anda ingin menggunakan anotasi di modul Gradle yang tidak menggunakan plugin Android untuk Gradle (com.android.application atau com.android.library) tetapi menggunakan plugin Gradle Java sebagai gantinya, Anda harus menyertakan repositori SDK secara eksplisit karena Android mendukung pustaka yang tidak tersedia dari repositori JCenter Java:

repositories {
   jcenter()
   maven { url '<your-SDK-path>/extras/android/m2repository' }
}

Catatan: Jika Anda menggunakan pustaka appcompat, Anda tidak perlu menambahkan dependensi support-annotations. Karena pustaka appcompat sudah bergantung pada pustaka anotasi, Anda mempunyai akses ke anotasi.

Untuk daftar lengkap anotasi yang disertakan di repositori dukungan, periksa referensi pustaka Anotasi Dukungan atau gunakan fitur mengisi otomatis untuk menampilkan opsi yang tersedia untuk pernyataan import android.support.annotation..

Menjalankan Pemeriksaan Kode

Untuk memulai pemeriksaan kode dari Android Studio, yang mencakup validasi anotasi dan pemeriksaan Lint otomatis, pilih Analyze > Inspect Code dari bilah menu. Android Studio menampilkan pesan konflik untuk menandai potensi masalah apabila kode Anda bertentangan dengan anotasi dan menyarankan resolusi yang tepat.

Anda juga bisa memaksakan anotasi dengan menjalankan tugas lint menggunakan baris perintah. Meskipun ini mungkin berguna untuk menandai masalah server integrasi berkesinambungan, perhatikan bahwa tugas lint tidak memaksakan anotasi nullness (hanya Android Studio yang melakukannya). Untuk informasi selengkapnya tentang mengaktifkan dan menjalankan pemeriksaan Lint, lihat Memperbaiki Kode Anda dengan Lint.

Perhatikan bahwa meskipun konflik anotasi menghasilkan peringatan, peringatan ini tidak mencegah aplikasi Anda melakukan kompilasi.

Anotasi Nullness

Tambahkan anotasi @Nullable dan @NonNull untuk memeriksa nullness dari variabel, parameter, atau nilai kembalian yang diberikan. Anotasi @Nullable menunjukkan variabel, parameter, atau nilai kembalian yang boleh nol sedangkan @NonNull menunjukkan variabel, parameter, atau nilai kembalian yang tidak boleh nol.

Misalnya, jika variabel lokal yang berisi nilai nol diteruskan sebagai parameter ke metode dengan anotasi @NonNull yang terlampir pada parameter, pembangunan kode menghasilkan peringatan yang menunjukkan konflik bukan-nol. Di sisi lain, mencoba untuk mereferensikan hasil metode yang ditandai dengan @Nullable tanpa terlebih dahulu memeriksa jika hasilnya adalah nol akan menghasilkan peringatan nullness. Anda sebaiknya menggunakan @Nullable dengan metode nilai kembalian jika setiap penggunaan metode harus secara eksplisit diperiksa nol-nya.

Contoh berikut melampirkan anotasi @NonNull ke parameter context dan attrs untuk memeriksa bahwa nilai parameter yang diteruskan bukan nol. Contoh ini juga memeriksa bahwa metode onCreateView() sendirinya tidak mengembalikan nol:

import android.support.annotation.NonNull;
...

    /** Add support for inflating the <fragment> tag. **/
    @NonNull
    @Override
    public View onCreateView(String name, @NonNull Context context,
      @NonNull AttributeSet attrs) {
      ...
      }
...

Analisis Nullability

Android Studio mendukung menjalankan analisis nullability untuk secara otomatis menyimpulkan dan memasukkan anotasi nullness di kode Anda. Analisis nullability akan memindai kontrak di seluruh hierarki metode dalam kode Anda untuk mendeteksi:

Analisis kemudian secara otomatis menyisipkan anotasi nol yang tepat di lokasi yang dideteksi.

Untuk menjalankan analisis nullability di Android Studio, pilih Analyze > Infer Nullity. Android Studio menyisipkan anotasi Android @Nullable dan @NonNull di lokasi yang terdeteksi dalam kode Anda. Setelah menjalankan analisis nol, Anda sebaiknya memverifikasi anotasi yang diinjeksikan itu.

Catatan: Saat menambahkan anotasi nol, pelengkapan otomatis bisa menyarankan anotasi IntelliJ @Nullable dan @NotNull sebagai ganti anotasi nol Android dan mungkin mengimpor otomatis pustaka terkait. Akan tetapi, pemeriksa Lint Android Studio hanya mencari anotasi nol Android. Saat memverifikasi anotasi, konfirmasikan bahwa proyek Anda menggunakan anotasi nol Android sehingga pemeriksa Lint bisa dengan tepat memberi tahu Anda selama pemeriksaan kode.

Anotasi Sumber Daya

Memvalidasi tipe sumber daya bisa memberikan keuntungan karena Android merujuk pada sumber daya seperti sumber daya drawable dan string, yang diteruskan sebagai integer. Kode yang mengharapkan parameter untuk merefensikan tipe sumber daya tertentu, misalnya Drawable, bisa diteruskan sebagai tipe referensi int yang diharapkan, tetapi sebenarnya mereferensikan tipe sumber daya yang berbeda, seperti sumber daya R.string.

Misalnya, tambahkan anotasi @StringRes untuk memeriksa bahwa parameter sumber daya berisi referensi R.string, seperti ditunjukkan di sini:

public abstract void setTitle(@StringRes int resId) { … }

Selama pemeriksaan kode, anotasi menghasilkan peringatan jika referensi R.string tidak diteruskan di parameter.

Anotasi untuk tipe sumber daya lainnya, seperti @DrawableRes, @DimenRes, @ColorRes, dan @InterpolatorRes bisa ditambahkan dengan menggunakan format anotasi yang sama dan berjalan selama pemeriksaan kode. Jika parameter Anda mendukung beberapa tipe sumber daya, Anda bisa menempatkan lebih dari satu anotasi ini di parameter yang diberikan. Gunakan @AnyRes untuk menunjukkan bahwa parameter yang diberi anotasi bisa berupa segala tipe sumber daya R.

Meskipun Anda bisa menggunakan @ColorRes untuk menetapkan bahwa parameter seharusnya berupa sumber daya warna, integer warna (dalam format RRGGBB atau AARRGGBB) tidak dikenali sebagai sumber daya warna. Sebagai gantinya, gunakan anotasi @ColorInt untuk menunjukkan bahwa parameter harus berupa integer warna. Alat pembangunan akan menandai kode salah yang meneruskan ID sumber daya warna seperti android.R.color.black, bukannya integer warna, ke metode yang diberi anotasi.

Anotasi Thread

Anotasi thread memeriksa jika metode dipanggil dari tipe thread tertentu. Berikut adalah anotasi thread yang didukung:

Catatan: Alat pembangunan memperlakukan anotasi @MainThread dan @UiThread sebagai dapat saling ditukarkan sehingga Anda bisa memanggil metode @UiThread dari metode @MainThread, dan sebaliknya. Akan tetapi, ada kemungkinan thread UI berbeda dari thread utama pada aplikasi sistem dengan beberapa tampilan di thead berbeda. Karena itu, Anda sebaiknya menganotasikan metode yang terkait dengan hierarki tampilan aplikasi dengan @UiThread dan menganotasikan hanya metode yang terkait dengan daur hidup aplikasi dengan @MainThread.

Jika semua metode di sebuah kelas berbagi persyaratan threading yang sama, Anda bisa menambahkan anotasi thread tunggal ke kelas guna memverifikasi bahwa semua metode di kelas dipanggil dari tipe thread yang sama.

Penggunaan umum anotasi thread adalah untuk memvalidasi metode menggantikan kelas AsyncTask karena kelas ini menjalankan operasi latar belakang dan hanya mempublikasikan hasil di thread UI.

Anotasi Batasan Nilai

Menggunakan anotasi @IntRange, @FloatRange, dan @Size untuk memvalidasi nilai dari parameter yang diteruskan. Baik @IntRange maupun @FloatRange paling berguna saat diterapkan ke parameter, dengan pengguna paling sering memperoleh rentang yang salah.

Anotasi @IntRange memvalidasi bahwa nilai parameter integer atau long berada dalam rentang yang ditetapkan. Contoh berikut memastikan bahwa parameter alpha berisi nilai integer dari 0 sampai 255:

public void setAlpha(@IntRange(from=0,to=255) int alpha) { … }

Anotasi @FloatRange memeriksa bahwa nilai parameter float atau double berada dalam rentang nilai titik mengambang yang ditetapkan. Contoh berikut memastikan bahwa parameter alpha berisi nilai float dari 0,0 sampai 1,0:

public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}

Anotasi @Size memeriksa ukuran kumpulan atau larik, serta panjang string. Anotasi @Size bisa digunakan untuk memverifikasi kualitas berikut:

Contohnya, @Size(min=1) memeriksa jika kumpulan tidak kosong, dan @Size(3) memvalidasi bahwa sebuah larik tepat berisi tiga nilai. Contoh berikut memastikan bahwa larik location berisi setidaknya satu elemen:

int[] location = new int[3];
button.getLocationOnScreen(@Size(min=1) location);

Anotasi Izin

Menggunakan anotasi @RequiresPermission untuk memvalidasi izin pemanggil metode. Untuk memeriksa izin tunggal dari daftar izin valid, gunakan atribut anyOf. Untuk memeriksa set izin, gunakan atribut allOf. Contoh berikut menganotasikan metode setWallpaper() untuk memastikan bahwa pemanggil metode telah memiliki izin permission.SET_WALLPAPERS:

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

Contoh ini membutuhkan pemanggil metode copyFile() agar memiliki izin baca dan tulis ke penyimpanan eksternal:

@RequiresPermission(allOf = {
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.WRITE_EXTERNAL_STORAGE})
public static final void copyFile(String dest, String source) {
    ...
}

Untuk izin tentang maksud, tempatkan persyaratan izin pada bidang string yang mendefinisikan nama aksi maksud:

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

Untuk izin tentang penyedia materi yang membutuhkan izin akses baca dan tulis terpisah, bungkus setiap persyaratan izin di anotasi @RequiresPermission.Read atau @RequiresPermission.Write :

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

Izin Tidak Langsung

Saat izin bergantung pada nilai khusus yang disediakan ke parameter metode, gunakan @RequiresPermission dalam paramater itu sendiri, tanpa mendata izin khusus. Misalnya, metode startActivity(Intent) menggunakan izin tidak langsung pada maksud yang diteruskan ke metode:

public abstract void startActivity(@RequiresPermission Intent intent, @Nullable Bundle) {...}

Saat Anda menggunakan izin tidak langsung, alat pembangunan menjalankan analisis alur data untuk memeriksa jika argumen diteruskan ke dalam metode yang mempunyai anotasi @RequiresPermission apa pun. Alat itu kemudian menerapkan anotasi yang ada dari parameter pada metode itu sendiri. Dalam contoh startActivity(Intent), anotasi di kelas Intent menyebabkan munculnya peringatan tentang penggunaan startActivity(Intent) yang tidak valid saat maksud tanpa izin yang tepat diteruskan ke metode, seperti yang ditampilkan di gambar 1.

Gambar 1. Peringatan yang dihasilkan dari anotasi izin tidak langsung pada metode startActivity(Intent).

Alat pembangunan mengeluarkan peringatan di startActivity(Intent) dari anotasi pada nama aksi maksud yang bersesuaian di kelas Intent:

@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
@RequiresPermission(Manifest.permission.CALL_PHONE)
public static final String ACTION_CALL = "android.intent.action.CALL";

Jika perlu, Anda bisa mengganti @RequiresPermission dengan @RequiresPermission.Read dan/atau @RequiresPermission.Write saat menganotasikan parameter metode. Akan tetapi, izin tidak langsung @RequiresPermission sebaiknya tidak digunakan bersama dengan salah satu anotasi izin baik baca maupun tulis.

Anotasi Nilai Kembalian

Menggunakan anotasi @CheckResult untuk memvalidasi bahwa hasil atau nilai kembalian metode benar-benar digunakan. Alih-alih menganotasikan setiap metode non-void dengan @CheckResult, tambahkan anotasi untuk mengklarifikasi hasil metode yang berpotensi membingungkan. Misalnya, developer Java yang baru sering salah mengira bahwa <String>.trim() membuang spasi kosong dari string asli. Menganotasikan metode dengan @CheckResult menandai penggunaan <String>.trim() apabila pemanggil tidak melakukan apa pun dengan nilai kembalian metode.

Contoh berikut menganotasikan metode checkPermissions() untuk memastikan nilai kembalian metode benar-benar direferensikan. Contoh ini juga memberi nama metode enforcePermission() sebagai metode yang disarankan untuk developer sebagai pengganti:

@CheckResult(suggest="#enforcePermission(String,int,int,String)")
public abstract int checkPermission(@NonNull String permission, int pid, int uid);

Anotasi CallSuper

Menggunakan anotasi @CallSuper untuk memvalidasi bahwa penggantian metode akan memanggil implementasi metode yang super. Contoh berikut menganotasikan metode onCreate() untuk memastikan bahwa setiap implementasi metode penggantian akan memanggil super.onCreate():

@CallSuper
protected void onCreate(Bundle savedInstanceState) {
}

Anotasi Typedef

Menggunakan anotasi @IntDef dan @StringDef sehingga Anda bisa membuat anotasi integer yang dienumerasi dan set string untuk memvalidasi tipe referensi kode lainnya. Anotasi Typedef memastikan bahwa parameter, nilai kembalian, atau bidang tertentu mereferensikan set konstanta tertentu. Anotasi ini juga memungkinkan penyelesaian kode untuk secara otomatis menawarkan konstanta yang diizinkan.

Anotasi Typedef menggunakan @interface untuk mendeklarasikan tipe anotasi ter-enumerasi yang baru. Anotasi @IntDef dan @StringDef bersama dengan @Retention, menganotasikan anotasi baru dan diperlukan untuk mendefinisikan tipe yang dienumerasi. Anotasi @Retention(RetentionPolicy.SOURCE) memberi tahu compiler untuk tidak menyimpan data anotasi yang dienumerasi di file .class.

Contoh berikut menggambarkan langkah-langkah untuk membuat anotasi yang memastikan nilai diteruskan sebagai parameter metode yang mereferensikan salah satu konstanta yang ditetapkan:

import android.support.annotation.IntDef;
...
public abstract class ActionBar {
    ...
    // Define the list of accepted constants and declare the NavigationMode annotation
    @Retention(RetentionPolicy.SOURCE)
    @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
    public @interface NavigationMode {}

    // Declare the constants
    public static final int NAVIGATION_MODE_STANDARD = 0;
    public static final int NAVIGATION_MODE_LIST = 1;
    public static final int NAVIGATION_MODE_TABS = 2;

    // Decorate the target methods with the annotation
    @NavigationMode
    public abstract int getNavigationMode();

    // Attach the annotation
    public abstract void setNavigationMode(@NavigationMode int mode);

Saat Anda membangun kode ini, peringatan akan dikeluarkan jika parameter mode tidak mereferensikan salah satu dari konstanta yang ditetapkan (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, atau NAVIGATION_MODE_TABS).

Anda juga bisa mengombinasikan @IntDef dan @IntRange untuk menunjukkan bahwa integer dapat berupa set konstanta yang diberikan atau nilai dalam rentang.

Mengaktifkan penggabungan konstanta dengan flag

Jika pengguna bisa menggabungkan konstanta yang diizinkan dengan flag (seperti |, &, ^, dan seterusnya), Anda dapat mendefinisikan anotasi dengan atribut flag untuk memeriksa bila parameter atau nilai kembalian mereferensikan pola yang valid. Contoh berikut membuat anotasi DisplayOptions dengan daftar konstanta DISPLAY_ yang valid:

import android.support.annotation.IntDef;
...

@IntDef(flag=true, value={
        DISPLAY_USE_LOGO,
        DISPLAY_SHOW_HOME,
        DISPLAY_HOME_AS_UP,
        DISPLAY_SHOW_TITLE,
        DISPLAY_SHOW_CUSTOM
})
@Retention(RetentionPolicy.SOURCE)
public @interface DisplayOptions {}

...

Saat Anda membangun kode dengan tanda anotasi, peringatan akan dikeluarkan jika parameter yang didekorasi atau nilai kembalian tidak mereferensikan pola yang valid.

Anotasi Aksesibilitas Kode

Menggunakan anotasi @VisibleForTesting dan @Keep untuk menunjukkan aksesibilitas metode, kelas, atau bidang.

Anotasi @VisibleForTesting menunjukkan bahwa blok kode lebih terlihat daripada biasanya agar kode mudah diuji.

Anotasi @Keep memastikan bahwa elemen yang dianotasi tidak dibuang saat kode diperkecil pada waktu pembangunan. Anotasi ini biasanya ditambahkan ke metode dan kelas yang bisa diakses melalui refleksi untuk mencegah compiler menganggap bahwa kode tidak digunakan.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)