Skip to content

在 Kotlin 中呼叫 Java ​

Kotlin 在設計時就充分考慮了與 Java 的互通性。現有的 Java 程式碼可以自然地在 Kotlin 中被呼叫, 而 Kotlin 程式碼也可以同樣順暢地在 Java 中使用。

你無需額外設定即可使用大部分的 Java 程式碼:

kotlin
import java.util.*

fun demo(source: List<Int>) {
    val list = ArrayList<Int>()
    // 'for' 迴圈適用於 Java 集合:
    for (item in source) {
        list.add(item)
    }
    // 運算子慣例也同樣適用:
    for (i in 0..<source.size) {
        list[i] = source[i] // 呼叫了 get 與 set
    }
}

Getters 與 setters ​

遵循 Java 的 getter 與 setter 慣例的方法(名稱以 get 開頭的無參數方法,以及名稱以 set 開頭的單參數方法)在 Kotlin 中會表示為屬性。這類屬性也被稱為「合成屬性」(synthetic properties)。 Boolean 存取子方法(getter 名稱以 is 開頭,setter 名稱以 set 開頭)則會表示為與 getter 方法同名的屬性。

kotlin
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 類別只有 setter,它在 Kotlin 中不會顯示為屬性,因為 Kotlin 不支援唯寫(set-only)屬性。

只有無參數的 getter 才會表示為合成屬性。如果 getter 具有接受引數的多載,該多載不會公開為屬性,在多數情況下你必須使用其完整的方法名稱來呼叫。請參考以下 Java 類別:

java
// Java
public class Greeting {
    public String getMessage() {
        return "Hello!";
    }

    public String getMessage(String name) {
        return "Hello, " + name + "!";
    }
}

無參數的 getMessage() 方法可透過合成屬性 message 來存取。若要使用多載的 getMessage(String) 方法,請將其作為函式呼叫:

kotlin
// Kotlin
fun main() {
    val greeting = Greeting()
    println(greeting.message)              // 透過合成屬性存取 getMessage()
    println(greeting.getMessage("Kotlin")) // 呼叫多載的 getMessage(String) 方法
}

呼叫 greeting.message("Kotlin") 無法通過編譯並會回傳未解決的參照錯誤(接收者型別不相符),因為 message 屬性不接受引數。

然而在某些情況下,當帶有參數的 Java 方法覆寫了 Kotlin 的成員擴充屬性的 getter 時,Kotlin 會將該方法視為屬性。因此你只能在接收者的作用域內將其作為屬性呼叫,而不能透過其方法名稱呼叫:

java
// Java
public class Greeter implements Message {
    public String getText(String name) {
        return "Hello, " + name + "!";
    }
}
kotlin
// Kotlin
interface Message {
    val String.text: String
}

fun demo(greeter: Greeter) {
    greeter.getText("Kotlin")       // 錯誤:未解決的參照
    with(greeter) { "Kotlin".text } // 透過成員擴充屬性存取 getText(String)
}

回傳 void 的方法 ​

如果 Java 方法回傳 void,從 Kotlin 呼叫時其傳回型別會變成 Unit。如果你使用該傳回值,由於該值已知,Kotlin 編譯器會在呼叫點指派 Unit。

對屬於 Kotlin 關鍵字的 Java 識別符號進行跳脫 ​

