在 Kotlin 中调用 Java 代码

符合 Java 的 Get 和 Set 方法规约的方法(无参数, 名称以 get 开头, 或单个参数, 名称以 set 开头) 在 Kotlin 中会被识别为属性. 这些属性也被称为 合成属性(Synthetic Property). Boolean 类型的属性访问方法(Get 方法名称以 is 开头, Set 方法名称以 set 开头), 会被识别为属性, 其名称与 Get 方法相同.

import java.util.Calendar

fun calendarDemo() {
    val calendar = Calendar.getInstance()
    if (calendar.firstDayOfWeek == Calendar.SUNDAY) { // 这里会调用 getFirstDayOfWeek()
        calendar.firstDayOfWeek = Calendar.MONDAY // 这里会调用 setFirstDayOfWeek()
    }
    if (!calendar.isLenient) { // 这里会调用 isLenient()
        calendar.isLenient = true // 这里会调用 setLenient()
    }
}

上面的 calendar.firstDayOfWeek 就是合成属性的一个例子.

注意, 如果 Java 类中只有 set 方法, 那么在 Kotlin 中不会被识别为属性, 因为 Kotlin 不支持只写(set-only) 的属性.

warning

这个功能是 实验性功能. 它随时有可能变更或被删除. 我们建议你只为评估和试验目的来使用这个功能..

从 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
         // 调用 Java 合成属性的引用:
        .sortedBy(Person::age)
         // 通过 Kotlin 属性语法调用 Java 的 get 方法:
        .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
}

如果一个 Java 方法返回值为 void, 那么在 Kotlin 中调用时将返回 Unit. 如果, 在 Kotlin 中使用了返回值, 那么会由 Kotlin 编译器在调用处赋值, 因为返回值已经预先知道了(等于 Unit).

某些 Kotlin 关键字在 Java 中是合法的标识符: in, object, is, 等等. 如果 Java 类库中使用 Kotlin 的关键字作为方法名, 你仍然可以调用这个方法, 只要使用反引号(`)对方法名转义即可:

foo.`is`(bar)

Java 中的所有引用都可以为 null 值, 因此对于来自 Java 的对象, Kotlin 的严格的 null 值安全性要求就变得毫无意义了. Java 中定义的类型在 Kotlin 中会被特别处理, 被称为 平台数据类型(platform type). 对于这些类型, Null 值检查会被放松, 因此对它们来说, 只提供与 Java 中相同的 null 值安全保证(详情参见下文).

我们来看看下面的例子:

val list = ArrayList<String>() // 非 null 值 (因为是构造器方法的返回结果)
list.add("Item")
val size = list.size // 非 null 值 (因为是基本类型 int)
val item = list[0] // 类型自动推断结果为平台类型 (通常的 Java 对象)

对于平台数据类型的变量, 当你调用它的方法时, Kotlin 不会在编译时刻报告可能为 null 的错误, 但这个调用在运行时可能失败, 原因可能是发生 null 指针异常, 也可能是 Kotlin 编译时为防止 null 值错误而产生的断言, 在运行时导致失败:

item.substring(1) // 编译时允许这样的调用, 但在运行时如果 item == null 则会抛出异常

平台数据类型是 无法指示的(non-denotable), 也就是说你不能在语言中明确指出这样的类型. 当平台数据类型的值赋值给 Kotlin 变量时, 你可以依靠类型推断 (这时变量的类型会被自动推断为平台数据类型, 比如上面示例程序中的变量 item 就是如此), 或者你也可以选择期望的数据类型(可为 null 的类型和非 null 类型都允许):

val nullable: String? = item // 允许, 永远不会发生错误
val notNull: String = item // 允许, 但在运行时刻可能失败

如果你选择使用非 null 类型, 那么编译器会在赋值处理之前输出一个断言(assertion). 它负责防止 Kotlin 中的非 null 变量指向一个 null 值. 比如, 当你将平台数据类型的值传递给 Kotlin 函数的非 null 值参数时, 也会输出断言, 其他情况也会类似处理. 总之, 编译器会尽可能地防止 null 值错误在程序中扩散, 然而, 有些时候由于泛型的存在, 不可能完全消除这种错误.

@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()) // 警告: 可否为 null 设置不匹配
}

public class Base<@NotNull T> {}

class Derived<K> : Base<K> {} // 警告: 未定义 K 可否为 null

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

class BaseWithBound<T : Number> {}

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

@TypeQualifierNickname
@CheckForNull // 另一个 TypeQualifierNickname 的别名
@Retention(RetentionPolicy.RUNTIME)
public @interface MyNullable {
}

interface A {
    @MyNullable String foo(@MyNonnull String x);
    // Kotlin (strict 模式) 中会被看作: `fun foo(x: String): String?`

    String bar(List<@MyNonnull String> x);
    // Kotlin (strict 模式) 中会被看作: `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); // 在 Kotlin 中会被看作: fun foo(x: String?): String?

    @NotNullApi // 这个注解将会覆盖接口上的可否为 null 默认设定
    String bar(String x, @Nullable String y); // 在 Kotlin 中会被看作: fun bar(x: String, y: String?): String

    // List<String> 的类型参数会被看作可为 null,
    // 因为 `@NullableApi` 中包括了 `TYPE_USE` ElementType:
    String baz(List<String> x); // 在 Kotlin 中会被看作: fun baz(List<String?>?): String?

    // 参数 `x` 的类型为平台类型, 因为它的可否为 null 注解明确标注为 UNKNOWN:
    String qux(@Nonnull(when = When.UNKNOWN) String x); // 在 Kotlin 中会被看作: fun baz(x: String!): String?
}

