Platform types and Java nullability

A Java method declared as String findCity(String pin) returns a city for three PIN codes and null for every other one, and nothing in its signature says so. Kotlin cannot see inside Java code, so it neither trusts the result nor distrusts it: it gives the value a platform typeplatform type: The type Kotlin gives a value from Java code without nullability annotations, shown as String! in messages. It may or may not hold null, and the compiler lets the code treat it either way., written String!, and leaves the decision to you.

You will see what each decision does when a null arrives, make Java code state its nullability with JSpecify annotations, and wrap a Java class you cannot change behind a Kotlin adapter with exact types.

A value from unannotated Java has a platform type

PinDirectory is a Java class without any nullability annotation. The session compiles it with javac, compiles a Kotlin file against it with kotlinc, and runs the result:

from session import run

# A Java class without nullability annotations, compiled with javac, then used from Kotlin in four ways; and one
# deliberate type mismatch, so that the compiler's message shows the platform type String!.
run("""
cd plain
javac -d out PinDirectory.java
kotlinc -cp out Main.kt -include-runtime -d main.jar
java -cp main.jar:out MainKt
!kotlinc -cp out Show.kt -d show
""")

$ cd plain
$ javac -d out PinDirectory.java
$ kotlinc -cp out Main.kt -include-runtime -d main.jar
$ java -cp main.jar:out MainKt
110001: New Delhi, 9 letters
999999 as String?: no city
inferred: java.lang.NullPointerException: Cannot invoke "String.length()" because "city" is null
declared String: java.lang.NullPointerException: findCity(...) must not be null
$ kotlinc -cp out Show.kt -d show
Show.kt:3:21: error: initializer type mismatch: expected 'Int', actual 'String!'.
    val digits: Int = PinDirectory().findCity("110001")
                    ^
[exit status 1]

delhi.length compiled without a ?., although findCity can return null: the compiler allows every call on platform types and reports nothing. The last command is a deliberate mistake whose message names the type it gave the value, String!, meaning “String or String?, the compiler does not know which”. You cannot write String! yourself; it appears only in messages and in the editor’s hints.

Platform types leave the decision to you, and the decision is the type your code gives the value. Step through the PIN code 999999, which the directory does not know:

A variable declared String? is always safe: the compiler then asks for ?. or ?:, and the program printed “no city”. A variable declared String is checked by Kotlin when it is assigned, so a null fails there, with a message that names the Java call. A variable with an inferred type keeps the platform type and fails later, wherever it is used. The coding conventions turn this into a rule for public code: a function that returns a value of a platform type declares its Kotlin type, so that the decision is made once, where the value enters Kotlin.

Nullability annotations turn platform types into real types

Java nullability can be written into the Java code itself, as nullability annotationsnullability annotation: An annotation in Java code, such as JSpecify's @Nullable, that says whether a type may hold null. Kotlin reads it and sees the Java type as a real nullable or non-null type. that Kotlin reads. An annotated type reaches Kotlin as a real String? or String, and the compiler checks every use. JSpecify is a common set of such annotations for JVM languages: inside a class or package marked @NullMarked@NullMarked: A JSpecify annotation on a class, a package or a module: inside it, every type that has no @Nullable is non-null., a type without @Nullable is non-null. Here is the same directory with two annotations, used from the code that compiled before:

from session import library, run

# The directory annotated with JSpecify 1.0.0, whose jar is checked against the SHA-256 published on Maven Central.
library("org.jspecify:jspecify:1.0.0", "marked/lib")
run("""
cd marked
shasum -a 256 lib/jspecify-1.0.0.jar
javac -cp lib/jspecify-1.0.0.jar -d out PinDirectory.java
!kotlinc -cp out:lib/jspecify-1.0.0.jar Broken.kt -d broken
kotlinc -cp out:lib/jspecify-1.0.0.jar Fixed.kt -include-runtime -d fixed.jar
java -cp fixed.jar:out:lib/jspecify-1.0.0.jar FixedKt
""")

$ cd marked
$ shasum -a 256 lib/jspecify-1.0.0.jar
1fad6e6be7557781e4d33729d49ae1cdc8fdda6fe477bb0cc68ce351eafdfbab  lib/jspecify-1.0.0.jar
$ javac -cp lib/jspecify-1.0.0.jar -d out PinDirectory.java
$ kotlinc -cp out:lib/jspecify-1.0.0.jar Broken.kt -d broken
Broken.kt:5:18: error: only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver of type 'String?'.
    println(delhi.length)
                 ^
Broken.kt:6:22: error: initializer type mismatch: expected 'String', actual 'String?'.
    val city: String = directory.findCity("999999")
                     ^
Broken.kt:8:32: error: null cannot be a value of a non-null type 'String'.
    println(directory.findCity(null))
                               ^^^^
[exit status 1]
$ kotlinc -cp out:lib/jspecify-1.0.0.jar Fixed.kt -include-runtime -d fixed.jar
$ java -cp fixed.jar:out:lib/jspecify-1.0.0.jar FixedKt
110001: 9 letters
999999: unknown PIN code

All three lines of Broken.kt would compile against the plain class, and all three are refused now, each with the message of an ordinary Kotlin type: findCity gives a String?, so delhi.length and the assignment to a String are refused, and its parameter is a non-null String, so findCity(null) is refused too. The fixed version handles null where the value arrives. The first command printed the SHA-256 of the JSpecify 1.0.0 jar, so you can check that your copy is the same file.

Kotlin reads several families of nullability annotations, and Java nullability reached more code in stages:

Since Kotlin 2.1.0, a JSpecify mismatch is an error by default, which is why Broken.kt failed instead of compiling with warnings. A Java library you call may already carry these annotations: the Spring Boot documentation says that most Spring projects provide null safety through JSpecify, and Android’s interop guide asks every public Java API to annotate the nullability of its parameters, returns and fields.

Where Kotlin checks values at the Java boundary, measured Pro: opens with a Pro, Premium or Ultimate pass

Moving a Java code base to JSpecify, step by step Pro: opens with a Pro, Premium or Ultimate pass

Practise: an adapter with exact types

LegacyDirectory is an old Java class that you cannot change, and it returns null in two ways without saying so. CityLookup.kt wraps it in a Kotlin class, and as given, three of its four checks fail:

from session import run

# The practice: an old Java class, and the Kotlin adapter whose checks fail as it is given.
run("""
cd practice
javac -d out LegacyDirectory.java
kotlinc -cp out CityLookup.kt -include-runtime -d lookup.jar
!java -cp lookup.jar:out CityLookupKt
""")

$ cd practice
$ javac -d out LegacyDirectory.java
$ kotlinc -cp out CityLookup.kt -include-runtime -d lookup.jar
$ java -cp lookup.jar:out CityLookupKt
ok   city("110001") = New Delhi, want New Delhi
FAIL city("999999") = NullPointerException, want null
FAIL cities("Goa") = NullPointerException, want []
FAIL cities("Kerala") = [Kochi, null, Thiruvananthapuram], want [Kochi, Thiruvananthapuram]
1 of 4 checks pass
[exit status 1]

Copy the two files, give CityLookup exact types, and run the four commands of the session until all four checks pass. First hint: city should say in its return type that the city may be unknown, and a platform list can be cleaned with orEmpty() and filterNotNull() before it leaves the adapter.

Then test what you know of platform types and of the annotations that replace them. The questions start with the idea your answers show you know least:

Interview questions

Key takeaways

• A value from unannotated Java has a platform type, shown as String! in messages, and the compiler allows every call on it, so a null fails while the program runs.
• Give a Java value its Kotlin type where it arrives: String? makes the compiler ask for ?. or ?:, and String fails at the assignment with a message that names the Java call.
• With nullability annotations such as JSpecify’s @NullMarked and @Nullable, Java types reach Kotlin as real String? and String, and since Kotlin 2.1.0 a JSpecify mismatch is a compile error.