您的外掛程式可使用 JDT API 搜尋工作區中的 Java 專案, 以找出 Java 元素, 像是:方法參照、欄位宣告、介面的實作者等。
Java 搜尋的進入點為 SearchEngine 類別。 您可以在 Java 元素內搜尋特殊型樣,並將搜尋範圍限定在特定元素。您可以使用 createPattern 來建立搜尋型樣。型樣是使用 createJavaSearchScope 來限定範圍。定義了型樣和範圍之後,就可使用 search 方法來收集結果。
搜尋結果將報告至 SearchRequestor,因此您必須延伸它,才能存取結果。
搜尋作業會使用一個說明搜尋本質的型樣,以及一個用以限制調查範圍的範圍。
搜尋型樣是定義如何尋找搜尋結果。您可以從 Java 元素建立一個搜尋型樣(請參閱 createPatternPattern(IJavaElement, int)), 或從字串建立搜尋型樣(請參閱 createPattern(String, int, int, int))。後面的方法支援萬用字元(亦即 '*'),並可用來擴大搜尋結果。
舉例來說,下列是說明如何建立一個搜尋型樣,以搜尋給定方法的參照:
// 取得方法 IMethod method = ...; // 建立搜尋型樣 SearchPattern pattern = SearchPattern.createPattern(method, IJavaSearchConstants.REFERENCES);
下列說明如何建立一個搜尋型樣,以搜尋所有開頭為 "Obj" 之類型的宣告:
// 建立搜尋型樣 SearchPattern pattern = SearchPattern.createPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, SearchPattern.R_PATTERN_MATCH | SearchPattern.R_CASE_SENSITIVE);
所支援的搜尋型樣如下:
如果您對給定專案或給定套件中的搜尋結果感興趣, 或者如果您知道搜尋結果可侷限在給定類型的階層中, 您可使用 createJavaSearchScope(IJavaElement[]) 或 createHierarchyScope(IType) 建立適當的搜尋範圍。
舉例來說,下列是說明如何建立一個以給定套件為主的搜尋範圍:
// 取得套件 IPackageFragment pkg = ...; // 建立搜尋範圍 IJavaSearchScope scope = SearchEngine.createJavaSearchScope(new IJavaElement[] {pkg});
下列說明如何建立一個以給定類型階層為主的搜尋範圍:
// 取得類型 IType type = ...; // 建立搜尋範圍 IJavaSearchScope scope = SearchEngine.createHierarchyScope(type);
最後,您可以建立一個以整個工作區為主的搜尋範圍:
// 建立搜尋範圍 IJavaSearchScope scope = SearchEngine.createWorkspaceScope();
建立好搜尋型樣與搜尋範圍之後,且已實作 SearchRequestor, 即可按如下所示啟動搜尋查詢:
// 取得搜尋型樣 SearchPattern pattern = ...; // 取得搜尋範圍 IJavaSearchScope scope = ...; // 取得搜尋要求者 SearchRequestor requestor = ...; // 搜尋 SearchEngine searchEngine = new SearchEngine(); searchEngine.search(pattern, new SearchParticipant[] {SearchEngine.getDefaultSearchParticipant()}, scope, requestor, null);
開始搜尋的通知會利用 beginReporting 方法傳送至搜尋要求者。 然後,利用 acceptSearchMatch 方法報告每一個搜尋結果。最後,再以 endReporting 表示搜尋已結束。
您可以利用 acceptSearchMatch 方法來報告搜尋結果。 下面幾段詳述搜尋比對。
搜尋結果可對應至 Java 元素(如:類型宣告), 或者可含在 Java 元素中(例如,方法內之類型的參照)。 搜尋引擎會固定試著尋找對應至(或包含)搜尋結果之最內層的 Java 元素。 例如,搜尋方法的參照可以在初值設定程式中找到這樣的參照。 包含這個方法參照的初值設定程式是搜尋的元素。
搜尋引擎也會試著尋找包含 Java 元素的資源。因此,如果 Java 元素是編譯單元中的一個方法, 則資源會是對應的 IFile。 如果元素內含在 .jar 檔中,則資源會是 .jar 檔(如果這個 .jar 檔位於工作區中的話)。如果其為外部 .jar 檔,則資源為空值。
程式檔位置會以內含搜尋結果之編譯單元的相對位置提供。 如果搜尋結果內含在 .jar 檔中,則程式檔位置會是所附加之程式檔的相對位置。 如果 .jar 檔沒有附加程式碼,則為 (-1, -1)。
在大部分情況下,搜尋結果皆為精確的, 也就是說,搜尋引擎能夠根據所要求的,確切提供相符項目。 不過,在某些情況下,搜尋引擎無法如此做, 在這類情況下,相符項目並不精確。 造成相符項目不精確的部分可能原因如下: