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