Eclipse 3.0 和 3.1 之間的不相容性

Eclipse 3.0 和 3.1 之間的不相容性在於它們對於外掛程式的影響。 下列項目說明已變更的區域,並且提供將 3.0 的外掛程式移轉到 3.1 的指示。 請注意,如果您無法在 3.1 上執行 3.0 的外掛程式,您只需查看以下指示即可。

  1. 外掛程式喜好設定
  2. IPath 限制的變更
  3. 延伸登錄
  4. 程式碼格式製作器選項
  5. 對 AntCorePreferences 的 API 合約變更
  6. 對 JFace 中的 Policy 類別的 API 合約變更
  7. 為容許空值之預設視景所做的 API 合約變更
  8. 對 IViewLayout 的 API 合約變更
  9. 對 IVMInstall 的 API 合約變更
  10. SelectionEnabler.SelectionClass 可供套件檢視
  11. ContributionItem.getParent() 可以傳回空值
  12. IPropertySource 和 IPropertySource2 中的 isPropertySet(boolean) 的變更
  13. 從 org.eclipse.ui.commands 延伸點刪除的 handlerSubmission 元素
  14. TeamUI made final 中的 Static 非 final API 欄位 GLOBAL_IGNORES_CHANGED
  15. 使用 FillLayout 時發生 ClassCastException
  16. 用已除去的母項來建立小組件

1. 外掛程式喜好設定

受影響的項目:藉由覆寫 Plugin#initializeDefaultPreferences 的方法,來起始設定其預設外掛程式喜好設定值,或使用喜好設定變更接聽器的外掛程式。

說明:在 Eclipse 3.1 中,從 org.eclipse.ui.plugin.AbstractUIPlugin#getPreferenceStore 取得的 org.eclipse.jface.preference.IPreferenceStore 物件,已移轉到 org.eclipse.core.runtime 外掛程式所提供的新 3.0 Eclipse 喜好設定組織架構之上。

必須採取的動作:因此,使用喜好設定 API 的用戶端應該檢查兩個可能的問題:

  1. 喜好設定變更事件中所含的物件類型並無法得到保證;事件中的新舊值可能是空值、 String 或 typed 物件。因此,如果要成為正常的用戶端, 喜好設定變更接聽器應該能夠處理這三種可能的狀況。
  2. 如果您的外掛程式使用 org.eclipse.ui.plugin.AbstractUIPlugin#initializeDefaultPreferences, 您必須在所需外掛程式的外掛程式清單併入 org.eclipse.core.runtime.compatibility 外掛程式, 因為這個相依關係已經從 org.eclipse.ui.workbench 外掛程式中移除。

請參閱喜好設定儲存庫文件,以取得詳細資料。

2. IPath 限制的變更

受影響的項目:負責建立、操作或儲存 IPath 物件的外掛程式。

說明:在 Eclipse 3.0 中,IPath 的路徑區段有許多限制, 這些限制比基礎作業系統的限制更嚴格。其中包括:

當平台的資料位置(工作區)是在沒有這些限制的檔案系統中時, Eclipse 3.1 已經移除這些限制。

所需要的動作:為了正確處理展開的路徑範圍, 在外掛程式內所有的 PathIPath 用法都可以依照下列方式來檢閱和更新。 在 3.0 中視為合法的所有路徑上,大部分未修改的外掛程式都會維持 3.0 中的規則。 然而,除非已經進行這些預先說明的變更,否則在 3.0 中視為不合法, 但在 3.1 中視為合法的路徑中,外掛程式就有可能會失敗。

如果用來儲存路徑字串表示法的外掛程式所使用的格式需要能夠在不同的平台上讀取, 則外掛程式應該移轉到新的 Path.fromPortableString Factory 方法。這個方法會從可在不同的平台上執行的格式來產生 IPath 實例。這個路徑的字串表示法可以利用 IPath.toPortableString 方法來建立。 受影響的 Meta 資料檔的範例包括儲存在 Eclipse 工作區專案內部的檔案(.project、.classpath 等等), 以及儲存在喜好設定儲存庫中的所有路徑 (org.eclipse.core.runtime.preferences.IPreferencesService)。

附註:fromPortableString 將會正確地讀取使用 Eclipse 3.0 的 IPath.toString 方法所建立的全部路徑字串, 但無法讀取使用 Eclipse 3.1 的 toString 方法建立的路徑字串。因此,在大部分的情況下,您不需要變更現有 meta 資料檔格式, 不過在開始寫入具有 toPortableString 的路徑以及讀取具有 fromPortableString 的路徑時除外。

