Posted by James Lau, Product Manager (@jmslau)
When using the Java programming language, one of the most common pitfalls is trying to access a member of a null reference, causing a NullPointerException to be thrown. Kotlin offers protection against this by baking nullable and non-nullable types into the type system. This helps eliminate NullPointerExceptions from your code and improve your app's overall quality. When Kotlin code is calling into APIs written in the Java programming language, it relies on nullability annotations in those APIs to determine the nullability of each parameter and the return type. Unannotated parameters and return types are treated as platform types, which weakens the null-safety guarantee of Kotlin.
As part of yesterday's Android 9 announcement, we have also released a new Android SDK that contains nullability annotations for some of the most frequently used APIs. This will preserve the null-safety guarantee when your Kotlin code is calling into any annotated APIs in the SDK. Even if you are using the Java programming language, you can still benefit from these annotations by using Android Studio to catch nullability contract violations.
Not a breaking change
Normally, nullability contract violations in Kotlin result in compilation errors. But to ensure the newly annotated APIs are compatible with your existing code, we are using an internal mechanism provided by the Kotlin compiler team to mark the APIs as recently annotated. Recently annotated APIs will result only in warnings instead of errors from the Kotlin compiler. You will need to use Kotlin 1.2.60 or later.
Our plan is to have newly added nullability annotations produce warnings only, and increase the severity level to errors starting in the following year's Android SDK. The goal is to provide you with sufficient time to update your code.
How to use the "Kotlin-friendly" SDK
To get started, go to Tools > SDK Manager in Android Studio. Select Android SDK on the left menu, and make sure the SDK Platforms tab is open.
Use SDK Manager in Android Studio to install SDK for API Level 28 Revision 6
Check Android 8.+ (P) and click OK. This will install the Android SDK Platform 28 revision 6 if it is not already installed. After that, set your project's compile SDK version to API 28 to start using the new Android Pie SDK with nullability annotations.
Use the Project Structure Dialog to change your project's Compile Sdk Version to API 28
You may also need to update your Kotlin plugin in Android Studio if it's not already up-to-date. Make sure your Kotlin plugin version is 1.2.60 or later by going to Tools > Kotlin > Configure Kotlin Plugin Updates.
Once it's set up, your builds will start showing warnings if you have any code that violates nullability contracts in the Android SDK. An example of such a warning is shown below.
Sample warning from the Kotlin compiler when code violates a
recently added nullability contract in the Android SDK.
You will also start seeing warnings in Android Studio's code editor if you call an Android API with the incorrect nullability. An example is shown below.
Android Studio warning about passing a null reference to a parameter
annotated as a recently non-null type in the android.graphics.Path API.
Leveraging nullability annotations from the Java programming language
You can benefit from the new nullability annotations even if your code is in the Java programming language. By default, Android Studio will highlight any nullability contract violations with a warning, like the one below:
Android Studio showing a warning about nullability contract violation
in code written in the Java programming language
To ensure that you have this inspection enabled, you can go to the IDE's settings page and search for "Constant conditions & exceptions" inspection and make sure that item is checked.
Use the Inspections page under Settings to ensure the Constant conditions & exceptions code inspection is enabled.
If you are using the Java programming language, nullability contract violations will not produce any compiler warning or error. Only the in-IDE code inspections are available to flag these issues.
You can also run code inspections across your entire project and see the aggregated results. Click on Analyze > Inspect Code… to start.
What's Next
The Android SDK API surface is very large, and we have only annotated a small percentage of the APIs so far - there is still lots of work remaining. Over the next several Android SDK releases, we will continue to add nullability annotations to the existing Android APIs, as well as making sure new APIs are annotated.
With the "Kotlin-friendly" Android SDK, the nullability annotations in AndroidX (part of the Jetpack family), and Android KTX, we are continuing to improve the Android APIs for developers using Kotlin. If you have not yet tried Kotlin, we encourage you to try it. Not only can Kotlin make your code more concise, it can also improve the stability of your apps.
Happy Kotlin-ing!
