Utilizzo del motore di ricerca Java

Il plugin in uso può utilizzare l'API JDT per la ricerca all'interno dei progetti Java dell'area di lavoro di elementi Java, quali riferimenti di metodi, dichiarazioni di campi, implementatori di un'interfaccia e così via.

Il punto di immissione per la ricerca Java è la classeSearchEngine. È possibile effettuare la ricerca di modelli particolari all'interno di un elemento Java e costituire l'ambito della ricerca con determinati elementi.  I modelli di ricerca possono essere creati mediante createPattern.  L'ambito di un modello può essere creato mediante createJavaSearchScope.  Una volta definiti modello e ambito, il metodo search viene utilizzato per raccogliere i risultati.

I risultati della ricerca vengono riportati in una classe SearchRequestor che deve essere estesa per poter accedere ai risultati.

Preparazione per la ricerca

Un'operazione di ricerca utilizzerà sia un modello per la descrizione della natura della ricerca sia un ambito per la restrizione del campo di ricerca.

Creazione di un modello di ricerca Java

Un modello di ricerca definisce le modalità di esecuzione dei risultati della ricerca. È possibile creare un modello di ricerca da un elemento Java (vedere createPatternPattern(IJavaElement, int)) oppure da una stringa (vedere createPattern(String, int, int, int).) L'ultimo metodo supporta i caratteri jolly (ossia '*') e può essere utilizzato per ampliare i risultati della ricerca.

Di seguito è riportato un esempio di creazione di un modello per la ricerca di riferimenti a un determinato metodo:

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

È riportato anche un esempio di creazione di un modello per la ricerca di dichiarazioni di tutti i tipi che comincino con "Obj":

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

Sono supportati i seguenti modelli di ricerca:

Creazione di un ambito di ricerca Java

Se si è interessati ai risultati della ricerca in un determinato progetto o anche in un determinato pacchetto oppure se è noto che i risultati della ricerca possono trovarsi solo in una gerarchia di un determinato tipo, è possibile creare l'ambito di ricerca appropriato utilizzando createJavaSearchScope(IJavaElement[]) oppure createHierarchyScope(IType).

Di seguito è riportato un esempio di creazione di un ambito di ricerca in un determinato pacchetto:

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

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

È riportato anche un esempio di creazione di un ambito di ricerca nella gerarchia di un determinato tipo:

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

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

Infine, è possibile creare un ambito di ricerca sull'intero spazio di lavoro:

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

Ricerca

Una volta creato un modello di ricerca e un ambito di ricerca, ed esteso SearchRequestor, è possibile avviare una query di ricerca come descritto di seguito:

    // 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);

Al richiedente della ricerca viene inviata notifica dell'avvio della ricerca mediante il metodo beginReporting.  Quindi, viene riportato ciascun risultato della ricerca mediante il metodo acceptSearchMatch. Infine, endReporting indica che la ricerca è terminata.

Raccolta dei risultati della ricerca

I risultati della ricerca vengono riportati utilizzando il metodo acceptSearchMatch. I paragrafi riportati di seguito descrivono nei dettagli la corrispondenza della ricerca.

Risorse ed elementi Java

Un risultato della ricerca può corrispondere a un elemento Java (ad esempio una dichiarazione di tipi) oppure può essere contenuto in un elemento Java (ad esempio un riferimento a un tipo all'interno di un metodo). Il motore di ricerca effettua sempre il tentativo di trovare l'elemento Java più interno che corrisponde a o che contiene il risultato della ricerca. Ad esempio, la ricerca dei riferimenti a un metodo può trovare un riferimento in un inizializzatore. L'inizializzatore contenente questo riferimento del metodo è l'elemento della corrispondenza della ricerca.

Il motore di ricerca prova a fornire la risorsa contenente l'elemento Java. Se, quindi, l'elemento Java è un metodo di un'unità di compilazione, la risorsa sarà il metodo IFile corrispondente. Se l'elemento è contenuto in un file .jar, la risorsa sarà il file .jar, se tale file si trova nello spazio di lavoro. Se si tratta di un file .jar esterno, la risorsa sarà null.

Posizioni di origine

Le posizioni di origine fornite sono in relazione all'unità di compilazione contenente il risultato della ricerca. Se il risultato della ricerca è contenuto in un file .jar, le posizioni di origine sono in relazione all'origine collegata. Se al file .jar non è collegata alcuna origine, le posizioni saranno (-1, -1).

Risultati della ricerca accurati e non accurati

Nella maggior parte dei casi i risultati della ricerca sono accurati, ovvero il motore di ricerca è stato in grado di fornire l'esatto corrispondente della richiesta. Quando, invece, il motore di ricerca non è in grado di fornire questo risultato, la corrispondenza non è accurata. La corrispondenza può essere non accurata per i seguenti motivi: