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