Вызов Java из Kotlin

Геттеры и сеттеры

Методы, соответствующие соглашениям Java о геттерах и сеттерах (методы без аргументов, имена которых начинаются с get, и методы с одним аргументом, имена которых начинаются с set), представлены в Kotlin как свойства. Такие свойства также называются синтетическими свойствами. Boolean методы доступа (где имя геттера начинается с is, а имя сеттера — с set) представлены как свойства с тем же именем, что и метод-геттер.

import java.util.Calendar

fun calendarDemo() {
    val calendar = Calendar.getInstance()
    if (calendar.firstDayOfWeek == Calendar.SUNDAY) { // call getFirstDayOfWeek()
        calendar.firstDayOfWeek = Calendar.MONDAY // call setFirstDayOfWeek()
    }
    if (!calendar.isLenient) { // call isLenient()
        calendar.isLenient = true // call setLenient()
    }
}

Приведенный выше calendar.firstDayOfWeek — пример синтетического свойства.

Обратите внимание: если у класса Java есть только сеттер, он не виден в Kotlin как свойство, поскольку Kotlin не поддерживает свойства только для записи.

Ссылки на синтетические свойства Java

Начиная с Kotlin 1.8.20, можно создавать ссылки на синтетические свойства Java. Рассмотрим следующий код Java:

public class Person {
    private String name;
    private int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public String getName() {
        return name;
    }

    public int getAge() {
        return age;
    }
}

Kotlin всегда позволял писать person.age, где age — синтетическое свойство. Теперь можно также создавать ссылки на Person::age и person::age. То же самое применимо и к name.

val persons = listOf(Person("Jack", 11), Person("Sofie", 12), Person("Peter", 11))
    persons
         // Call a reference to Java synthetic property:
        .sortedBy(Person::age)
         // Call Java getter via the Kotlin property syntax:
        .forEach { person -> println(person.name) }

tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(
                org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1
            )
    }

tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion
            = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1
}

Методы, возвращающие void

Если метод Java возвращает void, при вызове из Kotlin он вернет Unit. Если кто-либо использует это возвращаемое значение, компилятор Kotlin присвоит его в месте вызова, поскольку само значение известно заранее (так как оно равно Unit).

Экранирование идентификаторов Java, являющихся ключевыми словами Kotlin

