Il plug-in in uso può utilizzare l'API JDT per la ricerca, all'interno dei progetti Java dello spazio 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 classe SearchEngine. È 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 createSearchPattern. 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 IJavaSearchResultCollector che deve essere implementata per poter accedere ai risultati.
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.
Un modello di ricerca definisce le modalità di esecuzione dei risultati della ricerca. È possibile creare un modello di ricerca da un elemento Java (vedere createSearchPattern(IJavaElement, int)) oppure da una stringa (vedere createSearchPattern(String, int, int, boolean).) 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:
// Ottenere il metodo IMethod method = ...; // Creare il modello di ricerca ISearchPattern pattern = SearchEngine.createSearchPattern(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":
// Creare il modello di ricerca ISearchPattern pattern = SearchEngine.createSearchPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, true);
Sono supportati i seguenti modelli di ricerca:
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:
// Ottenere il pacchetto IPackageFragment pkg = ...; // Creare l'ambito di ricerca IJavaSearchScope scope = SearchEngine.createJavaSearchScope(new IJavaElement[] {pkg});
È riportato anche un esempio di creazione di un ambito di ricerca nella gerarchia di un determinato tipo:
// Ottenere il tipo IType type = ...; // Creare l'ambito di ricerca IJavaSearchScope scope = SearchEngine.createHierarchyScope(type);
Infine, è possibile creare un ambito di ricerca sull'intero spazio di lavoro:
// Creare l'ambito di ricerca IJavaSearchScope scope = SearchEngine.createWorkspaceScope();
Una volta creato un modello di ricerca e un ambito di ricerca e implementato IJavaSearchResultCollector, è possibile avviare una query di ricerca come descritto di seguito:
// Ottenere il modello di ricerca ISearchPattern pattern = ...; // Ottenere l'ambito di ricerca IJavaSearchScope scope = ...; // Ottenere il raccoglitore dei risultati della ricerca IJavaSearchResultCollector collector = ...; // Eseguire la ricerca SearchEngine searchEngine = new SearchEngine(); searchEngine.search(ResourcesPlugin.getWorkspace(), pattern, scope, collector);
Al raccoglitore dei risultati della ricerca viene inviata notifica dell'avvio della ricerca mediante il metodo aboutToStart. Quindi, viene riportato ciascun risultato della ricerca mediante il metodo accept. Infine done indica che la ricerca è terminata.
I risultati della ricerca vengono riportati utilizzando il metodo accept. I paragrafi riportati di seguito descrivono nei dettagli ciascun argomento e il relativo metodo.
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. Se, ad esempio, si esegue la ricerca delle dichiarazioni di tipi per nome, è possibile trovare una dichiarazione di tipo locale. Dal momento che il modello Java non rappresenta i tipi locali, al raccoglitore di risultati viene fornito il metodo che contiene questa dichiarazione di tipo locale.
Il motore di ricerca prova a fornire al raccoglitore di risultati anche 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.
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).
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: