Usar recursos e APIs da linguagem Java 8

O Plug-in do Android para Gradle 3.0.0 e versões mais recentes são compatíveis com todos os recursos da linguagem Java 7 e com um subconjunto de recursos da linguagem Java 8, que variam de acordo com a versão da plataforma. Ao criar seu app usando o Plug-in do Android para Gradle 4.0.0 e versões mais recentes, você pode usar várias APIs da linguagem Java 8 sem exigir um nível mínimo da API para seu app.

Esta página descreve os recursos da linguagem Java 8 que você pode usar, como configurar seu projeto adequadamente para usá-los e possíveis problemas conhecidos. Para ter uma visão geral, assista também o vídeo a seguir.

Observação: o uso de recursos da linguagem Java 8 é opcional no desenvolvimento de apps para Android. Você pode manter os valores de compatibilidade de origem e destino definidos como Java 7, mas ainda será necessário compilar usando o JDK 8.

O Plug-in do Android para Gradle é compatível com alguns recursos da linguagem Java 8 e com algumas bibliotecas de terceiros que os utilizam. Conforme mostrado na figura 1, o conjunto de ferramentas padrão implementa os novos recursos da linguagem executando transformações de bytecode, denominadas desugar, como parte da compilação D8/R8 de arquivos de classe em código dex.

Figura 1. Compatibilidade com recursos da linguagem Java 8 usando transformações de bytecode desugar.

Compatibilidade com recursos da linguagem Java 8 (Plug-in do Android para Gradle 3.0.0+)

Para começar a usar os recursos da linguagem Java 8 compatíveis, atualize o plug-in do Android para a versão 3.0.0 (ou mais recente). Depois disso, para cada módulo que usa recursos da linguagem Java 8 (no código-fonte ou em dependências), atualize o arquivo build.gradle do módulo, conforme mostrado abaixo.

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"
    }
}

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"
    }
}

Ao criar seu app usando o Plug-in do Android para Gradle 3.0.0 ou versões mais recentes, o plug-in não é compatível com todos os recursos da linguagem Java 8. Os seguintes recursos de linguagem estão disponíveis em qualquer nível da API:

Além dos recursos da linguagem Java 8 acima, as versões de plug-in 3.0.0 e mais recentes ampliam a compatibilidade com try-with-resources (link em inglês) para todos os níveis de API do Android.

No momento, a simplificação não é compatível com MethodHandle.invoke ou MethodHandle.invokeExact (links em inglês). Se o código-fonte ou uma das dependências do módulo usar um desses métodos, será necessário especificar minSdkVersion 26 ou uma versão mais recente. Caso contrário, ocorrerá o seguinte erro:

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

Em alguns casos, o módulo pode não usar os métodos invoke ou invokeExact, mesmo se estiverem incluídos em uma dependência de biblioteca. Portanto, para continuar usando essa biblioteca com minSdkVersion 25 ou versões anteriores, ative a redução de código para remover os métodos não usados. Se isso não funcionar, use outra biblioteca que não utilize os métodos incompatíveis.

Os recursos de simplificação de recursos do Java 8+ disponíveis no Plug-in do Android para Gradle 3.0.0 não disponibilizam outras classes e APIs (como java.util.stream.*) para uso em versões mais antigas do Android. A compatibilidade com a simplificação parcial da API Java está disponível no Plug-in do Android para Gradle 4.0.0 ou mais recente e é descrita na seção a seguir.

Compatibilidade com a simplificação de APIs do Java 8+ (Android Gradle Plugin 4.0.0+)

Se você estiver criando o app usando o Android Gradle Plugin 4.0.0 ou mais recente, o plug-in vai ampliar a compatibilidade com o uso de várias APIs da linguagem Java 8 sem exigir um nível mínimo de API para o app.

Essa compatibilidade adicional com versões de plataforma mais antigas é possível porque o plug-in 4.0.0 e versões mais recentes ampliam o mecanismo de simplificação para funcionar com as APIs da linguagem Java. Portanto, você pode incluir APIs de linguagem padrão que estavam disponíveis apenas em versões recentes do Android (por exemplo, java.util.streams) em apps compatíveis com versões mais antigas do Android.

O seguinte conjunto de APIs é compatível com a criação do app usando o Plug-in do Android para Gradle 4.0.0 ou versões mais recentes:

• Fluxos sequenciais (java.util.stream)
• Um subconjunto de java.time
• java.util.function
• Adições recentes a java.util.{Map,Collection,Comparator}
• Recursos opcionais (java.util.Optional, java.util.OptionalInt e java.util.OptionalDouble) e algumas outras novas classes úteis com as APIs acima
• Algumas adições a java.util.concurrent.atomic (novos métodos em AtomicInteger, AtomicLong e AtomicReference)
• ConcurrentHashMap (com correções de bugs para o Android 5.0)

Para ver uma lista completa das APIs compatíveis, acesse APIs Java 8+ disponíveis pela simplificação.

Para oferecer compatibilidade com essas APIs de linguagem, o plug-in compila um arquivo DEX separado que contém uma implementação das APIs ausentes e as inclui no app. O processo de simplificação reescreve o código do app para usar essa biblioteca durante o tempo da execução.

Para ativar a compatibilidade com essas APIs de linguagem em qualquer versão da plataforma Android, atualize o plug-in do Android para 4.0.0 (ou mais recente) e inclua o seguinte no arquivo build.gradle do módulo do app:

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 {
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.5'
}

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 {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.5")
}

Também pode ser necessário incluir o snippet de código acima em um arquivo build.gradle do módulo da biblioteca se:

• os testes de instrumentação do módulo da biblioteca usam essas APIs de linguagem, seja diretamente, pelo módulo da biblioteca ou pelas dependências dele. Dessa forma, as APIs que não estiverem presentes serão fornecidas para o APK de teste de instrumentação;

• você quer executar o lint no módulo da biblioteca de forma isolada. O objetivo é ajudar o lint a reconhecer usos válidos das APIs de linguagem e evitar avisos falsos.

Além disso, a simplificação de APIs pode ser combinada com a redução, mas apenas ao usar o redutor R8.

Versões

A tabela a seguir exibe as versões da biblioteca de APIs do Java 8 e versões mais recentes, além da versão mínima do Plug-in do Android para Gradle com suporte para cada versão.