Некоторые ключевые слова Kotlin являются допустимыми идентификаторами в Java: in, object, is и другие. Если в библиотеке Java ключевое слово Kotlin используется в качестве имени метода, его все равно можно вызвать, экранировав обратными кавычками (`):

foo.`is`(bar)

Безопасность относительно null и платформенные типы

Любая ссылка в Java может быть null, из-за чего требования Kotlin к строгой безопасности относительно null непрактичны для объектов, полученных из Java. Типы объявлений Java рассматриваются в Kotlin как невыразимые и называются платформенными типами. Невыразимые типы нельзя явно записать в коде. Поэтому при присваивании платформенного значения переменной Kotlin можно:

• Положиться на вывод типов. В этом случае переменной будет присвоен выведенный платформенный тип.

• Выбрать предполагаемый тип. Kotlin допускает как nullable-, так и non-nullable-типы.

Проверки на null для таких типов ослаблены, поэтому гарантии безопасности для них такие же, как в Java (подробнее см. ниже). Рассмотрим следующие примеры:

val list = ArrayList<String>() // non-null (constructor result)
list.add("Item")
val size = list.size // non-null (primitive int)
val item = list[0] // platform type inferred (ordinary Java object)

При вызове методов у переменных платформенных типов Kotlin не сообщает об ошибках nullability во время компиляции, однако вызов может завершиться ошибкой во время выполнения из-за исключения о разыменовании null-указателя или проверки, которую Kotlin генерирует, чтобы предотвратить распространение null:

item.substring(1) // allowed, throws an exception if item == null

Значение платформенного типа можно присвоить переменной как nullable-, так и non-nullable-типа Kotlin. Однако если присвоить такое значение переменной non-nullable-типа, а во время выполнения значение окажется null, Kotlin выбросит NullPointerException. Чтобы этого избежать, явно укажите nullability в коде Kotlin:

val nullable: String? = item // allowed, always works
val notNull: String = item // allowed, may fail at runtime

Если выбрать non-nullable-тип, компилятор добавит проверку при присваивании. Это не позволит хранить null в non-nullable-переменных Kotlin. Проверки также добавляются при передаче платформенных значений функциям Kotlin, ожидающим non-null-значения, и в других случаях. В целом компилятор делает все возможное, чтобы не допустить распространения null по программе, хотя иногда полностью устранить его невозможно из-за обобщений.

-Xnullability-annotations=@<package-name>:<report-level>

@NotNull
Set<@NotNull String> toSet(@NotNull Collection<@NotNull String> elements) { ... }

fun toSet(elements: (Mutable)Collection<String>) : (Mutable)Set<String> { ... }

fun toSet(elements: (Mutable)Collection<String!>) : (Mutable)Set<String!> { ... }

public class Base<T> {}

public class Derived extends Base<@Nullable String> {}

fun takeBaseOfNotNullStrings(x: Base<String>) {}

fun main() {
    takeBaseOfNotNullStrings(Derived()) // warning: nullability mismatch
}

public class Base<@NotNull T> {}

class Derived<K> : Base<K> {} // warning: K has undefined nullability

public class BaseWithBound<T extends @NotNull Number> {}

class BaseWithBound<T : Number> {}

// Java
import org.jspecify.annotations.*;

@NullMarked
public class InventoryService {
    public String notNull() { return ""; }
    public @Nullable String nullable() { return null; }
}

// Kotlin
fun test(inventory: InventoryService) {
   inventory.notNull().length // OK
   inventory.nullable().length // Error: only safe (?.) or non-null asserted (!!) calls are allowed
}

-Xjspecify-annotations=<report-level>

@TypeQualifierNickname
@Nonnull(when = When.ALWAYS)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyNonnull {
}

@TypeQualifierNickname
@CheckForNull // a nickname to another type qualifier nickname
@Retention(RetentionPolicy.RUNTIME)
public @interface MyNullable {
}

interface A {
    @MyNullable String foo(@MyNonnull String x);
    // in Kotlin (strict mode): `fun foo(x: String): String?`

    String bar(List<@MyNonnull String> x);
    // in Kotlin (strict mode): `fun bar(x: List<String>!): String!`
}

@Nonnull
@TypeQualifierDefault({ElementType.METHOD, ElementType.PARAMETER})
public @interface NonNullApi {
}

@Nonnull(when = When.MAYBE)
@TypeQualifierDefault({ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE_USE})
public @interface NullableApi {
}

@NullableApi
interface A {
    String foo(String x); // fun foo(x: String?): String?

    @NotNullApi // overriding default from the interface
    String bar(String x, @Nullable String y); // fun bar(x: String, y: String?): String

    // The List<String> type argument is seen as nullable because of `@NullableApi`
    // having the `TYPE_USE` element type:
    String baz(List<String> x); // fun baz(List<String?>?): String?

    // The type of `x` parameter remains platform because there's an explicit
    // UNKNOWN-marked nullability annotation:
    String qux(@Nonnull(when = When.UNKNOWN) String x); // fun baz(x: String!): String?
}

// FILE: test/package-info.java
@NonNullApi // declaring all types in package 'test' as non-nullable by default
package test;

@Nonnull(when = When.ALWAYS)
@TypeQualifierDefault({ElementType.METHOD, ElementType.PARAMETER})
@UnderMigration(status = MigrationStatus.WARN)
public @interface NonNullApi {
}

// The types in the class are non-nullable, but only warnings are reported
// because `@NonNullApi` is annotated `@UnderMigration(status = MigrationStatus.WARN)`
@NonNullApi
public class Test {}

Сопоставленные типы

Kotlin обрабатывает некоторые типы Java особым образом. Такие типы загружаются не из Java «как есть», а сопоставляются с соответствующими типами Kotlin. Это сопоставление имеет значение только во время компиляции, представление во время выполнения остается неизменным. Примитивные типы Java сопоставляются с соответствующими типами Kotlin (учитывая платформенные типы):

Некоторые встроенные классы, не являющиеся примитивными, также сопоставляются:

Примитивные типы Java в упаковке сопоставляются с nullable-типами Kotlin:

Обратите внимание: примитивный тип в упаковке, используемый как параметр типа, сопоставляется с платформенным типом: например, List<java.lang.Integer> в Kotlin становится List<Int!>.

В Kotlin типы коллекций могут быть доступными только для чтения или изменяемыми, поэтому коллекции Java сопоставляются следующим образом (все типы Kotlin в этой таблице находятся в пакете kotlin.collections):

Массивы Java сопоставляются, как указано ниже:

Обобщения Java в Kotlin

Обобщения Kotlin немного отличаются от обобщений Java (см. раздел Обобщения). При импорте типов Java в Kotlin выполняются следующие преобразования:

• Подстановочные знаки Java преобразуются в проекции типов:

  • Foo<? extends Bar> становится Foo<out Bar!>!

  • Foo<? super Bar> становится Foo<in Bar!>!

• Сырые типы Java преобразуются в проекции со звездочкой:

  • List становится List<*>!, то есть List<out Any?>!

Как и в Java, обобщения Kotlin не сохраняются во время выполнения: объекты не содержат информации о фактических аргументах типов, переданных их конструкторам. Например, ArrayList<Integer>() неотличим от ArrayList<Character>(). Поэтому невозможно выполнять проверки is с учетом обобщений. Kotlin разрешает проверки is только для обобщенных типов с проекцией со звездочкой:

if (a is List<Int>) // Error: cannot check if it is really a List of Ints
// but
if (a is List<*>) // OK: no guarantees about the contents of the list

Массивы Java

В отличие от Java, массивы в Kotlin инвариантны. Это означает, что Kotlin не позволит присвоить Array<String> переменной типа Array<Any>, что предотвращает возможную ошибку во время выполнения. Передавать массив подкласса в метод Kotlin в качестве массива суперкласса также запрещено, но для методов Java это разрешено благодаря платформенным типам вида Array<(out) String>!.

На платформе Java массивы используются с примитивными типами данных, чтобы избежать затрат на упаковку и распаковку. Поскольку Kotlin скрывает эти детали реализации, для взаимодействия с кодом Java требуется обходное решение. Для этого предусмотрены специализированные классы для каждого типа массива примитивов (IntArray, DoubleArray, CharArray и так далее). Они не связаны с классом Array и компилируются в примитивные массивы Java для обеспечения максимальной производительности.

Предположим, что в Java есть метод, принимающий массив индексов типа int:

public class JavaArrayExample {
    public void removeIndices(int[] indices) {
        // code here...
    }
}

Чтобы передать массив примитивных значений, в Kotlin можно сделать следующее:

val javaObj = JavaArrayExample()
val array = intArrayOf(0, 1, 2, 3)
javaObj.removeIndices(array)  // passes int[] to method

При компиляции в байт-код JVM компилятор оптимизирует доступ к массивам, исключая дополнительные накладные расходы:

val array = arrayOf(1, 2, 3, 4)
array[1] = array[1] * 2 // no actual calls to get() and set() generated
for (x in array) { // no iterator created
    print(x)
}

Даже при обращении по индексу никаких дополнительных накладных расходов не возникает:

for (i in array.indices) { // no iterator created
    array[i] += 2
}

Наконец, проверки in также не требуют дополнительных накладных расходов:

if (i in array.indices) { // same as (i >= 0 && i < array.size)
    print(array[i])
}

Переменное число аргументов в Java

В классах Java иногда используется объявление метода с переменным числом аргументов (varargs) для индексов:

public class JavaArrayExample {

    public void removeIndicesVarArg(int... indices) {
        // code here...
    }
}

В этом случае для передачи IntArray нужно использовать оператор распространения *:

val javaObj = JavaArrayExample()
val array = intArrayOf(0, 1, 2, 3)
javaObj.removeIndicesVarArg(*array)

Операторы

Поскольку в Java нет способа пометить методы, для которых уместен операторный синтаксис, Kotlin разрешает использовать любые методы Java с подходящими именем и сигнатурой в качестве перегрузок операторов и для других соглашений (invoke() и т. д.). Вызов методов Java с использованием инфиксного синтаксиса не разрешен.

Проверяемые исключения

В Kotlin все исключения являются непроверяемыми, то есть компилятор не требует перехватывать их. Поэтому при вызове метода Java, объявляющего проверяемое исключение, Kotlin не требует от вас никаких действий:

fun render(list: List<*>, to: Appendable) {
    for (item in list) {
        to.append(item.toString()) // Java would require us to catch IOException here
    }
}

Методы Object

При импорте типов Java в Kotlin все ссылки на тип java.lang.Object преобразуются в Any. Поскольку Any не зависит от платформы, в нем объявлены только toString(), hashCode() и equals(), поэтому для предоставления доступа к другим членам java.lang.Object Kotlin использует функции-расширения.

import java.util.LinkedList

class SimpleBlockingQueue<T>(private val capacity: Int) {
    private val queue = LinkedList<T>()

    // java.lang.Object is used specifically to access wait() and notify()
    // In Kotlin, the standard 'Any' type does not expose these methods.
    @Suppress("PLATFORM_CLASS_MAPPED_TO_KOTLIN")
    private val lock = Object()

    fun put(item: T) {
        synchronized(lock) {
            while (queue.size >= capacity) {
                lock.wait()
            }
            queue.add(item)
            println("Produced: $item")

            lock.notifyAll()
        }
    }

    fun take(): T {
        synchronized(lock) {
            while (queue.isEmpty()) {
                lock.wait()
            }
            val item = queue.removeFirst()
            println("Consumed: $item")

            lock.notifyAll()
            return item
        }
    }
}

@Suppress("PLATFORM_CLASS_MAPPED_TO_KOTLIN")
(foo as java.lang.Object).wait()

val fooClass = foo::class.java

val fooClass = foo.javaClass

class Example : Cloneable {
    override fun clone(): Any { ... }
}

class C {
    protected fun finalize() {
        // finalization logic
    }
}

Наследование от классов Java

Класс в Kotlin может иметь в качестве суперкласса не более одного класса Java (и любое количество интерфейсов Java).

Доступ к статическим членам

Статические члены классов Java образуют для этих классов «объекты-компаньоны». Передавать такой «объект-компаньон» как значение нельзя, но можно обращаться к его членам напрямую, например:

if (Character.isLetter(a)) { ... }

Чтобы получить доступ к статическим членам типа Java, сопоставленного с типом Kotlin, используйте полное квалифицированное имя типа Java: java.lang.Integer.bitCount(foo).

Рефлексия Java

Рефлексия Java работает с классами Kotlin и наоборот. Как упоминалось выше, для перехода к рефлексии Java можно использовать instance::class.java, ClassName::class.java или instance.javaClass через java.lang.Class. Не используйте для этого ClassName.javaClass, поскольку оно ссылается на класс объекта-компаньона ClassName, который совпадает с ClassName.Companion::class.java, а не с ClassName::class.java.

Для каждого примитивного типа существуют два разных класса Java, и Kotlin предоставляет способы получить оба. Например, Int::class.java вернет экземпляр класса, представляющий сам примитивный тип и соответствующий Integer.TYPE в Java. Чтобы получить класс соответствующего типа-обертки, используйте Int::class.javaObjectType, что эквивалентно Integer.class в Java.

К другим поддерживаемым случаям относятся получение метода-геттера или метода-сеттера Java либо резервного поля свойства Kotlin, получение KProperty для поля Java, а также получение метода или конструктора Java для KFunction и наоборот.

SAM-преобразования

Kotlin поддерживает SAM-преобразования как для Java-, так и для интерфейсов Kotlin. Поддержка Java означает, что функциональные литералы Kotlin могут автоматически преобразовываться в реализации интерфейсов Java с одним нестандартным методом, если типы параметров метода интерфейса совпадают с типами параметров функции Kotlin.

Это можно использовать для создания экземпляров SAM-интерфейсов:

val runnable = Runnable { println("This runs in a runnable") }

...и при вызове методов:

val executor = ThreadPoolExecutor()
// Java signature: void execute(Runnable command)
executor.execute { println("This runs in a thread pool") }

Если в классе Java есть несколько методов, принимающих функциональные интерфейсы, нужный метод можно выбрать с помощью функции-адаптера, преобразующей лямбда-выражение в конкретный SAM-тип. При необходимости такие функции-адаптеры также генерируются компилятором:

executor.execute(Runnable { println("This runs in a thread pool") })

Использование JNI с Kotlin

Чтобы объявить функцию, реализованную в машинном коде (C или C++), необходимо пометить ее модификатором external:

external fun foo(x: Int): Double

Остальная часть процедуры выполняется точно так же, как в Java.

Геттеры и сеттеры свойств также можно пометить как external:

var myProperty: String
    external get
    external set

Внутри это создаст две функции getMyProperty и setMyProperty, обе помеченные как external.

Использование объявлений, сгенерированных Lombok, в Kotlin

В коде Kotlin можно использовать объявления, сгенерированные Lombok для Java. Если вам нужно сгенерировать и использовать эти объявления в одном смешанном модуле Java/Kotlin, инструкции приведены на странице плагина компилятора Lombok. Если вы вызываете такие объявления из другого модуля, использовать этот плагин для компиляции того модуля не нужно.