De Java-zoekfunctie gebruiken

U kunt voor uw plugin gebruikmaken van de JDT-API om Java-projecten in het werkgebied te doorzoeken op Java-elementen, zoals methodeverwijzingen, velddeclaraties, implementoren van een interface, etc.

Het ingangspunt voor een Java-zoekopdracht is de klasse SearchEngine. U kunt zoeken naar bepaalde patronen in een Java-element en het zoekopdrachtbereik verfijnen tot specifieke elementen.  Zoekpatronen kunnen worden aangemaakt met createPattern.  Een patroonbereik wordt gedefinieerd met createJavaSearchScope.  Als eenmaal een patroon en bereik zijn gedefinieerd, gebruikt u de methode search om de zoekresultaten te verzamelen.

Zoekresultaten worden doorgegeven aan een SearchRequestor, die u moet uitbreiden om toegang tot de resultaten te krijgen.

Zoekbewerking voorbereiden

Bij een zoekbewerking wordt zowel gebruik gemaakt van een patroon om het soort zoekopdracht te beschrijven als van een scope om het zoekbereik te beperken.

Een Java-zoekpatroon maken

In een zoekpatroon definieert u op welke wijze naar resultaten moet worden gezocht. U kunt een zoekpatroon maken op basis van een Java-element (zie createPatternPattern(IJavaElement, int)) of een tekenreeks (zie createPattern(String, int, int, int)). Bij de laatste methode worden jokertekens ('*') ondersteund zodat u meer zoekresultaten kunt verkrijgen.

Hieronder ziet u een voorbeeld van een zoekpatroon om te zoeken naar verwijzingen naar een bepaalde methode:

    // Methode ophalen
    IMethod method = ...;
    
    // Zoekpatroon maken
    SearchPattern pattern = SearchPattern.createPattern(method, IJavaSearchConstants.REFERENCES);

U kunt ook een zoekpatroon maken om te zoeken naar declaraties van alle typen die beginnen met "Obj":

    // Zoekpatroon maken
    SearchPattern pattern = SearchPattern.createPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, SearchPattern.R_PATTERN_MATCH | SearchPattern.R_CASE_SENSITIVE);

De volgende zoekpatronen worden ondersteund:

Een Java-zoekbereik maken

Als u geļnteresseerd bent in zoekresultaten voor een bepaald project of zelfs een pakket, of als u weet dat zoekresultaten alleen in de hiėrarchie van een bepaald type kunnen worden gevonden, kunt u het desbetreffende zoekbereik opgeven met createJavaSearchScope(IJavaElement[]) of createHierarchyScope(IType).

Hier ziet u hoe u een zoekbereik kunt opgeven voor een bepaald pakket:

    // Pakket ophalen
    IPackageFragment pkg = ...;

    // Zoekbereik maken
    IJavaSearchScope scope = SearchEngine.createJavaSearchScope(new IJavaElement[] {pkg});

Als u een zoekbereik wilt opgeven voor de hiėrarchie van een bepaald type, gaat u als volgt te werk:

    // Type ophalen
    IType type = ...;

    // Zoekbereik maken
    IJavaSearchScope scope = SearchEngine.createHierarchyScope(type);

Ten slotte kunt u een zoekbereik voor het hele werkgebied opgeven met createWorkspaceScope:

    // Zoekbereik maken
    IJavaSearchScope scope = SearchEngine.createWorkspaceScope();

Zoeken

Als u eenmaal een zoekpatroon en een zoekbereik hebt gemaakt, en u hebt SearchRequestor uitgebreid, kunt u als volgt een zoekopdracht starten:

    // Zoekpatroon ophalen
    SearchPattern pattern = ...;

    // Zoekbereik ophalen
    IJavaSearchScope scope = ...;

    // Zoekopvrager ophalen
    SearchRequestor requestor = ...;

    // Zoeken
    SearchEngine searchEngine = new SearchEngine();
    searchEngine.search(pattern, new SearchParticipant[] {SearchEngine.getDefaultSearchParticipant()}, scope, requestor, null);

Met de methode beginReporting wordt een melding naar de zoekopvrager verzonden dat de zoekopdracht is gestart. Vervolgens wordt elk zoekresultaat gerapporteerd via de methode acceptSearchMatch. Ten slotte wordt met endReporting aangegeven dat de zoekopdracht is voltooid.

Zoekresultaten verzamelen

Zoekresultaten worden gemeld met de methode acceptSearchMatch(SearchMatch). In de onderstaande alinea's worden enkele functies van SearchMatch besproken.

Resources en Java-elementen

Een zoekresultaat kan overeenkomen met een Java-element (bijvoorbeeld een typedeclaratie) of zijn ingesloten in een Java-element (bijvoorbeeld een verwijzing naar een type in een methode). De zoekengine probeert altijd het diepstgelegen Java-element te vinden dat overeenkomt met het zoekresultaat of waarin het zoekresultaat zich bevindt. Als u bijvoorbeeld verwijzingen naar een methode zoekt, kunnen deze worden gevonden in een initiator. De initiator die deze methodeverwijzing bevat, is het element van de zoekovereenkomst.

De zoekengine zoekt ook naar de resource waarin het Java-element zich bevindt. Als het Java-element in een compilatie-eenheid of een klassenbestand is opgenomen, is de resource het bijbehorende exemplaar van IFile. Als het Java-element in een JAR-bestand in het werkgebied is opgenomen, is de resultaatresource het JAR-bestand. Anders wordt null geretourneerd.

Bronposities

De bronposities getOffset en getLength zijn relatief ten opzichte van de compilatie-eenheid waarin het zoekresultaat zich bevindt. Als het zoekresultaat zich bevindt in een JAR-bestand, zijn de bronposities relatief ten opzichte van de gekoppelde bron. Als er geen bron aan het JAR-bestand gekoppeld is, zijn ze (-1, -1).

Nauwkeurige versus onnauwkeurige zoekresultaten

In de meeste gevallen zijn de zoekresultaten nauwkeurig. Dat houdt in dat de zoekengine kon bepalen dat de gevonden overeenkomst inderdaad het gezochte object is. In sommige gevallen is dit echter niet mogelijk en is het resultaat onnauwkeurig. Enkele mogelijke oorzaken van onnauwkeurige zoekresultaten zijn: