Java-Suchsteuerkomponente verwenden

Ihr Plug-in kann die JDT-API verwenden, um Java-Projekte im Arbeitsbereich nach Java-Elementen, wie z. B. Verweise auf Methoden, Felddeklarationen, Implementierungselemente einer Schnittstelle, zu durchsuchen.

Der Eingangspunkt für die Java-Suche ist die Klasse SearchEngine. Sie können nach bestimmten Mustern innerhalb eines Java-Elements suchen und die Suche auf bestimmte Elemente begrenzen.  Suchmuster können mit Hilfe von createPattern erstellt werden.  Ein Bereich für Suchmuster wird mit Hilfe von createJavaSearchScope angegeben.  Sobald ein Muster und ein Bereich definiert sind, wird die Methode search verwendet, um die Ergebnisse zu sammeln.

Suchergebnisse werden an einen SearchRequestor berichtet, den Sie weiterverbinden müssen, um auf die Ergebnisse zuzugreifen.

Suche vorbereiten

Eine Suchoperation verwendet sowohl ein Muster zur Beschreibung der Art der Suche, als auch einen eingeschränkten Suchbereich.

Java-Suchmuster erstellen

Ein Suchmuster definiert, wie die Suchergebnisse gesucht werden. Sie können ein Suchmuster entweder aus einem Java-Element erstellen (siehe hierzu createPatternPattern(IJavaElement, int)) oder aus einer Zeichenfolge (siehe hierzu createPattern(String, int, int, int).) Die zweite Methode unterstützt Platzhalter ("*") und kann verwendet werden, um die Suchergebnisse auszuweiten.

Ein Suchmuster für die Suche nach Verweisen auf eine bestimmte Methode wird beispielsweise folgendermaßen erstellt:

    // Methode abrufen
    IMethod method = ...;

    // Suchmuster erstellen
    SearchPattern pattern = SearchPattern.createPattern(method, IJavaSearchConstants.REFERENCES);

Erstellen eines Suchmusters für die Suche nach Deklarationen aller Typen, die mit 'Obj' beginnen:

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

Folgende Suchmuster werden unterstützt:

Java-Suchbereich erstellen

Wenn Sie sich für Suchergebnisse in einem bestimmten Projekt oder gar in einem bestimmten Paket interessieren, oder wenn Sie wissen, dass Suchergebnisse nur in der Hierarchie eines gegebenen Typs gefunden werden können, können Sie den entsprechenden Suchbereich mit Hilfe von createJavaSearchScope(IJavaElement[]) oder createHierarchyScope(IType) erstellen.

Ein Suchbereich für ein bestimmtes Paket wird beispielsweise wie folgt erstellt:

    // Paket abrufen
    IPackageFragment pkg = ...;

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

Erstellen eines Suchbereichs für die Hierarchie eines bestimmten Typs:

    // Typ abrufen
    IType type = ...;

    // Suchbereich erstellen
    IJavaSearchScope scope = SearchEngine.createHierarchyScope(type);

Schließlich können Sie einen Suchbereich erstellen, der den gesamten Arbeitsbereich umfasst, indem Sie createWorkspaceScope verwenden:

    // Suchbereich erstellen
    IJavaSearchScope scope = SearchEngine.createWorkspaceScope();

Suchen

Sobald Sie ein Suchmuster und einen Suchbereich erstellt haben und SearchRequestor weiterverbunden wurde, können Sie eine Suchabfrage wie folgt starten:

    // Suchmuster abrufen
    SearchPattern pattern = ...;

    // Suchbereich abrufen
    IJavaSearchScope scope = ...;

    // Suchanforderer abrufen
    SearchRequestor requestor = ...;

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

Eine Benachrichtigung darüber, dass die Suche beginnt, wird an Ihren Such-Requester mit Hilfe der Methode beginReporting gesendet.  Anschließend wird jedes Suchergebnis mit Hilfe der Methode acceptSearchMatch berichtet. Schließlich wird durch endReporting angegeben, dass die Suche beendet ist.

Suchergebnisse sammeln

Suchergebnisse werden mit Hilfe der Methode acceptSearchMatch(SearchMatch) berichtet. Die Absätze unten heben einige Funktionen von SearchMatch hervor.

Ressourcen und Java-Elemente

Ein Suchergebnis kann einem Java-Element zugeordnet werden (z. B. einer Typdeklaration), oder es kann in einem Java-Element enthalten sein (z. B. ein Verweis auf einen Typ innerhalb einer Methode). Die Suchsteuerkomponente versucht stets, das innerste Java-Element zu finden, das dem Suchergebnis zugeordnet ist bzw. das Suchergebnis enthält. Bei der Suche nach Verweisen auf eine Methode beispielsweise könnte ein solcher Verweis in einem Initialisierungsoperator gefunden werden. Der Initialisierungsoperator, der diesen Methodenverweis enthält, ist das Element der Übereinstimmung.

Die Suchmaschine versucht auch, die Ressource zu finden, die das Java-Element enthält. Wenn das Java-Element sich in einer Kompiliereinheit oder einen Klassendatei befindet, ist die Ressource die entsprechende IFile. Wenn das Java-Element sich in einer Datei mit der Erweiterung .jar befindet, ist die zurückgegebene Ressource die Datei mit der Erweiterung .jar, falls sie sich im Arbeitsbereich befindet. Andernfalls ist es Null.

Quellenpositionen

Die Suchpositionen getOffset und getLength werden relativ zur Kompiliereinheit angegeben, die die Suchergebnisse enthält. Ist das Suchergebnis in einer .jar-Datei enthalten, sind die Quellenpositionen relativ zu der zugeordneten Quelle. Sie sind (-1, -1), wenn der .jar-Datei keine Quelle zugeordnet wird.

Genaue und ungenaue Suchergebnisse

In den meisten Fällen sind die Suchergebnisse genau, d. h. die Suchsteuerkomponente konnte ermitteln, dass nach der angegebenen Übereinstimmung tatsächlich gesucht wurde. In einigen Fällen kann die Suchsteuerkomponente dies jedoch nicht ermitteln. Dann ist die Übereinstimmung ungenau. Für eine ungenaue Übereinstimmung kann es folgende Erklärungen geben: