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