Kotlin-Java interop guide

This document is a set of rules for authoring public APIs in Java and Kotlin with the intent that the code will feel idiomatic when consumed from the other language.

Last update: 2024-07-29

Java (for Kotlin consumption)

No hard keywords

Don't use any of Kotlin's hard keywords as the name of methods or fields. These require the use of backticks to escape when calling from Kotlin. Soft keywords, modifier keywords, and special identifiers are allowed.

For example, Mockito's when function requires backticks when used from Kotlin:

val callable = Mockito.mock(Callable::class.java)
Mockito.`when`(callable.call()).thenReturn(/* … */)

Avoid `Any` extension names

Avoid using the names of the extension functions on Any for methods or the names of the extension properties on Any for fields unless absolutely necessary. While member methods and fields will always have precedence over Any's extension functions or properties, it can be difficult when reading the code to know which one is being called.

Nullability annotations

Every non-primitive parameter, return, and field type in a public API should have a nullability annotation. Non-annotated types are interpreted as "platform" types, which have ambiguous nullability.

By default, the Kotlin compiler flags honors JSR 305 annotations but flags them with warnings. You can also set a flag to have the compiler treat the annotations as errors.

Lambda parameters last

Parameter types eligible for SAM conversion should be last.

For example, RxJava 2's Flowable.create() method signature is defined as:

public static <T> Flowable<T> create(
    FlowableOnSubscribe<T> source,
    BackpressureStrategy mode) { /* … */ }

Because FlowableOnSubscribe is eligible for SAM conversion, function calls of this method from Kotlin look like this:

Flowable.create({ /* … */ }, BackpressureStrategy.LATEST)

If the parameters were reversed in the method signature, though, function calls could use the trailing-lambda syntax:

Flowable.create(BackpressureStrategy.LATEST) { /* … */ }

Property prefixes

For a method to be represented as a property in Kotlin, strict "bean"-style prefixing must be used.

Accessor methods require a get prefix or for boolean-returning methods an is prefix can be used.

public final class User {
  public String getName() { /* … */ }
  public boolean isActive() { /* … */ }
}

val name = user.name // Invokes user.getName()
val active = user.isActive // Invokes user.isActive()

Associated mutator methods require a set prefix.

public final class User {
  public String getName() { /* … */ }
  public void setName(String name) { /* … */ }
  public boolean isActive() { /* … */ }
  public void setActive(boolean active) { /* … */ }
}

user.name = "Bob" // Invokes user.setName(String)
user.isActive = true // Invokes user.setActive(boolean)

If you want methods exposed as properties, don't use non-standard prefixes like has, set or non-get-prefixed accessors. Methods with non-standard prefixes are still callable as functions, which may be acceptable depending on the behavior of the method.

Operator overloading

Be mindful of method names that allow special call-site syntax (such as operator overloading in Kotlin). Ensure that methods names as such make sense to use with the shortened syntax.

public final class IntBox {
  private final int value;
  public IntBox(int value) {
    this.value = value;
  }
  public IntBox plus(IntBox other) {
    return new IntBox(value + other.value);
  }
}

val one = IntBox(1)
val two = IntBox(2)
val three = one + two // Invokes one.plus(two)

Kotlin (for Java consumption)

Filename

When a file contains top-level functions or properties, always annotate it with @file:JvmName("Foo") to provide a nice name.

By default, top-level members in a file MyClass.kt will end up in a class called MyClassKt which is unappealing and leaks the language as an implementation detail.

Consider adding @file:JvmMultifileClass to combine the top-level members from multiple files into a single class.

Lambda arguments

Single method interfaces (SAM) defined in Java can be implemented in both Kotlin and Java using lambda syntax, which inlines the implementation in an idiomatic way. Kotlin has several options for defining such interfaces, each with a slight difference.

Preferable definition

Higher-order functions that are meant to be used from Java shouldn't take function types that return Unit as that would require Java callers to return Unit.INSTANCE. Instead of inlining the function type in the signature, use functional (SAM) interfaces. Also consider using functional (SAM) interfaces instead of regular interfaces when defining interfaces that are expected to be used as lambdas, which allows idiomatic usage from Kotlin.

Consider this Kotlin definition:

fun interface GreeterCallback {
  fun greetName(String name)
}

fun sayHi(greeter: GreeterCallback) = /* … */

When invoked from Kotlin:

sayHi { println("Hello, $it!") }

When invoked from Java:

sayHi(name -> System.out.println("Hello, " + name + "!"));

Even when the function type does not return a Unit it might still be a good idea to make it a named interface to allow callers to implement it with a named class and not just lambdas (in both Kotlin and Java).

class MyGreeterCallback : GreeterCallback {
  override fun greetName(name: String) {
    println("Hello, $name!");
  }
}

Avoid function types that return `Unit`

Consider this Kotlin definition:

fun sayHi(greeter: (String) -> Unit) = /* … */

It requires Java callers to return Unit.INSTANCE:

sayHi(name -> {
  System.out.println("Hello, " + name + "!");
  return Unit.INSTANCE;
});

Avoid functional interfaces when the implementation is meant to have state

When the interface implementation is meant to have a state, using the lambda syntax doesn't make sense. Comparable is a prominent example, as it's meant to compare this to other, and lambdas don't have this. Not prefixing the interface with fun forces the caller to use object : ... syntax, which allows it to have state, providing a hint to the caller.

Consider this Kotlin definition:

// No "fun" prefix.
interface Counter {
  fun increment()
}

It prevents lambda syntax in Kotlin, requiring this longer version:

runCounter(object : Counter {
  private var increments = 0 // State

  override fun increment() {
    increments++
  }
})

Avoid `Nothing` generics

A type whose generic parameter is Nothing is exposed as raw types to Java. Raw types are rarely used in Java and should be avoided.

Document exceptions

Functions which can throw checked exceptions should document them with @Throws. Runtime exceptions should be documented in KDoc.

Be mindful of the APIs a function delegates to as they may throw checked exceptions which Kotlin otherwise silently allows to propagate.

Defensive copies

When returning shared or unowned read-only collections from public APIs, wrap them in an unmodifiable container or perform a defensive copy. Despite Kotlin enforcing their read-only property, there is no such enforcement on the Java side. Without the wrapper or defensive copy, invariants can be violated by returning a long-lived collection reference.

Companion functions

Public functions in a companion object must be annotated with @JvmStatic to be exposed as a static method.

Without the annotation, these functions are only available as instance methods on a static Companion field.

Incorrect: no annotation

class KotlinClass {
    companion object {
        fun doWork() {
            /* … */
        }
    }
}

public final class JavaClass {
    public static void main(String... args) {
        KotlinClass.Companion.doWork();
    }
}

Correct: @JvmStatic annotation

class KotlinClass {
    companion object {
        @JvmStatic fun doWork() {
            /* … */
        }
    }
}

public final class JavaClass {
    public static void main(String... args) {
        KotlinClass.doWork();
    }
}

Companion constants

Public, non-const properties which are effective constants in a companion object must be annotated with @JvmField to be exposed as a static field.

Without the annotation, these properties are only available as oddly-named instance "getters" on the static Companion field. Using @JvmStatic instead of @JvmField moves the oddly-named "getters" to static methods on the class, which is still incorrect.

Incorrect: no annotation

class KotlinClass {
    companion object {
        const val INTEGER_ONE = 1
        val BIG_INTEGER_ONE = BigInteger.ONE
    }
}

public final class JavaClass {
    public static void main(String... args) {
        System.out.println(KotlinClass.INTEGER_ONE);
        System.out.println(KotlinClass.Companion.getBIG_INTEGER_ONE());
    }
}

Incorrect: @JvmStatic annotation

class KotlinClass {
    companion object {
        const val INTEGER_ONE = 1
        @JvmStatic val BIG_INTEGER_ONE = BigInteger.ONE
    }
}

public final class JavaClass {
    public static void main(String... args) {
        System.out.println(KotlinClass.INTEGER_ONE);
        System.out.println(KotlinClass.getBIG_INTEGER_ONE());
    }
}

Correct: @JvmField annotation

