16 February 2023

API desugaring supporting Android 13 and java.nio

Posted by Clément Béra, Software engineer

We are happy to announce the release of a new version of API desugaring based on Android 13 and Java 11 language APIs. API desugaring allows developers to use more APIs without requiring a minimum API level for your app. This reduces friction during development. You are now free to use the java.nio APIs no matter which Android version is on the user’s device. For example, libraries such as kotlin.io.path are now available on all Android devices, including devices running Android 7 and lower.

In addition to supporting java.nio, API desugaring of java.time and java.util.stream has been updated to support APIs added up to Android 13. You can use recent APIs in your Android app such as Collectors#toUnmodifiableList.

New API desugaring specifications

To enable API desugaring, you set isCoreLibraryDesugaringEnabled and add the coreLibraryDesugaring dependency in the build.gradle.kts file.

android {
   ...
   compileSdk = 33

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

       ...
   }

   ...
   compileOptions {
       // Flag to enable support for API desugaring.
       isCoreLibraryDesugaringEnabled = true
      
       // Sets Java compatibility to Java 8
       sourceCompatibility = JavaVersion.VERSION_1_8
       targetCompatibility = JavaVersion.VERSION_1_8

   }
   kotlinOptions {
       jvmTarget = "1.8"
   }
}

dependencies {
 // Dependency required for API desugaring.
 coreLibraryDesugaring("com.android.tools:desugar_jdk_libs_nio:2.0.2")
}

The new version 2.0 release comes in 3 flavors:

com.android.tools:desugar_jdk_libs_nio:2.0.2 - the nio version includes all the desugaring available including the java.nio, java.time, stream, and functions APIs.
com.android.tools:desugar_jdk_libs:2.0.2 - the default version includes desugaring for the java.time, stream, and functions APIs. It’s similar to version 1.x API desugaring already available, but updated with APIs added up to Android 13.
com.android.tools:desugar_jdk_libs_minimal:2.0.2 - the minimal version includes only the java.util.function package and bug fixes on concurrent collections. It’s designed for minimal code size overhead.

Opting into more desugaring features will lead to a larger impact on your app’s code size. The minimal specification has, as its name indicates, a minimal impact on the code size of the app. The nio specification has the most impact.

The new java.nio APIs

The new java.nio APIs supported in API desugaring include:

All the classes and APIs in java.nio.file such as BasicFileAttributes, file manipulation, or usage of java.nio.file.Path.
Some extensions of java.nio.channels, such as the FileChannel#open methods.
A few utility methods such as File#toPath.

The following code snippet illustrates how you can now use the new java.nio APIs on all devices, including devices running Android 7 and lower, through the methods of kotlin.io.path which depend on java.nio.file.Files. A temp file can be created, written into, read, and its basic attributes and its existence can be queried using the new java.nio APIs.

import android.util.Log
import java.nio.file.StandardOpenOption.APPEND
import kotlin.io.path.createTempDirectory
import kotlin.io.path.deleteIfExists
import kotlin.io.path.exists
import kotlin.io.path.fileSize
import kotlin.io.path.readLines
import kotlin.io.path.writeLines

...
val TAG = "java.nio Test"
val tempDirectory = createTempDirectory("tempFile")
val tempFile = tempDirectory.resolve("tempFile")
tempFile.writeLines(listOf("first"))
tempFile.writeLines(listOf("second"), options = arrayOf(APPEND))
Log.d(TAG,"Content: ${tempFile.readLines()}")
Log.d(TAG,"Size: ${tempFile.fileSize()}")
Log.d(TAG,"Exists (before deletion): ${tempFile.exists()}")
tempFile.deleteIfExists()
Log.d(TAG,"Exists (after deletion): ${tempFile.exists()}")

// Resulting logcat output.
Content: first second
Size: 13
Exists (before deletion): true
Exists (after deletion): false

A few features however cannot be emulated for devices running Android 7 and lower and instead throw an instance of UnsupportedOperationException or return null. They still work on devices running Android 8 or higher, so existing code guarded by an API level check should work as it used to. See the complete list of APIs available and the known limitations.

The code has been extensively tested, but we are looking for additional inputs from app developers.

Please try out the new version of API desugaring, and let us know how it worked for you!

For additional background see the post Support for newer Java language APIs from when API desugaring was introduced.

Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.

Android compiler d8 Desugaring R8

API desugaring supporting Android 13 and java.nio

New API desugaring specifications

The new java.nio APIs

Google developers blog

Connect

Subscribe