// FILE: test/package-info.java
@NonNullApi // 'test' 包内的所有声明, 默认都是非 null
package test;

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

// 这个类中的类型将是非空的, 但编译时只会报告警告
// 因为对 `@NonNullApi` 添加了 `@UnderMigration(status = MigrationStatus.WARN)` 注解
@NonNullApi
public class Test {}

Kotlin 会对某些 Java 类型进行特殊处理. 这些类型会被从 Java 中原封不动地装载进来, 但被 映射 为对应的 Kotlin 类型. 映射过程只会在编译时发生, 运行时的数据表达不会发生变化. Java 的基本数据类型会被映射为对应的 Kotlin 类型(但请注意 平台数据类型 问题):

有些内建类虽然不是基本类型, 也会被映射为对应的 Kotlin 类型:

Java 中的装箱的基本类型(boxed primitive type), 会被映射为 Kotlin 的可为 null 类型:

注意, 装箱的基本类型用作类型参数时, 会被映射为平台类型: 比如, List<java.lang.Integer> 在 Kotlin 中会变为 List<Int!>.

集合类型在 Kotlin 中可能是只读的, 也可能是内容可变的, 因此 Java 的集合会被映射为以下类型(下表中所有的 Kotlin 类型都属于 kotlin.collections 包):

Java 数据的映射如下, 详情参见 下文:

note

这些 Java 类型的静态成员, 无法通过 Kotlin 类型的同伴对象直接访问. 要访问这些静态成员, 需要使用 Java 类型的完整限定名称, 比如 java.lang.Integer.toHexString(foo).

Kotlin 的泛型 与 Java 的泛型略有差异 (参见 泛型). 将 Java 类型导入 Kotlin 时, 会进行以下变换:

• Java 的通配符会被变换为 Kotlin 的类型投射:

  • Foo<? extends Bar> 变换为 Foo<out Bar!>!

  • Foo<? super Bar> 变换为 Foo<in Bar!>!

• Java 的原生类型(raw type) 转换为 Kotlin 的星号投射(star projection):

  • List 变换为 List<*>!, 也就是 List<out Any?>!

与 Java 一样, Kotlin 的泛型信息在运行时不会保留: 创建对象时传递给构造器的类型参数信息, 在对象中不会保留下来. 比如, ArrayList<Integer>() 与 ArrayList<Character>() 在运行时刻是无法区分的. 这就导致无法进行带有泛型信息的 is 判断. Kotlin 只允许对星号投射(star projection)的泛型类型进行 is 判断:

if (a is List<Int>) // 错误: 无法判断它是不是 Int 构成的 List
// 但是
if (a is List<*>) // OK: 这里的判断不保证 List 内容的数据类型

与 Java 不同, Kotlin 中的数组是不可变的(invariant). 这就意味着, Kotlin 不允许你将 Array<String> 赋值给 Array<Any> ,这样就可以避免发生运行时错误. 在调用 Kotlin 方法时, 如果参数声明为父类型的数组, 那么将子类型的数组传递给这个参数, 也是禁止的, 但对于 Java 的方法, 通过使用 Array<(out) String>! 形式的平台数据类型, 这是允许.

在 Java 平台上, 会使用基本类型构成的数组, 以避免装箱(boxing)/拆箱(unboxing)操作带来的性能损失. 由于 Kotlin 会隐藏这些实现细节, 因此与 Java 代码交互时需要使用一个替代办法. 对于每种基本类型, 都存在一个专门的类(IntArray, DoubleArray, CharArray, 等等) 来解决这种问题. 这些类与 Array 类没有关系, 而且会被编译为 Java 的基本类型数组, 以便达到最好的性能.

假设有一个 Java 方法, 接受一个名为 indices 的参数, 类型是 int 数组:

public class JavaArrayExample {
    public void removeIndices(int[] indices) {
        // 方法代码在这里...
    }
}

为了向这个方法传递一个基本类型值构成的数组, 在 Kotlin 中你可以编写下面的代码:

val javaObj = JavaArrayExample()
val array = intArrayOf(0, 1, 2, 3)
javaObj.removeIndices(array)  // 向方法传递 int[] 参数

编译输出 JVM 字节码时, 编译器会对数组的访问处理进行优化, 因此不会产生性能损失:

