L'utilizzo di strumenti di ispezione del codice, come lint, può aiutarti a individuare i problemi e a migliorare il codice, ma gli strumenti di ispezione possono solo dedurre. Gli ID risorsa Android, ad esempio, utilizzano un int
per identificare stringhe, immagini, colori e altri tipi di risorse, in modo che gli strumenti di ispezione non possano rilevare quando hai specificato una risorsa stringa in cui avresti dovuto specificare un colore. Questa situazione significa che l'app potrebbe non essere visualizzata correttamente o non essere eseguita affatto, anche se utilizzi l'ispezione del codice.
Le annotazioni consentono di fornire suggerimenti agli strumenti di ispezione del codice, ad esempio lint, per contribuire a rilevare questi problemi più sottili relativi al codice. Le annotazioni vengono aggiunte come tag di metadati che associ a variabili, parametri e valori restituiti per ispezionare valori restituiti dal metodo, parametri trasmessi, variabili locali e campi. Se utilizzate con gli strumenti di ispezione del codice, le annotazioni possono aiutarti a rilevare problemi come eccezioni di puntatore nullo e conflitti di tipo di risorsa.
Android supporta una varietà di annotazioni tramite la libreria delle annotazioni Jetpack.
Puoi accedere alla libreria tramite il pacchetto androidx.annotation
.
Nota: se un modulo ha una dipendenza da un processore di annotazione,
devi utilizzare la configurazione delle dipendenze kapt
o ksp
per Kotlin
o la configurazione delle dipendenze annotationProcessor
per Java per aggiungere questa
dipendenza.
Aggiungere annotazioni al progetto
Per attivare le annotazioni nel progetto, aggiungi la dipendenza androidx.annotation:annotation
alla libreria o all'app. Tutte le annotazioni aggiunte vengono controllate quando esegui un'ispezione del codice o un'attività lint
.
Aggiungi la dipendenza della libreria delle annotazioni Jetpack
La libreria di annotazioni Jetpack è pubblicata nel repository Maven di Google.
Per aggiungere la libreria Jetpack Anotations al tuo progetto, includi la seguente riga nel blocco dependencies
del tuo file build.gradle
o build.gradle.kts
:
Kotlin
dependencies { implementation("androidx.annotation:annotation:1.7.1") }
trendy
dependencies { implementation 'androidx.annotation:annotation:1.7.1' }
Se utilizzi le annotazioni nel tuo modulo della libreria, queste vengono incluse nell'artefatto
Android Archive (AAR) in formato XML nel file annotations.zip
. L'aggiunta della dipendenza androidx.annotation
non introduce una dipendenza per gli utenti downstream della libreria.
Nota: se utilizzi altre librerie Jetpack,
potrebbe non essere necessario aggiungere la dipendenza androidx.annotation
. Poiché molte altre librerie
Jetpack dipendono dalla libreria delle annotazioni, potresti già avere accesso alle
annotazioni.
Per un elenco completo delle annotazioni incluse nel repository Jetpack, consulta la pagina di riferimento sulla libreria di annotazioni Jetpack o utilizza la funzionalità di completamento automatico per visualizzare le opzioni disponibili per l'istruzione import androidx.annotation.
.
Esegui ispezioni del codice
Per avviare un'ispezione del codice da Android Studio, che include la convalida delle annotazioni e il controllo automatico dell'ilint, seleziona Analizza > Ispeziona codice dal menu. Android Studio visualizza messaggi di conflitto per segnalare potenziali problemi in cui il codice è in conflitto con le annotazioni e per suggerire possibili soluzioni.
Puoi anche applicare le annotazioni eseguendo l'attività lint
utilizzando la riga di comando. Anche se questo potrebbe essere utile per segnalare problemi con un server di integrazione continua, l'attività lint
non applica le annotazioni di nullità (descritte nella sezione seguente); lo fa solo Android Studio. Per saperne di più su come abilitare ed eseguire le ispezioni lint, consulta Migliorare il codice con i controlli lint.
Anche se i conflitti di annotazione generano avvisi, questi avvisi non impediscono la compilazione dell'app.
Annotazioni null
Le annotazioni nullo possono essere utili nel codice Java per stabilire se i valori possono essere nulli. Sono meno utili nel codice Kotlin, poiché Kotlin ha incorporato regole di variabilità che vengono applicate al momento della compilazione.Aggiungi le annotazioni @Nullable
e @NonNull
per verificare la nullità di una determinata variabile, parametro o valore restituito. L'annotazione @Nullable
indica una variabile, un parametro o un valore restituito che può essere nullo.
@NonNull
indica una variabile, un parametro o un valore restituito che non può essere nullo.
Ad esempio, se una variabile locale che contiene un valore null viene passata come parametro a un metodo con l'annotazione @NonNull
associata a questo parametro, la creazione del codice genera un avviso che indica un conflitto di tipo non null. Inoltre, il tentativo di fare riferimento al risultato di un metodo contrassegnato da @Nullable
senza prima verificare se il risultato è nullo genera un avviso di nullità. Usa @Nullable
nel valore restituito di un metodo solo se ogni utilizzo del metodo deve essere selezionato esplicitamente come null.
L'esempio seguente dimostra nulla in azione. Il codice di esempio Kotlin non utilizza l'annotazione @NonNull
perché viene aggiunto automaticamente al bytecode generato quando viene specificato un tipo non null. L'esempio Java utilizza l'annotazione @NonNull
nei parametri context
e attrs
per verificare che i valori dei parametri trasmessi non siano null. Verifica inoltre che il metodo onCreateView()
non restituisca null:
Kotlin
... /** Annotation not used because of the safe-call operator(?)**/ override fun onCreateView( name: String?, context: Context, attrs: AttributeSet ): View? { ... } ...
Java
import androidx.annotation.NonNull; ... /** Add support for inflating the <fragment> tag. **/ @NonNull @Override public View onCreateView(String name, @NonNull Context context, @NonNull AttributeSet attrs) { ... } ...
Analisi delle possibilità di null
Android Studio supporta l'esecuzione di un'analisi della possibilità di nulla per dedurre e inserire automaticamente le annotazioni di nullità nel codice. Un'analisi con supporto di valori null analizza i contratti in tutte le gerarchie dei metodi nel codice per rilevare:
- Metodi di chiamata che possono restituire un valore nullo.
- Metodi che non devono restituire un valore null.
- Variabili, ad esempio campi, variabili locali e parametri, che possono essere nulle.
- Variabili, come campi, variabili locali e parametri, che non possono contenere un valore null.
L'analisi inserisce quindi automaticamente le annotazioni null appropriate nelle località rilevate.
Per eseguire un'analisi nulla in Android Studio, seleziona Analizza >
Deduci nullità. Android Studio inserisce le annotazioni Android @Nullable
e @NonNull
nelle posizioni rilevate nel tuo codice. Dopo aver eseguito un'analisi null, è buona norma verificare le annotazioni inserite.
Nota: quando aggiungi annotazioni di null, il completamento automatico potrebbe
suggerire le annotazioni IntelliJ
@Nullable
e
@NotNull
anziché le annotazioni null di Android
e potrebbe importare automaticamente la libreria corrispondente. Tuttavia, lo strumento di controllo lint di Android Studio cerca solo le annotazioni null di Android. Quando verifichi le annotazioni, conferma che il progetto utilizzi le annotazioni null di Android in modo che il controllo lint possa inviarti una notifica corretta durante l'ispezione del codice.
Annotazioni delle risorse
La convalida dei tipi di risorse può essere utile perché i riferimenti Android alle risorse, ad esempio le risorse disegnabili e string, vengono passati come numeri interi.
Il codice che prevede che un parametro faccia riferimento a un tipo specifico di risorsa, come String
, può essere passato al tipo di riferimento previsto di int
, ma in realtà fa riferimento a un tipo di risorsa diverso, ad esempio una risorsa R.string
.
Ad esempio, aggiungi le annotazioni @StringRes
per verificare se un parametro risorsa contiene un riferimento R.string
, come mostrato qui:
Kotlin
abstract fun setTitle(@StringRes resId: Int)
Java
public abstract void setTitle(@StringRes int resId)
Durante l'ispezione del codice, l'annotazione genera un avviso se nel parametro non viene trasmesso un riferimento R.string
.
Le annotazioni per altri tipi di risorse, come @DrawableRes
, @DimenRes
, @ColorRes
e @InterpolatorRes
, possono essere
aggiunte utilizzando lo stesso formato di annotazione ed essere eseguite durante l'ispezione del codice.
Se il parametro
supporta più tipi di risorsa, puoi inserire più di un'annotazione di tipo di risorsa su un determinato
parametro. Utilizza @AnyRes
per indicare che il parametro annotato può essere qualsiasi tipo di risorsa R
.
Anche se puoi utilizzare @ColorRes
per specificare che un
parametro deve essere una risorsa colore, un numero intero di colore (nel formato RRGGBB
o
AARRGGBB
) non viene riconosciuto come risorsa colore. Utilizza invece l'annotazione @ColorInt
per indicare che un parametro deve essere un numero intero di colore. Gli strumenti di creazione segnalano ai metodi annotati il codice errato che trasmette un ID risorsa colore come android.R.color.black
, anziché un numero intero di colore.
Annotazioni in thread
Le annotazioni Thread controllano se un metodo viene chiamato da un tipo specifico di thread. Sono supportate le seguenti annotazioni dei thread:
Gli strumenti di creazione considerano le annotazioni @MainThread
e @UiThread
come intercambiabili, quindi puoi chiamare i metodi @UiThread
dai metodi @MainThread
e viceversa. Tuttavia, è possibile che un thread dell'interfaccia utente sia diverso dal thread principale nel caso di app di sistema con più visualizzazioni su thread diversi. Dovresti quindi annotare i metodi associati alla gerarchia delle visualizzazioni di un'app con @UiThread
e solo i metodi associati al ciclo di vita di un'app con @MainThread
.
Se tutti i metodi in una classe condividono lo stesso requisito di organizzazione in thread, puoi aggiungere un'annotazione singola per il thread alla classe per verificare che tutti i metodi della classe vengano chiamati dallo stesso tipo di thread.
Un uso comune delle annotazioni dei thread è verificare che i metodi o le classi annotati con @WorkerThread
vengano chiamati solo da un thread in background appropriato.
Annotazioni dei vincoli del valore
Utilizza le annotazioni @IntRange
,
@FloatRange
e
@Size
per
convalidare i valori dei parametri trasmessi. Sia @IntRange
che @FloatRange
sono più utili se applicati a parametri in cui è probabile che gli utenti commettano un intervallo errato.
L'annotazione @IntRange
convalida che un valore parametro lungo o intero
rientra in un intervallo specificato. L'esempio seguente indica che il parametro alpha
deve contenere un valore intero compreso tra 0 e 255:
Kotlin
fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { ... }
Java
public void setAlpha(@IntRange(from=0,to=255) int alpha) { ... }
L'annotazione @FloatRange
controlla se un valore di parametro in virgola mobile o doppio rientra in un intervallo specificato di valori in virgola mobile. L'esempio seguente indica che il parametro alpha
deve contenere un valore in virgola mobile compreso tra 0,0 e 1,0:
Kotlin
fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}
Java
public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
L'annotazione @Size
controlla le dimensioni di una raccolta o
di un array o la lunghezza di una stringa. L'annotazione @Size
può essere utilizzata per verificare
le seguenti qualità:
- Dimensioni minime, ad esempio
@Size(min=2)
- Dimensioni massime, ad esempio
@Size(max=2)
- Dimensioni esatte, ad esempio
@Size(2)
- Un numero di cui la dimensione deve essere un multiplo, ad esempio
@Size(multiple=2)
Ad esempio, @Size(min=1)
verifica se una raccolta non è vuota, e @Size(3)
verifica che un array contenga esattamente tre valori.
L'esempio seguente indica che l'array
location
deve contenere almeno un elemento:
Kotlin
fun getLocation(button: View, @Size(min=1) location: IntArray) { button.getLocationOnScreen(location) }
Java
void getLocation(View button, @Size(min=1) int[] location) { button.getLocationOnScreen(location); }
Annotazioni delle autorizzazioni
Utilizza l'annotazione @RequiresPermission
per convalidare le autorizzazioni del chiamante di un metodo. Per verificare la presenza di una singola autorizzazione
da un elenco di autorizzazioni valide, usa l'attributo anyOf
. Per verificare la presenza di un insieme di autorizzazioni, utilizza l'attributo allOf
. L'esempio seguente annota il metodo setWallpaper()
per indicare che il chiamante del metodo deve avere l'autorizzazione permission.SET_WALLPAPERS
:
Kotlin
@RequiresPermission(Manifest.permission.SET_WALLPAPER) @Throws(IOException::class) abstract fun setWallpaper(bitmap: Bitmap)
Java
@RequiresPermission(Manifest.permission.SET_WALLPAPER) public abstract void setWallpaper(Bitmap bitmap) throws IOException;
L'esempio seguente richiede che il chiamante del metodo copyImageFile()
disponga dell'accesso in lettura all'unità di archiviazione esterna e dell'accesso in lettura ai metadati della posizione nell'immagine copiata:
Kotlin
@RequiresPermission(allOf = [ Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION ]) fun copyImageFile(dest: String, source: String) { ... }
Java
@RequiresPermission(allOf = { Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION}) public static final void copyImageFile(String dest, String source) { //... }
Per le autorizzazioni per gli intent, inserisci il requisito di autorizzazione nel campo della stringa che definisce il nome dell'azione dell'intent:
Kotlin
@RequiresPermission(android.Manifest.permission.BLUETOOTH) const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"
Java
@RequiresPermission(android.Manifest.permission.BLUETOOTH) public static final String ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE";
Per le autorizzazioni sui fornitori di contenuti che richiedono autorizzazioni separate per l'accesso in lettura e scrittura, aggrega ogni requisito di autorizzazione in un'annotazione @RequiresPermission.Read
o @RequiresPermission.Write
:
Kotlin
@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS)) @RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS)) val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")
Java
@RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS)) @RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS)) public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");
Autorizzazioni indirette
Quando un'autorizzazione dipende dal valore specifico fornito al parametro di un metodo, utilizza @RequiresPermission
nel parametro stesso senza elencare le autorizzazioni specifiche.
Ad esempio, il metodo startActivity(Intent)
utilizza un'autorizzazione indiretta per l'intent trasmesso al metodo:
Kotlin
abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)
Java
public abstract void startActivity(@RequiresPermission Intent intent, @Nullable Bundle)
Quando utilizzi autorizzazioni indirette, gli strumenti di creazione eseguono l'analisi del flusso di dati per verificare se l'argomento trasmesso nel metodo ha annotazioni @RequiresPermission
. Quindi
applicano tutte le annotazioni esistenti del parametro al metodo stesso. Nell'esempio startActivity(Intent)
, le annotazioni nella classe Intent
causano gli avvisi risultanti per gli utilizzi non validi di startActivity(Intent)
quando viene trasmesso al metodo un intent senza le autorizzazioni appropriate, come mostrato nella Figura 1.
Gli strumenti di creazione generano l'avviso su startActivity(Intent)
dall'annotazione
nel nome dell'azione per l'intent corrispondente nella classe Intent
:
Kotlin
@RequiresPermission(Manifest.permission.CALL_PHONE) const val ACTION_CALL = "android.intent.action.CALL"
Java
@RequiresPermission(Manifest.permission.CALL_PHONE) public static final String ACTION_CALL = "android.intent.action.CALL";
Se necessario, puoi sostituire @RequiresPermission
con @RequiresPermission.Read
o @RequiresPermission.Write
durante l'annotazione del parametro di un metodo. Tuttavia, per le autorizzazioni indirette, @RequiresPermission
non deve
essere utilizzato insieme alle annotazioni delle autorizzazioni di lettura o scrittura.
Annotazioni dei valori restituiti
Utilizza l'annotazione @CheckResult
per verificare che il risultato o il valore restituito di un metodo venga effettivamente utilizzato. Anziché annotare ogni metodo non void con @CheckResult
, aggiungi l'annotazione per chiarire i risultati di metodi che potrebbero generare confusione.
Ad esempio, i nuovi sviluppatori Java spesso pensano erroneamente che <String>.trim()
rimuova gli spazi vuoti dalla stringa originale. L'annotazione
del metodo con @CheckResult
segnala l'utilizzo di <String>.trim()
in cui il chiamante non fa nulla con il valore restituito del metodo.
L'esempio seguente annota il metodo checkPermissions()
per verificare se si fa effettivamente riferimento al valore restituito del metodo. Indica inoltre il metodo enforcePermission()
come metodo da suggerire allo sviluppatore in sostituzione:
Kotlin
@CheckResult(suggest = "#enforcePermission(String,int,int,String)") abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int
Java
@CheckResult(suggest="#enforcePermission(String,int,int,String)") public abstract int checkPermission(@NonNull String permission, int pid, int uid);
Annotazioni CallSuper
Utilizza l'annotazione @CallSuper
per verificare che un metodo di override chiami la super implementazione del metodo.
L'esempio riportato di seguito annota il metodo onCreate()
per garantire che qualsiasi implementazione del metodo di override chiami super.onCreate()
:
Kotlin
@CallSuper override fun onCreate(savedInstanceState: Bundle?) { }
Java
@CallSuper protected void onCreate(Bundle savedInstanceState) { }
Annotazioni Typedef
Le annotazioni Typedef controllano se un determinato parametro, valore restituito o campo fa riferimento a un insieme specifico di costanti. Inoltre, consentono al completamento del codice di offrire automaticamente le costanti consentite.
Utilizza le annotazioni @IntDef
e @StringDef
per creare annotazioni enumerate di set di numeri interi e di stringhe per convalidare altri tipi di riferimenti al codice.
Le annotazioni Typedef utilizzano @interface
per dichiarare il nuovo tipo di annotazione enumerato.
Le annotazioni @IntDef
e @StringDef
, insieme a
@Retention
, annotano la nuova annotazione e sono necessarie per definire il
tipo enumerato. L'annotazione @Retention(RetentionPolicy.SOURCE)
indica al compilatore di non archiviare i dati dell'annotazione enumerati nel file .class
.
L'esempio seguente mostra i passaggi per creare un'annotazione che verifica se un valore trasmesso come parametro del metodo fa riferimento a una delle costanti definite:
Kotlin
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 }
Java
import androidx.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); }
Quando crei questo codice, viene generato un avviso se il parametro mode
non
fa riferimento a una delle costanti definite (NAVIGATION_MODE_STANDARD
,
NAVIGATION_MODE_LIST
o NAVIGATION_MODE_TABS
).
Combina @IntDef
e @IntRange
per indicare che un
numero intero può essere un determinato insieme di costanti o un valore compreso in un intervallo.
Attiva la combinazione di costanti e flag
Se gli utenti possono combinare le costanti consentite con un flag (come |
,
&
, ^
e così via), puoi definire un'annotazione con un
attributo flag
per verificare se un parametro o un valore restituito fa riferimento a un pattern valido.
L'esempio seguente crea l'annotazione DisplayOptions
con un elenco di costanti DISPLAY_
valide:
Kotlin
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 ...
Java
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(RetentionPolicy.SOURCE) public @interface DisplayOptions {} ...
Quando crei codice con un flag di annotazione, viene generato un avviso se il parametro decorato o il valore restituito non fa riferimento a un pattern valido.
Mantieni annotazione
L'annotazione @Keep
garantisce che una classe o un metodo annotati non vengano rimossi quando il codice viene minimizzato in fase di creazione. Questa annotazione viene in genere aggiunta ai metodi e alle classi a cui si accede tramite riflessione per evitare che il compilatore consideri il codice inutilizzato.
Attenzione : le classi e i metodi a cui inserisci
l'annotazione utilizzando @Keep
vengono sempre visualizzati nell'APK della tua app, anche se
non fai mai riferimento a queste classi e a questi metodi nella logica dell'app.
Per contenere le dimensioni dell'app, valuta se è necessario conservare ogni annotazione @Keep
nell'app. Se utilizzi il riflesso per accedere a una classe o a un metodo annotati, utilizza un condizionale
-if
nelle regole ProGuard, specificando la classe che esegue le chiamate di riflessione.
Per ulteriori informazioni su come minimizzare il codice e specificare quale codice non deve essere rimosso, consulta Ridurre, offuscare e ottimizzare l'app.
Annotazioni di visibilità del codice
Utilizza le seguenti annotazioni per indicare la visibilità di parti specifiche di codice, come metodi, classi, campi o pacchetti.
Rendi visibile il codice per i test
L'annotazione @VisibleForTesting
indica che un metodo annotato è più visibile del solito per renderlo testabile. Questa annotazione ha un argomento otherwise
facoltativo che consente di
specificare quale sarebbe la visibilità del metodo se non fosse necessario renderlo visibile
per i test. Lint utilizza l'argomento otherwise
per applicare la visibilità prevista.
Nell'esempio seguente, myMethod()
è in genere private
, ma è
package-private
per i test. Con la designazione VisibleForTesting.PRIVATE
, lint mostra un messaggio se questo metodo viene chiamato dall'esterno del contesto consentito dall'accesso a private
, ad esempio da un'altra unità di compilazione.
Kotlin
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) fun myMethod() { ... }
Java
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) void myMethod() { ... }
Puoi anche specificare @VisibleForTesting(otherwise = VisibleForTesting.NONE)
per indicare che un metodo esiste solo per i test. Questo modulo equivale all'utilizzo di
@RestrictTo(TESTS)
. Entrambi eseguono lo stesso controllo lint.
Limitare un'API
L'annotazione @RestrictTo
indica che l'accesso all'API annotata (pacchetto, classe o metodo) è limitato, come segue:
Sottoclassi
Utilizza il modulo di annotazione @RestrictTo(RestrictTo.Scope.SUBCLASSES)
per limitare l'accesso API solo alle sottoclassi.
Solo le classi che estendono la classe annotata possono accedere a questa API. Il modificatore protected
Java non è abbastanza restrittivo, perché consente l'accesso da classi non correlate all'interno dello stesso pacchetto. Inoltre, in alcuni casi vorrai lasciare un
metodo public
per flessibilità in futuro, perché non puoi mai creare un
protected
e un metodo con override public
in precedenza, ma vuoi fornire un
suggerimento che la classe è destinata a utilizzi all'interno della classe o solo dalle sottoclassi.
Librerie
Utilizza il modulo di annotazione @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
per
limitare l'accesso API solo alle tue librerie.
Solo il tuo codice della libreria può accedere all'API annotata. In questo modo puoi non solo organizzare il codice nella gerarchia dei pacchetti che preferisci, ma anche condividerlo con un gruppo di librerie correlate. Questa opzione è già disponibile per le librerie Jetpack
che contengono molto codice di implementazione non destinato all'uso esterno, ma deve essere
public
per condividerlo tra le varie librerie Jetpack complementari.
Test
Utilizza il modulo di annotazione @RestrictTo(RestrictTo.Scope.TESTS)
per impedire ad altri
sviluppatori di accedere alle tue API di test.
Solo il codice di test può accedere all'API annotata. Ciò impedisce ad altri sviluppatori di utilizzare le API per lo sviluppo che intendi includere solo a scopo di test.