Eclipse JDT
2.1

org.eclipse.jdt.core.search
Class SearchEngine

java.lang.Object
  |
  +--org.eclipse.jdt.core.search.SearchEngine

public class SearchEngine
extends Object

A SearchEngine searches for java elements following a search pattern. The search can be limited to a search scope.

Various search patterns can be created using the factory methods createSearchPattern(String, int, int, boolean), createSearchPattern(IJavaElement, int), createOrSearchPattern(ISearchPattern, ISearchPattern).

For example, one can search for references to a method in the hierarchy of a type, or one can search for the declarations of types starting with "Abstract" in a project.

This class may be instantiated; it is not intended to be subclassed.


Field Summary
static boolean VERBOSE
          For tracing purpose.
 
Constructor Summary
SearchEngine()
          Creates a new search engine.
SearchEngine(IWorkingCopy[] workingCopies)
          Creates a new search engine with a list of working copies that will take precedence over their original compilation units in the subsequent search operations.
 
Method Summary
static IJavaSearchScope createHierarchyScope(IType type)
          Returns a java search scope limited to the hierarchy of the given type.
static IJavaSearchScope createJavaSearchScope(IJavaElement[] elements)
          Returns a java search scope limited to the given java elements.
static IJavaSearchScope createJavaSearchScope(IJavaElement[] elements, boolean includeReferencedProjects)
          Returns a java search scope limited to the given java elements.
static IJavaSearchScope createJavaSearchScope(IResource[] resources)
          Deprecated. Use createJavaSearchScope(IJavaElement[]) instead
static ISearchPattern createOrSearchPattern(ISearchPattern leftPattern, ISearchPattern rightPattern)
          Returns a search pattern that combines the given two patterns into a "or" pattern.
static ISearchPattern createSearchPattern(IJavaElement element, int limitTo)
          Returns a search pattern based on a given Java element.
static ISearchPattern createSearchPattern(String stringPattern, int searchFor, int limitTo, boolean isCaseSensitive)
          Returns a search pattern based on a given string pattern.
static IJavaSearchScope createWorkspaceScope()
          Returns a java search scope with the workspace as the only limit.
 void search(IWorkspace workspace, IJavaElement element, int limitTo, IJavaSearchScope scope, IJavaSearchResultCollector resultCollector)
          Searches for the given Java element.
 void search(IWorkspace workspace, ISearchPattern searchPattern, IJavaSearchScope scope, IJavaSearchResultCollector resultCollector)
          Searches for matches of a given search pattern.
 void search(IWorkspace workspace, String patternString, int searchFor, int limitTo, IJavaSearchScope scope, IJavaSearchResultCollector resultCollector)
          Searches for the Java element determined by the given signature.
 void searchAllTypeNames(IWorkspace workspace, char[] packageName, char[] typeName, int matchMode, boolean isCaseSensitive, int searchFor, IJavaSearchScope scope, ITypeNameRequestor nameRequestor, int waitingPolicy, IProgressMonitor progressMonitor)
          Searches for all top-level types and member types in the given scope.
 void searchDeclarationsOfAccessedFields(IWorkspace workspace, IJavaElement enclosingElement, IJavaSearchResultCollector resultCollector)
          Searches for all declarations of the fields accessed in the given element.
 void searchDeclarationsOfReferencedTypes(IWorkspace workspace, IJavaElement enclosingElement, IJavaSearchResultCollector resultCollector)
          Searches for all declarations of the types referenced in the given element.
 void searchDeclarationsOfSentMessages(IWorkspace workspace, IJavaElement enclosingElement, IJavaSearchResultCollector resultCollector)
          Searches for all declarations of the methods invoked in the given element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERBOSE

public static boolean VERBOSE
For tracing purpose.
Constructor Detail

SearchEngine

public SearchEngine()
Creates a new search engine.

SearchEngine

public SearchEngine(IWorkingCopy[] workingCopies)
Creates a new search engine with a list of working copies that will take precedence over their original compilation units in the subsequent search operations.

Note that passing an empty working copy will be as if the original compilation unit had been deleted.

Parameters:
workingCopies - the working copies that take precedence over their original compilation units
Since:
2.0
Method Detail

createHierarchyScope

public static IJavaSearchScope createHierarchyScope(IType type)
                                             throws JavaModelException