val array = arrayOf(1, 2, 3, 4)
array[1] = array[1] * 2 // 编译器不会产生对 get() 和 set() 方法的调用
for (x in array) { // 不会创建迭代器(iterator)
    print(x)
}

即使你使用下标来访问数组元素, 也不会产生任何性能损失:

for (i in array.indices) { // 不会创建迭代器(iterator)
    array[i] += 2
}

最后, in 判断也不会产生性能损失:

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

Java 类的方法声明有时会对 indices 使用可变长的参数定义(varargs):

public class JavaArrayExample {

    public void removeIndicesVarArg(int... indices) {
        // 方法代码在这里...
    }
}

这种情况下, 为了将 IntArray 传递给这个参数, 需要使用展开(spread) * 操作符:

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

由于 Java 中无法将方法标记为操作符重载方法, Kotlin 允许我们使用任何的 Java 方法, 只要方法名称和签名定义满足操作符重载的要求, 或者满足其他规约(invoke() 等等.) 使用中缀调用语法来调用 Java 方法是不允许的.

在 Kotlin 中, 所有的异常都是不受控的(unchecked), 也就是说编译器不会强制要求你捕获任何异常. 因此, 当调用 Java 方法时, 如果这个方法声明了受控异常, Kotlin 不会要求你做任何处理:

fun render(list: List<*>, to: Appendable) {
    for (item in list) {
        to.append(item.toString()) // Java 会要求我们在这里捕获 IOException
    }
}

当 Java 类型导入 Kotlin 时, 所有 java.lang.Object 类型的引用都会被转换为 Any 类型. 由于 Any 类与具体的实现平台无关, 因此它声明的成员方法只有 toString(), hashCode() 和 equals(), 所以, 为了补足 java.lang.Object 中的其他方法, 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 处理逻辑
    }
}

Kotlin 类的超类中, 最多只能指定一个 Java 类(Java 接口的数量没有限制).

Java 类的静态成员(static member)构成这些类的"同伴对象(companion object)". 你不能将这样的"同伴对象" 当作值来传递, 但可以明确地访问它的成员, 比如:

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

当一个 Java 类型映射为一个 Kotlin 类型时, 如果要访问其中的静态成员, 需要使用 Java 类型的完整限定名: java.lang.Integer.bitCount(foo).

Java 的反射在 Kotlin 类中也可以使用, 反过来也是如此. 我们在上文中讲到, 你可以使用 instance::class.java, ClassName::class.java, 或者 instance.javaClass, 得到 java.lang.Class, 然后通过它就可以使用 Java 的反射功能. 这里不要使用 ClassName.javaClass, 因为它引用的是 ClassName 的同伴对象的类, 也就是 ClassName.Companion::class.java, 而不是 ClassName::class.java.

对每种基本类型, 有两种不同的 Java 类, Kotlin 对这两种类都提供了取得方法, 比如 Int::class.java 会返回表示基本类型本身的类实例, 对应于 Java 中的 Integer.TYPE. 要取得对应的包装对象(wrapper type)的类, 请使用 Int::class.javaObjectType, 等于 Java 的 Integer.class.

此外还支持其他反射功能, 比如可以得到 Kotlin 属性对应的 Java get/set 方法或后端成员, 可以得到 Java 成员变量对应的 KProperty, 得到 KFunction 对应的 Java 方法或构造器, 或者反过来得到 Java 方法或构造器对应的 KFunction.

Kotlin 支持 Java 和 Kotlin 接口 的 SAM(Single Abstract Method) 转换. 支持 Java 的 SAM 转换就是说, 如果一个 Java 接口中仅有一个方法, 并且没有默认实现, 那么只要 Java 接口方法与 Kotlin 函数参数类型一致, Kotlin 的函数字面值就可以自动转换为这个接口的实现者.

你可以使用这个功能来创建 SAM 接口的实例:

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

...也可以用在方法调用中:

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

如果 Java 类中有多个同名的方法, 而且方法参数都可以接受函数式接口, 那么你可以使用一个适配器函数(adapter function), 将 Lambda 表达式转换为某个具体的 SAM 类型, 然后就可以选择需要调用的方法. 编译器也会在需要的时候生成这些适配器函数:

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

note

SAM 转换只对接口有效, 不能用于抽象类, 即使抽象类中仅有唯一一个抽象方法.

要声明一个由本地代码(C 或者 C++)实现的函数, 你需要使用 external 修饰符标记这个函数:

external fun foo(x: Int): Double

剩下的工作与 Java 中完全相同.

还可以将属性的取得方法和设值方法标记为 external:

var myProperty: String
    external get
    external set

这段代码会创建两个函数 getMyProperty 和 setMyProperty, 并且都标记为 external.

在 Kotlin 代码中你可以使用 Java 代码由 Lombok 生成的声明. 如果你需要在 Java/Kotlin 代码混合的同一个模块中生成并使用这些声明, 具体方法请参见 Lombok 编译器插件. 如果你要在其他模块中使用这些声明, 那么不需要使用这个插件来编译这个模块.