在 Kotlin 中调用 Java 代码

Kotlin 在设计时就考虑了 Java 互操作性。可以从 Kotlin 中自然地调用现存的 Java 代码，并且在 Java 代码中也可以很顺利地调用 Kotlin 代码。在本节中我们会介绍从 Kotlin 中调用 Java 代码的一些细节。

几乎所有 Java 代码都可以使用而没有任何问题：

1. import java.util.*

3. fun demo(source: List<Int>) {
4. val list = ArrayList<Int>()
5. // “for”-循环用于 Java 集合：
6. for (item in source) {
7. list.add(item)
8. }
9. // 操作符约定同样有效：
10. for (i in 0..source.size - 1) {
11. list[i] = source[i] // 调用 get 和 set
12. }
13. }

Getter 和 Setter

遵循 Java 约定的 getter 和 setter 的方法（名称以 get 开头的无参数方法和以 set 开头的单参数方法）在 Kotlin 中表示为属性。Boolean 访问器方法（其中 getter 的名称以 is 开头而 setter 的名称以 set 开头）会表示为与 getter 方法具有相同名称的属性。例如：

1. import java.util.Calendar

3. fun calendarDemo() {
4. val calendar = Calendar.getInstance()
5. if (calendar.firstDayOfWeek == Calendar.SUNDAY) {  // 调用 getFirstDayOfWeek()
6. calendar.firstDayOfWeek = Calendar.MONDAY      // 调用ll setFirstDayOfWeek()
7. }
8. if (!calendar.isLenient) {                         // 调用 isLenient()
9. calendar.isLenient = true                      // 调用 setLenient()
10. }
11. }

请注意，如果 Java 类只有一个 setter，它在 Kotlin 中不会作为属性可见，因为 Kotlin 目前不支持只写（set-only）属性。

返回 void 的方法

如果一个 Java 方法返回 void，那么从 Kotlin 调用时中返回 Unit。万一有人使用其返回值，它将由 Kotlin 编译器在调用处赋值，因为该值本身是预先知道的（是 Unit）。

将 Kotlin 中是关键字的 Java 标识符进行转义

一些 Kotlin 关键字在 Java 中是有效标识符：in、 object、 is 等等。如果一个 Java 库使用了 Kotlin 关键字作为方法，你仍然可以通过反引号（`）字符转义它来调用该方法：

1. foo.`is`(bar)

空安全与平台类型

Java 中的任何引用都可能是 null，这使得 Kotlin 对来自 Java 的对象要求严格空安全是不现实的。Java 声明的类型在 Kotlin 中会被特别对待并称为平台类型。对这种类型的空检查会放宽，因此它们的安全保证与在 Java 中相同（更多请参见下文）。

考虑以下示例：

1. val list = ArrayList<String>() // 非空（构造函数结果）
2. list.add("Item")
3. val size = list.size // 非空（原生 int）
4. val item = list[0] // 推断为平台类型（普通 Java 对象）

当我们调用平台类型变量的方法时，Kotlin 不会在编译时报告可空性错误，但在运行时调用可能会失败，因为空指针异常或者 Kotlin 生成的阻止空值传播的断言：

1. item.substring(1) // 允许，如果 item == null 可能会抛出异常

平台类型是不可标示的，意味着不能在语言中明确地写下它们。当把一个平台值赋值给一个 Kotlin 变量时，可以依赖类型推断（该变量会具有推断出的的平台类型，如上例中 item 所具有的类型），或者我们可以选择我们期望的类型（可空或非空类型均可）：

1. val nullable: String? = item // 允许，没有问题
2. val notNull: String = item // 允许，运行时可能失败

如果我们选择非空类型，编译器会在赋值时触发一个断言。这防止 Kotlin 的非空变量保存空值。当我们把平台值传递给期待非空值等的 Kotlin 函数时，也会触发断言。总的来说，编译器尽力阻止空值通过程序向远传播（尽管鉴于泛型的原因，有时这不可能完全消除）。

平台类型表示法

如上所述，平台类型不能在程序中显式表述，因此在语言中没有相应语法。然而，编译器和 IDE 有时需要（在错误信息中、参数信息中等）显示他们，所以我们用一个助记符来表示他们：

• T! 表示“T 或者 T?”，
• (Mutable)Collection! 表示“可以可变或不可变、可空或不可空的 T 的 Java 集合”，
• Array<(out) T>! 表示“可空或者不可空的 T（或 T 的子类型）的 Java 数组”

### 可空性注解

具有可空性注解的Java类型并不表示为平台类型，而是表示为实际可空或非空的Kotlin 类型。编译器支持多种可空性注解，包括：

• JetBrains（org.jetbrains.annotations 包中的 @Nullable 和 @NotNull）
• Android（com.android.annotations 和 android.support.annotations)
• JSR-305（javax.annotation，详见下文）
• FindBugs（edu.umd.cs.findbugs.annotations）
• Eclipse（org.eclipse.jdt.annotation）
• Lombok（lombok.NonNull）。 你可以在 Kotlin 编译器源代码中找到完整的列表。

注解类型参数

可以标注泛型类型的类型参数，以便同时为其提供可空性信息。例如，考虑这些 Java 声明的注解：

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

在 Kotlin 中可见的是以下签名：

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

请注意 String 类型参数上的 @NotNull 注解。如果没有的话，类型参数会是平台类型：

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

标注类型参数适用于针对 Java 8 或更高版本环境，并且要求可空性注解支持 TYPE_USE 目标（org.jetbrains.annotations 15 或以上版本支持）。

JSR-305 支持

已支持 JSR-305 中定义的 @Nonnull注解来表示 Java 类型的可空性。

如果 @Nonnull(when = …) 值为 When.ALWAYS，那么该注解类型会被视为非空；When.MAYBE 与When.NEVER 表示可空类型；而 When.UNKNOWN 强制类型为平台类型。

可针对 JSR-305 注解编译库，但不需要为库的消费者将注解构件（如 jsr305.jar）指定为编译依赖。Kotlin 编译器可以从库中读取 JSR-305 注解，并不需要该注解出现在类路径中。

自 Kotlin 1.1.50 起，也支持自定义可空限定符（KEEP-79）（见下文）。

类型限定符别称（自 1.1.50 起）

如果一个注解类型同时标注有@TypeQualifierNickname与 JSR-305 @Nonnull（或者它的其他别称，如 @CheckForNull），那么该注解类型自身将用于检索精确的可空性，且具有与该可空性注解相同的含义：

1. @TypeQualifierNickname
2. @Nonnull(when = When.ALWAYS)
3. @Retention(RetentionPolicy.RUNTIME)
4. public @interface MyNonnull {
5. }

7. @TypeQualifierNickname
8. @CheckForNull // 另一个类型限定符别称的别称
9. @Retention(RetentionPolicy.RUNTIME)
10. public @interface MyNullable {
11. }

13. interface A {
14. @MyNullable String foo(@MyNonnull String x);
15. // 在 Kotlin（严格模式）中：`fun foo(x: String): String?`

17. String bar(List<@MyNonnull String> x);
18. // 在 Kotlin（严格模式）中：`fun bar(x: List<String>!): String!`
19. }

类型限定符默认值（自 1.1.50 起）

@TypeQualifierDefault引入应用时在所标注元素的作用域内定义默认可空性的注解。

这些注解类型应自身同时标注有 @Nonnull（或其别称）与 @TypeQualifierDefault(…) 注解，后者带有一到多个 ElementType 值：

• ElementType.METHOD 用于方法的返回值；
• ElementType.PARAMETER 用于值参数；
• ElementType.FIELD 用于字段；以及
• ElementType.TYPE_USE（自 1.1.60 起）适用于任何类型，包括类型参数、类型参数的上界与通配符类型。 当类型并未标注可空性注解时使用默认可空性，并且该默认值是由最内层标注有带有与所用类型相匹配的ElementType 的类型限定符默认注解的元素确定。

1. @Nonnull
2. @TypeQualifierDefault({ElementType.METHOD, ElementType.PARAMETER})
3. public @interface NonNullApi {
4. }

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

11. @NullableApi
12. interface A {
13. String foo(String x); // fun foo(x: String?): String?

15. @NotNullApi // 覆盖来自接口的默认值
16. String bar(String x, @Nullable String y); // fun bar(x: String, y: String?): String

18. // 由于 `@NullableApi` 具有 `TYPE_USE` 元素类型，
19. // 因此认为 List<String> 类型参数是可空的：
20. String baz(List<String> x); // fun baz(List<String?>?): String?

22. // “x”参数仍然是平台类型，因为有显式
23. // UNKNOWN 标记的可空性注解：
24. String qux(@Nonnull(when = When.UNKNOWN) String x); // fun baz(x: String!): String?
25. }

注意：本例中的类型只在启用了严格模式时出现，否则仍是平台类型。参见 @UnderMigration 注解与编译器配置两节。

也支持包级的默认可空性：

1. // 文件：test/package-info.java
2. @NonNullApi // 默认将“test”包中所有类型声明为不可空
3. package test;

@UnderMigration 注解（自 1.1.60 起）

库的维护者可以使用 @UnderMigration 注解（在单独的构件 kotlin-annotations-jvm 中提供）来定义可为空性类型限定符的迁移状态。 @UnderMigration(status = ...) 中的状态值指定了编译器如何处理 Kotlin 中注解类型的不当用法（例如，使用 @MyNullable 标注的类型值作为非空值）： - MigrationStatus.STRICT 使注解像任何纯可空性注解一样工作，即对不当用法报错并影响注解声明内的类型在 Kotlin 中的呈现； - 对于 MigrationStatus.WARN，不当用法报为警告而不是错误；但注解声明内的类型仍是平台类型；而 - MigrationStatus.IGNORE 则使编译器完全忽略可空性注解。 库的维护者还可以将 @UnderMigration 状态添加到类型限定符别称与类型限定符默认值：

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

7. // 类中的类型是非空的，但是只报警告
8. // 因为 `@NonNullApi` 标注了 `@UnderMigration(status = MigrationStatus.WARN)`
9. @NonNullApi
10. public class Test {}

注意：可空性注解的迁移状态并不会从其类型限定符别称继承，而是适用于默认类型限定符的用法。

如果默认类型限定符使用类型限定符别称，并且它们都标注有 @UnderMigration，那么使用默认类型限定符的状态。

编译器配置

可以通过添加带有以下选项的 -Xjsr305 编译器标志来配置 JSR-305 检测：

• -Xjsr305={strict|warn|ignore} 设置非 @UnderMigration 注解的行为。自定义的可空性限定符，尤其是@TypeQualifierDefault 已经在很多知名库中流传，而用户更新到包含 JSR-305 支持的 Kotlin 版本时可能需要平滑迁移。自 Kotlin 1.1.60 起，这一标志只影响非 @UnderMigration 注解。
• -Xjsr305=under-migration:{strict|warn|ignore}（自 1.1.60 起）覆盖 @UnderMigration 注解的行为。用户可能对库的迁移状态有不同的看法：他们可能希望在官方迁移状态为 WARN 时报错误，反之亦然，他们可能希望推迟错误报告直到他们完成迁移。
• -Xjsr305=@:{strict|warn|ignore}（自 1.1.60 起）覆盖单个注解的行为，其中 是该注解的完整限定类名。对于不同的注解可以多次出现。这对于管理特定库的迁移状态非常有用。

其中 strict、 warn 与 ignore 值的含义与 MigrationStatus 中的相同，并且只有 strict 模式会影响注解声明中的类型在 Kotlin 中的呈现。

注意：内置的 JSR-305 注解 @Nonnull、 @Nullable 与 @CheckForNull 总是启用并影响所注解的声明在 Kotlin 中呈现，无论如何配置编译器的 -Xjsr305 标志。

例如，将 -Xjsr305=ignore -Xjsr305=under-migration:ignore -Xjsr305=@org.library.MyNullable:warn 添加到编译器参数中，会使编译器对由@org.library.MyNullable 标注的不当用法生成警告，而忽略所有其他 JSR-305 注解。

对于 kotlin 1.1.50+/1.2 版本，其默认行为等同于 -Xjsr305=warn。strict 值应认为是实验性的（以后可能添加更多检测）。

已映射类型

Kotlin 特殊处理一部分 Java 类型。这样的类型不是“按原样”从 Java 加载，而是 映射 到相应的 Kotlin 类型。映射只发生在编译期间，运行时表示保持不变。Java 的原生类型映射到相应的 Kotlin 类型（请记住平台类型）：

{:.zebra}

一些非原生的内置类型也会作映射：

{:.zebra}

Java 的装箱原始类型映射到可空的 Kotlin 类型：

{:.zebra}

请注意，用作类型参数的装箱原始类型映射到平台类型：例如，List<java.lang.Integer> 在 Kotlin 中会成为 List<Int!>。

集合类型在 Kotlin 中可以是只读的或可变的，因此 Java 集合类型作如下映射：（下表中的所有 Kotlin 类型都驻留在 kotlin.collections包中）:

{:.zebra}

Java 的数组按下文所述映射：

{:.zebra}

注意：这些 Java 类型的静态成员不能在相应 Kotlin 类型的伴生对象中直接访问。要调用它们，请使用 Java 类型的完整限定名，例如 java.lang.Integer.toHexString(foo)。

Kotlin 中的 Java 泛型

Kotlin 的泛型与 Java 有点不同（参见泛型）。当将 Java 类型导入 Kotlin 时，我们会执行一些转换：

• Java 的通配符转换成类型投影，

• Foo 转换成 Foo!，

• Foo 转换成 Foo!；

• Java的原始类型转换成星投影，

• List 转换成 List<>!，即 List!。 和 Java 一样，Kotlin 在运行时不保留泛型，即对象不携带传递到他们构造器中的那些类型参数的实际类型。即 ArrayList<Integer>() 和 ArrayList<Character>() 是不能区分的。这使得执行 is-检测不可能照顾到泛型。Kotlin 只允许 _*is**_-检测星投影的泛型类型：

1. if (a is List<Int>) // 错误：无法检查它是否真的是一个 Int 列表
2. // but
3. if (a is List<*>) // OK：不保证列表的内容

Java 数组

与 Java 不同，Kotlin 中的数组是不型变的。这意味着 Kotlin 不允许我们把一个 Array<String> 赋值给一个 Array<Any>，从而避免了可能的运行时故障。Kotlin 也禁止我们把一个子类的数组当做超类的数组传递给 Kotlin 的方法，但是对于 Java 方法，这是允许的（通过 Array<(out) String>! 这种形式的平台类型）。

Java 平台上，数组会使用原生数据类型以避免装箱/拆箱操作的开销。由于 Kotlin 隐藏了这些实现细节，因此需要一个变通方法来与 Java 代码进行交互。对于每种原生类型的数组都有一个特化的类（IntArray、 DoubleArray、 CharArray 等等）来处理这种情况。它们与 Array 类无关，并且会编译成 Java 原生类型数组以获得最佳性能。

假设有一个接受 int 数组索引的 Java 方法：

1. public class JavaArrayExample {

3. public void removeIndices(int[] indices) {
4. // 在此编码……
5. }
6. }

在 Kotlin 中你可以这样传递一个原生类型的数组：

1. val javaObj = JavaArrayExample()
2. val array = intArrayOf(0, 1, 2, 3)
3. javaObj.removeIndices(array)  // 将 int[] 传给方法

当编译为 JVM 字节代码时，编译器会优化对数组的访问，这样就不会引入任何开销：

1. val array = arrayOf(1, 2, 3, 4)
2. array[1] = array[1] * 2 // 不会实际生成对 get() 和 set() 的调用
3. for (x in array) { // 不会创建迭代器
4. print(x)
5. }

即使当我们使用索引定位时，也不会引入任何开销：

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

最后，in-检测也没有额外开销：

1. if (i in array.indices) { // 同 (i >= 0 && i < array.size)
2. print(array[i])
3. }

Java 可变参数

Java 类有时声明一个具有可变数量参数（varargs）的方法来使用索引：

1. public class JavaArrayExample {

3. public void removeIndicesVarArg(int... indices) {
4. // 在此编码……
5. }
6. }

在这种情况下，你需要使用展开运算符 * 来传递 IntArray：

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

目前无法传递 null 给一个声明为可变参数的方法。

操作符

由于 Java 无法标记用于运算符语法的方法，Kotlin 允许具有正确名称和签名的任何 Java 方法作为运算符重载和其他约定（invoke() 等）使用。不允许使用中缀调用语法调用 Java 方法。

受检异常

在 Kotlin 中，所有异常都是非受检的，这意味着编译器不会强迫你捕获其中的任何一个。因此，当你调用一个声明受检异常的 Java 方法时，Kotlin 不会强迫你做任何事情：

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

对象方法

当 Java 类型导入到 Kotlin 中时，类型 java.lang.Object 的所有引用都成了 Any。而因为 Any 不是平台指定的，它只声明了 toString()、hashCode() 和 equals() 作为其成员，所以为了能用到 java.lang.Object 的其他成员，Kotlin 要用到扩展函数。

wait()/notify()

《Effective Java》第三版 第 81 条善意地建议优先使用并发工具（concurrency utilities）而不是 wait() 和 notify()。因此，类型 Any 的引用不提供这两个方法。如果你真的需要调用它们的话，你可以将其转换为 java.lang.Object：

1. (foo as java.lang.Object).wait()

getClass()

要取得对象的 Java 类，请在类引用上使用 java 扩展属性：

1. val fooClass = foo::class.java

上面的代码使用了自 Kotlin 1.1 起支持的绑定的类引用。你也可以使用 javaClass 扩展属性：

1. val fooClass = foo.javaClass

clone()

要覆盖 clone()，需要继承 kotlin.Cloneable：

1. class Example : Cloneable {
2. override fun clone(): Any { …… }
3. }

不要忘记《Effective Java》第三版 的第 13 条: 谨慎地改写clone。

finalize()

要覆盖 finalize()，所有你需要做的就是简单地声明它，而不需要 override 关键字：

1. class C {
2. protected fun finalize() {
3. // 终止化逻辑
4. }
5. }

根据 Java 的规则，finalize() 不能是 private 的。

从 Java 类继承

在 kotlin 中，类的超类中最多只能有一个 Java 类（以及按你所需的多个 Java 接口）。

访问静态成员

Java 类的静态成员会形成该类的“伴生对象”。我们无法将这样的“伴生对象”作为值来传递，但可以显式访问其成员，例如：

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

要访问已映射到 Kotlin 类型的 Java 类型的静态成员，请使用 Java 类型的完整限定名：java.lang.Integer.bitCount(foo)。

Java 反射

Java 反射适用于 Kotlin 类，反之亦然。如上所述，你可以使用 instance::class.java,ClassName::class.java 或者 instance.javaClass 通过 java.lang.Class 来进入 Java 反射。

其他支持的情况包括为一个 Kotlin 属性获取一个 Java 的 getter/setter 方法或者幕后字段、为一个 Java 字段获取一个 KProperty、为一个 KFunction 获取一个 Java 方法或者构造函数，反之亦然。

SAM 转换

就像 Java 8 一样，Kotlin 支持 SAM 转换。这意味着 Kotlin 函数字面值可以被自动的转换成只有一个非默认方法的 Java 接口的实现，只要这个方法的参数类型能够与这个 Kotlin 函数的参数类型相匹配。

你可以这样创建 SAM 接口的实例：

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

……以及在方法调用中：

1. val executor = ThreadPoolExecutor()
2. // Java 签名：void execute(Runnable command)
3. executor.execute { println("This runs in a thread pool") }

如果 Java 类有多个接受函数式接口的方法，那么可以通过使用将 lambda 表达式转换为特定的 SAM 类型的适配器函数来选择需要调用的方法。这些适配器函数也会按需由编译器生成：

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

请注意，SAM 转换只适用于接口，而不适用于抽象类，即使这些抽象类也只有一个抽象方法。

还要注意，此功能只适用于 Java 互操作；因为 Kotlin 具有合适的函数类型，所以不需要将函数自动转换为 Kotlin 接口的实现，因此不受支持。

在 Kotlin 中使用 JNI

要声明一个在本地（C 或 C++）代码中实现的函数，你需要使用 external 修饰符来标记它：

1. external fun foo(x: Int): Double

其余的过程与 Java 中的工作方式完全相同。

原文: <https://hltj.gitbooks.io/kotlin-reference-chinese/content/txt/java-interop.html>