資源標示元

我們知道外掛程式可定義 private 副檔名及提供這些檔案類型 private 編輯功能的組件編輯器 。在編輯(或建置)資源的過程中,外掛程式可能需要標示資源來將問題或 其他資訊通知使用者。資源標示元機制用來管理這種資訊。

標示元就像貼在資源上的一個黃色黏貼式附註。您可以在標示元上記錄問題 (例如位置、嚴重性)或欲完成作業的相關資訊。或者您可以簡單記錄標示元 位置當作書籤。

使用者可快速移至資源內標示的位置。工作台 UI 支援根據編輯器呈現書籤、岔斷點 、作業及問題。這些標示元亦可顯示為檢視畫面(例如作業或書籤檢視畫面) 中的項目。

平台資源 API 定義用於建立標示元、設定標示元值及擴充平台的新標示元類型之方 法。 當平台管理標示元時,它是控制其建立、除去和屬性值的外掛程式。

標示元意指小型輕裝備物件。單一專案中可能有幾百個甚至幾千個標示元。例 如,Java 編譯器使用標示元來標示在原始碼中找到的每一個問題。

平台會將附加至已除去資源的標示元丟棄,而外掛程式負責除去不再套用到仍存在資 源的舊標示元。

標示元作業

標示元與資源的行為類似。標示元為 handle 物件。您可 以從資源中取得標示元 handle,但無法得知它是否真的存在,除非使用 exists() 通訊協定或嘗試操作它。一旦確定標示元存在,您就可以 查詢已指定給它的具名屬性。

標示元由平台管理及擁有,平台負責標示元持續性及在新增、除去或變更標示元時通 知接聽器。外掛程式負責建立任何必要的標示元、變更標示元屬性,以及除去 不再需要的標示元。

標示元建立

標示元不直接使用建構子建立。它們使用相關資源上的 Factory 方法(IResource.createMarker())建立。

IMarker marker = file.createMarker(IMarker.TASK);

若要建立具有廣域範圍(無關任何特定資源)的標示元,您可以使用工作區根目錄(IWorkspace.getRoot())作為資源。

標示元除去

除去標示元的程式碼直接明確。

try {      marker.delete();
} catch (CoreException e) {      // 有問題
   }

當除去某個標示元時,它的標示元物件(handle)變成「陳舊的」。外掛程 式應使用 IMarker.exists() 通訊協定來確定標示元物件仍然有效。

標示元可批次除去,方法是要求資源除去其標示元。當一次除去許多標示元或個別標 示元參照或 ID 失效時,這個方法很有用。

int depth = IResource.DEPTH_INFINITE;try {      resource.deleteMarkers(IMarker.PROBLEM, true, depth);
} catch (CoreException e) {      // 有問題
   }

當除去一組標示元時,您可以指定要除去的標示元類型,如 IMarker.PROBLEM,或指定 null 來除去全部標示元。 第二個引數指示是否除去子類型標示元。(當定義新標示元類型時,我們會立 即看到子類型。)depth 引數控制除去的深度。

您亦可以使用 IWorkspace.deleteMarkers(IMarker []) 來刪除標示元。

標示元屬性

指定標示元後,您可以要求其相關聯的資源、ID(僅與該資源相關)及類型。 您亦可透過通用屬性來存取其餘資訊。

每一個標示元類型都有一組特定屬性,這組屬性由標示元類型建立者利用命名慣例定 義。IMarker 介面針對平台標示元類型定義一組含有標準屬性名稱(及一些期望值)的常數。下列 方法使用平台常數來操作屬性。

