annotazione livello API Android per librerie Android

Question

Sto scrivendo una libreria Android. La stragrande maggioranza dell'interfaccia in lbirary supporta l'API di Android di livello 10 o superiore. Alcune funzionalità, tuttavia, richiedono un livello API più elevato. Ad esempio, parte della libreria richiede l'API 18 per Bluetooth Low Energy.

Per motivi di concretezza, diciamo che la libreria produce tre classi ClassA, ClassB e ClassC. ClassA utilizza le funzionalità disponibili in API 10, ClassB utilizza le funzionalità disponibili in API 14 e ClassC utilizza le funzionalità disponibili in API 18.

Voglio essere in grado di innescare un problema di pelucchi (avviso/errore) ogni volta che qualcuno utilizza una classe da mia libreria senza avere il livello API richiesto nel progetto (a meno che non sopprimano l'avviso con l'annotazione appropriata), simile al problema NewApi già utilizzato da Lint.

Al termine della ricerca, ho trovato le seguenti soluzioni possibili:

1) Questa soluzione non è lungo le linee di pelucchi: Dividere la libreria in tre file .jar, dire lib_10.jar che include tutte le classi che utilizzano la funzionalità disponibili in API 10 (ClassA nell'esempio), lib_14.jar che include tutte le classi che utilizzano le funzionalità disponibili nell'API 14 (ClassB nell'esempio) e lib_18.jar che include tutte le classi che utilizzano le funzionalità disponibili nell'API 18 (ClassC nell'esempio). Questa soluzione consente la portabilità ma complicherebbe la successiva manutenibilità della base di codice e richiederebbe potenzialmente anche la duplicazione del codice.

2) Crea il mio annotazioni (per esempio, @RequireAndroidApi(API_LEVEL) che indica il livello minimo richiesto dalla API della classe/metodo annotato/etc ...) e utilizzare il lint-api.jar (http://tools.android.com/tips/lint-custom-rules) per creare una regole lint personalizzati che controllano l'utilizzo di eventuali classi/metodi annotati/ecc. con un'API inferiore a quella richiesta. Qualcosa che in seguito sarebbe simile a questa:

@RequireAndroidApi(10) 
Class ClassA { 
} 

@RequireAndroidApi(14) 
Class ClassB { 
} 

@RequireAndroidApi(18) 
Class ClassC { 
} 

Il problema è che non riuscivo a trovare una buona documentazione per l'API residuo di stoffa e sembra che questo sta reinventando la ruota di una funzionalità che non lasci residui supporta già (lint già controlli per il problema "NewApi").

3) Infine, sono riuscita a modificare <SDK>/platform-tools/api/api-versions.xml al fine di indicare il livello di API richiesta da ogni classe come segue:

<api version="1"> 
    ... 
    <class name="package/path/ClassA" since="10"> 
     <extends name="java/lang/Object" /> 
     <method name="&lt;init>()V" /> 
    </class> 
    <class name="package/path/ClassB" since="14"> 
     <extends name="java/lang/Object" /> 
     <method name="&lt;init>()V" /> 
    </class> 
    <class name="package/path/ClassC" since="18"> 
     <extends name="java/lang/Object" /> 
     <method name="&lt;init>()V" /> 
    </class> 
</api> 

Quali causato lanugine per attivare il problema NewApi nello stesso modo come si farebbe con le API Android. Mi piace questo tipo di soluzione perché non reinventa la ruota e inoltre eventuali errori generati in questo modo utilizzerebbero le soluzioni suggerite programmate in Eclipse o Android Studio per affrontare il problema (ad esempio "correzioni rapide" in Eclipse). Il problema con questa soluzione è che richiede la modifica di api-versions.xml fornita con l'SDK di Android, che rende questa soluzione non molto portabile per il rilascio della libreria per diversi motivi, tra cui: a) il file api-versions.xml non è locale a un progetto e modifica il comportamento di filaccia per tutti i progetti Android, compresi quelli che non usano la libreria; e b) api-versions.xml verrà sovrascritto ogni volta che l'SDK viene aggiornato dal gestore di Android SDK che sovrascrive qualsiasi modifica apportata.

Mi chiedevo se esiste una soluzione più semplice per ottenere questo "minimo errori/avvisi API" o se esiste un modo per scrivere un file separato simile a api-versions.xml che può essere inserito nella directory del progetto che può essere letto da lint ogni volta che viene lanciato del filato sul progetto in questione (qualcosa di simile a lint.xml).

Grazie per avermi seguito durante questa lunga descrizione del problema e apprezzo qualsiasi aiuto in anticipo.

Answer 1

L'ho fatto di recente su una classe di visualizzazione personalizzata, che richiedeva un costruttore speciale per alcuni livelli API.

L'ho fatto con l'annotazione @TargetApi.

Se un metodo è disponibile solo a partire dal livello di API 16:

@TargetApi(16) 
public void someMethod() {} 

Questo dovrebbe fare il trucco, inclusi gli errori di lanugine.

Answer 2

Non è necessario creare la propria annotazione, l'annotazione @RequiresApi della libreria di supporto Android è ciò che si sta cercando. Ad esempio:

@RequiresApi(Build.VERSION_CODES.LOLLIPOP) 
public void someMethod() {} 

Questa annotazione dice lanugine per avvertire se someMethod() è utilizzato in un contesto che può avere un livello di API inferiore.

Si noti che @TargetApi è diverso: viene utilizzato per assicurare l'interfaccia che il metodo annotato verrà chiamato solo con l'API di destinazione, in una situazione in cui altrimenti si avvertirebbe di non utilizzare tale metodo. Pertanto, è possibile utilizzare @TargetApi per disattivare l'avviso relativo ai pelucchi innescato da @RequiresApi.