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