| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><html><head> |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| |
| <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"><title>Using the Java search engine</title> |
| |
| |
| <link rel="stylesheet" type="text/css" href="../book.css"></head> |
| <body> |
| <h2>Using the Java search engine</h2> |
| <p> 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. </p> |
| <p> |
| The entry point for Java search is the <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html">SearchEngine</a></b> class. You can search for particular |
| patterns inside a Java element and scope the search to specific elements. |
| Search patterns can be created using <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchPattern.html#createPattern(org.eclipse.jdt.core.IJavaElement, int)">createPattern</a></b>. |
| A pattern is scoped using <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#createJavaSearchScope(org.eclipse.jdt.core.IJavaElement[])">createJavaSearchScope</a></b>. |
| Once a pattern and scope are defined, the <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#search(org.eclipse.jdt.core.search.SearchPattern, org.eclipse.jdt.core.search.SearchParticipant[], org.eclipse.jdt.core.search.IJavaSearchScope, org.eclipse.jdt.core.search.SearchRequestor, org.eclipse.core.runtime.IProgressMonitor)">search</a></b> |
| method is used to collect the results. </p> |
| |
| <p> |
| Search results are reported to a <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchRequestor.html">SearchRequestor</a></b> which you must |
| extend in order to access the results. </p> |
| |
| <h3> |
| Preparing for search</h3> |
| <p> A search operation will use both a pattern for describing the nature |
| of the search, and a scope for restraining the range of investigation. </p> |
| |
| <h4> |
| Creating a Java search pattern |
| </h4> |
| <p> |
| A search pattern defines how search results are found. You can either create a search pattern from a Java element (see |
| <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchPattern.html#createPattern(org.eclipse.jdt.core.IJavaElement, int)">createPatternPattern(IJavaElement, int)</a></b>) |
| or from a string (see <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchPattern.html#createPattern(java.lang.String, int, int, int)">createPattern(String, int, int, int)</a></b>.) |
| The last method supports wildcards (i.e. '*') and can be used to widen the search results.</p> |
| <p> |
| For example, creating a search pattern for searching for references to a given method is done as follows:</p> |
| <font color="#4444cc"><pre> |
| // Get the method |
| IMethod method = ...; |
| |
| // Create search pattern |
| SearchPattern pattern = SearchPattern.createPattern(method, IJavaSearchConstants.REFERENCES); |
| </pre></font> |
| <p> |
| Or creating a search pattern for searching for declarations of all types starting with "Obj":</p> |
| <font color="#4444cc"><pre> |
| // Create search pattern |
| SearchPattern pattern = SearchPattern.createPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, SearchPattern.R_PATTERN_MATCH | SearchPattern.R_CASE_SENSITIVE); |
| </pre></font> |
| <p> |
| The following search patterns are supported: |
| </p><ul> |
| <li>Package declarations</li> |
| <li>Type declarations</li> |
| <li>Field declarations</li> |
| <li>Method (and constructor) declarations</li> |
| <li>Package references</li> |
| <li>Type references</li> |
| <li>Interface implementors</li> |
| <li>Field references</li> |
| <li>Field write accesses</li> |
| <li>Field read accesses</li> |
| <li>Method (and constructor) references</li> |
| <li>Combinations of the above patterns using the OR pattern (see |
| <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchPattern.html#createOrPattern(org.eclipse.jdt.core.search.SearchPattern, org.eclipse.jdt.core.search.SearchPattern)">createOrPattern</a></b>)</li> |
| </ul> |
| |
| |
| <h4> |
| Creating a Java search scope |
| </h4> |
| <p> |
| 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 |
| <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#createJavaSearchScope(org.eclipse.jdt.core.IJavaElement[])">createJavaSearchScope(IJavaElement[])</a></b> |
| or <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#createHierarchyScope(org.eclipse.jdt.core.IType)">createHierarchyScope(IType)</a></b>.</p> |
| <p> |
| For example, creating a search scope on a given package is done as follows:</p> |
| <font color="#4444cc"><pre> |
| // Get the package |
| IPackageFragment pkg = ...; |
| |
| // Create search scope |
| IJavaSearchScope scope = SearchEngine.createJavaSearchScope(new IJavaElement[] {pkg}); |
| </pre></font> |
| <p> |
| Or creating a search scope on the hierarchy of a given type is:</p> |
| <font color="#4444cc"><pre> |
| // Get the type |
| IType type = ...; |
| |
| // Create search scope |
| IJavaSearchScope scope = SearchEngine.createHierarchyScope(type); |
| </pre></font> |
| <p> |
| Finally, you can create a search scope on the entire workspace:</p> |
| <font color="#4444cc"><pre> |
| // Create search scope |
| IJavaSearchScope scope = SearchEngine.createWorkspaceScope(); |
| </pre></font> |
| |
| <h3> |
| Searching</h3> |
| <p> |
| Once you have created a search pattern and a search scope, and you have extended |
| <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchRequestor.html">SearchRequestor</a></b>, |
| you can start a search query as follows: </p> |
| <font color="#4444cc"><pre> |
| // 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); |
| </pre></font> |
| <p> |
| A notification that the search starts is sent to your search requestor using the |
| <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchRequestor.html#beginReporting()">beginReporting</a></b> |
| method. Then, each search result is reported using the |
| <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchRequestor.html#acceptSearchMatch(org.eclipse.jdt.core.search.SearchMatch)">acceptSearchMatch</a></b> |
| method. Finally |
| <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchRequestor.html#endReporting()">endReporting</a></b> |
| indicates that the search has ended.</p> |
| |
| <h3> |
| Collecting search results</h3> |
| <p> |
| Search results are reported using the |
| <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchRequestor.html#acceptSearchMatch(org.eclipse.jdt.core.search.SearchMatch)">acceptSearchMatch</a></b> |
| method. Paragraphs below detail the search match. </p> |
| |
| <h4> |
| Resources and Java elements</h4> |
| <p> |
| 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 references to a method could find |
| such a reference in an initializer. The initializer that contains this method reference is the element of the search match. </p> |
| <p> |
| The search engine also tries to find the resource that contains the Java element. So if the Java |
| element is a method in a compilation unit, the resource is the corresponding |
| <a HREF="../../org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/resources/IFile.html"><b>IFile</b></a>. |
| 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 <b>null</b>. </p> |
| |
| <h4> |
| Source positions</h4> |
| <p> 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. </p> |
| |
| <h4> |
| Accurate versus inaccurate search results</h4> |
| <p> |
| 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: |
| </p><ul> |
| <li>The classpath on the project that contains the result is not properly set. For example, it refers to a project that is |
| not accessible, a jar on the classpath requires another jar that is not on the classpath, etc.</li> |
| <li>The user code would not compile. For example, it refers to a class that is not yet defined.</li> |
| </ul> |
| |
| |
| |
| </body></html> |
