API 契約規則
- 除非在 API 說明文件中註明,否則只有公開在 Javadoc 參照中的 API 才支援程式設計。Javadoc 中的 API 是穩定的,將不會因版本升級而移除。CARMA API 在新版本中可能會淘汰,但應該繼續可用,且程式設計師可以在將來如說明文件定義的那樣來使用它們。可能會在 CARMA 外掛程式中找到其他 API,但應該將它們視為不在支援範圍內,在未來的版本中可能會改變。
- 依程式設計師的觀點,CARMA 模型 API(com.ibm.carma.model 套件)應該是唯讀的,亦即,程式設計師不應在 CARMA 模型中嘗試手動建立/新增/移除項目。階層中的物件應該透過 refreshXXX() 及 createXXX() 方法來更新。
不支援使用 API 方法之外的方法建立模型物件。如果使用 API 方法之外的方法建立模型物件,則可能會導致不一致。
- 模型中的所有儲存庫資源清單都與過濾器字串相關聯。預設過濾器字串為“*”。
- 當執行方法時,大部分 CARMA 模型方法都需要與 CARMA 主機的連線在作用中。如果連線不在作用中,則會擲出 com.ibm.carma.transport.NotConnected 異常狀況。
- 需要啟動 CARMA 主機連線的 CARMA 方法在方法簽章中具有 org.eclipse.core.runtime.IProgressMonitor 參數。若要取消執行方法,請優先使用 IProgressMonitor.isCancelled() 方法,在「長時間執行」方法執行期間,會檢查該方法。
- CARMA 模型充當 CARMA 階層的資料快取。程式設計師有責任對模型使用 refreshXXX() 方法,以保持快取為新的。
- 必須起始設定 CARMA 模型快取。如果存取 CARMA 階層中尚未快取的部分,則會擲出 com.ibm.carma.transport.NotSynchronizedException。若要修復異常狀況,請對物件執行 refreshXXX() 方法。
- 當切斷與 CARMA 主機的連線時,「CARMA 模型」快取中的物件是可用的。CARMA 主機需要作用中的連線,才能對存取 CARMA 主機的快取物件執行方法。
- 模型變更透過通知向外與接聽器通訊。通知會發送至接聽模型物件的任何配接器。應該透過使用用於延伸 org.eclipse.emf.common.notify.Adapter 的類別,將接聽器新增至模型。
這就是「Eclipse 建模架構 (EMF)」通知方法。如需配接器通知的相關資訊,請參閱 EMF 說明文件。
- 預設 CARMA 使用者介面(包括已具體化的 com.ibm.carma.ui.* API)使用動作與工作的組合來對 CARMA 模型執行方法。用於延伸 org.eclipse.ui.IAction 或 org.eclipse.ui.IActionDelegate 的動作負責收集執行模型方法所需的資料。
所收集的資料會遞送至 CARMA 使用者介面工作,該工作已排程為在有資源可用時於背景中執行。如果模型方法導致對 CARMA 階層的更新,則會將通知從模型傳送至接聽器,這些接聽器會依需要更新使用者介面。
|
本資訊中心採用 Eclipse 技術。(http://www.eclipse.org)