लिंट जैसे कोड की जांच करने वाले टूल का इस्तेमाल करके, आपको समस्याओं का पता लगाने और अपने कोड को बेहतर बनाने में मदद मिल सकती है. हालांकि, जांच करने वाले टूल सिर्फ़ इतना ही अनुमान लगा सकते हैं. उदाहरण के लिए, Android रिसॉर्स आईडी, स्ट्रिंग, ग्राफ़िक, रंग, और अन्य रिसॉर्स टाइप की पहचान करने के लिए int का इस्तेमाल करते हैं. इसलिए, जांच करने वाले टूल यह नहीं बता सकते कि जहां आपको रंग रिसॉर्स का इस्तेमाल करना चाहिए था, वहां आपने स्ट्रिंग रिसॉर्स का इस्तेमाल किया है. इसका मतलब है कि कोड की जांच करने के बावजूद, आपका ऐप्लिकेशन गलत तरीके से रेंडर हो सकता है या बिलकुल भी काम नहीं कर सकता.
कोड में मौजूद ज़्यादा आसानी से नहीं दिखने वाली ऐसी समस्याओं का पता लगाने के लिए, लिंट जैसे कोड की जांच करने वाले टूल्स को एनोटेशन की मदद से अहम जानकारी दी जा सकती है. एनोटेशन, मेटाडेटा टैग के तौर पर जोड़े जाते हैं. इन्हें वैरिएबल, पैरामीटर, और रिटर्न वैल्यू से अटैच किया जाता है, ताकि मेथड की रिटर्न वैल्यू, पास किए गए पैरामीटर, लोकल वैरिएबल, और फ़ील्ड की जांच की जा सके. कोड की जांच करने वाले टूल के साथ इस्तेमाल करने पर, एनोटेशन की मदद से, आपको कई समस्याओं का पता चल सकता है. जैसे, null pointer exception और एक जैसे नाम या टाइप वाले कई रिसॉर्स की मौजूदगी से होने वाली समस्या.
Android, Jetpack एनोटेशन लाइब्रेरी की मदद से कई तरह के एनोटेशन इस्तेमाल करता है.
लाइब्रेरी को androidx.annotation पैकेज के ज़रिए ऐक्सेस किया जा सकता है.
ध्यान दें: अगर किसी मॉड्यूल में व्याख्या प्रोसेसर पर डिपेंडेंसी है, तो उस डिपेंडेंसी को जोड़ने के लिए, आपको Kotlin के लिए kapt या ksp डिपेंडेंसी कॉन्फ़िगरेशन या Java के लिए annotationProcessor डिपेंडेंसी कॉन्फ़िगरेशन का इस्तेमाल करना होगा.
अपने प्रोजेक्ट में एनोटेशन जोड़ना
अपने प्रोजेक्ट में एनोटेशन रन करने के लिए, अपनी लाइब्रेरी या ऐप्लिकेशन में androidx.annotation:annotation डिपेंडेंसी जोड़ें. कोड की जांच करने या lint टास्क चलाने पर, जोड़े गए सभी एनोटेशन की जांच की जाती है.
Jetpack Annotations लाइब्रेरी की डिपेंडेंसी जोड़ना
Jetpack Annotations लाइब्रेरी को Google के मेवन डेटाबेस पर पब्लिश किया गया है.
अपने प्रोजेक्ट में Jetpack Annotations लाइब्रेरी जोड़ने के लिए, अपनी build.gradle या build.gradle.kts फ़ाइल के dependencies ब्लॉक में यह लाइन शामिल करें:
Kotlin
dependencies { implementation("androidx.annotation:annotation:1.11.0") }
Groovy
dependencies { implementation 'androidx.annotation:annotation:1.11.0' }
अगर आपने अपने लाइब्रेरी मॉड्यूल में एनोटेशन का इस्तेमाल किया है, तो एनोटेशन को annotations.zip फ़ाइल में, एक्सएमएल फ़ॉर्मैट में Android Archive (AAR) आर्टफ़ैक्ट के हिस्से के तौर पर शामिल किया जाता है. androidx.annotation डिपेंडेंसी जोड़ने से, आपकी लाइब्रेरी के डाउनस्ट्रीम उपयोगकर्ताओं के लिए कोई डिपेंडेंसी नहीं बनती.
ध्यान दें: अगर Jetpack की अन्य लाइब्रेरी का इस्तेमाल किया जा रहा है, तो हो सकता है कि आपको androidx.annotation डिपेंडेंसी जोड़ने की ज़रूरत न पड़े. कई अन्य Jetpack लाइब्रेरी, एनोटेशन लाइब्रेरी पर निर्भर करती हैं. इसलिए, हो सकता है कि आपके पास एनोटेशन का ऐक्सेस पहले से ही हो.
Jetpack डेटाबेस में शामिल एनोटेशन की पूरी सूची देखने के लिए, Jetpack एनोटेशन लाइब्रेरी का रेफ़रंस देखें या import androidx.annotation. स्टेटमेंट के लिए उपलब्ध विकल्प दिखाने के लिए, अपने-आप पूरा होने वाली सुविधा का इस्तेमाल करें.
कोड की जांच रन करना
Android Studio से कोड की जांच शुरू करने के लिए, मेन्यू में जाकर विश्लेषण करें > कोड की जांच करें को चुनें. इसमें एनोटेशन की पुष्टि करना और लिंट की अपने-आप जांच करना शामिल है. Android Studio, संभावित समस्याओं को फ़्लैग करने के लिए, कॉन्फ़्लिक्ट मैसेज दिखाता है. ऐसा तब होता है, जब आपका कोड एनोटेशन से मेल नहीं खाता. साथ ही, यह संभावित समाधान भी सुझाता है.
कमांड लाइन का इस्तेमाल करके lint टास्क को रन करके भी एनोटेशन लागू किए जा सकते हैं. हालांकि, यह इंटिग्रेशन सर्वर में लगातार होने वाली समस्याओं को फ़्लैग करने के लिए मददगार हो सकता है, लेकिन lint टास्क, शून्य होने की जानकारी देने वाला एनोटेशन लागू नहीं करता. इन एनोटेशन के बारे में अगले सेक्शन में बताया गया है. सिर्फ़ Android Studio ऐसा करता है. लिंट की जांच करने की सुविधा चालू करने और उसे चलाने के बारे में ज़्यादा जानकारी के लिए, लिंट की जांच की मदद से अपने कोड को बेहतर बनाना लेख पढ़ें.
एनोटेशन के टकराव से चेतावनियां जनरेट होती हैं. हालांकि, इन चेतावनियों की वजह से आपके ऐप्लिकेशन को कंपाइल होने से नहीं रोका जाता.
Nullness annotations
Java कोड में, वैल्यू के शून्य होने की शर्त लागू करने के लिए, शून्यता एनोटेशन का इस्तेमाल किया जा सकता है. ये Kotlin कोड में कम काम के होते हैं, क्योंकि Kotlin में वैल्यू न होने की स्थिति के लिए पहले से नियम मौजूद होते हैं. ये नियम, कोड को कंपाइल करने के समय लागू किए जाते हैं.किसी वैरिएबल, पैरामीटर या रिटर्न वैल्यू के खाली होने की जांच करने के लिए, @Nullable और @NonNull एनोटेशन जोड़ें. @Nullable एनोटेशन से किसी ऐसे वैरिएबल, पैरामीटर या रिटर्न वैल्यू का पता चलता है जो शून्य हो सकती है.
@NonNull से किसी ऐसे वैरिएबल, पैरामीटर या रिटर्न वैल्यू का पता चलता है जो शून्य नहीं हो सकती.
उदाहरण के लिए, अगर किसी ऐसे लोकल वैरिएबल को पैरामीटर के तौर पर किसी ऐसे तरीके में पास किया जाता है जिसमें कोई वैल्यू नहीं है और उस पैरामीटर में @NonNull एनोटेशन जुड़ा है, तो कोड बनाने पर एक चेतावनी जनरेट होती है. इस चेतावनी से पता चलता है कि कोई वैल्यू मौजूद है. साथ ही, @Nullable से मार्क किए गए किसी तरीके के नतीजे का रेफ़रंस देने से पहले, शून्यता की चेतावनी जनरेट होती है. ऐसा, यह जांच किए बिना होता है कि नतीजा शून्य है या नहीं. किसी तरीके की रिटर्न वैल्यू पर @Nullable का इस्तेमाल सिर्फ़ तब करें, जब तरीके के हर इस्तेमाल के लिए साफ़ तौर पर शून्य की जांच की जानी हो.
नीचे दिए गए उदाहरण में, वैल्यू न होने की स्थिति के बारे में बताया गया है. उदाहरण के तौर पर दिया गया कोड, @NonNull एनोटेशन का इस्तेमाल नहीं करता. ऐसा इसलिए होता है, क्योंकि बिना शून्य वाला वैल्यू टाइप तय करने पर, यह जनरेट किए गए बाइट कोड में अपने-आप जुड़ जाता है:
// ... /** Annotation not used because of the safe-call operator(?)**/ override fun onCreateView( name: String, context: Context, attrs: AttributeSet ): View? { // ... } // ...
वैल्यू के शून्य होने की जांच
Android Studio में, वैल्यू के शून्य होने की संभावना का विश्लेषण करने की सुविधा है. इससे, कोड में अपने-आप अनुमान लगाया जाता है और वैल्यू के शून्य होने की जानकारी देने वाले एनोटेशन डाले जाते हैं. वैल्यू न होने की संभावना का विश्लेषण, आपके कोड में मौजूद सभी तरीकों की हैरारकी में कॉन्ट्रैक्ट को स्कैन करता है, ताकि यह पता लगाया जा सके:
- ऐसे तरीके इस्तेमाल करना जो शून्य वैल्यू दिखा सकते हैं.
- ऐसे तरीके जिनसे शून्य वैल्यू नहीं मिलनी चाहिए.
- फ़ील्ड, लोकल वैरिएबल, और पैरामीटर जैसे वैरिएबल, जिनकी वैल्यू शून्य हो सकती है.
- ऐसे वैरिएबल जिनमें कोई वैल्यू नहीं हो सकती. जैसे, फ़ील्ड, लोकल वैरिएबल, और पैरामीटर.
इसके बाद, विश्लेषण की मदद से, ढूंढी गई जगहों पर अपने-आप सही शून्य एनोटेशन डाले जाते हैं.
Android Studio में वैल्यू के शून्य होने की जांच करने के लिए, विश्लेषण करें >
शून्य होने की जानकारी पाएं को चुनें. Android Studio, आपके कोड में ढूंढी गई जगहों पर Android @Nullable और @NonNull एनोटेशन डालता है. शून्य की वैल्यू का विश्लेषण रन करने के बाद, इंजेक्ट किए गए एनोटेशन की पुष्टि करना अच्छा होता है.
ध्यान दें: शून्य की वैल्यू वाले एनोटेशन जोड़ते समय, अपने-आप जानकारी भरने की सुविधा, Android के शून्य की वैल्यू वाले एनोटेशन के बजाय, IntelliJ
@Nullable और
@NotNull एनोटेशन का सुझाव दे सकती है. साथ ही, उससे जुड़ी लाइब्रेरी अपने-आप इंपोर्ट हो सकती है. हालांकि, Android Studio के लिंट चेकर में सिर्फ़ Android के शून्य वैल्यू वाले एनोटेशन दिखते हैं. एनोटेशन की पुष्टि करते समय, पक्का करें कि आपका प्रोजेक्ट, Android के शून्य वैल्यू वाले एनोटेशन का इस्तेमाल करता हो, ताकि कोड की जांच के दौरान, लिंट चेकर आपको सही तरीके से सूचना दे सके.
रिसॉर्स के एनोटेशन
रिसॉर्स टाइप की पुष्टि करना मददगार हो सकता है, क्योंकि Android में ड्रॉ करने लायक और स्ट्रिंग जैसे रिसॉर्स के रेफ़रंस, पूर्णांक के तौर पर पास किए जाते हैं.
ऐसे कोड में, पैरामीटर के लिए किसी खास तरह के रिसॉर्स, जैसे कि String का रेफ़रंस देने की उम्मीद की जाती है. इसे int के रेफ़रंस टाइप के तौर पर पास किया जा सकता है, लेकिन असल में यह किसी दूसरे तरह के रिसॉर्स, जैसे कि R.string रिसॉर्स का रेफ़रंस देता है.
उदाहरण के लिए, @StringRes एनोटेशन जोड़कर यह पता लगाया जा सकता है कि किसी रिसॉर्स पैरामीटर में R.string रेफ़रंस है या नहीं. इसके बारे में यहां बताया गया है:
abstract fun setTitle(@StringRes resId: Int)
कोड की जांच के दौरान, अगर पैरामीटर में R.string रेफ़रंस पास नहीं किया जाता है, तो एनोटेशन से चेतावनी जनरेट होती है.
@DrawableRes, @DimenRes, @ColorRes, और @InterpolatorRes जैसे अन्य टाइप के रिसॉर्स के लिए एनोटेशन, एनोटेशन के एक ही फ़ॉर्मैट का इस्तेमाल करके जोड़े जा सकते हैं और कोड की जांच के दौरान चलाए जा सकते हैं.
अगर आपका पैरामीटर, एक से ज़्यादा तरह के रिसॉर्स के साथ काम करता है, तो किसी दिए गए पैरामीटर पर एक से ज़्यादा तरह के रिसॉर्स के एनोटेशन डाले जा सकते हैं. @AnyRes का इस्तेमाल करके बताएं कि एनोटेट किया गया पैरामीटर, किसी भी तरह का R रिसॉर्स हो सकता है.
हालांकि, @ColorRes का इस्तेमाल करके यह बताया जा सकता है कि पैरामीटर, कलर रिसॉर्स होना चाहिए. हालांकि, कलर इंटीजर (RRGGBB या AARRGGBB फ़ॉर्मैट में) को कलर रिसॉर्स के तौर पर नहीं पहचाना जाता. इसके बजाय, @ColorInt एनोटेशन का इस्तेमाल करके बताएं कि पैरामीटर, कलर इंटीजर होना चाहिए. बिल्ड टूल, ऐसे गलत कोड को फ़्लैग करेंगे जो एनोटेट किए गए तरीकों को कलर इंटीजर के बजाय, android.R.color.black जैसे कलर रिसॉर्स आईडी पास करता है.
थ्रेड एनोटेशन
थ्रेड एनोटेशन यह जांच करते हैं कि किसी तरीके को किसी खास तरह की थ्रेड से कॉल किया गया है या नहीं. थ्रेड के लिए, ये एनोटेशन इस्तेमाल किए जा सकते हैं:
बिल्ड टूल, @MainThread और @UiThread एनोटेशन को एक-दूसरे की जगह पर इस्तेमाल किए जा सकने वाले एनोटेशन के तौर पर इस्तेमाल करते हैं. इसलिए, @MainThread वाले तरीकों से @UiThread वाले तरीकों को कॉल किया जा सकता है और इसके उलट भी. हालांकि, अलग-अलग थ्रेड पर कई व्यू वाले सिस्टम ऐप्लिकेशन के मामले में, यूज़र इंटरफ़ेस (यूआई) थ्रेड मुख्य थ्रेड से अलग हो सकती है. इसलिए, आपको ऐप्लिकेशन के व्यू हैरारकी से जुड़े तरीकों को @UiThread के साथ एनोटेट करना चाहिए. साथ ही, ऐप्लिकेशन के लाइफ़साइकल से जुड़े तरीकों को सिर्फ़ @MainThread के साथ एनोटेट करना चाहिए.
अगर किसी क्लास के सभी तरीकों के लिए थ्रेडिंग की एक जैसी ज़रूरत है, तो क्लास में एक थ्रेड एनोटेशन जोड़ा जा सकता है. इससे यह पुष्टि की जा सकती है कि क्लास के सभी तरीकों को एक ही तरह की थ्रेड से कॉल किया जाता है.
थ्रेड एनोटेशन का आम तौर पर, इस बात की पुष्टि करने के लिए इस्तेमाल किया जाता है कि @WorkerThread के साथ एनोटेट किए गए तरीकों या क्लास को सिर्फ़ सही बैकग्राउंड थ्रेड से कॉल किया जाता है.
वैल्यू की सीमा तय करने वाले एनोटेशन
पास किए गए पैरामीटर की वैल्यू की पुष्टि करने के लिए, @IntRange,
@FloatRange, और
@Size एनोटेशन का इस्तेमाल करें. @IntRange और @FloatRange दोनों सबसे ज़्यादा तब काम के होते हैं, जब इन्हें उन पैरामीटर पर लागू किया जाता है जिनमें उपयोगकर्ताओं को गलत रेंज मिलने की संभावना होती है.
@IntRange एनोटेशन की मदद से यह पुष्टि की जाती है कि कोई पूर्णांक या लंबे पैरामीटर वाली वैल्यू, तय रेंज में है या नहीं. नीचे दिए गए उदाहरण से पता चलता है कि alpha
पैरामीटर में 0 से 255 के बीच की कोई पूर्णांक वैल्यू होनी चाहिए:
fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { // ... }
@FloatRange एनोटेशन की मदद से यह जांच की जाती है कि कोई फ़्लोट या डबल पैरामीटर वाली वैल्यू, फ़्लोटिंग पॉइंट वैल्यू की तय रेंज में है या नहीं. नीचे दिए गए उदाहरण से पता चलता है कि alpha पैरामीटर में 0.0 से 1.0 के बीच की कोई फ़्लोट वैल्यू होनी चाहिए:
fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) { // ... }
@Size एनोटेशन, किसी कलेक्शन या ऐरे के साइज़ या स्ट्रिंग की लंबाई की जांच करता है. @Size एनोटेशन का इस्तेमाल, इन क्वालिटी की पुष्टि करने के लिए किया जा सकता है:
- कम से कम साइज़, जैसे कि
@Size(min=2) - ज़्यादा से ज़्यादा साइज़, जैसे कि
@Size(max=2) - सटीक साइज़, जैसे कि
@Size(2) - ऐसी संख्या, साइज़ को जिसका मल्टिपल होना चाहिए जैसे कि
@Size(multiple=2)
उदाहरण के लिए, @Size(min=1)
यह जांच करता है कि कोई कलेक्शन खाली तो नहीं है. साथ ही, @Size(3)
यह पुष्टि करता है कि किसी कलेक्शन में ठीक तीन वैल्यू मौजूद हैं.
नीचे दिए गए उदाहरण से पता चलता है कि location कलेक्शन में कम से कम एक एलिमेंट होना चाहिए:
fun getLocation(button: View, @Size(min = 1) location: IntArray) { button.getLocationOnScreen(location) }
अनुमति से जुड़े एनोटेशन
किसी तरीके को कॉलर की अनुमतियों की पुष्टि करने के लिए, @RequiresPermission
एनोटेशन का इस्तेमाल करें. मान्य अनुमतियों की सूची में से किसी एक अनुमति की जांच करने के लिए, anyOf एट्रिब्यूट का इस्तेमाल करें. अनुमतियों के सेट की जांच करने के लिए, allOf एट्रिब्यूट का इस्तेमाल करें. यहां दिए गए उदाहरण में, setWallpaper() तरीके के लिए एनोटेशन दिया गया है. इससे पता चलता है कि इस तरीके के कॉलर के पास permission.SET_WALLPAPERS अनुमति होनी चाहिए:
@RequiresPermission(Manifest.permission.SET_WALLPAPER) @Throws(IOException::class) abstract fun setWallpaper(bitmap: Bitmap)
नीचे दिए गए उदाहरण में, copyImageFile() तरीके के कॉलर के पास, कॉपी की गई इमेज में मौजूद बाहरी स्टोरेज और जगह की जानकारी के मेटाडेटा, दोनों का रीड ऐक्सेस होना ज़रूरी है:
@RequiresPermission( allOf = [ Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION ] ) fun copyImageFile(dest: String, source: String) { // ... }
इंटेंट की अनुमतियों के लिए, अनुमति की ज़रूरी शर्त को उस स्ट्रिंग फ़ील्ड पर डालें जो इंटेंट कार्रवाई के नाम को तय करता है:
@RequiresPermission(android.Manifest.permission.BLUETOOTH) const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"
कॉन्टेंट देने वाली उन कंपनियों की अनुमतियों के लिए, जिन्हें कॉन्टेंट को पढ़ने और उसमें बदलाव करने के लिए अलग-अलग अनुमतियों की ज़रूरत होती है, हर अनुमति की ज़रूरत को @RequiresPermission.Read या @RequiresPermission.Write एनोटेशन में रैप करें:
@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS)) @RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS)) val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")
इनडायरेक्ट अनुमतियां
जब कोई अनुमति, किसी तरीके के पैरामीटर में दी गई खास वैल्यू पर निर्भर करती है, तो खास अनुमतियों को सूची में शामिल किए बिना, पैरामीटर पर @RequiresPermission का इस्तेमाल करें.
उदाहरण के लिए, startActivity(Intent)
तरीका, इंटेंट पर अन्य ऐप्लिकेशन से मिली अनुमतियों का इस्तेमाल करता है:
abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)
अन्य ऐप्लिकेशन से मिली अनुमतियों का इस्तेमाल करने पर, बिल्ड टूल्स डेटा फ़्लो का विश्लेषण करते हैं. इससे यह पता चलता है कि तरीके में पास किए गए तर्क में कोई @RequiresPermission एनोटेशन है या नहीं. इसके बाद, वे किसी भी मौजूदा एनोटेशन को, पैरामीटर से तरीके पर लागू कर देते हैं. startActivity(Intent) उदाहरण में, Intent क्लास में एनोटेशन होने पर, startActivity(Intent) के गलत इस्तेमाल से जुड़ी चेतावनियां दिखती हैं. ऐसा तब होता है, जब सही अनुमतियों के बिना कोई इंटेंट, तरीके को पास किया जाता है. इसकी जानकारी, पहली इमेज में दी गई है.
पहली इमेज. startActivity(Intent) तरीके पर, अन्य ऐप्लिकेशन से मिली अनुमतियों के एनोटेशन से जनरेट की गई चेतावनी.
बिल्ड टूल्स, Intent क्लास में मौजूद इंटेंट कार्रवाई के नाम पर एनोटेशन से, startActivity(Intent) पर चेतावनी जनरेट करते हैं:
@RequiresPermission(Manifest.permission.CALL_PHONE) const val ACTION_CALL = "android.intent.action.CALL"
ज़रूरत पड़ने पर, किसी तरीके के पैरामीटर को एनोटेट करते समय, @RequiresPermission.Read या @RequiresPermission.Write के बजाय @RequiresPermission का इस्तेमाल किया जा सकता है. हालांकि, अन्य ऐप्लिकेशन से मिली अनुमतियों के लिए, @RequiresPermission का इस्तेमाल, पढ़ने या फ़ाइल या एंट्री में बदलाव करने की अनुमति की अनुमतियों के एनोटेशन के साथ नहीं किया जाना चाहिए.
रिटर्न वैल्यू वाले एनोटेशन
@CheckResult एनोटेशन का इस्तेमाल करके, पुष्टि करें कि किसी तरीके के नतीजे या रिटर्न वैल्यू का असल में इस्तेमाल किया गया है. हर वैल्यू वाले तरीके के लिए, @CheckResult एनोटेट करने के बजाय, एनोटेशन जोड़ें जिससे संभावित रूप से भ्रमित करने वाले तरीकों के नतीजों को साफ़ तौर पर बताया जा सके.
उदाहरण के लिए, नए Java डेवलपर अक्सर इस ग़लतफ़हमी में रहते हैं कि
<String>.trim(), ओरिजनल स्ट्रिंग से खाली स्पेस हटा देता है. @CheckResult के साथ एनोटेट करने पर, <String>.trim() के इस्तेमाल को फ़्लैग किया जाता है. ऐसा तब किया जाता है, जब कॉलर, तरीके की रिटर्न वैल्यू का इस्तेमाल न करता हो.
नीचे दिए गए उदाहरण में, checkPermissions()
तरीके के लिए एनोटेशन दिया गया है, ताकि यह जांचा जा सके कि तरीके की रिटर्न वैल्यू का असल में रेफ़रंस दिया गया है या नहीं. इसमें enforcePermission()
तरीके को, डेवलपर को रिप्लेसमेंट के लिए सुझाए जाने वाले तरीके के तौर पर भी नाम दिया गया है:
@CheckResult(suggest = "#enforcePermission(String,int,int,String)") abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int
CallSuper एनोटेशन
@CallSuper एनोटेशन का इस्तेमाल करके पुष्टि करें कि ओवरराइड करने वाला कोई तरीका, तरीके के सुपर इंप्लिमेंटेशन को कॉल करता है.
यहां दिए गए उदाहरण में, onCreate() तरीके के लिए एनोटेशन दिया गया है. इससे यह पक्का किया जा सकता है कि ओवरराइड करने वाले किसी भी तरीके के इंप्लिमेंटेशन, super.onCreate() को कॉल करें:
@CallSuper override fun onCreate(savedInstanceState: Bundle?) { }
टाइपडेफ़ एनोटेशन
टाइपडेफ़ एनोटेशन यह जांच करते हैं कि कोई पैरामीटर, रिटर्न वैल्यू या फ़ील्ड, कॉन्स्टेंट के किसी खास सेट का रेफ़रंस देता है या नहीं. ये कोड अपने-आप पूरा होने की सुविधा को भी रन करते हैं, ताकि इस्तेमाल की अनुमति वाले कॉन्स्टेंट अपने-आप दिखें.
@IntDef और @StringDef एनोटेशन का इस्तेमाल करके, पूर्णांक और स्ट्रिंग सेट के एनोटेशन बनाएं. इससे कोड के अन्य रेफ़रंस की पुष्टि की जा सकती है.
टाइपडेफ़ एनोटेशन, एनोटेशन के नए टाइप की जानकारी देने के लिए @interface का इस्तेमाल करते हैं.
@IntDef और @StringDef एनोटेशन, @Retention के साथ मिलकर नए एनोटेशन को एनोटेट करते हैं. साथ ही, ये एनोटेशन, इन्युमरेडेट टाइप के डेटा को तय करने के लिए ज़रूरी हैं. @Retention(RetentionPolicy.SOURCE) एनोटेशन, कंपाइलर को बताता है कि इन्युमरेडेट एनोटेशन के लिए दिए गए डेटा को .class फ़ाइल में सेव न करें.
यहां दिए गए उदाहरण में, एनोटेशन बनाने का तरीका बताया गया है. इससे यह पता चलता है कि किसी तरीके के पैरामीटर के तौर पर पास की गई वैल्यू, तय की गई किसी कॉन्स्टेंट वैल्यू का रेफ़रंस देती है या नहीं:
// import androidx.annotation.IntDef // ... // Define the list of accepted constants and declare the NavigationMode annotation. @Retention(AnnotationRetention.SOURCE) @IntDef(NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS) annotation class NavigationMode // Declare the constants. const val NAVIGATION_MODE_STANDARD = 0 const val NAVIGATION_MODE_LIST = 1 const val NAVIGATION_MODE_TABS = 2 abstract class ActionBar { // Decorate the target methods with the annotation. // Attach the annotation. @get:NavigationMode @setparam:NavigationMode abstract var navigationMode: Int }
इस कोड को बनाने पर, अगर mode पैरामीटर, तय की गई किसी एक कॉन्स्टेंट वैल्यू (NAVIGATION_MODE_STANDARD,
NAVIGATION_MODE_LIST या NAVIGATION_MODE_TABS) का रेफ़रंस नहीं देता है, तो चेतावनी जनरेट होती है.
@IntDef और @IntRange को जोड़कर यह दिखाएं कि कोई पूर्णांक, कॉन्स्टेंट का एक सेट हो सकता है या किसी रेंज में मौजूद वैल्यू हो सकता है.
फ़्लैग के साथ कॉन्स्टेंट को जोड़ने की सुविधा रन करना
अगर उपयोगकर्ता, अनुमति वाले कॉन्स्टेंट को किसी फ़्लैग (जैसे, |, &, ^ वगैरह) के साथ जोड़ सकते हैं, तो flag एट्रिब्यूट के साथ एनोटेशन तय किया जा सकता है. इससे यह पता लगाया जा सकता है कि कोई पैरामीटर या रिटर्न वैल्यू, किसी मान्य पैटर्न का रेफ़रंस देती है या नहीं.
यहां दिए गए उदाहरण में, मान्य DISPLAY_ कॉन्स्टेंट की सूची के साथ DisplayOptions एनोटेशन बनाया गया है:
// import androidx.annotation.IntDef // ... @IntDef( flag = true, value = [ DISPLAY_USE_LOGO, DISPLAY_SHOW_HOME, DISPLAY_HOME_AS_UP, DISPLAY_SHOW_TITLE, DISPLAY_SHOW_CUSTOM ] ) @Retention(AnnotationRetention.SOURCE) annotation class DisplayOptions // ...
जब एनोटेशन फ़्लैग के साथ कोड बनाया जाता है, तो अगर डेकोरेट किया गया पैरामीटर या रिटर्न वैल्यू किसी मान्य पैटर्न का रेफ़रंस नहीं देती है, तो चेतावनी जनरेट होती है.
एनोटेशन बनाए रखें
@Keep एनोटेशन यह पक्का करता है कि बिल्ड के समय कोड को छोटा करने पर, एनोटेट की गई क्लास या तरीका न हटाया जाए. आम तौर पर, यह एनोटेशन उन तरीकों और क्लास में जोड़ा जाता है जिन्हें रिफ़्लेक्शन के ज़रिए ऐक्सेस किया जाता है. इससे कंपाइलर, कोड को इस्तेमाल न किए गए कोड के तौर पर नहीं देखता.
चेतावनी: @Keep का इस्तेमाल करके जिन क्लास और तरीकों को एनोटेट किया जाता है वे हमेशा आपके ऐप्लिकेशन के APK में दिखते हैं. भले ही, आपने अपने ऐप्लिकेशन के लॉजिक में कभी भी इन क्लास और तरीकों का रेफ़रंस न दिया हो.
अपने ऐप्लिकेशन का साइज़ छोटा रखने के लिए, इस बात पर विचार करें कि क्या आपके ऐप्लिकेशन में हर @Keep एनोटेशन को बनाए रखना ज़रूरी है. अगर एनोटेट की गई क्लास या तरीके को ऐक्सेस करने के लिए, रिफ़्लेक्शन का इस्तेमाल किया जाता है, तो अपने ProGuard नियमों में -if शर्त का इस्तेमाल करें. साथ ही, रिफ़्लेक्शन कॉल करने वाली क्लास की जानकारी दें.
अपने कोड को छोटा करने और यह बताने के लिए कि कौनसा कोड नहीं हटाना है, अपने ऐप्लिकेशन को छोटा करें, उसे छिपाएं, और ऑप्टिमाइज़ करें लेख पढ़ें.
कोड दिखने की सेटिंग से जुड़े एनोटेशन
कोड के कुछ हिस्सों, जैसे कि मेथड, क्लास, फ़ील्ड या पैकेज की विज़िबिलिटी दिखाने के लिए, यहां दिए गए एनोटेशन का इस्तेमाल करें.
टेस्टिंग के लिए कोड को विज़िबल बनाना
@VisibleForTesting एनोटेशन से पता चलता है कि एनोटेट किया गया तरीका, आम तौर पर ज़रूरत से ज़्यादा दिखता है, ताकि उस तरीके की जांच की जा सके. इस एनोटेशन में एक वैकल्पिक otherwise आर्ग्युमेंट होता है. इससे यह तय किया जा सकता है कि टेस्टिंग के लिए इसे दिखाने की ज़रूरत न होने पर, इस तरीके को कैसे दिखाया जाए. लिंट, otherwise आर्ग्युमेंट का इस्तेमाल करके, तय की गई विज़िबिलिटी लागू करता है.
नीचे दिए गए उदाहरण में, myMethod() आम तौर पर private होता है, लेकिन यह जांच के लिए
package-private होता है. VisibleForTesting.PRIVATE के साथ, अगर इस तरीके को private ऐक्सेस की अनुमति वाले कॉन्टेक्स्ट के बाहर से कॉल (जैसे, किसी दूसरी कंपाइलेशन यूनिट से कॉल किया गया तरीका) किया जाता है, तो लिंट एक मैसेज दिखाता है.
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) fun myMethod() { // ... }
यह बताने के लिए कि कोई तरीका सिर्फ़ टेस्टिंग के लिए मौजूद है, @VisibleForTesting(otherwise = VisibleForTesting.NONE)
का इस्तेमाल भी किया जा सकता है. यह फ़ॉर्म,
@RestrictTo(TESTS) का इस्तेमाल करने जैसा ही है. दोनों एक ही तरह की लिंट की जांच करते हैं.
किसी एपीआई पर पाबंदी लगाना
@RestrictTo
एनोटेशन से पता चलता है कि एनोटेट किए गए एपीआई (पैकेज, क्लास या तरीके) का ऐक्सेस सीमित है.
इसकी जानकारी यहां दी गई है:
सबक्लास
एपीआई के ऐक्सेस को सिर्फ़ सबक्लास तक सीमित करने के लिए, एनोटेशन फ़ॉर्म @RestrictTo(RestrictTo.Scope.SUBCLASSES) का इस्तेमाल करें.
इस एपीआई को सिर्फ़ वे क्लास ऐक्सेस कर सकती हैं जो एनोटेट की गई क्लास को एक्सटेंड करती हैं. Java
protected मॉडिफ़ायर, ऐक्सेस को पूरी तरह से सीमित नहीं करता है. इसकी वजह यह है कि यह एक ही पैकेज में मौजूद, उन क्लास से ऐक्सेस करने की अनुमति देता है जो आपस में जुड़ी नहीं हैं. इसके अलावा, कुछ मामलों में आपको आने वाले समय में बदलाव करने की सुविधा के लिए, किसी तरीके को public के तौर पर छोड़ना पड़ सकता है. ऐसा इसलिए, क्योंकि पहले से protected और ओवरराइड किए गए किसी तरीके को public नहीं बनाया जा सकता. हालांकि, आपको यह संकेत देना है कि क्लास का इस्तेमाल सिर्फ़ क्लास के अंदर या सबक्लास से किया जाना चाहिए.
लाइब्रेरी
एपीआई के ऐक्सेस को सिर्फ़ अपनी लाइब्रेरी तक सीमित करने के लिए, एनोटेशन फ़ॉर्म @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX) का इस्तेमाल करें.
एनोटेट किए गए एपीआई को सिर्फ़ आपकी लाइब्रेरी का कोड ऐक्सेस कर सकता है. इससे, अपने कोड को अपनी पसंद के पैकेज के हिसाब से व्यवस्थित करने के साथ-साथ, उस कोड को मिलती-जुलती लाइब्रेरी के ग्रुप के साथ शेयर भी किया जा सकता है. यह विकल्प, उन Jetpack लाइब्रेरी के लिए पहले से उपलब्ध है जिनमें लागू करने के लिए बहुत सारा कोड होता है. यह कोड, बाहरी इस्तेमाल के लिए नहीं होता. हालांकि, अलग-अलग तरह की अन्य Jetpack लाइब्रेरी के साथ शेयर करने के लिए, इसे public होना चाहिए.
जांच करना
दूसरे डेवलपर को आपके टेस्टिंग एपीआई ऐक्सेस करने से रोकने के लिए, एनोटेशन फ़ॉर्म @RestrictTo(RestrictTo.Scope.TESTS) का इस्तेमाल करें.
एनोटेट किए गए एपीआई को सिर्फ़ टेस्टिंग कोड ऐक्सेस कर सकता है. इससे, दूसरे डेवलपर को सिर्फ़ टेस्टिंग के मकसद से बनाए गए एपीआई को डेवलपमेंट के लिए इस्तेमाल करने से रोका जा सकता है.