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