Does Kotlin stdlib provides stable Java API?

Support
#1

In mixed Java/Kotlin codebase I’ve seen usage of CollectionsKt#filter in Java code.

Is this API considered public or can it change between minor stdlib versions?

For Kotlin it doesn’t matter if filter moves between files, but for Java it’s important because we have to import class CollectionsKt, and if filter moves to IterablesKt than our code will break.

#2

Everything in the kotlin standard library is considered public and stable with a few exceptions. Those are documented with a special Experimental annotation (https://kotlinlang.org/docs/reference/experimental.html).
The features that are currently experimental (AFAIK) are: Multiplatform, Coroutines (to some extent) and unsinged numbers / inline classes.

#3

Remove a method from a class is a breaking change: your example is source compatible but not binary compatible.

#4

This document contains most of the important information about what is considered stable in kotlin and the definition of “stable” used: https://kotlinlang.org/docs/reference/evolution/kotlin-evolution.html

#5

We keep public binary API stable by dumping it as it is visible from Java and comparing that dump with the reference dump: https://github.com/JetBrains/kotlin/blob/1.3.50/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt

Beware that the reference dump also includes declarations marked as experimental and they are not distinguished currently in any special way, so it should not be considered as a list of entirely stable API — the original declarations written in Kotlin should be consulted for the experimental or deprecated status first.

So answering your original question, the public non-experimental Kotlin API visible from Java is considered stable and CollectionsKt#filter is not going to move from that class.

#6

Just out of interest, is there any easy way of generating such a file? I guess I can look at the kotlin project in github to see how it’s done but I imagine it’s hard to find without knowing where to look.

#7

The code that dumps these declaration is located two levels up, in the https://github.com/JetBrains/kotlin/blob/1.3.50/libraries/tools/binary-compatibility-validator/ subproject. It uses org.ow2.asm and kotlinx-metadata libraries to introspect classes. The code is tailored to the standard library specific needs, though we have the similar code dumping declarations for kotlinx.* libraries. Perhaps one day it could be extracted to a separate Gradle plugin or something like that.

1 Like
#8

This is the answer. Thank you.

#9

For future reference, I think it has been done now:

1 Like