在 Kotlin 中呼叫 Java
Kotlin 在設計時就充分考慮了與 Java 的互通性。現有的 Java 程式碼可以自然地在 Kotlin 中被呼叫, 而 Kotlin 程式碼也可以同樣順暢地在 Java 中使用。
你無需額外設定即可使用大部分的 Java 程式碼:
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 方法同名的屬性。
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
public class Greeting {
public String getMessage() {
return "Hello!";
}
public String getMessage(String name) {
return "Hello, " + name + "!";
}
}無參數的 getMessage() 方法可透過合成屬性 message 來存取。若要使用多載的 getMessage(String) 方法,請將其作為函式呼叫:
// 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
public class Greeter implements Message {
public String getText(String name) {
return "Hello, " + name + "!";
}
}// 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 關鍵字作為名稱,你仍然可以透過反引號(`)字元跳脫來呼叫該方法:
matcher.`is`(expected)Null 安全性與平台型別
Java 中的任何參照都可能為 null,這使得 Kotlin 嚴格的 null 安全性要求對於來自 Java 的物件顯得不切實際。 Java 宣告的型別在 Kotlin 中會被視為不可標記型別(non-denotable),並稱為「平台型別」(platform types)。 你無法在程式碼中明確寫出這些不可標記型別。因此,當把平台型別的值指派給 Kotlin 變數時,你可以:
- 依賴型別推論。在此情況下,該變數具有推論出的平台型別。
- 選擇你期望的型別。Kotlin 同時允許可 null 型別與不可 null 型別。
平台型別放寬了 null 檢查,因此它們擁有與對應的 Java 型別相同的安全保證。請參考以下範例:
val list = ArrayList<String>() // 非 null(建構函式結果)
list.add("Item")
val size = list.size // 非 null(基本型別 int)
val item = list[0] // 推論為平台型別(一般 Java 物件)當你在平台型別的變數上呼叫方法時,Kotlin 在編譯期不會發出可 null 性錯誤,但在執行時期呼叫可能會失敗,原因可能是 NullPointer 異常,或是 Kotlin 為了防止 null 擴散而產生的斷言失敗:
item.substring(1) // 允許,但如果 item == null 則會擲出異常你可以將平台型別的值指派給可 null 或不可 null 的 Kotlin 型別變數。然而,如果你將該值指派給不可 null 型別的變數,而該值在執行時期實際上為 null,Kotlin 就會擲出 NullPointerException。為了避免這種情況,請在 Kotlin 程式碼中加入明確的可 null 性宣告:
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 性不符:
-Xnullability-annotations=@<package-name>:<report-level>指定完全限定的可 null 性註解的套件名稱,以及以下報告層級之一:
ignore:忽略可 null 性不相符warn:回報警告strict:回報錯誤。
JSpecify 是唯一預設使用 strict 報告層級的受支援風格。 無需額外設定即可使用它針對可 null 性註解回報錯誤。
請參閱 Kotlin 編譯器原始碼以獲取受支援的可 null 性註解的完整清單。
可變性註解
你可以使用可變性註解來標註 Java 宣告,以指定回傳的集合在 Kotlin 中是唯讀的還是可變的。 如果你將該值指派給具有不同可變性的集合型別,編譯器會回報型別不相符。 診斷嚴重層級取決於具體的可變性註解。
編譯器支援數種可變性註解,包括:
kotlin.annotations.jvm.ReadOnlykotlin.annotations.jvm.Mutableorg.jetbrains.annotations.Unmodifiableorg.jetbrains.annotations.UnmodifiableView
請參閱 Kotlin 編譯器原始碼以獲取受支援的可變性註解的完整清單。
標註型別引數與型別參數
你也可以標註泛型型別的型別引數和型別參數,為它們提供可 null 性資訊。
本節中的所有範例均使用來自 org.jetbrains.annotations 套件的 JetBrains 可 null 性註解。
型別引數
請參考 Java 宣告上的這些註解:
@NotNull
Set<@NotNull String> toSet(@NotNull Collection<@NotNull String> elements) { ... }它們會在 Kotlin 中產生以下簽章:
fun toSet(elements: (Mutable)Collection<String>) : (Mutable)Set<String> { ... }當型別引數缺少 @NotNull 註解時,你會得到平台型別:
fun toSet(elements: (Mutable)Collection<String!>) : (Mutable)Set<String!> { ... }Kotlin 還會考慮基底類別和介面的型別引數上的可 null 性註解。例如,有兩個具備以下簽章的 Java 類別:
public class Base<T> {}public class Derived extends Base<@Nullable String> {}在 Kotlin 程式碼中,在預期為 Base<String> 之處傳入 Derived 的執行個體會產生警告。
fun takeBaseOfNotNullStrings(x: Base<String>) {}
fun main() {
takeBaseOfNotNullStrings(Derived()) // 警告:可 null 性不符
}Derived 的上限被設定為 Base<String?>,這與 Base<String> 不同。
進一步了解 Kotlin 中的 Java 泛型。
型別參數
預設情況下,Kotlin 和 Java 中普通型別參數的可 null 性都是未定義的。在 Java 中,你可以使用可 null 性註解來指定它。讓我們標註 Base 類別的型別參數:
public class Base<@NotNull T> {}從 Base 繼承時,Kotlin 預期一個不可 null 的型別引數或型別參數。 因此,以下 Kotlin 程式碼會產生警告:
class Derived<K> : Base<K> {} // 警告:K 具有未定義的可 null 性你可以透過指定上限 K : Any 來解決此問題。
Kotlin 還支援在 Java 型別參數的界限上使用可 null 性註解。讓我們為 Base 新增界限:
public class BaseWithBound<T extends @NotNull Number> {}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
import org.jspecify.annotations.*;
@NullMarked
public class InventoryService {
public String notNull() { return ""; }
public @Nullable String nullable() { return null; }
}在 Kotlin 中,這些型別會被視為一般的可 null 和不可 null 型別,而不是平台型別:
// Kotlin
fun test(inventory: InventoryService) {
inventory.notNull().length // 正常
inventory.nullable().length // 錯誤:僅允許安全呼叫 (?.) 或非 null 斷言 (!!) 呼叫
}預設情況下,Kotlin 編譯器會將 JSpecify 註解的可 null 性不相符回報為錯誤。 你可以使用以下編譯器選項來自訂 JSpecify 可 null 性診斷的嚴重層級:
-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 性註解相同的含義:
@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 與該型別用法相符的最內層封裝元素決定。
@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 性:
// 檔案: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 狀態新增到型別限定詞別名和型別限定詞預設值中:
@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 型別 |
|---|---|
byte | kotlin.Byte |
short | kotlin.Short |
int | kotlin.Int |
long | kotlin.Long |
char | kotlin.Char |
float | kotlin.Float |
double | kotlin.Double |
boolean | kotlin.Boolean |
一些非基本型別的內建類別也會進行對應:
| Java 型別 | Kotlin 型別 |
|---|---|
java.lang.Object | kotlin.Any! |
java.lang.Cloneable | kotlin.Cloneable! |
java.lang.Comparable | kotlin.Comparable! |
java.lang.Enum | kotlin.Enum! |
java.lang.annotation.Annotation | kotlin.Annotation! |
java.lang.CharSequence | kotlin.CharSequence! |
java.lang.String | kotlin.String! |
java.lang.Number | kotlin.Number! |
java.lang.Throwable | kotlin.Throwable! |
Java 的裝箱(boxed)基本型別會對應到可 null 的 Kotlin 型別:
| Java 型別 | Kotlin 型別 |
|---|---|
java.lang.Byte | kotlin.Byte? |
java.lang.Short | kotlin.Short? |
java.lang.Integer | kotlin.Int? |
java.lang.Long | kotlin.Long? |
java.lang.Character | kotlin.Char? |
java.lang.Float | kotlin.Float? |
java.lang.Double | kotlin.Double? |
java.lang.Boolean | kotlin.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 檢查:
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 方法:
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) { // 不會建立迭代器
array[i] += 2
}最後,in 檢查同樣沒有額外開銷:
if (i in array.indices) { // 等同於 (i >= 0 && i < array.size)
print(array[i])
}Java 可變參數 (varargs)
Java 類別有時會針對帶有可變數量引數(varargs)的索引使用方法宣告:
public class JavaArrayExample {
public void removeIndicesVarArg(int... indices) {
// 你的程式碼
}
}在那種情況下,你需要使用展開運算子 * 來傳遞 IntArray:
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 中搭配索引存取運算子使用:
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;
}
}fun main() {
val container = IntContainer()
container[0] = 42 // 呼叫 set(0, 42)
println(container[0]) // 呼叫 get(0)
}受檢例外 (Checked exceptions)
在 Kotlin 中,所有例外都是非受檢的,這意味著編譯器不會強制你攔截任何例外。 因此,當你呼叫宣告了受檢例外的 Java 方法時,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 警告:
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 警告:
@Suppress("PLATFORM_CLASS_MAPPED_TO_KOTLIN")
(instance as java.lang.Object).wait()getClass()
若要檢索物件的 Java 類別,請在類別參照上使用 java 擴充屬性:
val instanceClass = instance::class.java上面的程式碼使用了綁定類別參照。你也可以使用 javaClass 擴充屬性:
val instanceClass = instance.javaClassclone()
若要覆寫 clone(),你的類別需要繼承 kotlin.Cloneable:
class Example : Cloneable {
override fun clone(): Any { ... }
}別忘了參閱《Effective Java 第三版》第 13 條:謹慎覆寫 clone。
finalize()
若要覆寫 finalize(),宣告時無需使用 override 關鍵字:
class C {
protected fun finalize() {
// 最終化邏輯
}
}根據 Java 的規則,finalize() 不得為 private。
finalize() 方法在現代 Java 版本中已被棄用。請考慮改用 java.lang.ref.Cleaner 或 try-with-resources 等替代方案。
繼承 Java 類別
在 Kotlin 中,最多只能有一個 Java 類別(以及任意數量的 Java 介面)作為某個類別的超類型。
存取 static 成員
Java 類別的 static 成員會為這些類別組成「伴生物件」。你無法將此類「伴生物件」作為值傳遞,但可以明確存取其成員,例如:
if (Character.isLetter(a)) { ... }若要呼叫已匯入的 Java 類別的 static 方法,請直接使用類別名稱,就像在 Java 中一樣。請參考以下 Java 類別:
package org.example;
public class MathUtils {
public static int triple(int value) {
return value * 3;
}
}匯入該類別並透過類別名稱呼叫其 static 方法:
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 介面的執行個體:
val runnable = Runnable { println("This runs in a runnable") }以及在方法呼叫中使用:
val executor = Executors.newSingleThreadExecutor()
// Java 簽章:void execute(Runnable command)
executor.execute { println("This runs in a thread pool") }如果 Java 類別有多個接受函式語言介面的方法,你可以透過使用將 lambda 轉換為特定 SAM 型別的適配器函式來選擇需要呼叫的方法。編譯器在需要時也會產生這些適配器函式:
executor.execute(Runnable { println("This runs in a thread pool") })SAM 轉換僅適用於介面。它們不適用於抽象類別,即使這些類別只有一個抽象方法。
在 Kotlin 中使用 JNI
若要宣告以原生(C 或 C++)程式碼實作的函式,你需要使用 external 修飾詞標註它:
external fun calculateSum(x: Int): Double其餘程序與 Java 完全相同。
你也可以將屬性的 getter 和 setter 標記為 external:
var myProperty: String
external get
external set在背後,這將建立兩個標記為 external 的函式 getMyProperty 與 setMyProperty。
在 Kotlin 中使用 Lombok 產生的宣告
你可以在 Kotlin 程式碼中使用 Java 的 Lombok 所產生的宣告。 如果你需要在同一個 Java/Kotlin 混合模組中產生並使用這些宣告,可以在 Lombok 編譯器外掛程式頁面了解如何操作。 如果你是從另一個模組呼叫此類宣告,則無需使用該外掛程式來編譯該模組。
