org.eclipse.wst.jsdt.core.search
Class SearchEngine

java.lang.Object
  extended by org.eclipse.wst.jsdt.core.search.SearchEngine

public class SearchEngine
extends java.lang.Object

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

Various search patterns can be created using the factory methods SearchPattern.createPattern(String, int, int, int), SearchPattern.createPattern(IJavaScriptElement, int), SearchPattern.createOrPattern(SearchPattern, SearchPattern).

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.

Provisional API: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.


Constructor Summary
SearchEngine()
          Creates a new search engine.
SearchEngine(IJavaScriptUnit[] workingCopies)
          Creates a new search engine with a list of working copies that will take precedence over their original javascript unit s in the subsequent search operations.
SearchEngine(WorkingCopyOwner workingCopyOwner)
          Creates a new search engine with the given working copy owner.
 
Method Summary
static IJavaScriptSearchScope createHierarchyScope(IType type)
          Returns a JavaScript search scope limited to the hierarchy of the given type.
static IJavaScriptSearchScope createHierarchyScope(IType type, WorkingCopyOwner owner)
          Returns a JavaScript search scope limited to the hierarchy of the given type.
static IJavaScriptSearchScope createJavaSearchScope(IJavaScriptElement[] elements)
          Returns a JavaScript search scope limited to the given JavaScript elements.
static IJavaScriptSearchScope createJavaSearchScope(IJavaScriptElement[] elements, boolean includeReferencedProjects)
          Returns a JavaScript search scope limited to the given JavaScript elements.
static IJavaScriptSearchScope createJavaSearchScope(IJavaScriptElement[] elements, int includeMask)
          Returns a JavaScript search scope limited to the given JavaScript elements.
static TypeNameMatch createTypeNameMatch(IType type, int modifiers)
          Create a type name match on a given type with specific modifiers.
static IJavaScriptSearchScope createWorkspaceScope()
          Returns a JavaScript search scope with the workspace as the only limit.
static SearchParticipant getDefaultSearchParticipant()
          Returns a new default JavaScript search participant.
 void search(SearchPattern pattern, SearchParticipant[] participants, IJavaScriptSearchScope scope, SearchRequestor requestor, IProgressMonitor monitor)
          Searches for matches of a given search pattern.
 void searchAllTypeNames(char[][] qualifications, char[][] typeNames, IJavaScriptSearchScope scope, TypeNameMatchRequestor nameMatchRequestor, int waitingPolicy, IProgressMonitor progressMonitor)
          Searches for all top-level types and member types in the given scope matching any of the given qualifications and type names in a case sensitive way.
 void searchAllTypeNames(char[][] qualifications, char[][] typeNames, IJavaScriptSearchScope scope, TypeNameRequestor nameRequestor, int waitingPolicy, IProgressMonitor progressMonitor)
          Searches for all top-level types and member types in the given scope matching any of the given qualifications and type names in a case sensitive way.
 void searchAllTypeNames(char[] packageName, int packageMatchRule, char[] typeName, int typeMatchRule, int searchFor, IJavaScriptSearchScope scope, TypeNameMatchRequestor nameMatchRequestor, int waitingPolicy, IProgressMonitor progressMonitor)
          Searches for all top-level types and member types in the given scope.
 void searchAllTypeNames(char[] packageName, int packageMatchRule, char[] typeName, int typeMatchRule, int searchFor, IJavaScriptSearchScope scope, TypeNameRequestor nameRequestor, int waitingPolicy, IProgressMonitor progressMonitor)
          Searches for all top-level types and member types in the given scope.
 void searchDeclarationsOfAccessedFields(IJavaScriptElement enclosingElement, SearchRequestor requestor, IProgressMonitor monitor)
          Searches for all declarations of the fields accessed in the given element.
 void searchDeclarationsOfReferencedTypes(IJavaScriptElement enclosingElement, SearchRequestor requestor, IProgressMonitor monitor)
          Searches for all declarations of the types referenced in the given element.
 void searchDeclarationsOfSentMessages(IJavaScriptElement enclosingElement, SearchRequestor requestor, IProgressMonitor monitor)
          Searches for all declarations of the methods invoked in the given element.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SearchEngine

public SearchEngine()
Creates a new search engine.


SearchEngine

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

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

Since 3.0 the given working copies take precedence over primary working copies (if any).

Parameters:
workingCopies - the working copies that take precedence over their original javascript unit s

SearchEngine

public SearchEngine(WorkingCopyOwner workingCopyOwner)
Creates a new search engine with the given working copy owner. The working copies owned by this owner will take precedence over the primary javascript unit s in the subsequent search operations.

Parameters:
workingCopyOwner - the owner of the working copies that take precedence over their original javascript unit s
Method Detail

createHierarchyScope

public static IJavaScriptSearchScope createHierarchyScope(IType type)
                                                   throws JavaScriptModelException
Returns a JavaScript search scope limited to the hierarchy of the given type. The JavaScript 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:
JavaScriptModelException - if the hierarchy could not be computed on the given type

createHierarchyScope

public static IJavaScriptSearchScope createHierarchyScope(IType type,
                                                          WorkingCopyOwner owner)
                                                   throws JavaScriptModelException
Returns a JavaScript search scope limited to the hierarchy of the given type. When the hierarchy is computed, the types defined in the working copies owned by the given owner take precedence over the original javascript unit s. The JavaScript 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
owner - the owner of working copies that take precedence over original javascript unit s
Returns:
a new hierarchy scope
Throws:
JavaScriptModelException - if the hierarchy could not be computed on the given type

createJavaSearchScope

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

If an element is an IJavaScriptProject, 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 javascript 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 JavaScript elements the scope is limited to
Returns:
a new JavaScript search scope

createJavaSearchScope

public static IJavaScriptSearchScope createJavaSearchScope(IJavaScriptElement[] elements,
                                                           boolean includeReferencedProjects)
Returns a JavaScript search scope limited to the given JavaScript elements. The JavaScript elements resulting from a search with this scope will be children of the given elements. If an element is an IJavaScriptProject, 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 javascript unit and class files of this package fragment will be included. Subpackages will NOT be included.

Parameters:
elements - the JavaScript elements the scope is limited to
includeReferencedProjects - a flag indicating if referenced projects must be recursively included
Returns:
a new JavaScript search scope

createJavaSearchScope

public static IJavaScriptSearchScope createJavaSearchScope(IJavaScriptElement[] elements,
                                                           int includeMask)
Returns a JavaScript search scope limited to the given JavaScript elements. The JavaScript elements resulting from a search with this scope will be children of the given elements. If an element is an IJavaScriptProject, then it includes: - its source folders if IJavaScriptSearchScope.SOURCES is specified, - its application libraries (internal and external jars, class folders that are on the raw includepath, or the ones that are coming from a includepath path variable, or the ones that are coming from a includepath container with the K_APPLICATION kind) if IJavaScriptSearchScope.APPLICATION_LIBRARIES is specified - its system libraries (internal and external jars, class folders that are coming from an IJsGlobalScopeContainer with the K_SYSTEM kind) if IJavaScriptSearchScope.APPLICATION_LIBRARIES is specified - its referenced projects (with their source folders and jars, recursively) if IJavaScriptSearchScope.REFERENCED_PROJECTS is specified. 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 javascript unit and class files of this package fragment will be included. Subpackages will NOT be included.

Parameters:
elements - the JavaScript elements the scope is limited to
includeMask - the bit-wise OR of all include types of interest
Returns:
a new JavaScript search scope
See Also:
IJavaScriptSearchScope.SOURCES, IJavaScriptSearchScope.APPLICATION_LIBRARIES, IJavaScriptSearchScope.SYSTEM_LIBRARIES, IJavaScriptSearchScope.REFERENCED_PROJECTS

createTypeNameMatch

public static TypeNameMatch createTypeNameMatch(IType type,
                                                int modifiers)
Create a type name match on a given type with specific modifiers.

Parameters:
type - The javascript model handle of the type
modifiers - Modifiers of the type
Returns:
A non-null match on the given type.

createWorkspaceScope

public static IJavaScriptSearchScope createWorkspaceScope()
Returns a JavaScript search scope with the workspace as the only limit.

Returns:
a new workspace scope

getDefaultSearchParticipant

public static SearchParticipant getDefaultSearchParticipant()
Returns a new default JavaScript search participant.

Returns:
a new default JavaScript search participant

search

public void search(SearchPattern pattern,
                   SearchParticipant[] participants,
                   IJavaScriptSearchScope scope,
                   SearchRequestor requestor,
                   IProgressMonitor monitor)
            throws CoreException
Searches for matches of a given search pattern. Search patterns can be created using helper methods (from a String pattern or a JavaScript element) and encapsulate the description of what is being searched (for example, search method declarations in a case sensitive way).

Parameters:
pattern - the pattern to search
participants - the particpants in the search
scope - the search scope
requestor - the requestor to report the matches to
monitor - the progress monitor used to report progress
Throws:
CoreException - if the search failed. Reasons include:
  • the includepath is incorrectly set

searchAllTypeNames

public void searchAllTypeNames(char[] packageName,
                               int packageMatchRule,
                               char[] typeName,
                               int typeMatchRule,
                               int searchFor,
                               IJavaScriptSearchScope scope,
                               TypeNameRequestor nameRequestor,
                               int waitingPolicy,
                               IProgressMonitor progressMonitor)
                        throws JavaScriptModelException
Searches for all top-level types and member types in the given scope. The search can be selecting specific types (given a package name using specific match mode and/or a type name using another specific match mode).

Parameters:
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. May be null, then any package name is accepted.
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. May be null, then any type name is accepted.
packageMatchRule - one of combined with SearchPattern.R_CASE_SENSITIVE, e.g. SearchPattern.R_EXACT_MATCH | SearchPattern.R_CASE_SENSITIVE if an exact and case sensitive match is requested, or SearchPattern.R_PREFIX_MATCH if a prefix non case sensitive match is requested.
typeMatchRule - one of combined with SearchPattern.R_CASE_SENSITIVE, e.g. SearchPattern.R_EXACT_MATCH | SearchPattern.R_CASE_SENSITIVE if an exact and case sensitive match is requested, or SearchPattern.R_PREFIX_MATCH if a prefix non case sensitive match is requested.
searchFor - determines the nature of the searched elements
scope - the scope to search in
nameRequestor - the requestor that collects the results of the search
waitingPolicy - one of
progressMonitor - the progress monitor to report progress to, or null if no progress monitor is provided
Throws:
JavaScriptModelException - if the search failed. Reasons include:
  • the includepath is incorrectly set

searchAllTypeNames

public void searchAllTypeNames(char[] packageName,
                               int packageMatchRule,
                               char[] typeName,
                               int typeMatchRule,
                               int searchFor,
                               IJavaScriptSearchScope scope,
                               TypeNameMatchRequestor nameMatchRequestor,
                               int waitingPolicy,
                               IProgressMonitor progressMonitor)
                        throws JavaScriptModelException
Searches for all top-level types and member types in the given scope. The search can be selecting specific types (given a package name using specific match mode and/or a type name using another specific match mode).

Provided TypeNameMatchRequestor requestor will collect TypeNameMatch matches found during the search.

Parameters:
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. May be null, then any package name is accepted.
packageMatchRule - one of combined with SearchPattern.R_CASE_SENSITIVE, e.g. SearchPattern.R_EXACT_MATCH | SearchPattern.R_CASE_SENSITIVE if an exact and case sensitive match is requested, or SearchPattern.R_PREFIX_MATCH if a prefix non case sensitive match is requested.
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. May be null, then any type name is accepted.
typeMatchRule - one of combined with SearchPattern.R_CASE_SENSITIVE, e.g. SearchPattern.R_EXACT_MATCH | SearchPattern.R_CASE_SENSITIVE if an exact and case sensitive match is requested, or SearchPattern.R_PREFIX_MATCH if a prefix non case sensitive match is requested.
searchFor - determines the nature of the searched elements
scope - the scope to search in
nameMatchRequestor - the requestor that collects matches of the search.
waitingPolicy - one of
progressMonitor - the progress monitor to report progress to, or null if no progress monitor is provided
Throws:
JavaScriptModelException - if the search failed. Reasons include:
  • the includepath is incorrectly set

searchAllTypeNames

public void searchAllTypeNames(char[][] qualifications,
                               char[][] typeNames,
                               IJavaScriptSearchScope scope,
                               TypeNameRequestor nameRequestor,
                               int waitingPolicy,
                               IProgressMonitor progressMonitor)
                        throws JavaScriptModelException
Searches for all top-level types and member types in the given scope matching any of the given qualifications and type names in a case sensitive way.

Parameters:
qualifications - the qualified name of the package/enclosing type of the searched types. May be null, then any package name is accepted.
typeNames - the simple names of the searched types. If this parameter is null, then no type will be found.
scope - the scope to search in
nameRequestor - the requestor that collects the results of the search
waitingPolicy - one of
progressMonitor - the progress monitor to report progress to, or null if no progress monitor is provided
Throws:
JavaScriptModelException - if the search failed. Reasons include:
  • the includepath is incorrectly set

searchAllTypeNames

public void searchAllTypeNames(char[][] qualifications,
                               char[][] typeNames,
                               IJavaScriptSearchScope scope,
                               TypeNameMatchRequestor nameMatchRequestor,
                               int waitingPolicy,
                               IProgressMonitor progressMonitor)
                        throws JavaScriptModelException
Searches for all top-level types and member types in the given scope matching any of the given qualifications and type names in a case sensitive way.

Provided TypeNameMatchRequestor requestor will collect TypeNameMatch matches found during the search.

Parameters:
qualifications - the qualified name of the package/enclosing type of the searched types. May be null, then any package name is accepted.
typeNames - the simple names of the searched types. If this parameter is null, then no type will be found.
scope - the scope to search in
nameMatchRequestor - the requestor that collects matches of the search.
waitingPolicy - one of
progressMonitor - the progress monitor to report progress to, or null if no progress monitor is provided
Throws:
JavaScriptModelException - if the search failed. Reasons include:
  • the includepath is incorrectly set

searchDeclarationsOfAccessedFields

public void searchDeclarationsOfAccessedFields(IJavaScriptElement enclosingElement,
                                               SearchRequestor requestor,
                                               IProgressMonitor monitor)
                                        throws JavaScriptModelException
Searches for all declarations of the fields accessed in the given element. The element can be a javascript unit , a source type, or a source method. Reports the field declarations using the given requestor.

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:
enclosingElement - the method, type, or javascript unit to be searched in
requestor - a callback object to which each match is reported
monitor - the progress monitor used to report progress
Throws:
JavaScriptModelException - if the search failed. Reasons include:
  • the element doesn't exist
  • the includepath is incorrectly set

searchDeclarationsOfReferencedTypes

public void searchDeclarationsOfReferencedTypes(IJavaScriptElement enclosingElement,
                                                SearchRequestor requestor,
                                                IProgressMonitor monitor)
                                         throws JavaScriptModelException
Searches for all declarations of the types referenced in the given element. The element can be a javascript unit , a source type, or a source method. Reports the type declarations using the given requestor.

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:
enclosingElement - the method, type, or javascript unit to be searched in
requestor - a callback object to which each match is reported
monitor - the progress monitor used to report progress
Throws:
JavaScriptModelException - if the search failed. Reasons include:
  • the element doesn't exist
  • the includepath is incorrectly set

searchDeclarationsOfSentMessages

public void searchDeclarationsOfSentMessages(IJavaScriptElement enclosingElement,
                                             SearchRequestor requestor,
                                             IProgressMonitor monitor)
                                      throws JavaScriptModelException
Searches for all declarations of the methods invoked in the given element. The element can be a javascript unit , a source type, or a source method. Reports the method declarations using the given requestor.

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:
enclosingElement - the method, type, or javascript unit to be searched in
requestor - a callback object to which each match is reported
monitor - the progress monitor used to report progress
Throws:
JavaScriptModelException - if the search failed. Reasons include:
  • the element doesn't exist
  • the includepath is incorrectly set