1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.maven.index;
20
21 import java.io.File;
22 import java.io.IOException;
23 import java.util.Collection;
24 import java.util.List;
25 import java.util.Map;
26
27 import org.apache.lucene.search.Query;
28 import org.apache.lucene.store.Directory;
29 import org.apache.maven.index.context.ContextMemberProvider;
30 import org.apache.maven.index.context.IndexCreator;
31 import org.apache.maven.index.context.IndexingContext;
32 import org.apache.maven.index.context.UnsupportedExistingLuceneIndexException;
33 import org.apache.maven.index.expr.SearchExpression;
34
35 /**
36 * The Nexus indexer is a statefull facade that maintains state of indexing contexts.
37 * <p>
38 * The following code snippet shows how to register indexing context, which should be done once on the application
39 * startup and Nexus indexer instance should be reused after that.
40 *
41 * <pre>
42 * NexusIndexer indexer;
43 *
44 * IndexingContext context = indexer.addIndexingContext( indexId, // index id (usually the same as repository id)
45 * repositoryId, // repository id
46 * directory, // Lucene directory where index is stored
47 * repositoryDir, // local repository dir or null for remote repo
48 * repositoryUrl, // repository url, used by index updater
49 * indexUpdateUrl, // index update url or null if derived from repositoryUrl
50 * false, false );
51 * </pre>
52 *
53 * An indexing context could be populated using one of {@link #scan(IndexingContext)},
54 * {@link #addArtifactToIndex(ArtifactContext, IndexingContext)} or
55 * {@link #deleteArtifactFromIndex(ArtifactContext, IndexingContext)} methods.
56 * <p>
57 * An {@link org.apache.maven.index.updater.IndexUpdater} could be used to fetch indexes from remote repositories.
58 * These indexers could be created using the Indexer CLI command line tool or
59 * {@link org.apache.maven.index.packer.IndexPacker} API.
60 * <p>
61 * Once index is populated you can perform search queries using field names declared in the {@link ArtifactInfo}:
62 *
63 * <pre>
64 * // run search query
65 * BooleanQuery q = new BooleanQuery.Builder()
66 * .add(indexer.constructQuery(ArtifactInfo.GROUP_ID, term), Occur.SHOULD)
67 * .add(indexer.constructQuery(ArtifactInfo.ARTIFACT_ID, term), Occur.SHOULD)
68 * .add(new PrefixQuery(new Term(ArtifactInfo.SHA1, term)), Occur.SHOULD)
69 * .build();
70 *
71 * FlatSearchRequest request = new FlatSearchRequest(q);
72 * FlatSearchResponse response = indexer.searchFlat(request);
73 * ...
74 * </pre>
75 *
76 * Query could be also constructed using a convenience {@link NexusIndexer#constructQuery(Field, SearchExpression)}
77 * method that handles creation of the wildcard queries. Also see {@link DefaultQueryCreator} for more details on
78 * supported queries.
79 *
80 * @see IndexingContext
81 * @see org.apache.maven.index.updater.IndexUpdater
82 * @see DefaultQueryCreator
83 * @author Jason van Zyl
84 * @author Tamas Cservenak
85 * @author Eugene Kuleshov
86 * @deprecated Use {@link Indexer} instead.
87 */
88 @Deprecated
89 public interface NexusIndexer {
90 /**
91 * Adds an indexing context to Nexus indexer.
92 *
93 * @since 5.1.0
94 */
95 void addIndexingContext(IndexingContext context);
96
97 /**
98 * Adds an indexing context to Nexus indexer.
99 *
100 * @param id the ID of the context.
101 * @param repositoryId the ID of the repository that this context represents.
102 * @param repository the location of the repository.
103 * @param indexDirectory the location of the Lucene indexes.
104 * @param repositoryUrl the location of the remote repository.
105 * @param indexUpdateUrl the alternate location of the remote repository indexes (if they are not in default place).
106 * @param indexers the set of indexers to apply to this context.
107 * @return
108 * @throws IOException in case of some serious IO problem.
109 * @throws UnsupportedExistingLuceneIndexException if a Lucene index already exists where location is specified, but
110 * it has no Nexus descriptor record or it has, but the embedded repoId differs from the repoId
111 * specified from the supplied one.
112 * @throws IllegalArgumentException in case the supplied list of IndexCreators are not satisfiable
113 * @deprecated Use {@link Indexer} instead.
114 */
115 @Deprecated
116 IndexingContext addIndexingContext(
117 String id,
118 String repositoryId,
119 File repository,
120 File indexDirectory,
121 String repositoryUrl,
122 String indexUpdateUrl,
123 List<? extends IndexCreator> indexers)
124 throws IOException, UnsupportedExistingLuceneIndexException;
125
126 /**
127 * Adds an indexing context to Nexus indexer. It "forces" this operation, thus no
128 * UnsupportedExistingLuceneIndexException is thrown. If it founds an existing lucene index, it will simply
129 * stomp-over and rewrite (or add) the Nexus index descriptor.
130 *
131 * @param id the ID of the context.
132 * @param repositoryId the ID of the repository that this context represents.
133 * @param repository the location of the repository.
134 * @param indexDirectory the location of the Lucene indexes.
135 * @param repositoryUrl the location of the remote repository.
136 * @param indexUpdateUrl the alternate location of the remote repository indexes (if they are not in default place).
137 * @param indexers the set of indexers to apply to this context.
138 * @return
139 * @throws IOException in case of some serious IO problem.
140 * @throws IllegalArgumentException in case the supplied list of IndexCreators are not satisfiable
141 * @deprecated Use {@link Indexer} instead.
142 */
143 @Deprecated
144 IndexingContext addIndexingContextForced(
145 String id,
146 String repositoryId,
147 File repository,
148 File indexDirectory,
149 String repositoryUrl,
150 String indexUpdateUrl,
151 List<? extends IndexCreator> indexers)
152 throws IOException;
153
154 /**
155 * Adds an indexing context to Nexus indexer.
156 *
157 * @param id the ID of the context.
158 * @param repositoryId the ID of the repository that this context represents.
159 * @param repository the location of the repository.
160 * @param directory the location of the Lucene indexes.
161 * @param repositoryUrl the location of the remote repository.
162 * @param indexUpdateUrl the alternate location of the remote repository indexes (if they are not in default place).
163 * @param indexers the set of indexers to apply to this context.
164 * @return
165 * @throws IOException in case of some serious IO problem.
166 * @throws UnsupportedExistingLuceneIndexException if a Lucene index already exists where location is specified, but
167 * it has no Nexus descriptor record or it has, but the embedded repoId differs from the repoId
168 * specified from the supplied one.
169 * @throws IllegalArgumentException in case the supplied list of IndexCreators are not satisfiable
170 * @deprecated Use {@link Indexer} instead.
171 */
172 @Deprecated
173 IndexingContext addIndexingContext(
174 String id,
175 String repositoryId,
176 File repository,
177 Directory directory,
178 String repositoryUrl,
179 String indexUpdateUrl,
180 List<? extends IndexCreator> indexers)
181 throws IOException, UnsupportedExistingLuceneIndexException;
182
183 /**
184 * Adds an indexing context to Nexus indexer. It "forces" this operation, thus no
185 * UnsupportedExistingLuceneIndexException is thrown. If it founds an existing lucene index, it will simply
186 * stomp-over and rewrite (or add) the Nexus index descriptor.
187 *
188 * @param id the ID of the context.
189 * @param repositoryId the ID of the repository that this context represents.
190 * @param repository the location of the repository.
191 * @param directory the location of the Lucene indexes.
192 * @param repositoryUrl the location of the remote repository.
193 * @param indexUpdateUrl the alternate location of the remote repository indexes (if they are not in default place).
194 * @param indexers the set of indexers to apply to this context.
195 * @return
196 * @throws IOException in case of some serious IO problem.
197 * @throws IllegalArgumentException in case the supplied list of IndexCreators are not satisfiable
198 * @deprecated Use {@link Indexer} instead.
199 */
200 @Deprecated
201 IndexingContext addIndexingContextForced(
202 String id,
203 String repositoryId,
204 File repository,
205 Directory directory,
206 String repositoryUrl,
207 String indexUpdateUrl,
208 List<? extends IndexCreator> indexers)
209 throws IOException;
210
211 @Deprecated
212 IndexingContext addMergedIndexingContext(
213 String id,
214 String repositoryId,
215 File repository,
216 File indexDirectory,
217 boolean searchable,
218 Collection<IndexingContext> contexts)
219 throws IOException;
220
221 @Deprecated
222 IndexingContext addMergedIndexingContext(
223 String id,
224 String repositoryId,
225 File repository,
226 File indexDirectory,
227 boolean searchable,
228 ContextMemberProvider membersProvider)
229 throws IOException;
230
231 @Deprecated
232 IndexingContext addMergedIndexingContext(
233 String id,
234 String repositoryId,
235 File repository,
236 Directory indexDirectory,
237 boolean searchable,
238 Collection<IndexingContext> contexts)
239 throws IOException;
240
241 @Deprecated
242 IndexingContext addMergedIndexingContext(
243 String id,
244 String repositoryId,
245 File repository,
246 Directory indexDirectory,
247 boolean searchable,
248 ContextMemberProvider membersProvider)
249 throws IOException;
250
251 /**
252 * Removes the indexing context from Nexus indexer, closes it and deletes (if specified) the index files.
253 *
254 * @param context
255 * @param deleteFiles
256 * @throws IOException
257 * @deprecated Use {@link Indexer} instead.
258 */
259 @Deprecated
260 void removeIndexingContext(IndexingContext context, boolean deleteFiles) throws IOException;
261
262 /**
263 * Returns the map of indexing contexts keyed by their ID.
264 *
265 * @deprecated Use {@link Indexer} instead.
266 */
267 @Deprecated
268 Map<String, IndexingContext> getIndexingContexts();
269
270 // ----------------------------------------------------------------------------
271 // Scanning
272 // ----------------------------------------------------------------------------
273 /**
274 * Performs full scan (reindex) for the local repository belonging to supplied context.
275 *
276 * @param context
277 * @deprecated Use {@link Indexer} instead.
278 */
279 @Deprecated
280 void scan(IndexingContext context) throws IOException;
281
282 /**
283 * Performs full scan (reindex) for the local repository belonging to supplied context. ArtifactListener is used
284 * during that process.
285 *
286 * @param context
287 * @param listener
288 * @deprecated Use {@link Indexer} instead.
289 */
290 @Deprecated
291 void scan(IndexingContext context, ArtifactScanningListener listener) throws IOException;
292
293 /**
294 * Performs optionally incremental scan (reindex/full reindex) for the local repository belonging to the supplied
295 * context.
296 *
297 * @param context
298 * @param update if incremental reindex wanted, set true, otherwise false and full reindex will happen
299 * @deprecated Use {@link Indexer} instead.
300 */
301 @Deprecated
302 void scan(IndexingContext context, boolean update) throws IOException;
303
304 /**
305 * Performs optionally incremental scan (reindex) for the local repository, with listener.
306 *
307 * @param context
308 * @param listener
309 * @param update if incremental reindex wanted, set true, otherwise false and full reindex will happen
310 * @deprecated Use {@link Indexer} instead.
311 */
312 @Deprecated
313 void scan(IndexingContext context, ArtifactScanningListener listener, boolean update) throws IOException;
314
315 /**
316 * Performs optionally incremental scan (reindex) for the local repository.
317 *
318 * @param context
319 * @param fromPath a path segment if you want "sub-path" reindexing (ie. reindex just a given subfolder of a
320 * repository, ot whole repository from root.
321 * @param listener
322 * @param update if incremental reindex wanted, set true, otherwise false and full reindex will happen
323 * @deprecated Use {@link Indexer} instead.
324 */
325 @Deprecated
326 void scan(IndexingContext context, String fromPath, ArtifactScanningListener listener, boolean update)
327 throws IOException;
328
329 @Deprecated
330 void artifactDiscovered(ArtifactContext ac, IndexingContext context) throws IOException;
331
332 // ----------------------------------------------------------------------------
333 // Modifying
334 // ----------------------------------------------------------------------------
335
336 @Deprecated
337 void addArtifactToIndex(ArtifactContext ac, IndexingContext context) throws IOException;
338
339 @Deprecated
340 void addArtifactsToIndex(Collection<ArtifactContext> acs, IndexingContext context) throws IOException;
341
342 @Deprecated
343 void deleteArtifactFromIndex(ArtifactContext ac, IndexingContext context) throws IOException;
344
345 @Deprecated
346 void deleteArtifactsFromIndex(Collection<ArtifactContext> acs, IndexingContext context) throws IOException;
347
348 // ----------------------------------------------------------------------------
349 // Searching
350 // ----------------------------------------------------------------------------
351
352 /**
353 * Searches according the request parameters.
354 *
355 * @param request
356 * @return
357 * @throws IOException
358 * @deprecated Use {@link Indexer} instead.
359 */
360 @Deprecated
361 FlatSearchResponse searchFlat(FlatSearchRequest request) throws IOException;
362
363 /**
364 * Searches according to request parameters.
365 *
366 * @param request
367 * @return
368 * @throws IOException
369 * @deprecated Use {@link Indexer} instead.
370 */
371 @Deprecated
372 IteratorSearchResponse searchIterator(IteratorSearchRequest request) throws IOException;
373
374 /**
375 * Searches according the request parameters.
376 *
377 * @param request
378 * @return
379 * @throws IOException
380 * @deprecated Use {@link Indexer} instead.
381 */
382 @Deprecated
383 GroupedSearchResponse searchGrouped(GroupedSearchRequest request) throws IOException;
384
385 // ----------------------------------------------------------------------------
386 // Query construction
387 // ----------------------------------------------------------------------------
388
389 /**
390 * Helper method to construct Lucene query for given field without need for knowledge (on caller side) HOW is a
391 * field indexed, and WHAT query is needed to achieve that.
392 *
393 * @param field
394 * @param query
395 * @param type
396 * @return
397 * @deprecated Use {@link Indexer} instead.
398 */
399 @Deprecated
400 Query constructQuery(Field field, String query, SearchType type) throws IllegalArgumentException;
401
402 /**
403 * Helper method to construct Lucene query for given field without need for knowledge (on caller side) HOW is a
404 * field indexed, and WHAT query is needed to achieve that.
405 *
406 * @param field
407 * @param expression
408 * @return
409 * @deprecated Use {@link Indexer} instead.
410 */
411 @Deprecated
412 Query constructQuery(Field field, SearchExpression expression) throws IllegalArgumentException;
413
414 // ----------------------------------------------------------------------------
415 // Identification
416 // Since 4.0: Indexer does not make any assumptions, it is caller call to decide what to do with multiple results
417 // ----------------------------------------------------------------------------
418
419 @Deprecated
420 Collection<ArtifactInfo> identify(Field field, String query) throws IllegalArgumentException, IOException;
421
422 @Deprecated
423 Collection<ArtifactInfo> identify(File artifact) throws IOException;
424
425 @Deprecated
426 Collection<ArtifactInfo> identify(File artifact, Collection<IndexingContext> contexts) throws IOException;
427
428 @Deprecated
429 Collection<ArtifactInfo> identify(Query query) throws IOException;
430
431 @Deprecated
432 Collection<ArtifactInfo> identify(Query query, Collection<IndexingContext> contexts) throws IOException;
433 }