package org.eclipse.jdt.internal.core.builder; | |
/* | |
* (c) Copyright IBM Corp. 2000, 2001. | |
* All Rights Reserved. | |
*/ | |
import org.eclipse.jdt.core.*; | |
/** | |
* An <code>ISearch</code> represents an image search and its results. | |
* <code>ISearch</code>es are created by <code>ISearchFactory</code> objects. | |
* They can be queried for results and report progress as the search runs. A | |
* search can be stopped before it finishes and can be run again. | |
* <code>ISearch</code> is implemented in a thread safe manner. | |
* <p> | |
* The search is not precise. Instead it provides a best-effort search. | |
* No occurrences of what is being searched for will be missed, and no duplicate | |
* results will be returned. However, the search may occasionally return additional | |
* matches which don't actually relate to what was being searched for. | |
* This will only be an issue when searching for source references. An | |
* example of this would be if a search for references to a field called <code>io</code> was | |
* performed. Any methods which contained a reference to <code>java.io.</code><i>something</i> | |
* would be returned as matches, because in the source, it is unclear whether | |
* <code>io</code> is a field in some class called <code>java</code> or not. | |
* <p> | |
* ISearchFactory shows examples of using ISearch. | |
* | |
* @see ISearchFactory | |
*/ | |
public interface ISearch extends Runnable | |
{ | |
/** | |
* Adds the specified action listener to receive progress and result events | |
* from this search. Progress events occur as a search examines the types | |
* and packages in the search scope. Result events occur as a search finds | |
* matches to the search criteria. | |
* @param listener the search listener | |
* @see ISearchListener | |
* @see SearchProgressEvent | |
* @see SearchResultEvent | |
* @see ISearch#removeSearchListener | |
*/ | |
void addSearchListener(ISearchListener listener); | |
/** | |
* Cancels the search. If the search is not running, this operation has no | |
* effect. | |
*/ | |
void cancelSearch(); | |
/** | |
* Returns whether two ISearch objects are equal or not. | |
* Two ISearch objects are considered to be equal if | |
* they are the same object OR: | |
* <ul> | |
* <li> neither is equal to null AND | |
* <li> both searches have the same kind (i.e.. search for type), name | |
* (i.e., type named 'Foo') return type, number and type of parameters | |
* (even if not used -- as in the case of search for type), and search | |
* context (i.e., ISearchFactory.SEARCH_FOR_DECLS) | |
* <li> their scopes are equal (contain the same IPackage and IType handles, in any order) | |
* </ul> | |
*/ | |
boolean equals(Object obj); | |
/** | |
* Returns the item <i>n</i>th item in the search result. This may be a field, | |
* method, constructor, package, or type object. | |
*/ | |
IHandle getItem(int n); | |
/** | |
* Returns the number of items in the search scope which matched the | |
* search goal so far. Note that the result may not include all matches | |
* within the search space if the search is still running or was cancelled. | |
*/ | |
int getItemCount(); | |
/** | |
* Returns the positions for the <i>n</i>th item in the search result. | |
* If no positions exist, null is returned. | |
*/ | |
int[] getPositions(int n); | |
/** | |
* Returns whether a search is currently in progress. | |
*/ | |
boolean isSearching(); | |
/** | |
* Removes the specified action listener so that it no longer | |
* receives progress and result events from the search. | |
* @param listener the search listener | |
* @see ISearchListener | |
* @see SearchProgressEvent | |
* @see SearchResultEvent | |
* @see ISearch#addSearchListener | |
*/ | |
void removeSearchListener(ISearchListener listener); | |
/** | |
* Performs the search. Upon return the results can be obtained via | |
* <code>getItem</code>. During the search, the results are made available | |
* as they are found, and progress and results are reported to registered | |
* <code>ISearchListener</code>s. | |
*/ | |
void run(); | |
} |