從寫在程式中的字串文字來建立路徑的外掛程式則需要移轉, 因為這些字串文字會假設 ':' 和 '\' 在所有的平台上具有特殊意義。最簡單的解決方案是將路徑字串文字限定至 所有平台上已支援的子集(避免冒號和反斜線字元)。路徑文字可支援完整的有效 Unix 路徑集, 其方法是使用 Path.toPortableString 產生的可攜性路徑字串格式。這個格式會將第一個單一冒號 (':') 解譯成裝置分隔字元,將斜線 ('/') 解譯成區段分隔字元,並且將雙冒號 ("::") 解譯成文字冒號字元。例如,程式碼 new Path("c:/temp") 現在會在 Unix 平台上產生包含兩個區段的相對路徑。同樣地, new Path("a\\b") 現在會在 Unix 平台上建立一個包含單一區段的路徑, 以及在 Windows 上建立包含兩個區段的路徑。

使用 IPath.append(String) 方法來建構路徑的外掛程式可能需要更新它們的程式碼, 因為這個方法會假設 ':' 和 '\' 在所有的平台上具有特殊意義。 在 Eclipse 3.1 中,這個方法會使用作業系統特定的裝置和區段分隔字元來解譯所提供的路徑字串。例如,現在在 Unix 上呼叫 append("a\\b") 時, 會附加一個單一區段,而如果是在 Windows 呼叫,則會繼續附加兩個區段。

由平台所讀取和解譯的所有資料檔不再將所有平台上的 ':' 和 '\' 視為特殊字元。如果儲存在資料檔中的所有路徑可在多個平台上讀取,則必須採用可攜性格式。例如, 圖示檔的路徑和 plugin.xml 中的其他路徑,必須只用 '/' 作為路徑區段分隔字元。

3. 延伸登錄

受影響的項目:從 Eclipse 平台的外掛程式或延伸登錄來操作或保留 IExtensionPointIExtensionIConfigurationElement 物件的外掛程式。

說明:在 3.0 之前,所有從延伸登錄(屬於先前的外掛程式登錄)取得的物件都可以使用。在 Eclipse 3.0 中的變更可容許以動態方式新增或移除外掛程式, 而不必重新啟動 Eclipse。若移除外掛程式而沒有重新啟動, 則它在延伸登錄中的項目就會變成無效。這表示如果有另一個外掛程式保留從已刪除的外掛程式延伸登錄項目取得的物件, 則該外掛程式保留的會是無效的物件。用戶端唯一可以取得的提示將是取自對 IRegistryChangeEvent 的接聽。 這個問題從 Eclipse 3.0 開始就存在,但是實際上很少發現, 因為在移除外掛程式時,大多不會重新啟動 Eclipse。

3.1 是以下列方式解決這個問題:

所需要的動作:如果您的外掛程式需要察覺動態(亦即, 可以處理即時新增或移除外掛程式),則處理取自其他外掛程式的 IExtensionPointIExtensionIConfigurationElement 物件的程式碼必須變更,以便將 IRegistryChangeEvent 當作已檢查的異常狀況來捕捉。當外掛程式是由並行的執行緒來移除時(如果發生, 則大多是屬於這種情況),捕捉異常狀況(而不是執行 isValid() 事先檢查)是唯一安全的處理方法。

4. 程式碼格式製作器選項

受影響的項目:依程式的方式來存取 Java 程式碼格式製作器選項的外掛程式。

說明:在 Eclipse 3.0 中,程式碼格式製作器選項 org.eclipse.jdt.core.formatter.DefaultCodeFormatterConstants#FORMATTER_TAB_CHAR 的值只能是 TABSPACE。規格並沒有明確提到值類型為列舉表,並且在後續的版次將會增加。在 Eclipse 3.1 中, 已將第三個可能的值 MIXED 新增至位址錯誤 73104。 規格已經變更,已併入這個新的值,以及容許在日後新增更多的值。

所需要的動作:依程式的方式讀取或設定這個程式碼格式製作器選項的用戶端應該檢查其程式碼, 以考量新增的第三個值,並確定程式碼的撰寫方式健全,以便在發現非預期的選項值時,程式碼能以溫和的方式失效。

5. 對 AntCorePreferences 的 API 合約變更

受影響的項目:建立 org.eclipse.ant.core.AntCorePreferences 的實例或作為其子類別的外掛程式

說明:在 Eclipse 3.0 中,org.eclipse.ant.core.AntCorePreferences 類別並未標示用戶端無法建立實例或作為子類別。這個錯誤在 Eclipse 3.1 中已經解決,類別已標示為不適合作為子類別或建立實例。

所需要的動作:依程式的方式建立 org.eclipse.ant.core.AntCorePreferences 實例的用戶端應該移轉其程式碼來擷取喜好設定,方法是使用:org.eclipse.ant.core.AntCorePlugin.getPreferences()。 任何子類別都需要重新處理,使它們不再是 org.eclipse.ant.core.AntCorePreferences 的子類別。

6. 對 JFace 中的 Policy 類別的 API 合約變更

受影響的項目:置換工作台所設定之 JFace 日誌的 RCP 應用程式。

說明:在 Eclipse 3.0 中,工作台會將工作台日誌設定成 用來記載 JFace 錯誤的日誌,其方法將工作台的外掛程式日誌直接傳送到 org.eclipse.jface.util.Policy.setLog(ILog)。在 3.1 中,已經從 JFace 移除對 ILog 的相依關係, 以便在 Eclipse 執行時期外部啟用利用 SWT 和 JFace 的獨立式應用程式。另外也採用一個新的 ILogger 介面, 以符合 JFace 的需求。工作台已經變更,以提供一個 ILogger 來封裝工作台 ILog。如需進一步的詳細資料, 請參閱錯誤 88608

所需要的動作:大部分的 RCP 應用程式都不需要置換工作台所設定的日誌,但如果它們先前已經呼叫 Policy.setLog(ILog),就需要將其改變來改成傳送 ILogger

7. 為容許空值之預設視景所做的 API 合約變更

受影響的項目:只接受非空值預設視景的 RCP 應用程式。

說明:為了讓 RCP 應用程式從空白視窗啟動,而且不開啟任何視景(加強功能 71150), WorkbenchAdvisor.getInitialWindowPerspectiveId()IPerspectiveRegistry.getDefaultPerspective() 已經變成可以容許傳回空值。在 IDE 中,一律有一個預設視景, 所以 IPerspectiveRegistry.getDefaultPerspective() 將不會傳回空值。同樣地,如果現有的 RCP 應用程式先前從 WorkbenchAdvisor.getInitialWindowPerspectiveId() 傳回的值不是空值, 則 IPerspectiveRegistry.getDefaultPerspective() 仍會傳回非空值的值。

所需要的動作:用戶端不需要採取任何動作。

8. 對 IViewLayout 的 API 合約變更

受影響的項目:實作 org.eclipse.ui.IViewLayout 的外掛程式。

說明:在 Eclipse 3.0 中,org.eclipse.ui.IViewLayout 類別並未標示用戶端無法實作。這個錯誤在 Eclipse 3.1 中已經解決,類別已標示為不適合由用戶端來實作。

所需要的動作:任何實作的類別都需要重新處理, 使它們不再實作 org.eclipse.ui.IViewLayout

9. 對 IVMInstall 的 API 合約變更

受影響的項目:實作 org.eclipse.jdt.launching.IVMInstall. 的外掛程式。

說明:在 Eclipse 3.0 中,org.eclipse.jdt.launching.IVMInstall 類別並未標示用戶端無法直接實作。這個錯誤在 Eclipse 3.1 中已經解決,類別已標示為不適合由用戶端來直接實作。 為了維護二進位相容性,我們仍然允許用戶端直接實作介面,但強烈建議用戶端改為建立 org.eclipse.jdt.launching.AbstractVMInstall 子類別。實作 IVMInstall 的用戶端也應實作新選用介面 org.eclipse.jdt.launching.IVMInstall2, 其為 AbstractVMInstall 現在實作的介面。建議用戶端實作新介面 (IVMInstall2),避免發生附註在錯誤 73493 中的問題。建議的移轉方式是建立 AbstractVMInstall 子類別。

所需要的動作:應重新處理任何尚未建立 org.eclipse.jdt.launching.AbstractVMInstall 子類別的實作類別, 以建立 org.eclipse.jdt.launching.AbstractVMInstall 的子類別。

10.SelectionEnabler.SelectionClass 可供套件檢視

受影響的項目:使用 org.eclipse.ui.SelectionEnabler.SelectionClass 的外掛程式。

說明:在 Eclipse 3.0 中,巢狀的實作類別 org.eclipse.ui.SelectionEnabler.SelectionClass 是公開的, 而且其用法沒有限制。這個錯誤在 Eclipse 3.1 中已經解決,類別已變成可供套件檢視的類別。

所需要的動作:任何延伸 org.eclipse.ui.SelectionEnabler.SelectionClass 或為其建立實例的類別都需要重新處理, 使它們不再參照這個類別。

11.ContributionItem.getParent() 可以傳回空值

受影響的項目:org.eclipse.jface.action.ContributionItem 的子類別中呼叫 getParent() 的外掛程式。

說明:在 Eclipse 3.0 中,org.eclipse.jface.action.ContributionItem.getParent() 方法並未指定它可以傳回空值。這個錯誤在 Eclipse 3.1 中已經解決,方法的 Javadoc 已經指明它可以傳回空值。 如需詳細資料,請參閱錯誤 92777

所需要的動作:任何呼叫 ContributionItem.getParent() 的程式碼都必須確定 它可以處理空值的結果。

12.對 IPropertySource 和 IPropertySource2 中的 isPropertySet(boolean) 的變更

受影響的項目:實作 org.eclipse.ui.views.properties.IPropertySourceIPropertySource2 的外掛程式。

說明:在 Eclipse 3.0 中,方法 org.eclipse.ui.views.properties.IPropertySource.isPropertySet(boolean) 的規格變更錯誤,並指定若指定內容不具備有意義的預設值時,要傳回 true。在舊版中,則指定在此情況下要傳回 false。 這是不小心造成的中斷 API 變更,如果內容來源實作 IPropertySource, 而不是實作 IPropertySource2,則實作和以前一樣可以執行。 這個問題在 3.1 中已經更正,IPropertySource.isPropertySet(boolean) 已經回復成其稍早的規格(在此情況下,應該傳回 false), 而 IPropertySource2.isPropertySet(boolean) 則會置換這個值, 並指定在此情況下應該傳回 true。如需取得詳細資料,請參閱錯誤 21756

所需要的動作:任何實作 IPropertySource 或 IPropertySource2 的類別, 其中部分的內容並不具備有意義的預設值,因此應該加以檢查,以確定它們可以為 isPropertySource(boolean) 傳回適當的值。 用戶端應該檢查「內容」視圖中的「還原預設值」按鈕可依照其內容來源的預期方式來運作。

13.從 org.eclipse.ui.commands 延伸點刪除的 handlerSubmission 元素

受影響的項目:使用引進 org.eclipse.ui.commands 延伸點 Eclipse 3.0 之實驗性質 handlerSubmission 元素的外掛程式。

說明:在 Eclipse 3.0 中,實驗性質元素已引進 org.eclipse.ui.commands 延伸點。這個元素用來透過 XML 來登錄處理常式。從那時候起,便已引進先進機制 org.eclipse.ui.handlers 延伸點。因為該元素標示為實驗性質,因此現在已移除。

必須採取的動作:定義 handlerSubmission 元素的所有外掛程式都應該移轉到 org.eclipse.ui.commands 延伸點。

14.TeamUI made final 中的 Static 非 final API 欄位 GLOBAL_IGNORES_CHANGED

受影響的項目:設定 TeamUI 之 GLOBAL_IGNORES_CHANGED 欄位的外掛程式。

說明:在 Eclipse 3.0 中,已將 GLOBAL_IGNORES_CHANGED 欄位新增至 TeamUI 類別。這個欄位是用於內容變更事件中的常數,指出已變更由「團隊」外掛程式所維護的整體忽略清單。這個欄位在 3.0 中未標示為 final,但實際上應該要標示。在 3.1 時已是 final。

必須採取的動作:設定上述欄位的所有外掛程式都不可再這麼做。

15.使用 FillLayout 時發生 ClassCastException

受影響的項目:不正確使用 FillLayout 的外掛程式。

說明:在 Eclipse 3.0 中,沒有任何佈置資料與 FillLayout 相關聯,而且如果應用程式將佈置資料指派給由 FillLayout 所管理的子項,系統便不會處理。在 Eclipse 3.1 中,已新增支援至 FillLayout 的快取記憶體大小資訊,以增進調整大小的效能。 快取的資料會儲存在 FillData 物件,其與每個由 FillLayout 所管理的子項有關。如果應用程式不正確地指派佈置資料給子項,則在母項中呼叫 computeSize 時,便會擲出 ClassCastException。

必須採取的動作:在 FillLayout 中,尋找已指派佈置資料和停止指派資料佈置的任何子項。

16.用已除去的母項來建立小組件時,發生 IllegalArgumentException

受影響的項目:建立小組件時捕捉到異常狀況的外掛程式。

說明:在 Eclipse 3.0 中,如果小組件是用已除去的母項來建立的,並不會擲出任何異常狀況,但稍後小組件程式碼便會失敗,或者會擲出 SWTException 以及「小組件已除去」文字。在 Eclipse 3.1 中, 如果用已除去的母項來建立小組件,則建構子會擲出 IllegalArgumentException 以及「引數無效」文字。

必須採取的動作:建立小組件時處理 SWTException 的所有程式碼也需要處理 IllegalArgumentException。