Moduł dodatkowy użytkownika może korzystać z interfejsu API środowiska JDT do wyszukiwania w projektach Java elementów, takich jak odwołania do metod, deklaracje pól, implementatorzy interfejsu itp.
Punktem wejścia wyszukiwania Java jest klasa SearchEngine. Można wyszukiwać określonych wzorców w elemencie Java i ograniczyć wyszukiwanie do określonych elementów. Wzorce wyszukiwania mogą być tworzone za pomocą metody createPattern. Zasięg wzorca jest ustalany za pomocą metody createJavaSearchScope. Po ustaleniu wzorca i zasięgu metoda search jest używana do zbierania wyników.
Wyniki wyszukiwania są zgłaszane w klasie SearchRequestor, która musi zostać rozszerzona, aby można było uzyskać dostęp do wyników.
Operacja wyszukiwania będzie korzystać z wzorca opisującego rodzaj wyszukiwania i zasięgu ograniczającego zakres wyszukiwania.
Wzorzec wyszukiwania pozwala zdefiniować sposób uzyskiwania wyników wyszukiwania. Wzorzec wyszukiwania można utworzyć na podstawie elementu Java (patrz createPatternPattern(IJavaElement, int)) lub na podstawie łańcucha (patrz createPattern(String, int, int, int)). Ostatnia metoda obsługuje znaki specjalne (tzn. "*"), które mogą być używane do poszerzenia wyników wyszukiwania.
Na przykład tworzenie wzorca wyszukiwania służącego do wyszukiwania odwołań do danej metody wygląda następująco:
// Pobranie metody IMethod method = ...; // Tworzenie wzorca wyszukiwania SearchPattern pattern = SearchPattern.createPattern(method, IJavaSearchConstants.REFERENCES);
Tworzenie wzorca wyszukiwania służącego do wyszukiwania deklaracji wszystkich typów rozpoczynających się od "Obj":
// Tworzenie wzorca wyszukiwania SearchPattern pattern = SearchPattern.createPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, SearchPattern.R_PATTERN_MATCH | SearchPattern.R_CASE_SENSITIVE);
Obsługiwane są następujące wzorce wyszukiwania:
Jeśli wyniki wyszukiwania mają pochodzić z danego projektu lub pakietu lub jeśli wiadomo, że wyniki wyszukiwania mogą pochodzić tylko z hierarchii określonego typu, można utworzyć odpowiedni zasięg wyszukiwania za pomocą metody createJavaSearchScope(IJavaElement[]) lub metody createHierarchyScope(IType).
Na przykład tworzenie zasięgu wyszukiwania dla danego pakietu wygląda następująco:
// Pobranie pakietu IPackageFragment pkg = ...; // Tworzenie zasięgu wyszukiwania IJavaSearchScope scope = SearchEngine.createJavaSearchScope(new IJavaElement[] {pkg});
Tworzenie zasięgu wyszukiwania dla hierarchii określonego typu:
// Pobranie typu IType type = ...; // Tworzenie zasięgu wyszukiwania IJavaSearchScope scope = SearchEngine.createHierarchyScope(type);
Tworzenie zasięgu wyszukiwania dla całego obszaru roboczego:
// Tworzenie zasięgu wyszukiwania IJavaSearchScope scope = SearchEngine.createWorkspaceScope();
Po utworzeniu wzorca i zasięgu wyszukiwania oraz rozszerzeniu klasy SearchRequestor można rozpocząć wyszukiwanie w następujący sposób:
// Pobranie wzorca wyszukiwania SearchPattern pattern = ...; // Pobranie zasięgu wyszukiwania IJavaSearchScope scope = ...; // Pobranie requestera wyszukiwania SearchRequestor requestor = ...; // Wyszukiwanie SearchEngine searchEngine = new SearchEngine(); searchEngine.search(pattern, new SearchParticipant[] {SearchEngine.getDefaultSearchParticipant()}, scope, requestor, null);
Powiadomienie o rozpoczęciu wyszukiwania jest wysyłane do requestera wyszukiwania za pomocą metody beginReporting. Następnie każdy wynik wyszukiwania jest zgłaszany za pomocą metody acceptSearchMatch. Metoda endReporting wskazuje zakończenie wyszukiwania.
Wyniki wyszukiwania są zgłaszane za pomocą metody acceptSearchMatch. Poniższe akapity opisują szczegółowo zagadnienia dotyczące dopasowań wyszukiwania.
Wynik wyszukiwania może odpowiadać elementowi Java (np. deklaracji typu) lub może być zawarty w elemencie Java (np. odwołanie do typu wewnątrz metody). Mechanizm wyszukiwania stara się zawsze znaleźć najbardziej wewnętrzny element Java odpowiadający wynikowi wyszukiwania lub zawierający ten wynik. Na przykład wyszukiwania odwołań do metody może znaleźć takie odwołanie w inicjatorze. Inicjator zawierający to odwołanie do metody jest elementem dopasowania wyszukiwania.
Mechanizm wyszukiwania stara się również znaleźć zasób zawierający dany element Java. Jeśli więc elementem Java jest metoda w jednostce kompilacji, zasobem jest odpowiedni plik (reprezentowany przez obiekt klasy implementującej interfejs IFile). Jeśli element znajduje się w pliku .jar, zasobem jest plik .jar, jeśli znajduje się on obszarze roboczym. Jeśli jest to zewnętrzny plik .jar, zasób to null.
Pozycje w źródle są podawane względem jednostki kompilacji zawierającej wynik wyszukiwania. Jeśli wynik wyszukiwania jest zawarty w pliku .jar, pozycje źródła podawane są względem przyłączonego źródła. Pozycje te mają wartość (-1, -1), jeśli do pliku .jar nie jest przyłączony kod źródłowy.
W większości przypadków wyniki są dokładne, co oznacza, że mechanizm wyszukiwania jest w stanie określić, że dane dopasowanie to dokładnie ten element, który był przedmiotem zapytania. Jednak w niektórych przypadkach nie jest to możliwe i dopasowanie nie jest dokładne. Niektóre możliwe przyczyny niedokładnego dopasowania to: