Utilizzo di funzionalità e API del linguaggio Java 8

Il plug-in Android per Gradle 3.0.0 e versioni successive supporta tutte le funzionalità del linguaggio Java 7 e un sottoinsieme di funzionalità del linguaggio Java 8 che variano in base alla versione della piattaforma. Quando crei la tua app utilizzando il plug-in Android per Gradle 4.0.0 e versioni successive, puoi utilizzare alcune API del linguaggio Java 8 senza richiedere un livello API minimo per la tua app.

Questa pagina descrive le funzionalità del linguaggio Java 8 che puoi utilizzare, come configurare correttamente il tuo progetto per utilizzarle ed eventuali problemi noti che potresti riscontrare. Guarda il seguente video per una panoramica delle funzionalità del linguaggio Java 8.

Il plug-in Android per Gradle fornisce il supporto integrato per l'utilizzo di alcune funzionalità del linguaggio Java 8 e di librerie di terze parti che le utilizzano. La toolchain predefinita implementa le nuove funzionalità del linguaggio eseguendo trasformazioni del bytecode, chiamate desugar, nell'ambito della compilazione D8/R8 dei file di classe in codice DEX, come mostrato nella Figura 1.

Supporto delle funzionalità del linguaggio Java 8 tramite trasformazioni bytecode "desugar"
Figura 1. Supporto delle funzionalità del linguaggio Java 8 tramite trasformazioni bytecode desugar.

Supporto delle funzionalità del linguaggio Java 8 (plug-in Android per Gradle 3.0.0 e versioni successive)

Per iniziare a utilizzare le funzionalità del linguaggio Java 8 supportate:

  1. Aggiorna il plug-in Android per Gradle alla versione 3.0.0 o successive.
  2. Per ogni modulo che utilizza le funzionalità del linguaggio Java 8 (nel codice sorgente o tramite dipendenze), aggiorna il file build.gradle o build.gradle.kts del modulo come mostrato di seguito:

Kotlin

android {
    ...
    // Configure only for each module that uses Java 8
    // language features (either in its source code or
    // through dependencies).
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Alla moda

android {
    ...
    // Configure only for each module that uses Java 8
    // language features (either in its source code or
    // through dependencies).
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Quando crei la tua app utilizzando il plug-in Android per Gradle 3.0.0 e versioni successive, il plug-in non supporta tutte le funzionalità del linguaggio Java 8. Le seguenti funzionalità del linguaggio sono disponibili su qualsiasi livello API:

Funzionalità del linguaggio Java 8 Note
Espressioni lambda Android non supporta la serializzazione delle espressioni lambda.
Riferimenti dei metodi  
Annotazioni dei tipi Le informazioni sull'annotazione del tipo sono disponibili solo in tempo di compilazione, non in tempo di esecuzione. La piattaforma supporta TYPE nel livello API 24 e versioni precedenti, ma non ElementType.TYPE_USE o ElementType.TYPE_PARAMETER.
Metodi di interfaccia predefiniti e statici  
Annotazioni ripetute  

Oltre a queste funzionalità del linguaggio Java 8, le versioni 3.0.0 e successive del plug-in Android per Gradle estendono il supporto di try-with-resources a tutti i livelli API Android.

Desugar non supporta MethodHandle.invoke o MethodHandle.invokeExact. Se il codice sorgente o una delle dipendenze del modulo utilizza uno di questi metodi, devi specificare minSdkVersion 26 o un valore superiore. In caso contrario, riceverai il seguente errore:

Dex: Error converting bytecode to dex:
Cause: signature-polymorphic method called without --min-sdk-version >= 26

In alcuni casi, il modulo potrebbe non utilizzare i metodi invoke o invokeExact anche se sono inclusi in una dipendenza della libreria. Per continuare a utilizzare la libreria con minSdkVersion 25 o versioni precedenti, attiva la riduzione del codice per rimuovere i metodi inutilizzati. Se il problema persiste, valuta la possibilità di utilizzare una libreria alternativa che non utilizzi i metodi non supportati.

Desugaring delle funzionalità dei linguaggi Java 8 e versioni successive sul plug-in Android per Gradle 3.0.0 e versioni successive e non rende disponibili classi e API aggiuntive (come java.util.stream.*) per l'utilizzo su versioni di Android precedenti. Il supporto per il desugaring parziale delle API Java è disponibile a partire dal plug-in Android Gradle 4.0.0 o versioni successive, come descritto nella sezione seguente.

Supporto del desugaring delle API Java 8 e versioni successive (plug-in Android per Gradle 4.0.0 e versioni successive)

Se crei la tua app utilizzando il plug-in Android per Gradle 4.0.0 o versioni successive, il plug-in estende il supporto per l'utilizzo di una serie di API del linguaggio Java 8 senza richiedere un livello API minimo per la tua app. Con il plug-in Android per Gradle 7.4.0 o versioni successive, sono disponibili anche diverse API del linguaggio Java 11 con la libreria di desugaring 2.0.0 o versioni successive.

Questo supporto aggiuntivo per le versioni precedenti della piattaforma è possibile perché il plug-in 4.0.0 e versioni successive estende il motore di desugaring per eseguire il desugaring anche delle API del linguaggio Java. Puoi includere API di linguaggio standard che erano disponibili solo nelle versioni recenti di Android (come java.util.streams) nelle app che supportano versioni precedenti di Android.

Il seguente insieme di API è supportato quando crei la tua app utilizzando il plug-in Android Gradle 4.0.0 o versioni successive:

  • Stream sequenziali (java.util.stream)
  • Un sottoinsieme di java.time
  • java.util.function
  • Aggiunte recenti a java.util.{Map,Collection,Comparator}
  • Optionals (java.util.Optional, java.util.OptionalInt e java.util.OptionalDouble) e alcune nuove classi
  • Alcune aggiunte a java.util.concurrent.atomic (nuovi metodi su AtomicInteger, AtomicLong e AtomicReference)
  • ConcurrentHashMap (con correzioni di bug per Android 5.0)

Con il plug-in Android per Gradle 7.4.0 o versioni successive, sono supportate API Java 11 aggiuntive, ad esempio un sottoinsieme del pacchetto java.nio.file.

Per un elenco completo delle API supportate, consulta API Java 8+ disponibili tramite desugaring e API Java 11+ disponibili tramite desugaring.

Per supportare queste API di linguaggio, il plug-in compila un file DEX separato che contiene un'implementazione delle API mancanti e lo include nella tua app. Il processo di desugaring riscrive il codice della tua app in modo che utilizzi questa libreria in fase di runtime. Il codice sorgente compilato nel file DEX separato è disponibile nel repository GitHub desugar_jdk_libs.

Per attivare il supporto di queste API di linguaggio su qualsiasi versione della piattaforma Android:

  1. Aggiorna il plug-in Android per Gradle alla versione 4.0.0 (o successiva).
  2. Includi quanto segue nel file build.gradle o build.gradle.kts del modulo dell'app:

Kotlin

android {
    defaultConfig {
        // Required when setting minSdkVersion to 20 or lower
        multiDexEnabled = true
    }

    compileOptions {
        // Flag to enable support for the new language APIs

        // For AGP 4.1+
        isCoreLibraryDesugaringEnabled = true
        // For AGP 4.0
        // coreLibraryDesugaringEnabled = true

        // Sets Java compatibility to Java 8
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

dependencies {
    // For AGP 7.4+
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.3")
    // For AGP 7.3
    // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.2.3")
    // For AGP 4.0 to 7.2
    // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.9")
}

Alla moda

android {
    defaultConfig {
        // Required when setting minSdkVersion to 20 or lower
        multiDexEnabled true
    }

    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    // For AGP 7.4+
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.3'
    // For AGP 7.3
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.2.3'
    // For AGP 4.0 to 7.2
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.9'
}

Tieni presente che potrebbe essere necessario includere anche lo snippet di codice precedente nel file build.gradle o build.gradle.kts di un modulo della libreria se:

  • I test di instrumentazione del modulo della libreria utilizzano queste API di linguaggio (direttamente o tramite il modulo della libreria o le sue dipendenze). In questo modo, le API mancanti vengono fornite per l'APK di test di instrumentazione.

  • Vuoi eseguire lint sul modulo della libreria in isolamento. In questo modo, lint può riconoscere gli utilizzi validi delle API del linguaggio ed evitare di segnalare falsi avvisi.

Tieni presente inoltre che il desugaring dell'API può essere combinato con la riduzione, ma solo quando utilizzi lo shrinker R8.

Versioni

La tabella seguente mostra le versioni della libreria API Java 8+ e la versione minima del plug-in Android per Gradle che supporta ogni versione:

Versione Versione minima del plug-in Android per Gradle
1.1.9 4.0.0
1.2.3 7.3.0
2.0.3 7.4.0-alpha10

Per informazioni dettagliate sulle versioni della libreria API Java 8+, consulta il file CHANGELOG.md nel repository GitHub desugar_jdk_libs.