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
27 import org.apache.lucene.search.Query;
28 import org.apache.maven.index.context.ContextMemberProvider;
29 import org.apache.maven.index.context.ExistingLuceneIndexMismatchException;
30 import org.apache.maven.index.context.IndexCreator;
31 import org.apache.maven.index.context.IndexingContext;
32 import org.apache.maven.index.expr.SearchExpression;
33
34 /**
35 * Indexer component. It is the main component of Maven Indexer, offering {@link IndexingContext} creation and close
36 * methods, context maintenance (scan, add, remove) and search methods. Supersedes the {@link NexusIndexer} component,
37 * making it less cludged, and focusing on main use cases. This component does not hold any reference to contexts
38 * it creates or uses, and caller of every method (except the createIndexingContext naturally) is obliged to
39 * explicitly supply {@link IndexingContext} to work with (perform searches or such).
40 *
41 * @author cstamas
42 * @since 5.1.0
43 */
44 public interface Indexer
45 {
46 /**
47 * Creates an indexing context.
48 *
49 * @param id the ID of the context.
50 * @param repositoryId the ID of the repository that this context represents. You might have several contexts
51 * indexing same repository ID, but on separate locations.
52 * @param repository the location of the repository on FS.
53 * @param indexDirectory the location of the Lucene indexes on FS.
54 * @param repositoryUrl the location of the remote repository or {@code null} if this indexing context does not need
55 * remote updates (is not a proxy).
56 * @param indexUpdateUrl the alternate location of the remote repository indexes (if they are not in default place)
57 * or {@code null} if defaults are applicable.
58 * @param searchable if context should be searched in non-targeted mode.
59 * @param reclaim if indexDirectory is known to contain (or should contain) valid Maven Indexer lucene index, and no
60 * checks needed to be performed, or, if we want to "stomp" over existing index (unsafe to do!).
61 * @param indexers the set of indexers to apply to this context.
62 * @return the context created.
63 * @throws IOException in case of some serious IO problem.
64 * @throws ExistingLuceneIndexMismatchException if a Lucene index already exists where location is specified, but
65 * it has no Nexus descriptor record or it has, but the embedded repoId differs from the repoId
66 * specified from the supplied one. Never thrown if {@code reclaim} is {@code true}, as in that case, if
67 * Lucene index exists but any of those criteria above are not met, the existing index is overwritten,
68 * and equipped with proper descriptor silently.
69 * @throws IllegalArgumentException in case the supplied list of IndexCreators are having non-satisfiable
70 * dependencies.
71 */
72 IndexingContext createIndexingContext( String id, String repositoryId, File repository, File indexDirectory,
73 String repositoryUrl, String indexUpdateUrl, boolean searchable,
74 boolean reclaim, List<? extends IndexCreator> indexers )
75 throws IOException, ExistingLuceneIndexMismatchException, IllegalArgumentException;
76
77 /**
78 * Creates a merged indexing context.
79 *
80 * @param id the ID of the context.
81 * @param repositoryId the ID of the repository that this context represents. You might have several contexts
82 * indexing same repository ID, but on separate locations.
83 * @param repository the location of the repository on FS.
84 * @param indexDirectory the location of the Lucene indexes on FS.
85 * @param searchable if context should be searched in non-targeted mode.
86 * @param membersProvider the {@link ContextMemberProvider}, never null.
87 * @return the context created.
88 * @throws IOException in case of some serious IO problem.
89 */
90 IndexingContext createMergedIndexingContext( String id, String repositoryId, File repository, File indexDirectory,
91 boolean searchable, ContextMemberProvider membersProvider )
92 throws IOException;
93
94 /**
95 * Closes the indexing context: closes it and deletes (if specified) the index files.
96 *
97 * @param context the one needed to be closed, never {@code null}.
98 * @param deleteFiles {@code true} if all indexer related files (including Lucene index!) needs to be deleted,
99 * {@code false} otherwise.
100 * @throws IOException
101 */
102 void closeIndexingContext( IndexingContext context, boolean deleteFiles )
103 throws IOException;
104
105 // ----------------------------------------------------------------------------
106 // Modifying
107 // ----------------------------------------------------------------------------
108
109 /**
110 * Adds the passed in artifact contexts to passed in indexing context.
111 *
112 * @param ac
113 * @param context
114 * @throws IOException
115 */
116 void addArtifactToIndex( ArtifactContext ac, IndexingContext context )
117 throws IOException;
118
119 /**
120 * Adds the passed in artifact contexts to passed in indexing context.
121 *
122 * @param acs
123 * @param context
124 * @throws IOException
125 */
126 void addArtifactsToIndex( Collection<ArtifactContext> acs, IndexingContext context )
127 throws IOException;
128
129 /**
130 * Removes the passed in artifacts contexts from passed in indexing context.
131 *
132 * @param acs
133 * @param context
134 * @throws IOException
135 */
136 void deleteArtifactsFromIndex( Collection<ArtifactContext> acs, IndexingContext context )
137 throws IOException;
138
139 // ----------------------------------------------------------------------------
140 // Searching
141 // ----------------------------------------------------------------------------
142
143 /**
144 * Searches according the request parameters.
145 *
146 * @param request
147 * @return search response
148 * @throws IOException
149 */
150 FlatSearchResponse searchFlat( FlatSearchRequest request )
151 throws IOException;
152
153 /**
154 * Searches according to request parameters.
155 *
156 * @param request
157 * @return search response
158 * @throws IOException
159 */
160 IteratorSearchResponse searchIterator( IteratorSearchRequest request )
161 throws IOException;
162
163 /**
164 * Searches according the request parameters.
165 *
166 * @param request
167 * @return search response
168 * @throws IOException
169 */
170 GroupedSearchResponse searchGrouped( GroupedSearchRequest request )
171 throws IOException;
172
173 // ----------------------------------------------------------------------------
174 // Identify
175 // ----------------------------------------------------------------------------
176
177 /**
178 * Performs an "identity" search. Passed in {@link File} will have SHA1 hash calculated, and an
179 * {@link #identify(Query, Collection)} method will be invoked searching with calculated hash the {@link MAVEN#SHA1}
180 * field. This is just a shorthand method, as these calls are simply calculating hex encoded SHA1 of the file, and
181 * invoking the {@link #constructQuery(Field, SearchExpression)} and {@link #identify(Query, Collection)} methods.
182 *
183 * @param artifact the file
184 * @param contexts in which to perform the action
185 * @return collection of identified matches.
186 * @throws IOException
187 */
188 Collection<ArtifactInfo> identify( File artifact, Collection<IndexingContext> contexts )
189 throws IOException;
190
191 /**
192 * Performs an "identity" search. Those are usually simple key-value queries, involving "unique" fields like
193 * {@link MAVEN#SHA1} or such.
194 *
195 * @param query
196 * @param contexts
197 * @return collection of identified matches.
198 * @throws IOException
199 */
200 Collection<ArtifactInfo> identify( Query query, Collection<IndexingContext> contexts )
201 throws IOException;
202
203 // ----------------------------------------------------------------------------
204 // Query construction
205 // ----------------------------------------------------------------------------
206
207 /**
208 * Helper method to construct Lucene query for given field without need for knowledge (on caller side) HOW is a
209 * field indexed, and WHAT query is needed to achieve that search.
210 *
211 * @param field
212 * @param expression
213 * @return the query to be used for search.
214 * @see SearchExpression
215 * @see org.apache.maven.index.expr.UserInputSearchExpression
216 * @see org.apache.maven.index.expr.SourcedSearchExpression
217 * @throws IllegalArgumentException
218 */
219 Query constructQuery( Field field, SearchExpression expression )
220 throws IllegalArgumentException;
221
222 /**
223 * Helper method to construct Lucene query for given field without need for knowledge (on caller side) HOW is a
224 * field indexed, and WHAT query is needed to achieve that search.
225 *
226 * @param field
227 * @param expression
228 * @param searchType
229 * @return
230 * @throws IllegalArgumentException
231 */
232 Query constructQuery( Field field, String expression, SearchType searchType )
233 throws IllegalArgumentException;
234 }