有些 Kotlin 關鍵字在 Java 中是合法的識別符號:如 in、object、is 等。如果 Java 程式庫中的方法使用了 Kotlin 關鍵字作為名稱,你仍然可以透過反引號(`)字元跳脫來呼叫該方法:

kotlin
matcher.`is`(expected)

Null 安全性與平台型別 ​

Java 中的任何參照都可能為 null,這使得 Kotlin 嚴格的 null 安全性要求對於來自 Java 的物件顯得不切實際。 Java 宣告的型別在 Kotlin 中會被視為不可標記型別(non-denotable),並稱為「平台型別」(platform types)。 你無法在程式碼中明確寫出這些不可標記型別。因此,當把平台型別的值指派給 Kotlin 變數時,你可以:

  • 依賴型別推論。在此情況下,該變數具有推論出的平台型別。
  • 選擇你期望的型別。Kotlin 同時允許可 null 型別與不可 null 型別。

平台型別放寬了 null 檢查,因此它們擁有與對應的 Java 型別相同的安全保證。請參考以下範例:

kotlin
val list = ArrayList<String>() // 非 null(建構函式結果)
list.add("Item")
val size = list.size // 非 null(基本型別 int)
val item = list[0] // 推論為平台型別(一般 Java 物件)

當你在平台型別的變數上呼叫方法時,Kotlin 在編譯期不會發出可 null 性錯誤,但在執行時期呼叫可能會失敗,原因可能是 NullPointer 異常,或是 Kotlin 為了防止 null 擴散而產生的斷言失敗:

kotlin
item.substring(1) // 允許,但如果 item == null 則會擲出異常

你可以將平台型別的值指派給可 null 或不可 null 的 Kotlin 型別變數。然而,如果你將該值指派給不可 null 型別的變數,而該值在執行時期實際上為 null,Kotlin 就會擲出 NullPointerException。為了避免這種情況,請在 Kotlin 程式碼中加入明確的可 null 性宣告:

kotlin
val nullable: String? = item // 允許,一律正常運作
val notNull: String = item // 允許,但執行時期可能會失敗

如果你選擇不可 null 型別,編譯器會在指派時發出斷言。這能防止 Kotlin 的不可 null 變數持有 null。當你將平台值傳遞給預期非 null 值的 Kotlin 函式等其他情況時,也會發出斷言。 總體而言,編譯器會盡最大努力防止 null 在程式中廣泛傳播,儘管有時因為泛型的關係無法完全消除。

平台型別的標記法 ​

如上一節所述,平台型別無法在程式中明確提及,因此語言中沒有針對它們的語法。然而,編譯器和 IDE 有時需要顯示它們(例如在錯誤訊息或參數提示中),因此提供了一種助記標記法:

  • T! 表示「T 或 T?」
  • (Mutable)Collection<T>! 表示「T 的 Java 集合,可能是可變的也可能不是,可能是可 null 的也可能不是」
  • Array<(out) T>! 表示「T(或 T 的子型別)的 Java 陣列,可能是可 null 的也可能不是」

當你在錯誤訊息或 IDE 工具提示中看到此標記法時,請為你的 Kotlin 變數新增明確的型別註解以還原 null 安全性檢查,或者使用可 null 性註解從來源端消除平台型別。

可 null 性註解 ​

帶有可 null 性註解的 Java 型別不會表示為平台型別,而是表示為實際的可 null 或不可 null Kotlin 型別。編譯器支援多種風格的可 null 性註解,包括:

  • JetBrains (來自 org.jetbrains.annotations 套件的 @Nullable 與 @NotNull)
  • JSpecify (org.jspecify.annotations)
  • Android (com.android.annotations、android.support.annotation、androidx.annotation、android.annotation)
  • JSR-305 (javax.annotation)
  • FindBugs (edu.umd.cs.findbugs.annotations)
  • Eclipse (org.eclipse.jdt.annotation)
  • Lombok (lombok.NonNull)
  • RxJava 3 (io.reactivex.rxjava3.annotations)
  • Vert.x (io.vertx.codegen.annotations)

你可以使用以下編譯器選項,指示編譯器針對特定的可 null 性註解回報可 null 性不符:

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

指定完全限定的可 null 性註解的套件名稱,以及以下報告層級之一:

  • ignore:忽略可 null 性不相符
  • warn:回報警告
  • strict:回報錯誤。

JSpecify 是唯一預設使用 strict 報告層級的受支援風格。 無需額外設定即可使用它針對可 null 性註解回報錯誤。

請參閱 Kotlin 編譯器原始碼以獲取受支援的可 null 性註解的完整清單。

可變性註解 ​

你可以使用可變性註解來標註 Java 宣告,以指定回傳的集合在 Kotlin 中是唯讀的還是可變的。 如果你將該值指派給具有不同可變性的集合型別,編譯器會回報型別不相符。 診斷嚴重層級取決於具體的可變性註解。

編譯器支援數種可變性註解,包括:

  • kotlin.annotations.jvm.ReadOnly
  • kotlin.annotations.jvm.Mutable
  • org.jetbrains.annotations.Unmodifiable
  • org.jetbrains.annotations.UnmodifiableView

請參閱 Kotlin 編譯器原始碼以獲取受支援的可變性註解的完整清單。

標註型別引數與型別參數 ​

你也可以標註泛型型別的型別引數和型別參數,為它們提供可 null 性資訊。

本節中的所有範例均使用來自 org.jetbrains.annotations 套件的 JetBrains 可 null 性註解。

型別引數 ​

請參考 Java 宣告上的這些註解:

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

它們會在 Kotlin 中產生以下簽章:

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

當型別引數缺少 @NotNull 註解時,你會得到平台型別:

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

Kotlin 還會考慮基底類別和介面的型別引數上的可 null 性註解。例如,有兩個具備以下簽章的 Java 類別:

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

在 Kotlin 程式碼中,在預期為 Base<String> 之處傳入 Derived 的執行個體會產生警告。

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

fun main() {
    takeBaseOfNotNullStrings(Derived()) // 警告:可 null 性不符
}

Derived 的上限被設定為 Base<String?>,這與 Base<String> 不同。

進一步了解 Kotlin 中的 Java 泛型。

型別參數 ​

預設情況下,Kotlin 和 Java 中普通型別參數的可 null 性都是未定義的。在 Java 中,你可以使用可 null 性註解來指定它。讓我們標註 Base 類別的型別參數:

java
public class Base<@NotNull T> {}

從 Base 繼承時,Kotlin 預期一個不可 null 的型別引數或型別參數。 因此,以下 Kotlin 程式碼會產生警告:

kotlin
class Derived<K> : Base<K> {} // 警告:K 具有未定義的可 null 性

你可以透過指定上限 K : Any 來解決此問題。

Kotlin 還支援在 Java 型別參數的界限上使用可 null 性註解。讓我們為 Base 新增界限:

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

Kotlin 將其轉譯如下:

kotlin
class BaseWithBound<T : Number> {}

因此傳入可 null 型別作為型別引數或型別參數會產生警告。

標註型別引數與型別參數需要 Java 8 目標或更高版本。該功能需要可 null 性註解支援 TYPE_USE 目標(org.jetbrains.annotations 在 15 及以上版本支援此功能)。

如果可 null 性註解除了 TYPE_USE 目標外還支援其他適用於型別的目標,則 TYPE_USE 具有優先權。例如,如果 @Nullable 同時具有 TYPE_USE 和 METHOD 目標,則 Java 方法簽章 @Nullable String[] f() 在 Kotlin 中會變成 fun f(): Array<String?>!。

JSpecify 支援 ​

Kotlin 支援 JSpecify 可 null 性註解,它為 Java 可 null 性提供了一套統一的註解。JSpecify 允許你為 Java 宣告提供詳細的可 null 性資訊,幫助 Kotlin 在與 Java 程式碼互動時維護 null 安全性。

Kotlin 支援 org.jspecify.annotations 套件中的以下註解:

  • @Nullable 將型別標記為可 null。

  • @NonNull 將型別標記為不可 null。

  • @NullMarked 將某個作用域(例如類別或套件)內的所有型別預設標記為不可 null,除非另有註解標註。

    此註解不適用於區域變數和型別變數(泛型)。型別變數會維持「與 null 無關」(null-agnostic),直到提供了具體的可 null 或不可 null 型別。

  • @NullUnmarked 則反轉 @NullMarked 的效果,將作用域內的所有型別還原為平台型別。

請參考以下帶有 JSpecify 註解的 Java 類別:

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

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

在 Kotlin 中,這些型別會被視為一般的可 null 和不可 null 型別,而不是平台型別:

kotlin
// Kotlin
fun test(inventory: InventoryService) {
    inventory.notNull().length  // 正常
    inventory.nullable().length // 錯誤:僅允許安全呼叫 (?.) 或非 null 斷言 (!!) 呼叫
}

預設情況下,Kotlin 編譯器會將 JSpecify 註解的可 null 性不相符回報為錯誤。 你可以使用以下編譯器選項來自訂 JSpecify 可 null 性診斷的嚴重層級:

bash
-Xjspecify-annotations=<report-level>

可用的報告層級為:

層級說明
strict將可 null 性不相符回報為錯誤(預設值)。
warn回報警告。
ignore忽略可 null 性不相符。

如需更多關於 JSpecify 註解的資訊,請參閱 JSpecify 使用者指南。

JSR-305 支援 ​

Kotlin 支援定義在 JSR-305 中的 @Nonnull 註解,用以表示 Java 型別的可 null 性。

如果 @Nonnull(when = ...) 的值為 When.ALWAYS,則被標註的型別會被視為不可 null;When.MAYBE 與 When.NEVER 表示可 null 型別;而 When.UNKNOWN 則會強制該型別成為平台型別。

程式庫可以針對 JSR-305 註解進行編譯,但沒有必要讓包含註解的構件(例如 jsr305.jar)成為該程式庫使用者的編譯相依性。Kotlin 編譯器可以直接從程式庫讀取 JSR-305 註解,而無需讓這些註解存在於 classpath 中。

同時也支援自訂可 null 性限定詞 (KEEP-79)(見下文)。

型別限定詞別名 (Type qualifier nicknames) ​

如果某個註解型別同時被 @TypeQualifierNickname 與 JSR-305 的 @Nonnull(或其另一個別名,如 @CheckForNull)所標註,那麼該註解型別本身就會被用來擷取精確的可 null 性,且具有與該可 null 性註解相同的含義:

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

@TypeQualifierNickname
@CheckForNull // 另一個型別限定詞別名的別名
@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!`
}

型別限定詞預設值 (Type qualifier defaults) ​

@TypeQualifierDefault 允許引入在套用時定義被標註元素作用域內預設可 null 性的註解。

此類註解型別本身應同時標註 @Nonnull(或其別名)以及帶有一個或多個 ElementType 值的 @TypeQualifierDefault(...):

  • ElementType.METHOD:用於方法的回傳型別
  • ElementType.PARAMETER:用於值參數
  • ElementType.FIELD:用於欄位
  • ElementType.TYPE_USE:用於任何型別,包括型別引數、型別參數的上限以及萬用字元型別

當型別本身未被可 null 性註解標註時,會套用預設的可 null 性,該預設值由標註了型別限定詞預設值註解且其 ElementType 與該型別用法相符的最內層封裝元素決定。

java
@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?

    @NonNullApi // 覆寫來自介面的預設值
    String bar(String x, @Nullable String y); // 在 Kotlin 中:fun bar(x: String, y: String?): String

    // 由於 `@NullableApi` 具有 `TYPE_USE` 元素型別,
    // List<String> 的型別引數被視為可 null:
    String baz(List<String> x); // 在 Kotlin 中:fun baz(List<String?>?): String?

    // 由於存在明確標記為 UNKNOWN 的可 null 性註解,
    // `x` 參數的型別仍保持為平台型別:
    String qux(@Nonnull(when = When.UNKNOWN) String x); // 在 Kotlin 中:fun qux(x: String!): String?
}

此範例中的型別僅在啟用 strict 模式時生效;否則仍保持為平台型別。 請參閱 @UnderMigration 註解與編譯器設定章節。

也支援套件層級的預設可 null 性:

java
// 檔案:test/package-info.java
@NonNullApi // 預設將 'test' 套件中的所有型別宣告為不可 null
package test;

@UnderMigration 註解 ​

程式庫維護者可以使用 @UnderMigration 註解(在獨立構件 kotlin-annotations-jvm 中提供)來定義可 null 性型別限定詞的遷移狀態。

@UnderMigration(status = ...) 中的狀態值指定了編譯器如何處理 Kotlin 中對被標註型別的不當用法(例如將標註了 @MyNullable 的型別值當作非 null 使用):

  • MigrationStatus.STRICT:讓該註解像一般可 null 性註解一樣運作,即針對不當用法回報錯誤,並影響標註宣告在 Kotlin 中呈現的型別
  • MigrationStatus.WARN:不當用法會被回報為編譯警告而非錯誤,但標註宣告中的型別仍保持為平台型別
  • MigrationStatus.IGNORE:使編譯器完全忽略該可 null 性註解

程式庫維護者可以將 @UnderMigration 狀態新增到型別限定詞別名和型別限定詞預設值中:

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

// 類別中的型別為不可 null,但僅會回報警告,
// 因為 `@NonNullApi` 標註了 `@UnderMigration(status = MigrationStatus.WARN)`
@NonNullApi
public class Test {}

