public abstract class SearchParticipant
extends java.lang.Object
A search participant is involved in the indexing phase and in the search phase. The indexing phase consists in taking one or more search documents, parse them, and add index entries in an index chosen by the participant. An index is identified by a path on disk. The search phase consists in selecting the indexes corresponding to a search pattern and a search scope, from these indexes the search infrastructure extracts the document paths that match the search pattern asking the search participant for the corresponding document, finally the search participant is asked to locate the matches precisely in these search documents.
This class is intended to be subclassed by clients. During the indexing phase, a subclass will be called with the following requests in order:
During the search phase, a subclass will be called with the following requests in order: 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.Modifier | Constructor and Description |
---|---|
protected |
SearchParticipant()
Creates a new search participant.
|
Modifier and Type | Method and Description |
---|---|
void |
beginSearching()
Notification that this participant's help is needed in a search.
|
void |
doneSearching()
Notification that this participant's help is no longer needed.
|
java.lang.String |
getDescription()
Returns a displayable name of this search participant.
|
abstract SearchDocument |
getDocument(java.lang.String documentPath)
Returns a search document for the given path.
|
abstract void |
indexDocument(SearchDocument document,
IPath indexLocation)
Indexes the given document in the given index.
|
abstract void |
locateMatches(SearchDocument[] documents,
SearchPattern pattern,
IJavaScriptSearchScope scope,
SearchRequestor requestor,
IProgressMonitor monitor)
Locates the matches in the given documents using the given search pattern
and search scope, and reports them to the givenn search requestor.
|
void |
removeIndex(IPath indexLocation)
Removes the index for a given path.
|
void |
scheduleDocumentIndexing(SearchDocument document,
IPath indexLocation)
Schedules the indexing of the given document.
|
abstract IPath[] |
selectIndexes(SearchPattern query,
IJavaScriptSearchScope scope)
Returns the collection of index locations to consider when performing the
given search query in the given scope.
|
protected SearchParticipant()
public void beginSearching()
This method should be re-implemented in subclasses that need to do something when the participant is needed in a search.
public void doneSearching()
This method should be re-implemented in subclasses that need to do something when the participant is no longer needed in a search.
public java.lang.String getDescription()
This method should be re-implemented in subclasses that need to display a meaningfull name.
public abstract SearchDocument getDocument(java.lang.String documentPath)
Implementors of this method can either create an instance of their own subclass of
SearchDocument
or return an existing instance of such a subclass.
documentPath
- the path of the document.public abstract void indexDocument(SearchDocument document, IPath indexLocation)
SearchDocument.addIndexEntry(char[], char[])
as many times as
needed to add index entries to the index. If delegating to another
participant, it should use the original index location (and not the
delegatee's one). In the particular case of delegating to the default
search participant (see SearchEngine.getDefaultSearchParticipant()
),
the provided document's path must be a path ending with one of the
Java-like extensions
or with '.class'.
The given index location must represent a path in the file system to a file that either already exists or is going to be created. If it exists, it must be an index file, otherwise its data might be overwritten.
Clients are not expected to call this method.
document
- the document to indexindexLocation
- the location in the file system to the indexpublic abstract void locateMatches(SearchDocument[] documents, SearchPattern pattern, IJavaScriptSearchScope scope, SearchRequestor requestor, IProgressMonitor monitor) throws CoreException
Note that a participant (e.g. a JSP participant) can pre-process the contents of the given documents,
create its own documents whose contents are JavaScript javascript unit s and delegate the match location
to the default participant (see SearchEngine.getDefaultSearchParticipant()
). Passing its own
SearchRequestor
this particpant can then map the match positions back to the original
contents, create its own matches and report them to the original requestor.
Implementors of this method should check the progress monitor
for cancelation when it is safe and appropriate to do so. The cancelation
request should be propagated to the caller by throwing
OperationCanceledException
.
documents
- the documents to locate matches inpattern
- the search pattern to use when locating matchesscope
- the scope to limit the search torequestor
- the requestor to report matches tomonitor
- the progress monitor to report progress to,
or null
if no progress should be reportedCoreException
- if the requestor had problem accepting one of the matchespublic void removeIndex(IPath indexLocation)
The given index location must represent a path in the file system to a file that already exists and must be an index file, otherwise nothing will be done.
It is strongly recommended to use this method instead of deleting file directly otherwise cached index will not be removed.
indexLocation
- the location in the file system to the indexpublic final void scheduleDocumentIndexing(SearchDocument document, IPath indexLocation)
indexDocument(document, indexPath)
will be called in a different thread than the caller's thread.
The given index location must represent a path in the file system to a file that either already exists or is going to be created. If it exists, it must be an index file, otherwise its data might be overwritten.
When the index is no longer needed, clients should use removeIndex(IPath)
to discard it.
document
- the document to indexindexLocation
- the location on the file system of the indexpublic abstract IPath[] selectIndexes(SearchPattern query, IJavaScriptSearchScope scope)
An index location represents a path in the file system to a file that holds index information.
Clients are not expected to call this method.
query
- the search pattern to considerscope
- the given search scopeCopyright (c) IBM Corp. and others 2000, 2010. All Rights Reserved.