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