IMarker marker = file.createMarker(IMarker.TASK);   if (marker.exists()) {
try {         marker.setAttribute(IMarker.MESSAGE, "A sample marker message");
         marker.setAttribute(IMarker.PRIORITY, IMarker.PRIORITY_HIGH);
} catch (CoreException e) {         // 您需要處理標示元不存在的情況      }
   }

屬性通常維護為名稱/值對組,其中的名稱為字串,而值可以是任何支援的值類型( boolean、integer、string)。值類型的限制可讓平台快速又簡單地繼續維持標示元。

查詢標示元

您可以查詢資源的標示元及其子項的標示元。例如,查詢無限深度的工作區根目錄可 以參考到工作區中所有標示元。

IMarker[] problems = null;int depth = IResource.DEPTH_INFINITE;try {      problems = resource.findMarkers(IMarker.PROBLEM, true, depth);
} catch (CoreException e) {      // 有問題
   }

findMarkers 傳回的結果視傳遞的引數而定。在上述片段中,我們尋 找資源及其所有直接和間接後代上出現類型 PROBLEM 的所有標示元 。

如果您傳遞 null 為標示元類型,則會取得與該資源相關聯的所有標示元類 型。 第二個引數指定是否要查閱資源的子項。當您查閱資源的子項時, depth引數控制搜尋的深度。此深度可以是 DEPTH_ZERO(僅 指定的資源)、DEPTH_ONE(資源及其所有直接字項)或 DEPTH_INFINITE(資源及其所有直接和間接後代)。

標示元持續性

平台標準標示元(作業、問題和書籤)為持續性。這表示它們的狀態會在工 作台關閉和啟動間儲存。然而,您可能會將保留屬性 transient 設成 true, 選擇性地讓持續性類型的標示元變成暫時性。

外掛程式所宣告的新標示元類型不是持續性,除非宣告它們為持續性。

以新標示元類型擴充平台

外掛程式可使用 org.eclipse.core.resources.markers 延伸點來宣告它們自己的標示元類型。代表問題、作業及書籤的標準標示元類型由平 台在資源外掛程式的標記中宣告。

      <extension
      id="problemmarker" 
      point="org.eclipse.core.resources.markers" 
      name="%problemName">
      <super type="org.eclipse.core.resources.marker"/>
      <persistent value="true"/>
      <attribute name="severity"/>
      <attribute name="message"/>
      <attribute name="location"/>
      </extension>
   <extension
      id="taskmarker" 
      point="org.eclipse.core.resources.markers" 
      name="%taskName">
      <super type="org.eclipse.core.resources.marker"/>
      <persistent value="true"/>
      <attribute name="priority"/>
      <attribute name="message"/>
      <attribute name="done"/>
      <attribute name="userEditable"/>      
      </extension>
   <extension
      id="bookmark" 
      point="org.eclipse.core.resources.markers" 
      name="%bookmarkName">
      <super type="org.eclipse.core.resources.marker"/>
      <persistent value="true"/>
      <attribute name="message"/>
      <attribute name="location"/>
      </extension>

新標示元類型使用多親繼承衍生自現存的標示元類型。新標示元類型從它們的 Super 類型繼承所有屬性,並新增定義為宣告部份的任何新屬性。它們也從其 Super 類型 的 Super 類型以遞移方式繼承屬性。下列標記在假定的 com.example.markers 外掛程式中定義新標示元種類。

      <extension
      id="mymarker"
      point="org.eclipse.core.resources.markers" />
   <extension
      id="myproblem"
      point="org.eclipse.core.resources.markers">
      <super type="org.eclipse.core.resources.problemmarker"/>
      <super type="com.example.markers.mymarker"/>
      <attribute name="myAttribute" />
      <persistent value="true" />
      </extension>

請注意:類型 org.eclipse.core.resources.problemmarker 實際上是其中 一個預定的類型(又稱為 IMarker.PROBLEM)。

標示元 Super 類型唯一沒有繼承的一面是它的 persistence 旗標。 persistence 的預設值為 False,所以任何應為持續性的標示元類型必須指定 <persistent value="true"/>

在您的外掛程式 manifest 檔中宣告新標示元類型後,您可以建立 com.example.markers.myproblem 標示元類型實例,及隨意設定或取得 myAttribute 屬性。

宣告新屬性可讓您使資料與您打算在別處(在您的檢視畫面及編輯器)使用的標示元 產生關聯。特定類型的標示元不需要有所有已宣告屬性的值。解決命名慣例問題的屬 性宣告比限制內容的屬性宣告多(所以每個人都使用 "message" 來表示 標示元說明)。

public IMarker createMyMarker(IResource resource) {try {         IMarker marker = resource.createMarker("com.example.markers.myproblem");
         marker.setAttribute("myAttribute", "MYVALUE");
         return marker;
} catch (CoreException e) {         // 您需要處理屬性值被拒絕的情況
      }
   }

您可以用查詢平台標示元類型的相同方式來查詢自己的標示元類型。下面方法 尋找與指定目標資源及其所有後代相關的所有 mymarkers。請注意:這也會 尋找所有 myproblems,因為 includeSubtypes 引數傳遞的是 True。

public IMarker[] findMyMarkers(IResource target) {      String type = "com.example.markers.mymarker";
      IMarker[] markers = target.findMarkers(type, true, IResource.DEPTH_INFINITE);
   }

Copyright IBM Corporation and others 2000, 2003.