您的外掛程式可使用 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);
最後,您可以利用 createWorkspaceScope 來建立包含整個工作區的搜尋範圍:
// 建立搜尋範圍 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(SearchMatch) 方法來報告的。 下列各段強調 SearchMatch 的一些特性。
搜尋結果可對應至 Java 元素(如:類型宣告), 或者可含在 Java 元素中(例如,方法內之類型的參照)。 搜尋引擎會固定試著尋找對應至(或包含)搜尋結果之最內層的 Java 元素。 例如,搜尋方法的參照可以在起始設定程式中找到這樣的參照。 包含這個方法參照的起始設定程式是搜尋的元素。
搜尋引擎也會試著尋找包含 Java 元素的資源。如果 Java 元素包含在編譯單元或類別檔中,資源便是對應的 IFile。 如果 Java 元素包含在 .jar 檔中,如果這個 .jar 檔在工作區中,傳回的資源便是它,否則會傳回 null。
來源位置 getOffset 和 getLength 是相對於包含搜尋結果的編譯單元而提供的。 如果搜尋結果內含在 .jar 檔中,則程式檔位置會是所附加之程式檔的相對位置。 如果 .jar 檔沒有附加程式碼,則為 (-1, -1)。
在大部分情況下,搜尋結果皆為精確的, 也就是說,搜尋引擎能夠根據所要求的,確切提供相符項目。 不過,在某些情況下,搜尋引擎無法如此做, 在這類情況下,相符項目並不精確。 造成相符項目不精確的部分可能原因如下: