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 in einem Java-Element suchen und für die Suche einen Bereich spezifischer Elemente angeben.  Suchmuster können mit Hilfe von createPattern erstellt werden.  Ein Bereich für Suchmuster wird mit Hilfe von createJavaSearchScope angegeben.  Nach der Definition eines Musters und eines Bereichs wird die Methode search verwendet, um die Ergebnisse zu erfassen.

Suchergebnisse werden an einen SearchRequestor gemeldet, der erweitert werden muss, damit der Zugriff auf die Ergebnisse möglich ist.

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:

    // Get the method
    IMethod method = ...;
    
    // Create search pattern
    SearchPattern pattern = SearchPattern.createPattern(method, IJavaSearchConstants.REFERENCES);

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

    // Create search pattern
    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

Sind Sie an Suchergebnissen in einem bestimmten Projekt oder in einem bestimmten Paket interessiert, oder können sich Suchergebnisse nur in einer Hierarchie eines bestimmten Typs befinden, können Sie den entsprechenden Suchbereich unter Verwendung von createJavaSearchScope(IJavaElement[]) oder createHierarchyScope(IType) erstellen.

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

    // Get the package
    IPackageFragment pkg = ...;

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

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

    // Get the type
    IType type = ...;

    // Create search scope
    IJavaSearchScope scope = SearchEngine.createHierarchyScope(type);

Am Schluss können Sie einen Suchbereich für den gesamten Arbeitsbereich erstellen:

    // Create search scope
    IJavaSearchScope scope = SearchEngine.createWorkspaceScope();

Suchen

Nachdem Sie ein Suchmuster und einen Suchbereich erstellt und SearchRequestor erweitert haben, können Sie eine Suchabfrage wie folgt starten:

    // Get the search pattern
    SearchPattern pattern = ...;

    // Get the search scope
    IJavaSearchScope scope = ...;

    // Get the search requestor
    SearchRequestor requestor = ...;

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

Eine Benachrichtigung über das Starten der Suche wird unter Verwendung der Methode beginReporting an Ihren Suchrequester gesendet.  Anschließend werden alle Suchergebnisse unter Verwendung der Methode acceptSearchMatch gemeldet. Schließlich wird durch endReporting angegeben, dass die Suche beendet ist.

Suchergebnisse sammeln

Suchergebnisse werden unter Verwendung der Methode acceptSearchMatch gemeldet. In den nachstehenden Abschnitten wird die Suchübereinstimmung erläutert.

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 Suchübereinstimmung.

Die Suchmaschine versucht auch, die Ressource zu finden, die das Java-Element enthält. Ist das Java-Element also eine Methode in einer Kompiliereinheit, ist die Ressource die entsprechende IFile. Ist das Element in einer .jar-Datei enthalten, ist die Ressource die .jar-Datei (wenn sich diese .jar-Datei im Arbeitsbereich befindet). Handelt es sich um eine externe .jar-Datei, ist die Ressource Null.

Quellenpositionen

Quellenpositionen werden relativ zu der Kompiliereinheit angegeben, die das Suchergebnis 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: