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 }