bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_search.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><html><head>
 <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.&nbsp;
 Search patterns can be created using <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#createSearchPattern(org.eclipse.jdt.core.IJavaElement, int)">createSearchPattern</a></b>.&nbsp;
 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>.&nbsp;
 Once a pattern and scope are defined, the <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#search(org.eclipse.core.resources.IWorkspace, org.eclipse.jdt.core.search.ISearchPattern, org.eclipse.jdt.core.search.IJavaSearchScope, org.eclipse.jdt.core.search.IJavaSearchResultCollector)">search</a></b>
  method is used to collect the results. </p>

 <p>
 Search results are reported to an  <b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html">IJavaSearchResultCollector</a></b> which you must
 implement 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/SearchEngine.html#createSearchPattern(org.eclipse.jdt.core.IJavaElement, int)">createSearchPattern(IJavaElement, int)</a></b>)
 or from a string (see <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#createSearchPattern(java.lang.String, int, int, boolean)">createSearchPattern(String, int, int, boolean)</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
     ISearchPattern pattern = SearchEngine.createSearchPattern(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
     ISearchPattern pattern = SearchEngine.createSearchPattern(&quot;Obj*&quot;, IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, true);
 </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/SearchEngine.html#createOrSearchPattern(org.eclipse.jdt.core.search.ISearchPattern, org.eclipse.jdt.core.search.ISearchPattern)">createOrSearchPattern</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 implemented
 <b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html">IJavaSearchResultCollector</a></b>,
 you can start a search query as follows: </p>
 <font color="#4444cc"><pre>
     // 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);
 </pre></font>
 <p>
 A notification that the search starts is sent to your search result collector using the
 <b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html#aboutToStart()">aboutToStart</a></b>
 method. &nbsp;Then, each search result is reported using the
 <b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html#accept(org.eclipse.core.resources.IResource, int, int, org.eclipse.jdt.core.IJavaElement, int)">accept</a></b>
 method. Finally
 <b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html#done()">done</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/IJavaSearchResultCollector.html#accept(org.eclipse.core.resources.IResource, int, int, org.eclipse.jdt.core.IJavaElement, int)">accept</a></b>
 method. Paragraphs below detail each argument to this method. </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 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. </p>
 <p>
 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
 <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 accesible, 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>

 <p><a href="../hglegal2003.htm"><img src="../ngibmcpy2003.gif" width=324 height=14 alt="Copyright IBM Corporation and others 2000, 2003. All Rights Reserved." border="0"></a>
 </p>

 </body></html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><html><head>
	<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/SearchEngine.html#createSearchPattern(org.eclipse.jdt.core.IJavaElement, int)">createSearchPattern</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.core.resources.IWorkspace, org.eclipse.jdt.core.search.ISearchPattern, org.eclipse.jdt.core.search.IJavaSearchScope, org.eclipse.jdt.core.search.IJavaSearchResultCollector)">search</a></b>
	method is used to collect the results. </p>

	<p>
	Search results are reported to an <b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html">IJavaSearchResultCollector</a></b> which you must
	implement 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/SearchEngine.html#createSearchPattern(org.eclipse.jdt.core.IJavaElement, int)">createSearchPattern(IJavaElement, int)</a></b>)
	or from a string (see <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#createSearchPattern(java.lang.String, int, int, boolean)">createSearchPattern(String, int, int, boolean)</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
	ISearchPattern pattern = SearchEngine.createSearchPattern(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
	ISearchPattern pattern = SearchEngine.createSearchPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, true);
	</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/SearchEngine.html#createOrSearchPattern(org.eclipse.jdt.core.search.ISearchPattern, org.eclipse.jdt.core.search.ISearchPattern)">createOrSearchPattern</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 implemented
	<b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html">IJavaSearchResultCollector</a></b>,
	you can start a search query as follows: </p>
	<font color="#4444cc"><pre>
	// 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);
	</pre></font>
	<p>
	A notification that the search starts is sent to your search result collector using the
	<b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html#aboutToStart()">aboutToStart</a></b>
	method.  Then, each search result is reported using the
	<b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html#accept(org.eclipse.core.resources.IResource, int, int, org.eclipse.jdt.core.IJavaElement, int)">accept</a></b>
	method. Finally
	<b><a href="../reference/api/org/eclipse/jdt/core/search/IJavaSearchResultCollector.html#done()">done</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/IJavaSearchResultCollector.html#accept(org.eclipse.core.resources.IResource, int, int, org.eclipse.jdt.core.IJavaElement, int)">accept</a></b>
	method. Paragraphs below detail each argument to this method. </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 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. </p>
	<p>
	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
	<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 accesible, 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>

	<p><a href="../hglegal2003.htm"><img src="../ngibmcpy2003.gif" width=324 height=14 alt="Copyright IBM Corporation and others 2000, 2003. All Rights Reserved." border="0"></a>
	</p>

	</body></html>