可 null 性註解的遷移狀態不會被其型別限定詞別名繼承,但會套用於其在預設型別限定詞中的用法。

如果預設型別限定詞使用了型別限定詞別名,且它們都帶有 @UnderMigration,則會使用預設型別限定詞中的狀態。

編譯器設定 ​

可以透過新增帶有以下值(及其組合)的 -Xjsr305 編譯器選項來設定 JSR-305 檢查:

  • -Xjsr305={strict|warn|ignore}:設定非 @UnderMigration 註解的行為。 自訂可 null 性限定詞(特別是 @TypeQualifierDefault)已經廣泛存在於許多知名程式庫中,使用者在更新到包含 JSR-305 支援的 Kotlin 版本時可能需要平滑遷移。 此選項僅影響非 @UnderMigration 註解。
  • -Xjsr305=under-migration:{strict|warn|ignore}:覆寫 @UnderMigration 註解的行為。 使用者對於程式庫的遷移狀態可能有不同看法: 他們可能希望在官方遷移狀態為 WARN 時就報錯,反之亦然, 他們可能希望推遲某些程式庫的錯誤回報,直到完成遷移為止。
  • -Xjsr305=@<fq.name>:{strict|warn|ignore}:針對單個註解覆寫行為,其中 <fq.name> 是該註解的完全限定類別名稱。可以針對不同的註解多次出現。 這對於管理特定程式庫的遷移狀態非常有用。

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 註解。

預設行為與 -Xjsr305=warn 相同。strict 值應被視為實驗性的(未來可能會對其新增更多檢查)。

對應型別 (Mapped types) ​

Kotlin 會對某些 Java 型別進行特殊處理。這類型別不會直接從 Java「原樣」載入,而是會「對應」到相對應的 Kotlin 型別。 此對應僅在編譯期有意義,執行時期的表示形式保持不變。 Java 的基本型別會對應到相對應的 Kotlin 型別(同時考慮平台型別):

Java 型別Kotlin 型別
bytekotlin.Byte
shortkotlin.Short
intkotlin.Int
longkotlin.Long
charkotlin.Char
floatkotlin.Float
doublekotlin.Double
booleankotlin.Boolean

一些非基本型別的內建類別也會進行對應:

Java 型別Kotlin 型別
java.lang.Objectkotlin.Any!
java.lang.Cloneablekotlin.Cloneable!
java.lang.Comparablekotlin.Comparable!
java.lang.Enumkotlin.Enum!
java.lang.annotation.Annotationkotlin.Annotation!
java.lang.CharSequencekotlin.CharSequence!
java.lang.Stringkotlin.String!
java.lang.Numberkotlin.Number!
java.lang.Throwablekotlin.Throwable!

Java 的裝箱(boxed)基本型別會對應到可 null 的 Kotlin 型別:

Java 型別Kotlin 型別
java.lang.Bytekotlin.Byte?
java.lang.Shortkotlin.Short?
java.lang.Integerkotlin.Int?
java.lang.Longkotlin.Long?
java.lang.Characterkotlin.Char?
java.lang.Floatkotlin.Float?
java.lang.Doublekotlin.Double?
java.lang.Booleankotlin.Boolean?

請注意,用作型別參數的裝箱基本型別會對應到平台型別: 例如,List<java.lang.Integer> 在 Kotlin 中會變成 List<Int!>。

集合型別在 Kotlin 中可以是唯讀的或可變的,因此 Java 的集合對應如下 (此表格中的所有 Kotlin 型別均位於 kotlin.collections 套件中):

Java 型別Kotlin 唯讀型別Kotlin 可變型別載入的平台型別
Iterator<T>Iterator<T>MutableIterator<T>(Mutable)Iterator<T>!
Iterable<T>Iterable<T>MutableIterable<T>(Mutable)Iterable<T>!
Collection<T>Collection<T>MutableCollection<T>(Mutable)Collection<T>!
Set<T>Set<T>MutableSet<T>(Mutable)Set<T>!
List<T>List<T>MutableList<T>(Mutable)List<T>!
ListIterator<T>ListIterator<T>MutableListIterator<T>(Mutable)ListIterator<T>!
Map<K, V>Map<K, V>MutableMap<K, V>(Mutable)Map<K, V>!
Map.Entry<K, V>Map.Entry<K, V>MutableMap.MutableEntry<K,V>(Mutable)Map.(Mutable)Entry<K, V>!

Java 的陣列對應如下文所述:

Java 型別Kotlin 型別
int[]kotlin.IntArray!
String[]kotlin.Array<(out) String!>!

這些 Java 型別的 static 成員無法直接在 Kotlin 型別的伴生物件上存取。要呼叫它們,請使用 Java 型別的完全限定名稱,例如 java.lang.Integer.toHexString(255)。

Kotlin 中的 Java 泛型 ​

Kotlin 的泛型與 Java 略有不同(請參閱泛型)。 將 Java 型別匯入至 Kotlin 時,會執行以下轉換:

  • Java 的萬用字元會轉換為型別投影:

    • Foo<? extends Bar> 變成 Foo<out Bar!>!
    • Foo<? super Bar> 變成 Foo<in Bar!>!
  • Java 的原始型別(raw types)會轉換為星號投影:

    • List 變成 List<*>!,即 List<out Any?>!

與 Java 一樣,Kotlin 的泛型在執行時期不會被保留:物件不會攜帶傳遞給其建構函式的實際型別引數資訊。例如,ArrayList<Integer>() 與 ArrayList<Character>() 在執行時期是無法區分的。 這使得無法執行考慮泛型的 is 檢查。 Kotlin 僅允許對星號投影的泛型型別進行 is 檢查:

kotlin
if (a is List<Int>) // 錯誤:無法檢查它是否真的是 Int 的 List
// 但
if (a is List<*>)   // 正常:不對 list 的內容做任何保證

Java 陣列 ​

與 Java 不同,Kotlin 中的陣列是不變的(invariant)。這意味著 Kotlin 不允許你將 Array<String> 指派給 Array<Any>,從而避免了可能的執行時期失敗。將子類別的陣列作為超類別的陣列傳遞給 Kotlin 方法也是被禁止的,但對於 Java 方法,這可以透過形式為 Array<(out) String>! 的平台型別來允許。

在 Java 平台上,陣列會搭配基本資料型別使用,以避免裝箱/拆箱操作的開銷。 由於 Kotlin 隱藏了這些實作細節,因此需要一種因應措施來與 Java 程式碼互動。 針對每種基本型別陣列都有專門的類別(IntArray、DoubleArray、CharArray 等)來處理此情況。 它們與 Array 類別無關,並且會編譯為 Java 的基本型別陣列以獲得最高效能。

假設有一個接受整數索引陣列的 Java 方法:

java
public class JavaArrayExample {
    public void removeIndices(int[] indices) {
        // 你的程式碼
    }
}

若要傳遞基本型別值的陣列,你可以在 Kotlin 中執行以下操作:

kotlin
val javaObj = JavaArrayExample()
val array = intArrayOf(0, 1, 2, 3)
javaObj.removeIndices(array) // 將 int[] 傳遞給方法

在編譯為 JVM 位元組碼時,編譯器會最佳化對陣列的存取,因此不會引入任何額外開銷:

kotlin
val array = arrayOf(1, 2, 3, 4)
array[1] = array[1] * 2 // 不會產生實際對 get() 和 set() 的呼叫
for (x in array) {      // 不會建立迭代器 (iterator)
    print(x)
}

即使你使用索引進行遍歷,也不會引入任何額外開銷:

kotlin
for (i in array.indices) { // 不會建立迭代器
    array[i] += 2
}

最後,in 檢查同樣沒有額外開銷:

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

Java 可變參數 (varargs) ​

Java 類別有時會針對帶有可變數量引數(varargs)的索引使用方法宣告:

java
public class JavaArrayExample {

    public void removeIndicesVarArg(int... indices) {
        // 你的程式碼
    }
}

在那種情況下,你需要使用展開運算子 * 來傳遞 IntArray:

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

運算子 ​

由於 Java 無法標記適合使用運算子語法的方法,因此 Kotlin 允許將任何具有正確名稱和簽章的 Java 方法用作運算子多載和其他慣例(invoke() 等)。 不允許使用中綴呼叫(infix call)語法來呼叫 Java 方法。

例如,你可以使用宣告了 get(int) 和 set(int, T) 方法的 Java 類別,並在 Kotlin 中搭配索引存取運算子使用:

java
public class IntContainer {
    private final int[] values = new int[10];

    public int get(int index) {
        return values[index];
    }

    public void set(int index, int value) {
        values[index] = value;
    }
}
kotlin
fun main() {
    val container = IntContainer()
    container[0] = 42     // 呼叫 set(0, 42)
    println(container[0]) // 呼叫 get(0)
}

受檢例外 (Checked exceptions) ​

在 Kotlin 中,所有例外都是非受檢的,這意味著編譯器不會強制你攔截任何例外。 因此,當你呼叫宣告了受檢例外的 Java 方法時,Kotlin 不會強制你執行任何操作:

kotlin
fun render(list: List<*>, to: Appendable) {
    for (item in list) {
        to.append(item.toString()) // 在 Java 中,你必須攔截 Appendable.append() 擲出的 IOException
    }
}

Object 方法 ​

當 Java 型別匯入到 Kotlin 時,所有 java.lang.Object 型別的參照都會轉換為 Any。 由於 Any 並非平台專用,它僅宣告了 toString()、hashCode() 和 equals() 作為其成員, 因此為了讓 java.lang.Object 的其他成員可用,Kotlin 使用了擴充函式。

wait() 與 notify() ​

wait() 和 notify() 方法在 Any 型別的參照上不可用。通常不建議使用它們,而是建議改用 java.util.concurrent。

如果你必須呼叫這些方法,請透過 Java 物件存取它們,並抑制 PLATFORM_CLASS_MAPPED_TO_KOTLIN 警告:

kotlin
import java.util.LinkedList

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

    // 使用 java.lang.Object 執行個體來存取 wait() 和 notify()
    // 在 Kotlin 中,標準的 'Any' 型別沒有公開這些方法
    @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
        }
    }
}

或者明確轉換為 java.lang.Object 並抑制 PLATFORM_CLASS_MAPPED_TO_KOTLIN 警告:

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

getClass() ​

若要檢索物件的 Java 類別,請在類別參照上使用 java 擴充屬性:

kotlin
val instanceClass = instance::class.java

上面的程式碼使用了綁定類別參照。你也可以使用 javaClass 擴充屬性:

kotlin
val instanceClass = instance.javaClass

clone() ​

若要覆寫 clone(),你的類別需要繼承 kotlin.Cloneable:

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

別忘了參閱《Effective Java 第三版》第 13 條:謹慎覆寫 clone。

finalize() ​

若要覆寫 finalize(),宣告時無需使用 override 關鍵字:

kotlin
class C {
    protected fun finalize() {
        // 最終化邏輯
    }
}

根據 Java 的規則,finalize() 不得為 private。

finalize() 方法在現代 Java 版本中已被棄用。請考慮改用 java.lang.ref.Cleaner 或 try-with-resources 等替代方案。

繼承 Java 類別 ​

在 Kotlin 中,最多只能有一個 Java 類別(以及任意數量的 Java 介面)作為某個類別的超類型。

存取 static 成員 ​

Java 類別的 static 成員會為這些類別組成「伴生物件」。你無法將此類「伴生物件」作為值傳遞,但可以明確存取其成員,例如:

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

若要呼叫已匯入的 Java 類別的 static 方法,請直接使用類別名稱,就像在 Java 中一樣。請參考以下 Java 類別:

java
package org.example;

public class MathUtils {
    public static int triple(int value) {
        return value * 3;
    }
}

匯入該類別並透過類別名稱呼叫其 static 方法:

kotlin
import org.example.MathUtils

fun main() {
    println(MathUtils.triple(5)) // 呼叫 static triple() 方法
}

若要存取對應到 Kotlin 型別的 Java 型別的 static 成員,請使用該 Java 型別的完整限定名稱:java.lang.Integer.bitCount(5)。

Java 反射 ​

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。若要取得對應包裝型別的類別,請使用 Int::class.javaObjectType,這相當於 Java 的 Integer.class。

其他受支援的情況包括:為 Kotlin 屬性取得 Java getter/setter 方法或支援欄位、為 Java 欄位取得 KProperty、為 KFunction 取得 Java 方法或建構函式,反之亦然。

SAM 轉換 ​

Kotlin 支援對 Java 與 Kotlin 介面進行 SAM 轉換。 對 Java 的這項支援意味著只要介面方法的參數型別與 Kotlin 函式的參數型別相符,Kotlin 函式常值就可以自動轉換為具有單一非預設方法的 Java 介面實作。

你可以使用它來建立 SAM 介面的執行個體:

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

以及在方法呼叫中使用:

kotlin
val executor = Executors.newSingleThreadExecutor()
// Java 簽章:void execute(Runnable command)
executor.execute { println("This runs in a thread pool") }

如果 Java 類別有多個接受函式語言介面的方法,你可以透過使用將 lambda 轉換為特定 SAM 型別的適配器函式來選擇需要呼叫的方法。編譯器在需要時也會產生這些適配器函式:

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

SAM 轉換僅適用於介面。它們不適用於抽象類別,即使這些類別只有一個抽象方法。

在 Kotlin 中使用 JNI ​

若要宣告以原生(C 或 C++)程式碼實作的函式,你需要使用 external 修飾詞標註它:

kotlin
external fun calculateSum(x: Int): Double

其餘程序與 Java 完全相同。

你也可以將屬性的 getter 和 setter 標記為 external:

kotlin
var myProperty: String
    external get
    external set

在背後,這將建立兩個標記為 external 的函式 getMyProperty 與 setMyProperty。

在 Kotlin 中使用 Lombok 產生的宣告 ​

你可以在 Kotlin 程式碼中使用 Java 的 Lombok 所產生的宣告。 如果你需要在同一個 Java/Kotlin 混合模組中產生並使用這些宣告,可以在 Lombok 編譯器外掛程式頁面了解如何操作。 如果你是從另一個模組呼叫此類宣告,則無需使用該外掛程式來編譯該模組。