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 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.&nbsp;
 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>.&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.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(&quot;Obj*&quot;, 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 only be found in the 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 comprising the entire workspace using
 <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#createWorkspaceScope()">createWorkspaceScope</a></b>:</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. &nbsp;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(SearchMatch)</a></b>
 method. Paragraphs below highlight some features of
 <b><a href="../reference/api/org/eclipse/jdt/core/search/SearchMatch.html">SearchMatch</a></b>. </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. If the Java
 element is contained in a compilation unit or a class file, 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 Java element is contained in a .jar file, the returned resource is that .jar
 file if it is in the workspace, <b>null</b> otherwise. </p>

 <h4>
 Source positions</h4>
 <p>Source positions <b><a HREF="../reference/api/org/eclipse/jdt/core/search/SearchMatch.html#getOffset()">
 getOffset</a></b> and <b><a HREF="../reference/api/org/eclipse/jdt/core/search/SearchMatch.html#getLength()">getLength</a></b> 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>
	<!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 only be found in the 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 comprising the entire workspace using
	<b><a href="../reference/api/org/eclipse/jdt/core/search/SearchEngine.html#createWorkspaceScope()">createWorkspaceScope</a></b>:</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(SearchMatch)</a></b>
	method. Paragraphs below highlight some features of
	<b><a href="../reference/api/org/eclipse/jdt/core/search/SearchMatch.html">SearchMatch</a></b>. </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. If the Java
	element is contained in a compilation unit or a class file, 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 Java element is contained in a .jar file, the returned resource is that .jar
	file if it is in the workspace, <b>null</b> otherwise. </p>

	<h4>
	Source positions</h4>
	<p>Source positions <b><a HREF="../reference/api/org/eclipse/jdt/core/search/SearchMatch.html#getOffset()">
	getOffset</a></b> and <b><a HREF="../reference/api/org/eclipse/jdt/core/search/SearchMatch.html#getLength()">getLength</a></b> 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>