Returns a java search scope limited to the hierarchy of the given type. The java elements resulting from a search with this scope will be types in this hierarchy, or members of the types in this hierarchy.
Parameters:
type - the focus of the hierarchy scope
Returns:
a new hierarchy scope
Throws:
JavaModelException - if the hierarchy could not be computed on the given type

createJavaSearchScope

public static IJavaSearchScope createJavaSearchScope(IResource[] resources)
Deprecated. Use createJavaSearchScope(IJavaElement[]) instead

Returns a java search scope limited to the given resources. The java elements resulting from a search with this scope will have their underlying resource included in or equals to one of the given resources.

Resources must not overlap, for example, one cannot include a folder and its children.

Parameters:
resources - the resources the scope is limited to
Returns:
a new java search scope

createJavaSearchScope

public static IJavaSearchScope createJavaSearchScope(IJavaElement[] elements)
Returns a java search scope limited to the given java elements. The java elements resulting from a search with this scope will be children of the given elements.

If an element is an IJavaProject, then the project's source folders, its jars (external and internal) and its referenced projects (with their source folders and jars, recursively) will be included. If an element is an IPackageFragmentRoot, then only the package fragments of this package fragment root will be included. If an element is an IPackageFragment, then only the compilation unit and class files of this package fragment will be included. Subpackages will NOT be included.

In other words, this is equivalent to using SearchEngine.createJavaSearchScope(elements, true).

Parameters:
elements - the java elements the scope is limited to
Returns:
a new java search scope
Since:
2.0

createJavaSearchScope

public static IJavaSearchScope createJavaSearchScope(IJavaElement[] elements,
                                                     boolean includeReferencedProjects)
Returns a java search scope limited to the given java elements. The java elements resulting from a search with this scope will be children of the given elements. If an element is an IJavaProject, then the project's source folders, its jars (external and internal) and - if specified - its referenced projects (with their source folders and jars, recursively) will be included. If an element is an IPackageFragmentRoot, then only the package fragments of this package fragment root will be included. If an element is an IPackageFragment, then only the compilation unit and class files of this package fragment will be included. Subpackages will NOT be included.
Parameters:
elements - the java elements the scope is limited to
includeReferencedProjects - a flag indicating if referenced projects must be recursively included
Returns:
a new java search scope
Since:
2.0

createOrSearchPattern

public static ISearchPattern createOrSearchPattern(ISearchPattern leftPattern,
                                                   ISearchPattern rightPattern)
Returns a search pattern that combines the given two patterns into a "or" pattern. The search result will match either the left pattern or the right pattern.
Parameters:
leftPattern - the left pattern
rightPattern - the right pattern
Returns:
a "or" pattern

createSearchPattern

public static ISearchPattern createSearchPattern(String stringPattern,
                                                 int searchFor,
                                                 int limitTo,
                                                 boolean isCaseSensitive)
Returns a search pattern based on a given string pattern. The string patterns support '*' wild-cards. The remaining parameters are used to narrow down the type of expected results.
Examples:
Parameters:
stringPattern - the given pattern
searchFor - determines the nature of the searched elements
  • IJavaSearchConstants.CLASS: only look for classes
  • IJavaSearchConstants.INTERFACE: only look for interfaces
  • IJavaSearchConstants.TYPE: look for both classes and interfaces
  • IJavaSearchConstants.FIELD: look for fields
  • IJavaSearchConstants.METHOD: look for methods
  • IJavaSearchConstants.CONSTRUCTOR: look for constructors
  • IJavaSearchConstants.PACKAGE: look for packages
limitTo - determines the nature of the expected matches
  • IJavaSearchConstants.DECLARATIONS: will search declarations matching with the corresponding element. In case the element is a method, declarations of matching methods in subtypes will also be found, allowing to find declarations of abstract methods, etc.
  • IJavaSearchConstants.REFERENCES: will search references to the given element.
  • IJavaSearchConstants.ALL_OCCURRENCES: will search for either declarations or references as specified above.
  • IJavaSearchConstants.IMPLEMENTORS: for interface, will find all types which implements a given interface.
isCaseSensitive - indicates whether the search is case sensitive or not.
Returns:
a search pattern on the given string pattern, or null if the string pattern is ill-formed.

createSearchPattern

public static ISearchPattern createSearchPattern(IJavaElement element,
                                                 int limitTo)
Returns a search pattern based on a given Java element. The pattern is used to trigger the appropriate search, and can be parameterized as follows:
Parameters:
element - the java element the search pattern is based on
limitTo - determines the nature of the expected matches
  • IJavaSearchConstants.DECLARATIONS: will search declarations matching with the corresponding element. In case the element is a method, declarations of matching methods in subtypes will also be found, allowing to find declarations of abstract methods, etc.
  • IJavaSearchConstants.REFERENCES: will search references to the given element.
  • IJavaSearchConstants.ALL_OCCURRENCES: will search for either declarations or references as specified above.
  • IJavaSearchConstants.IMPLEMENTORS: for interface, will find all types which implements a given interface.
Returns:
a search pattern for a java element or null if the given element is ill-formed

createWorkspaceScope

public static IJavaSearchScope createWorkspaceScope()
Returns a java search scope with the workspace as the only limit.
Returns:
a new workspace scope

search

public void search(IWorkspace workspace,
                   String patternString,
                   int searchFor,
                   int limitTo,
                   IJavaSearchScope scope,
                   IJavaSearchResultCollector resultCollector)
            throws JavaModelException
Searches for the Java element determined by the given signature. The signature can be incomplete. For example, a call like search(ws, "run()", METHOD,REFERENCES, col) searches for all references to the method run. Note that by default the pattern will be case insensitive. For specifying case s sensitive search, use search(workspace, createSearchPattern(patternString, searchFor, limitTo, true), scope, resultCollector);
Parameters:
workspace - the workspace
pattern - the pattern to be searched for
searchFor - a hint what kind of Java element the string pattern represents. Look into IJavaSearchConstants for valid values
limitTo - one of the following values:
  • IJavaSearchConstants.DECLARATIONS: search for declarations only
  • IJavaSearchConstants.REFERENCES: search for all references
  • IJavaSearchConstants.ALL_OCCURENCES: search for both declarations and all references
  • IJavaSearchConstants.IMPLEMENTORS: search for all implementors of an interface; the value is only valid if the Java element represents an interface
scope - the search result has to be limited to the given scope
resultCollector - a callback object to which each match is reported
Throws:
JavaModelException - if the search failed. Reasons include:
  • the classpath is incorrectly set

search

public void search(IWorkspace workspace,
                   IJavaElement element,
                   int limitTo,
                   IJavaSearchScope scope,
                   IJavaSearchResultCollector resultCollector)
            throws JavaModelException
Searches for the given Java element.
Parameters:
workspace - the workspace
element - the Java element to be searched for
limitTo - one of the following values:
  • IJavaSearchConstants.DECLARATIONS: search for declarations only
  • IJavaSearchConstants.REFERENCES: search for all references
  • IJavaSearchConstants.ALL_OCCURENCES: search for both declarations and all references
  • IJavaSearchConstants.IMPLEMENTORS: search for all implementors of an interface; the value is only valid if the Java element represents an interface
scope - the search result has to be limited to the given scope
resultCollector - a callback object to which each match is reported
Throws:
JavaModelException - if the search failed. Reasons include:
  • the element doesn't exist
  • the classpath is incorrectly set

search

public void search(IWorkspace workspace,
                   ISearchPattern searchPattern,
                   IJavaSearchScope scope,
                   IJavaSearchResultCollector resultCollector)
            throws JavaModelException
Searches for matches of a given search pattern. Search patterns can be created using helper methods (from a String pattern or a Java element) and encapsulate the description of what is being searched (for example, search method declarations in a case sensitive way).
Parameters:
workspace - the workspace
searchPattern - the pattern to be searched for
scope - the search result has to be limited to the given scope
resultCollector - a callback object to which each match is reported
Throws:
JavaModelException - if the search failed. Reasons include:
  • the classpath is incorrectly set

searchAllTypeNames

public void searchAllTypeNames(IWorkspace workspace,
                               char[] packageName,
                               char[] typeName,
                               int matchMode,
                               boolean isCaseSensitive,
                               int searchFor,
                               IJavaSearchScope scope,
                               ITypeNameRequestor nameRequestor,
                               int waitingPolicy,
                               IProgressMonitor progressMonitor)
                        throws JavaModelException
Searches for all top-level types and member types in the given scope. The search can be selecting specific types (given a package or a type name prefix and match modes).
Parameters:
workspace - the workspace to search in
packageName - the full name of the package of the searched types, or a prefix for this package, or a wild-carded string for this package.
typeName - the dot-separated qualified name of the searched type (the qualification include the enclosing types if the searched type is a member type), or a prefix for this type, or a wild-carded string for this type.
matchMode - one of
  • IJavaSearchConstants.EXACT_MATCH if the package name and type name are the full names of the searched types.
  • IJavaSearchConstants.PREFIX_MATCH if the package name and type name are prefixes of the names of the searched types.
  • IJavaSearchConstants.PATTERN_MATCH if the package name and type name contain wild-cards.
isCaseSensitive - whether the search should be case sensitive
searchFor - one of
  • IJavaSearchConstants.CLASS if searching for classes only
  • IJavaSearchConstants.INTERFACE if searching for interfaces only
  • IJavaSearchConstants.TYPE if searching for both classes and interfaces
scope - the scope to search in
nameRequestor - the requestor that collects the results of the search
waitingPolicy - one of
  • IJavaSearchConstants.FORCE_IMMEDIATE_SEARCH if the search should start immediately
  • IJavaSearchConstants.CANCEL_IF_NOT_READY_TO_SEARCH if the search should be cancelled if the underlying indexer has not finished indexing the workspace
  • IJavaSearchConstants.WAIT_UNTIL_READY_TO_SEARCH if the search should wait for the underlying indexer to finish indexing the workspace
progressMonitor - the progress monitor to report progress to, or null if no progress monitor is provided
Throws:
JavaModelException - if the search failed. Reasons include:
  • the classpath is incorrectly set

searchDeclarationsOfAccessedFields

public void searchDeclarationsOfAccessedFields(IWorkspace workspace,
                                               IJavaElement enclosingElement,
                                               IJavaSearchResultCollector resultCollector)
                                        throws JavaModelException
Searches for all declarations of the fields accessed in the given element. The element can be a compilation unit, a type, or a method. Reports the field declarations using the given collector.

Consider the following code:

		class A {
			int field1;
		}
		class B extends A {
			String value;
		}
		class X {
			void test() {
				B b = new B();
				System.out.println(b.value + b.field1);
			};
		}
 
then searching for declarations of accessed fields in method X.test() would collect the fields B.value and A.field1.

Parameters:
workspace - the workspace
enclosingElement - the method, type, or compilation unit to be searched in
resultCollector - a callback object to which each match is reported
Throws:
JavaModelException - if the search failed. Reasons include:
  • the element doesn't exist
  • the classpath is incorrectly set

searchDeclarationsOfReferencedTypes

public void searchDeclarationsOfReferencedTypes(IWorkspace workspace,
                                                IJavaElement enclosingElement,
                                                IJavaSearchResultCollector resultCollector)
                                         throws JavaModelException
Searches for all declarations of the types referenced in the given element. The element can be a compilation unit, a type, or a method. Reports the type declarations using the given collector.

Consider the following code:

		class A {
		}
		class B extends A {
		}
		interface I {
		  int VALUE = 0;
		}
		class X {
			void test() {
				B b = new B();
				this.foo(b, I.VALUE);
			};
		}
 
then searching for declarations of referenced types in method X.test() would collect the class B and the interface I.

Parameters:
workspace - the workspace
enclosingElement - the method, type, or compilation unit to be searched in
resultCollector - a callback object to which each match is reported
Throws:
JavaModelException - if the search failed. Reasons include:
  • the element doesn't exist
  • the classpath is incorrectly set

searchDeclarationsOfSentMessages

public void searchDeclarationsOfSentMessages(IWorkspace workspace,
                                             IJavaElement enclosingElement,
                                             IJavaSearchResultCollector resultCollector)
                                      throws JavaModelException
Searches for all declarations of the methods invoked in the given element. The element can be a compilation unit, a type, or a method. Reports the method declarations using the given collector.

Consider the following code:

		class A {
			void foo() {};
			void bar() {};
		}
		class B extends A {
			void foo() {};
		}
		class X {
			void test() {
				A a = new B();
				a.foo();
				B b = (B)a;
				b.bar();
			};
		}
 
then searching for declarations of sent messages in method X.test() would collect the methods A.foo(), B.foo(), and A.bar().

Parameters:
workspace - the workspace
enclosingElement - the method, type, or compilation unit to be searched in
resultCollector - a callback object to which each match is reported
Throws:
JavaModelException - if the search failed. Reasons include:
  • the element doesn't exist
  • the classpath is incorrectly set

Eclipse JDT
2.1

Copyright (c) IBM Corp. and others 2000, 2003. All Rights Reserved.