Eclipse 平台
API 使用規則

版本 0.15 - 上次修訂日期 2001 年 3 月 30 日 12:00

以下是用戶端使用 Eclipse 平台 API(及其他元件)的規則。

為什麼用 API

Eclipse 平台定義 API 元素供它的用戶端使用,也就是撰寫外掛程式的 ISV。 這些外掛程式又可以定義 API 元素,供它們的用戶端使用,依此類推。 API 元素是公開的介面:它們含有它們要做什麼及應該如何使用它們的相關規格。 API 元素在支援的範圍內:如果有不符合指定的行為,Eclipse 平台團隊會修正實作錯誤。 由於中斷 API 的變更相關成本非常高,因此,Eclipse 平台團隊也會嘗試在後續的主要版本中,適當地發展 API 元素。

如何區分 API 和非 API

在基礎本質,API 元素文件說明有其規格,而本身是內部實作細節的非 API 元素通常不會有公佈的文件或規格。 因此,如果您找不到某項目的文件,通常就代表它不是 API。

更明確地說,平台的程式碼基礎可區分成 API 和非 API 套件,所有 API 元素都宣告在指定的 API 套件中。

其他一切都視為內部實作細節,所有用戶端不在此限。 適當的用戶端程式碼絕對不能參照非 API 元素的名稱(甚至不能使用 Java Reflection)。 在某些情況下,會利用 Java 語言的名稱存取規則禁止不符合規定的參照。 不過,仍有些情況不可能採取這個方式。只要觀察一下這個簡單規則,就可以完全避免問題:

一般規則

API 元素的規格是從元素的 Java 原始碼中的 Javadoc 註解產生的。部份元素類型的規格採用合約的形式。 例如,在方法中,合約是在方法的呼叫者和實作者兩方之間。 基礎規則如下: 當 API 文件使用「必須」一詞時,表示當事人必須確保永遠會符合條款;凡有不符,即視為程式錯誤,會帶來非指定(也可能是非預期)的結果。 其他常識規則:

呼叫 public API 方法

對大部份用戶端而言,Eclipse API 的主體採 API 介面或類別中的 public 方法形式,讓用戶端在適當時可以呼叫它。

建立平台 API 類別的實例

不是任何人都可以建立所有具體 API 類別的實例。API 類別有一份建立實例的合約,指出建立實例所需遵循的條款。 合約也可涵蓋像剩餘起始設定責任(例如,在實例完全作用之前,配置某個內容)及相關生命週期 責任(如呼叫 dispose() 來釋出實例所緊握著的 OS 資源)等內容。 設計要由用戶端來建立實例的類別,在 Javadoc 類別註解中會有明確的旗標(含有類似「用戶端可以建立實例」的文字).

建立平台 API 類別的子類別

只有 API 類別是設計成要建立子類別的。 API 類別有一份子類別合約,指出宣告子類別所需遵守的條款。 這個合約也涵蓋了起始設定和生命週期的責任。 設計要由用戶端來建立子類別的類別,在 Javadoc 類別註解中會有明確的旗標(含有類似「用戶端可以建立子類別」的文字).

呼叫 protected API 方法

您通常可以從子類別中呼叫繼承的 protected 和 public 方法:不過,比起從階層外呼叫 public 方法,這種呼叫通常要更小心。

置換 API 方法

只有 public 和 protected API 方法的子集是設計成要加以置換的。 每個 API 方法都有一份子類別合約,指出子類別置換它時所要遵循的條款。預設值是不容許置換。 請務必檢查要置換的實際方法實作的子類別合約;當置換方法時,不會自動傳遞子類別合約的條款。

實作平台 API 介面

只有一部份 API 介面是設計成要由用戶端來實作的。 API 介面有一份合約指出實作它所需遵守的條款。 設計要由用戶端來實作的介面,在 Javadoc 類別註解中會有明確的旗標(含有類似「用戶端可以實作」的文字). 只有在 API 介面可以實作的情況下,用戶端才可以宣告 API 介面的子介面。

實作 public API 方法

請參閱「置換 API 方法」。

存取 API 類別和介面中的欄位

用戶端可以讀取 API 欄位,這些欄位大部份是 final 欄位。 某些類似結構的物件可能會有非 final public 欄位,除非另有說明,否則用戶端可以讀取和寫入它們。

強制轉型已知 API 類型的物件

如果 API 明確容許的話,已知 API 類型的物件只能強制轉型成不同的 API 類型(或利用 instanceof 進行有條件的強制轉型)。 當然,將任何物件強制轉型成非 API 類別或介面永遠是不恰當的。

違反規則

不論是有意或無意,違反規則都有其結果。 如果有 API 政策能制止規則的違反,事情會比較簡單。 不過,情況並非如此。 大體上,API 標準是受尊重的系統運作,每個用戶端都承擔瞭解和遵守規則的責任。

API 元素的合約界定支援而持續的行為。隨著 Eclipse 平台的發展和成長,將會由 API 合約來引導發展的呈現方式。在這些合約之外,一切都不在支援範圍內,隨時可能改變,且沒有通知(甚至中間版本或不同 OS 平台之間也是如此)。 凡是逾越這些規則的用戶端程式碼,當在平台的不同版本和 patch 層次上、在執行於不同的基礎 OS 時,在混合執行不同的共存外掛程式時,以及搭配執行不同工作台視景時,都可能失敗。 當然,沒人有意推斷任何特定的違規會如何回過頭來造成傷害。但選擇漠視規則的人,不能說沒有人提出警告,且最多只會得到早已告知的結果。

另一方面,遵守上述規則的用戶端外掛程式應該能歷經平台不同版本和 patch 層次、跨越不同的基礎 OS 而繼續運作,且應該能順利與其他外掛程式共存。 如果每一個都依規則而運作,Eclipse 平台會提供穩定的支援基礎,可供您在上面建置任何傑出的新產品。

Copyright IBM Corporation and others 2000, 2003.