Your plug-in can use the JDT API to search Java projects in the workspace for Java elements, such as method references, field declarations, implementors of an interface, etc.
The entry point for Java search is the SearchEngine class. Factory methods on this class, such as createSearchPattern (creates a search pattern) or createJavaSearchScope (creates a Java search scope) are used by the search method. This method reports results to an IJavaSearchResultCollector which you must implement.
A search operation will use both a pattern for describing the nature of the search, and a scope for restraining the range of investigation.
A search pattern defines how search results are found. You can either create a search pattern from a Java element (see createSearchPattern(IJavaElement, int)) or from a string (see createSearchPattern(String, int, int, boolean).) The last method supports wildcards (i.e. '*') and can be used to widen the search results.
For example, creating a search pattern for searching for references to a given method is done as follows:
// Get the method
IMethod method = ...;
// Create search pattern
ISearchPattern pattern = SearchEngine.createSearchPattern(method, IJavaSearchConstants.REFERENCES);
Or creating a search pattern for searching for declarations of all types starting with "Obj":
// Create search pattern
ISearchPattern pattern = SearchEngine.createSearchPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, true);
The following search patterns are supported:
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 be only in a hierarchy of a given type, you can create the appropriate search scope using createJavaSearchScope(IJavaElement[]) or createHierarchyScope(IType).
For example, creating a search scope on a given package is done as follows:
// Get the package
IPackageFragment pkg = ...;
// Create search scope
IJavaSearchScope scope = SearchEngine.createJavaSearchScope(new IJavaElement[] {pkg});
Or creating a search scope on the hierarchy of a given type is:
// Get the type
IType type = ...;
// Create search scope
IJavaSearchScope scope = SearchEngine.createHierarchyScope(type);
Finally, you can create a search scope on the entire workspace:
// Create search scope
IJavaSearchScope scope = SearchEngine.createWorkspaceScope();
Once you have created a search pattern and a search scope, and you have implemented IJavaSearchResultCollector, you can start a search query as follows:
// Get the search pattern
ISearchPattern pattern = ...;
// Get the search scope
IJavaSearchScope scope = ...;
// Get the search result collector
IJavaSearchResultCollector collector = ...;
// Search
SearchEngine searchEngine = new SearchEngine();
searchEngine.search(ResourcesPlugin.getWorkspace(), pattern, scope, collector);
A notification that the search starts is sent to your search result collector using the aboutToStart method. Then, each search result is reported using the accept method. Finally done indicates that the search has ended.
Search results are reported using the accept method. Paragraphs below detail each argument to this method.
A search result can correspond to a Java element (e.g. a type declaration) or it can be contained in a Java element (e.g. a reference to a type inside a method). The search engine always tries to find the innermost Java element that corresponds to or that contains the search result. For example, searching for type declarations by name could find a local type declaration. Since the Java model doesn't represent local types, the method that contains this local type declaration is given to the result collector.
The search engine also tries to give the resource that contains the Java element to the result collector. So if the Java element is a method in a compilation unit, the resource is the corresponding IFile. If the element is contained in a .jar file, the resource is the .jar file, if this .jar file is in the workspace. If it is an external .jar file, then the resource is null.
Source positions are given relative to the compilation unit that contains the search result. If the search result is contained in a .jar file, the source positions are relative to the attached source. They are (-1, -1) if there is no source attached to the .jar file.
In most cases search results are accurate, meaning that the search engine was able to determine that the given match is what was asked for. However in some cases the search engine is unable to do so, in such cases the match is inaccurate. Some possible reasons why a match could be inaccurate are: