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

If you are interested in search results in a given project or even in a given package, or if you know that search results can only be found in the hierarchy of a given type, you can create the appropriate search scope using createJavaSearchScope(IJavaElement[]) or 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);

Finally, you can create a search scope comprising the entire workspace using createWorkspaceScope:

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

Search results are reported using the acceptSearchMatch(SearchMatch) method. Paragraphs below highlight some features of SearchMatch.

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. If the Java element is contained in a compilation unit or a class file, the resource is the corresponding IFile. If the Java element is contained in a .jar file, the returned resource is that .jar file if it is in the workspace, null otherwise.

Posizioni di origine

Source positions getOffset and getLength are given relative to the compilation unit that contains the search result. 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: