SearchParticipant


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jdt.core.search;
12  
13  import org.eclipse.core.resources.IResource;
14  import org.eclipse.core.resources.IWorkspaceRoot;
15  import org.eclipse.core.resources.ResourcesPlugin;
16  import org.eclipse.core.runtime.*;
17  import org.eclipse.jdt.internal.core.JavaModel;
18  import org.eclipse.jdt.internal.core.JavaModelManager;
19  import org.eclipse.jdt.internal.core.search.indexing.IndexManager;
20  
21  /**
22   * A search participant describes a particular extension to a generic search
23   * mechanism, permitting combined search actions which will involve all required
24   * participants.
25   * <p>
26   * A search participant is involved in the indexing phase and in the search phase. 
27   * The indexing phase consists in taking one or more search documents, parse them, and
28   * add index entries in an index chosen by the participant. An index is identified by a
29   * path on disk.
30   * The search phase consists in selecting the indexes corresponding to a search pattern
31   * and a search scope, from these indexes the search infrastructure extracts the document paths
32   * that match the search pattern asking the search participant for the corresponding document,
33   * finally the search participant is asked to locate the matches precisely in these search documents.
34   * </p>
35   * <p>
36   * This class is intended to be subclassed by clients. During the indexing phase, 
37   * a subclass will be called with the following requests in order:
38   * <ul>
39   * <li>{@link #scheduleDocumentIndexing(SearchDocument, IPath)}</li>
40   * <li>{@link #indexDocument(SearchDocument, IPath)}</li>
41   * </ul>
42   * During the search phase, a subclass will be called with the following requests in order:
43   * <ul>
44   * <li>{@link #selectIndexes(SearchPattern, IJavaSearchScope)}</li>
45   * <li>one or more {@link #getDocument(String)}</li>
46   * <li>{@link #locateMatches(SearchDocument[], SearchPattern, IJavaSearchScope, SearchRequestor, IProgressMonitor)}</li>
47   * </ul>
48   * </p>
49   * 
50   * @since 3.0
51   */
52  public abstract class SearchParticipant {
53  
54      /**
55       * Creates a new search participant.
56       */
57      protected SearchParticipant() {
58          // do nothing
59      }
60      
61      /**
62       * Notification that this participant's help is needed in a search.
63       * <p>
64       * This method should be re-implemented in subclasses that need to do something
65       * when the participant is needed in a search.
66       * </p>
67       */
68      public void beginSearching() {
69          // do nothing
70      }
71  
72      /**
73       * Notification that this participant's help is no longer needed.
74       * <p>
75       * This method should be re-implemented in subclasses that need to do something
76       * when the participant is no longer needed in a search.
77       * </p>
78       */
79      public void doneSearching() {
80          // do nothing
81      }
82  
83      /**
84       * Returns a displayable name of this search participant.
85       * <p>
86       * This method should be re-implemented in subclasses that need to 
87       * display a meaningfull name.
88       * </p>
89       * 
90       * @return the displayable name of this search participant
91       */
92      public String   getDescription() {
93          return "Search participant"; //$NON-NLS-1$
94      }
95  
96      /**
97       * Returns a search document for the given path.
98       * The given document path is a string that uniquely identifies the document.
99       * Most of the time it is a workspace-relative path, but it can also be a file system path, or a path inside a zip file.
100      * <p>
101      * Implementors of this method can either create an instance of their own subclass of 
102      * {@link SearchDocument} or return an existing instance of such a subclass.
103      * </p>
104      * 
105      * @param documentPath the path of the document.
106      * @return a search document
107      */
108     public abstract SearchDocument getDocument(String   documentPath);
109 
110     /**
111      * Indexes the given document in the given index. A search participant
112      * asked to index a document should parse it and call 
113      * {@link SearchDocument#addIndexEntry(char[], char[])} as many times as
114      * needed to add index entries to the index. If delegating to another
115      * participant, it should use the original index location (and not the
116      * delegatee's one). In the particular case of delegating to the default
117      * search participant (see {@link SearchEngine#getDefaultSearchParticipant()}),
118      * the provided document's path must be a path ending with one of the 
119      * {@link org.eclipse.jdt.core.JavaCore#getJavaLikeExtensions() Java-like extensions} 
120      * or with '.class'.
121      * <p>
122      * The given index location must represent a path in the file system to a file that
123      * either already exists or is going to be created. If it exists, it must be an index file,
124      * otherwise its data might be overwritten.
125      * </p><p>
126      * Clients are not expected to call this method.
127      * </p>
128      * 
129      * @param document the document to index
130      * @param indexLocation the location in the file system to the index
131      */
132     public abstract void indexDocument(SearchDocument document, IPath indexLocation);
133 
134     /**
135      * Locates the matches in the given documents using the given search pattern
136      * and search scope, and reports them to the givenn search requestor. This
137      * method is called by the search engine once it has search documents
138      * matching the given pattern in the given search scope.
139      * <p>
140      * Note that a participant (e.g. a JSP participant) can pre-process the contents of the given documents, 
141      * create its own documents whose contents are Java compilation units and delegate the match location 
142      * to the default participant (see {@link SearchEngine#getDefaultSearchParticipant()}). Passing its own
143      * {@link SearchRequestor} this particpant can then map the match positions back to the original
144      * contents, create its own matches and report them to the original requestor.
145      * </p><p>
146      * Implementors of this method should check the progress monitor
147      * for cancelation when it is safe and appropriate to do so.  The cancelation
148      * request should be propagated to the caller by throwing 
149      * <code>OperationCanceledException</code>.
150      * </p>
151      * 
152      * @param documents the documents to locate matches in
153      * @param pattern the search pattern to use when locating matches
154      * @param scope the scope to limit the search to
155      * @param requestor the requestor to report matches to
156      * @param monitor the progress monitor to report progress to,
157      * or <code>null</code> if no progress should be reported
158      * @throws CoreException if the requestor had problem accepting one of the matches
159      */
160     public abstract void locateMatches(SearchDocument[] documents, SearchPattern pattern, IJavaSearchScope scope, SearchRequestor requestor, IProgressMonitor monitor) throws CoreException;
161 
162     /**
163      * Removes the index for a given path. 
164      * <p>
165      * The given index location must represent a path in the file system to a file that
166      * already exists and must be an index file, otherwise nothing will be done.
167      * </p><p>
168      * It is strongly recommended to use this method instead of deleting file directly
169      * otherwise cached index will not be removed.
170      * </p>
171      * 
172      * @param indexLocation the location in the file system to the index
173      * @since 3.2
174      */
175     public void removeIndex(IPath indexLocation){
176         IndexManager manager = JavaModelManager.getJavaModelManager().getIndexManager();
177         manager.removeIndexPath(indexLocation);
178     }
179 
180     /**
181      * Schedules the indexing of the given document.
182      * Once the document is ready to be indexed, 
183      * {@link #indexDocument(SearchDocument, IPath) indexDocument(document, indexPath)}
184      * will be called in a different thread than the caller's thread.
185      * <p>
186      * The given index location must represent a path in the file system to a file that
187      * either already exists or is going to be created. If it exists, it must be an index file,
188      * otherwise its data might be overwritten.
189      * </p><p>
190      * When the index is no longer needed, clients should use {@link #removeIndex(IPath) }
191      * to discard it.
192      * </p>
193      * 
194      * @param document the document to index
195      * @param indexLocation the location on the file system of the index
196      */
197     public final void scheduleDocumentIndexing(SearchDocument document, IPath indexLocation) {
198         IPath documentPath = new Path(document.getPath());
199         IWorkspaceRoot root = ResourcesPlugin.getWorkspace().getRoot();
200         Object   file = JavaModel.getTarget(root, documentPath, true);
201         IPath containerPath = documentPath;
202         if (file instanceof IResource) {
203             containerPath = ((IResource)file).getProject().getFullPath();
204         } else if (file == null) {
205             containerPath = documentPath.removeLastSegments(documentPath.segmentCount()-1);
206         }
207         IndexManager manager = JavaModelManager.getJavaModelManager().getIndexManager();
208         // TODO (frederic) should not have to create index manually, should expose API that recreates index instead
209         manager.ensureIndexExists(indexLocation, containerPath);
210         manager.scheduleDocumentIndexing(document, containerPath, indexLocation, this);
211     }
212 
213     /**
214      * Returns the collection of index locations to consider when performing the
215      * given search query in the given scope. The search engine calls this
216      * method before locating matches.
217      * <p>
218      * An index location represents a path in the file system to a file that holds index information. 
219      * </p><p>
220      * Clients are not expected to call this method.
221      * </p>
222      * 
223      * @param query the search pattern to consider
224      * @param scope the given search scope
225      * @return the collection of index paths to consider
226      */
227     public abstract IPath[] selectIndexes(SearchPattern query, IJavaSearchScope scope);
228 }
229
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags