資源標記

我們知道外掛程式可定義 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);
   }