class KotlinClass {
    companion object {
        const val INTEGER_ONE = 1
        @JvmField val BIG_INTEGER_ONE = BigInteger.ONE
    }
}

public final class JavaClass {
    public static void main(String... args) {
        System.out.println(KotlinClass.INTEGER_ONE);
        System.out.println(KotlinClass.BIG_INTEGER_ONE);
    }
}

Idiomatic naming

Kotlin has different calling conventions than Java which can change the way you name functions. Use @JvmName to design names such that they'll feel idiomatic for both language's conventions or to match their respective standard library naming.

This most frequently occurs for extension functions and extension properties because the location of the receiver type is different.

sealed class Optional<T : Any>
data class Some<T : Any>(val value: T): Optional<T>()
object None : Optional<Nothing>()

@JvmName("ofNullable")
fun <T> T?.asOptional() = if (this == null) None else Some(this)

// FROM KOTLIN:
fun main(vararg args: String) {
    val nullableString: String? = "foo"
    val optionalString = nullableString.asOptional()
}

// FROM JAVA:
public static void main(String... args) {
    String nullableString = "Foo";
    Optional<String> optionalString =
          Optionals.ofNullable(nullableString);
}

Function overloads for defaults

Functions with parameters having a default value must use @JvmOverloads. Without this annotation it is impossible to invoke the function using any default values.

When using @JvmOverloads, inspect the generated methods to ensure they each make sense. If they don't, perform one or both of the following refactorings until satisfied:

Change the parameter order to prefer those with defaults being towards the end.
Move the defaults into manual function overloads.

Incorrect: No @JvmOverloads

class Greeting {
    fun sayHello(prefix: String = "Mr.", name: String) {
        println("Hello, $prefix $name")
    }
}

public class JavaClass {
    public static void main(String... args) {
        Greeting greeting = new Greeting();
        greeting.sayHello("Mr.", "Bob");
    }
}

Correct: @JvmOverloads annotation.

class Greeting {
    @JvmOverloads
    fun sayHello(prefix: String = "Mr.", name: String) {
        println("Hello, $prefix $name")
    }
}

public class JavaClass {
    public static void main(String... args) {
        Greeting greeting = new Greeting();
        greeting.sayHello("Bob");
    }
}

Lint Checks

Requirements

Android Studio version: 3.2 Canary 10 or later
Android Gradle Plugin version: 3.2 or later

Supported Checks

There are now Android Lint checks that will help you detect and flag some of the interoperability issues described previously. Only issues in Java (for Kotlin consumption) are detected. Specifically, the supported checks are:

Unknown Nullness
Property Access
No Hard Kotlin keywords
Lambda Parameters Last

Android Studio

To enable these checks, go to File > Preferences > Editor > Inspections and check the rules that you want to enable under Kotlin Interoperability:

Figure 1. Kotlin interoperability settings in Android Studio.

Once you have checked the rules you would like to enable, the new checks will run when you run your code inspections (Analyze > Inspect Code…)

Command-line builds

To enable these checks from the command-line builds, add the following line in your build.gradle file:

Groovy

android {

    ...

    lintOptions {
        enable 'Interoperability'
    }
}

Kotlin

android {
    ...

    lintOptions {
        enable("Interoperability")
    }
}

For the full set of configurations supported inside lintOptions, refer to the Android Gradle DSL reference.

Then, run ./gradlew lint from the command line.

Kotlin-Java interop guide

Java (for Kotlin consumption)

No hard keywords

Avoid Any extension names

Nullability annotations

Lambda parameters last

Property prefixes

Operator overloading

Kotlin (for Java consumption)

Filename

Lambda arguments

Preferable definition

Avoid function types that return Unit

Avoid functional interfaces when the implementation is meant to have state

Avoid Nothing generics

Document exceptions

Defensive copies

Companion functions

Companion constants

Idiomatic naming

Function overloads for defaults

Lint Checks

Requirements

Supported Checks

Android Studio

Command-line builds

Groovy

Kotlin

Avoid `Any` extension names

Avoid function types that return `Unit`

Avoid `Nothing` generics