1 package org.apache.archiva.metadata.repository; 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 org.apache.archiva.metadata.QueryParameter; 23 import org.apache.archiva.metadata.model.ArtifactMetadata; 24 import org.apache.archiva.metadata.model.MetadataFacet; 25 import org.apache.archiva.metadata.model.ProjectMetadata; 26 import org.apache.archiva.metadata.model.ProjectVersionMetadata; 27 import org.apache.archiva.metadata.model.ProjectVersionReference; 28 29 import javax.annotation.Nullable; 30 import javax.annotation.ParametersAreNonnullByDefault; 31 import java.time.ZonedDateTime; 32 import java.util.List; 33 import java.util.stream.Stream; 34 35 /** 36 * A Metadata repository provides information about artifact metadata. It does not provide the artifact data itself. 37 * It may be possible to use the same backend for metadata and storage, but this depends on the backends and they are 38 * provided by different APIs. 39 * <p> 40 * The motivation for this API is to provide fast access to the repository metadata and fulltext search. Also dependencies 41 * are stored in this repository. 42 * <p> 43 * The methods here do not update the artifacts itself. They are only updating the data in the metadata repository. 44 * That means, if you want to update some artifact, you should make sure to update the artifact itself and the metadata 45 * repository (either directly or by repository scanning). 46 * <p> 47 * Currently we are providing JCR, File based and Cassandra as backend for the metadata. 48 * <p> 49 * The metadata repository uses sessions for accessing the data. Please make sure to always close the sessions after using it. 50 * Best idiom for using the sessions: 51 * <code> 52 * try(RepositorySession session = sessionFactory.createSession() { 53 * // do your stuff 54 * } 55 * </code> 56 * <p> 57 * It is implementation dependent, if the sessions are really used by the backend. E.g. the file based implementation ignores 58 * the sessions completely. 59 * <p> 60 * Sessions should be closed immediately after usage. If it is expensive to open a session for a given backend. The backend 61 * should provide a session pool if possible. There are methods for refreshing a session if needed. 62 * <p> 63 * You should avoid stacking sessions, which means, you should not create a new session in the same thread, when a session is opened already. 64 * <p> 65 * Some backend implementations (JCR) update the metadata in the background, that means update of the metadata is not reflected 66 * immediately. 67 * <p> 68 * The base metadata coordinates are: 69 * <ul> 70 * <li>Repository ID: The identifier of the repository, where the artifact resides</li> 71 * <li>Namespace: This is a hierarchical coordinate for locating the projects. E.g. this corresponds to the groupId in maven. </li> 72 * <li>Project ID: The project itself</li> 73 * <li>Version: Each project may have different versions.</li> 74 * <li>Artifact: Artifacts correspond to files / blob data. Each artifact has additional metadata, like name, version, modification time, ...</li> 75 * </ul> 76 * <p> 77 * As the repository connects to some backend either locally or remote, the access to the repository may fail. The methods capsule the 78 * backend errors into <code>{@link MetadataRepositoryException}</code>. 79 * <p> 80 * Facets are the way to provide additional metadata that is not part of the base API. It depends on the repository type (e.g. Maven, NPM, 81 * not the metadata backend) what facets are stored in addition to the standard metadata. 82 * Facets have a specific facet ID that represents the schema for the data stored. For creating specific objects for a given 83 * facet id the <code>{@link org.apache.archiva.metadata.model.MetadataFacetFactory}</code> is used. 84 * For each facet id there may exist multiple facet instances on each level. Facet instances are identified by their name, which may be 85 * a hierarchical path. 86 * The data in each facet instance is stored in properties (key-value pairs). The properties are converted into / from the specific 87 * facet object. 88 * <p> 89 * Facets can be stored on repository, project, version and artifact level. 90 * <p> 91 * For retrieving artifacts there are methods that return lists and streaming based methods. Some implementations (e.g. JCR) use 92 * lazy loading for the retrieved objects. So the streaming methods may be faster and use less memory than the list based methods. 93 * But for some backends there is no difference. 94 */ 95 @SuppressWarnings( "NullableProblems" ) 96 @ParametersAreNonnullByDefault 97 public interface MetadataRepository 98 { 99 100 101 /** 102 * Update metadata for a particular project in the metadata repository, or create it, if it does not already exist. 103 * 104 * @param session The session used for updating. 105 * @param repositoryId the repository the project is in 106 * @param project the project metadata to create or update 107 * @throws MetadataRepositoryException if the update fails 108 */ 109 void updateProject( RepositorySession session, String repositoryId, ProjectMetadata project ) 110 throws MetadataRepositoryException; 111 112 /** 113 * Update the metadata of a given artifact. If the artifact, namespace, version, project does not exist in the repository it will be created. 114 * 115 * @param session The repository session 116 * @param repositoryId The repository id 117 * @param namespace The namespace ('.' separated) 118 * @param projectId The project id 119 * @param projectVersion The project version 120 * @param artifactMeta Information about the artifact itself. 121 * @throws MetadataRepositoryException if something goes wrong during update. 122 */ 123 void updateArtifact( RepositorySession session, String repositoryId, 124 String namespace, String projectId, String projectVersion, 125 ArtifactMetadata artifactMeta ) 126 throws MetadataRepositoryException; 127 128 /** 129 * Updates the metadata for a specific version of a given project. If the namespace, project, version does not exist, 130 * it will be created. 131 * 132 * @param session The repository session 133 * @param repositoryId The repository id 134 * @param namespace The namespace ('.' separated) 135 * @param projectId The project id 136 * @param versionMetadata The metadata for the version 137 * @throws MetadataRepositoryException if something goes wrong during update 138 */ 139 void updateProjectVersion( RepositorySession session, String repositoryId, 140 String namespace, String projectId, 141 ProjectVersionMetadata versionMetadata ) 142 throws MetadataRepositoryException; 143 144 /** 145 * Create the namespace in the repository, if it does not exist. 146 * Namespaces do not have specific metadata attached. 147 * 148 * @param session The repository session 149 * @param repositoryId The repository id 150 * @param namespace The namespace ('.' separated) 151 * @throws MetadataRepositoryException if something goes wrong during update 152 */ 153 void updateNamespace( RepositorySession session, String repositoryId, String namespace ) 154 throws MetadataRepositoryException; 155 156 /** 157 * Return the facet names stored for the given facet id on the repository level. 158 * 159 * @param session The repository session 160 * @param repositoryId The repository id 161 * @param facetId The facet id 162 * @return The list of facet names, or an empty list, if there are no facets stored on this repository for the given facet id. 163 * @throws MetadataRepositoryException if something goes wrong 164 */ 165 List<String> getMetadataFacets( RepositorySession session, String repositoryId, String facetId ) 166 throws MetadataRepositoryException; 167 168 169 /** 170 * The same as {@link #getMetadataFacetStream(RepositorySession, String, Class, QueryParameter)} 171 * but uses default query parameters. 172 * <p> 173 * There is no limitation of the number of result objects returned, but implementations may have a hard upper bound for 174 * the number of results. 175 * 176 * @param session The repository session. 177 * @param repositoryId The repository id. 178 * @param facetClazz The facet class 179 * @param <T> The facet type 180 * @return A stream of facet objects, or a empty stream if no facet was found. 181 * @throws MetadataRepositoryException if the facet retrieval fails. 182 * @since 3.0 183 */ 184 <T extends MetadataFacet> Stream<T> getMetadataFacetStream( RepositorySession session, 185 String repositoryId, Class<T> facetClazz ) 186 throws MetadataRepositoryException; 187 188 /** 189 * Returns a stream of MetadataFacet elements that match the given facet class. 190 * Implementations should order the resulting stream by facet name. 191 * 192 * @param session The repository session 193 * @param repositoryId The repository id 194 * @param facetClazz The class of the facet 195 * @param <T> The facet type 196 * @return A stream of facet objects, or a empty stream if no facet was found. 197 * @throws MetadataRepositoryException if the facet retrieval fails 198 * @since 3.0 199 */ 200 <T extends MetadataFacet> Stream<T> getMetadataFacetStream( RepositorySession session, 201 String repositoryId, Class<T> facetClazz, 202 QueryParameter queryParameter ) 203 throws MetadataRepositoryException; 204 205 /** 206 * Returns true, if there is facet data stored for the given facet id on the repository on repository level. The facet data itself 207 * may be empty. It's just checking if there is an object stored for the given facet id. 208 * 209 * @param session The repository session 210 * @param repositoryId The repository id 211 * @param facetId The facet id 212 * @return true if there is data stored this facetId on repository level. 213 * @throws MetadataRepositoryException if something goes wrong 214 * @since 1.4-M4 215 */ 216 boolean hasMetadataFacet( RepositorySession session, String repositoryId, String facetId ) 217 throws MetadataRepositoryException; 218 219 /** 220 * Returns the facet data stored on the repository level. The facet instance is identified by the facet id and the 221 * facet name. The returned object is a instance created by using <code>{@link org.apache.archiva.metadata.model.MetadataFacetFactory}</code>. 222 * 223 * @param session The repository session 224 * @param repositoryId The repository id 225 * @param facetId The facet id 226 * @param name The attribute name 227 * @return The facet values 228 * @throws MetadataRepositoryException if something goes wrong. 229 */ 230 MetadataFacet getMetadataFacet( RepositorySession session, String repositoryId, String facetId, 231 String name ) 232 throws MetadataRepositoryException; 233 234 /** 235 * Returns the facet instance for the given class, which is stored on repository level for the given name. 236 * If the given name does not point to a instance that can be represented by this class, <code>null</code> will be returned. 237 * If the facet is not found the method returns <code>null</code>. 238 * 239 * @param session The repository session 240 * @param repositoryId The id of the repository 241 * @param clazz The facet object class 242 * @param name The name of the facet (name or path) 243 * @param <T> The type of the facet object 244 * @return The facet instance, if it exists. 245 * @throws MetadataRepositoryException if the data cannot be retrieved from the backend 246 * @since 3.0 247 */ 248 <T extends MetadataFacet> T getMetadataFacet( RepositorySession session, String repositoryId, 249 Class<T> clazz, String name ) 250 throws MetadataRepositoryException; 251 252 /** 253 * Adds a facet to the repository level. 254 * 255 * @param session The repository session 256 * @param repositoryId The id of the repository 257 * @param metadataFacet The facet to add 258 * @throws MetadataRepositoryException if the facet cannot be stored. 259 */ 260 void addMetadataFacet( RepositorySession session, String repositoryId, 261 MetadataFacet metadataFacet ) 262 throws MetadataRepositoryException; 263 264 /** 265 * Removes all facets with the given facetId from the repository level. 266 * 267 * @param session The repository session 268 * @param repositoryId The id of the repository 269 * @param facetId The facet id 270 * @throws MetadataRepositoryException if the removal fails 271 */ 272 void removeMetadataFacets( RepositorySession session, String repositoryId, String facetId ) 273 throws MetadataRepositoryException; 274 275 /** 276 * Removes the given facet from the repository level, if it exists. 277 * 278 * @param session The repository session 279 * @param repositoryId The id of the repository 280 * @param facetId The facet id 281 * @param name The facet name or path 282 */ 283 void removeMetadataFacet( RepositorySession session, String repositoryId, String facetId, String name ) 284 throws MetadataRepositoryException; 285 286 287 /** 288 * Is the same as {@link #getArtifactsByDateRange(RepositorySession, String, ZonedDateTime, ZonedDateTime, QueryParameter)}, but 289 * uses default query parameters. 290 */ 291 List<ArtifactMetadata> getArtifactsByDateRange( RepositorySession session, String repositoryId, 292 @Nullable ZonedDateTime startTime, @Nullable ZonedDateTime endTime ) 293 throws MetadataRepositoryException; 294 295 /** 296 * Searches for artifacts where the 'whenGathered' attribute value is between the given start and end time. 297 * If start or end time or both are <code>null</code>, the time range for the search is unbounded for this parameter. 298 * 299 * @param session The repository session 300 * @param repositoryId The repository id 301 * @param startTime The start time/date as zoned date, can be <code>null</code> 302 * @param endTime The end time/date as zoned date, can be <code>null</code> 303 * @param queryParameter Additional parameters for the query that affect ordering and returned results 304 * @return The list of metadata objects for the found instances. 305 * @throws MetadataRepositoryException if the query fails. 306 * @since 3.0 307 */ 308 List<ArtifactMetadata> getArtifactsByDateRange( RepositorySession session, String repositoryId, 309 @Nullable ZonedDateTime startTime, @Nullable ZonedDateTime endTime, 310 QueryParameter queryParameter ) 311 throws MetadataRepositoryException; 312 313 314 /** 315 * Returns all the artifacts who's 'whenGathered' attribute value is inside the given time range (inclusive) as stream of objects. 316 * <p> 317 * Implementations should return a stream of sorted objects. The objects should be sorted by the 'whenGathered' date in ascending order. 318 * 319 * @param session The repository session 320 * @param repositoryId The repository id 321 * @param startTime The start time, can be <code>null</code> 322 * @param endTime The end time, can be <code>null</code> 323 * @return A stream of artifact metadata objects, or a empty stream if no artifact was found. 324 * @throws MetadataRepositoryException if the artifact retrieval fails. 325 * @since 3.0 326 */ 327 Stream<ArtifactMetadata> getArtifactByDateRangeStream( RepositorySession session, String repositoryId, 328 @Nullable ZonedDateTime startTime, @Nullable ZonedDateTime endTime ) 329 throws MetadataRepositoryException; 330 331 /** 332 * Returns all the artifacts who's 'whenGathered' attribute value is inside the given time range (inclusive) as stream of objects. 333 * <p> 334 * If no sort attributes are given by the queryParameter, the result is sorted by the 'whenGathered' date. 335 * 336 * @param session The repository session 337 * @param repositoryId The repository id 338 * @param startTime The start time, can be <code>null</code> 339 * @param endTime The end time, can be <code>null</code> 340 * @param queryParameter Additional parameters for the query that affect ordering and number of returned results. 341 * @return A stream of artifact metadata objects. 342 * @throws MetadataRepositoryException if the artifact retrieval fails. 343 * @since 3.0 344 */ 345 Stream<ArtifactMetadata> getArtifactByDateRangeStream( RepositorySession session, String repositoryId, 346 @Nullable ZonedDateTime startTime, @Nullable ZonedDateTime endTime, 347 QueryParameter queryParameter ) 348 throws MetadataRepositoryException; 349 350 351 /** 352 * Returns the artifacts that match the given checksum. All checksum types are searched. 353 * 354 * @param session The repository session 355 * @param repositoryId The repository id 356 * @param checksum The checksum as string of numbers 357 * @return The list of artifacts that match the given checksum. 358 * @throws MetadataRepositoryException if the artifact retrieval fails 359 */ 360 List<ArtifactMetadata> getArtifactsByChecksum( RepositorySession session, String repositoryId, String checksum ) 361 throws MetadataRepositoryException; 362 363 /** 364 * Get artifacts with a project version metadata key that matches the passed value. 365 * 366 * @param session The repository session 367 * @param key The attribute key to search 368 * @param value The attribute value used for search 369 * @param repositoryId can be <code>null</code>, meaning search in all repositories 370 * @return a list of artifacts. A empty list, if no artifact was found. 371 * @throws MetadataRepositoryException if the artifact retrieval fails. 372 */ 373 List<ArtifactMetadata> getArtifactsByProjectVersionFacet( RepositorySession session, String key, String value, 374 @Nullable String repositoryId ) 375 throws MetadataRepositoryException; 376 377 /** 378 * Get artifacts with an artifact metadata key that matches the passed value. 379 * <code>key</code> ist the string representation of one of the metadata attributes. Only artifacts are returned where 380 * the attribute value matches exactly the given search value. 381 * 382 * @param session The repository session. 383 * @param key The string representation of the artifact metadata attribute. 384 * @param value The search value. 385 * @param repositoryId can be <code>null</code>, meaning search in all repositories 386 * @return a list of artifact objects for each artifact that matches the search string 387 * @throws MetadataRepositoryException if the artifact retrieval fails. 388 */ 389 List<ArtifactMetadata> getArtifactsByAttribute( RepositorySession session, String key, String value, @Nullable String repositoryId ) 390 throws MetadataRepositoryException; 391 392 /** 393 * Get artifacts with a attribute on project version level that matches the passed value. 394 * Possible keys are 'scm.url', 'org.name', 'url', 'mailingList.0.name', 'license.0.name',... 395 * 396 * @param session the repository session. 397 * @param key The name of the attribute (may be nested like scm.url, mailinglist.0.name) 398 * @param value The value to search for 399 * @param repositoryId can be <code>null</code>, which means to search in all repositories 400 * @return a list of artifacts or a empty list, if no artifact was found 401 * @throws MetadataRepositoryException if the artifact retrieval fails 402 */ 403 List<ArtifactMetadata> getArtifactsByProjectVersionAttribute( RepositorySession session, String key, String value, @Nullable String repositoryId ) 404 throws MetadataRepositoryException; 405 406 /** 407 * Removes the data for the artifact with the given coordinates from the metadata repository. This will not remove the artifact itself 408 * from the storage. It will only remove the metadata. 409 * 410 * @param session The repository session 411 * @param repositoryId The repository id 412 * @param namespace The namespace of the project 413 * @param project The project name 414 * @param version The project version 415 * @param id The artifact id 416 * @throws MetadataRepositoryException if the artifact retrieval fails, or if the artifact cannot be found. 417 */ 418 void removeArtifact( RepositorySession session, String repositoryId, String namespace, String project, String version, String id ) 419 throws MetadataRepositoryException; 420 421 /** 422 * Remove timestamped version of artifact. This removes a snapshot artifact by giving the artifact metadata 423 * and the base version of the project. 424 * 425 * @param session The repository session 426 * @param artifactMetadata the artifactMetadata with the timestamped version (2.0-20120618.214135-2) 427 * @param baseVersion the base version of the snapshot (2.0-SNAPSHOT) 428 * @throws MetadataRepositoryException if the removal fails. 429 * @since 1.4-M3 430 */ 431 void removeTimestampedArtifact( RepositorySession session, ArtifactMetadata artifactMetadata, String baseVersion ) 432 throws MetadataRepositoryException; 433 434 /** 435 * FIXME need a unit test!!! 436 * Removes the {@link MetadataFacet} of the given artifact. 437 * 438 * @param session The repository session 439 * @param repositoryId The repository id. 440 * @param namespace The namespace 441 * @param project The project name 442 * @param version The project version 443 * @param metadataFacet The facet data 444 * @throws MetadataRepositoryException if the removal failed 445 * @since 1.4-M3 446 */ 447 void removeFacetFromArtifact( RepositorySession session, String repositoryId, String namespace, String project, String version, 448 MetadataFacet metadataFacet ) 449 throws MetadataRepositoryException; 450 451 /** 452 * Deletes all metadata of the given repository. This includes artifact metadata and all associated metadata facets. 453 * 454 * @param session The repository session 455 * @param repositoryId the repository to delete 456 * @throws MetadataRepositoryException if the removal failed 457 */ 458 void removeRepository( RepositorySession session, String repositoryId ) 459 throws MetadataRepositoryException; 460 461 /** 462 * Removes the given namespace and its contents from the metadata repository. 463 * 464 * @param session The repository session 465 * @param repositoryId The repository id 466 * @param namespace The namespace '.' separated ( it's the groupId for maven ) 467 * @throws MetadataRepositoryException if the removal failed 468 * @since 1.4-M3 469 */ 470 void removeNamespace( RepositorySession session, String repositoryId, String namespace ) 471 throws MetadataRepositoryException; 472 473 /** 474 * Returns the metadata for all artifacts of the given repository. 475 * 476 * @param session The repository session 477 * @param repositoryId The repository id 478 * @return a list of artifact metadata objects. A empty list if no artifacts where found. 479 * @throws MetadataRepositoryException if the retrieval failed. 480 */ 481 List<ArtifactMetadata> getArtifacts( RepositorySession session, String repositoryId ) 482 throws MetadataRepositoryException; 483 484 /** 485 * Returns a stream of artifacts that are stored in the given repository. The number and order of elements in the stream 486 * is defined by the <code>queryParameter</code>. 487 * The efficiency of ordering of elements is dependent on the implementation. 488 * There may be some implementations that have to put a hard limit on the elements returned. 489 * If there are no <code>sortFields</code> defined in the query parameter, the order of elements in the stream is undefined and depends 490 * on the implementation. 491 * 492 * @param session The repository session. 493 * @param repositoryId The repository id. 494 * @return A stream of artifact metadata objects for each artifact found in the repository. 495 * @since 3.0 496 */ 497 Stream<ArtifactMetadata> getArtifactStream( RepositorySession session, String repositoryId, QueryParameter queryParameter ) 498 throws MetadataResolutionException; 499 500 /** 501 * Returns a stream of all the artifacts in the given repository using default query parameter. 502 * The order of the artifacts returned in the stream depends on the implementation. 503 * The number of elements in the stream is unlimited, but there may be some implementations that have to put a hard 504 * limit on the elements returned. 505 * For further information see {@link #getArtifactStream(RepositorySession, String, QueryParameter)} 506 * 507 * @param session The repository session 508 * @param repositoryId The repository id 509 * @return A (unlimited) stream of artifact metadata elements that are found in this repository 510 * @see #getArtifactStream(RepositorySession, String, QueryParameter) 511 * @since 3.0 512 */ 513 Stream<ArtifactMetadata> getArtifactStream( RepositorySession session, String repositoryId ) 514 throws MetadataResolutionException; 515 516 /** 517 * Returns a stream of artifacts found for the given artifact coordinates and using the <code>queryParameter</code> 518 * 519 * @param session The repository session. May not be <code>null</code>. 520 * @param repoId The repository id. May not be <code>null</code>. 521 * @param namespace The namespace. May not be <code>null</code>. 522 * @param projectId The project id. May not be <code>null</code>. 523 * @param projectVersion The project version. May not be <code>null</code>. 524 * @return A stream of artifact metadata object. Order and number of elements returned, depends on the <code>queryParameter</code>. 525 * @throws MetadataResolutionException if there are no elements for the given artifact coordinates. 526 * @since 3.0 527 */ 528 Stream<ArtifactMetadata> getArtifactStream( RepositorySession session, String repoId, 529 String namespace, String projectId, 530 String projectVersion, QueryParameter queryParameter ) 531 throws MetadataResolutionException; 532 533 /** 534 * Returns a stream of artifacts found for the given artifact coordinates. The order of elements returned, depends on the 535 * implementation. 536 * 537 * @param session The repository session. May not be <code>null</code>. 538 * @param repoId The repository id. May not be <code>null</code>. 539 * @param namespace The namespace. May not be <code>null</code>. 540 * @param projectId The project id. May not be <code>null</code>. 541 * @param projectVersion The project version. May not be <code>null</code>. 542 * @return A stream of artifact metadata object. Order and number of elements returned, depends on the <code>queryParameter</code>. 543 * @throws MetadataResolutionException if there are no elements for the given artifact coordinates. 544 * @since 3.0 545 */ 546 Stream<ArtifactMetadata> getArtifactStream( RepositorySession session, String repoId, 547 String namespace, String projectId, 548 String projectVersion ) 549 throws MetadataResolutionException; 550 551 /** 552 * Returns the metadata for the given project. If there are no custom properties stored on the project, it will 553 * just return a <code>ProjectMetadata</code> object with the data provided by parameters. 554 * 555 * @param session The session id 556 * @param repoId The repository id 557 * @param namespace The namespace '.'-separated. 558 * @param projectId The project name 559 * @return The project metadata or <code>null</code> if not found. 560 * @throws MetadataResolutionException if the metadata retrieval failed 561 */ 562 ProjectMetadata getProject( RepositorySession session, String repoId, String namespace, String projectId ) 563 throws MetadataResolutionException; 564 565 /** 566 * Returns the metadata for the project version. 567 * 568 * @param session The repository session. 569 * @param repoId The repository id. 570 * @param namespace The namespace '.'-separated 571 * @param projectId The project name 572 * @param projectVersion The project version 573 * @return The version metadata object, or <code>null</code>, if not found. 574 * @throws MetadataResolutionException if the retrieval of the metadata failed. 575 */ 576 ProjectVersionMetadata getProjectVersion( RepositorySession session, String repoId, String namespace, String projectId, String projectVersion ) 577 throws MetadataResolutionException; 578 579 /** 580 * Returns all artifact version strings for a given project version. This is for snapshot versions and returns the timestamped 581 * versions, if available. 582 * 583 * @param session The repository session. 584 * @param repoId The repository id. 585 * @param namespace The namespace '.'-separated 586 * @param projectId The project name. 587 * @param projectVersion The project version. 588 * @return A list of version strings, or a empty list if no versions are found, or this is not a snapshot version. 589 * @throws MetadataResolutionException if the retrieval of the metadata failed. 590 */ 591 List<String> getArtifactVersions( RepositorySession session, String repoId, String namespace, String projectId, String projectVersion ) 592 throws MetadataResolutionException; 593 594 /** 595 * Retrieve project references from the metadata repository. Note that this is not built into the content model for 596 * a project version as a reference may be present (due to reverse-lookup of dependencies) before the actual 597 * project is, and we want to avoid adding a stub model to the content repository. 598 * 599 * @param session The repository session. 600 * @param repoId The repository ID to look within 601 * @param namespace The namespace of the project to get references to 602 * @param projectId The identifier of the project to get references to 603 * @param projectVersion The version of the project to get references to 604 * @return a list of project references 605 * @throws MetadataResolutionException if the version could not be found. 606 */ 607 List<ProjectVersionReference> getProjectReferences( RepositorySession session, String repoId, String namespace, String projectId, 608 String projectVersion ) 609 throws MetadataResolutionException; 610 611 /** 612 * Returns the names of the root namespaces stored for this repository. 613 * 614 * @param session The repository session. 615 * @param repoId The repository id. 616 * @return A list of namespace names, or empty list, if no namespace is stored for this repository. 617 * @throws MetadataResolutionException If the retrieval failed. 618 */ 619 List<String> getRootNamespaces( RepositorySession session, String repoId ) 620 throws MetadataResolutionException; 621 622 /** 623 * Returns the list of namespace names that are children of the given namespace. It does not descend recursively. 624 * 625 * @param session The repository session. 626 * @param repoId The repository id. 627 * @param namespace The parent namespace '.'-separated. 628 * @return {@link List} of child namespace names, or a empty list, if there are no children for the given parent namespace. 629 * @throws MetadataResolutionException if the retrieval failed. 630 */ 631 List<String> getChildNamespaces( RepositorySession session, String repoId, String namespace ) 632 throws MetadataResolutionException; 633 634 /** 635 * Return the project names that of all projects stored under the given namespace. 636 * 637 * @param session The repository session. 638 * @param repoId The repository id. 639 * @param namespace The namespace '.'-separated. 640 * @return The list of project names or empty list if no project exists at the given namespace. 641 * @throws MetadataResolutionException if the retrieval failed. 642 */ 643 List<String> getProjects( RepositorySession session, String repoId, String namespace ) 644 throws MetadataResolutionException; 645 646 /** 647 * Returns the names of all versions stored under the given project. 648 * 649 * @param session The repository session. 650 * @param repoId The repository id. 651 * @param namespace The namespace '.'-separated. 652 * @param projectId The project name. 653 * @return The list of versions or a empty list, if not version was found. 654 * @throws MetadataResolutionException if the retrieval failed. 655 */ 656 List<String> getProjectVersions( RepositorySession session, String repoId, String namespace, String projectId ) 657 throws MetadataResolutionException; 658 659 /** 660 * Removes a project version and all its artifact and facet metadata under it. 661 * 662 * @param session The repository session. 663 * @param repoId The repository id. 664 * @param namespace The namespace '.'-separated. 665 * @param projectId The project name 666 * @param projectVersion The project version. 667 * @throws MetadataRepositoryException if the removal failed. 668 * @since 1.4-M4 669 */ 670 void removeProjectVersion( RepositorySession session, String repoId, String namespace, String projectId, String projectVersion ) 671 throws MetadataRepositoryException; 672 673 /** 674 * Returns the metadata of all artifacts stored for the given project version. 675 * 676 * @param session The repository session. 677 * @param repoId The repository id. 678 * @param namespace The namespace '.'-separated. 679 * @param projectId The project name. 680 * @param projectVersion The project version. 681 * @return The list of artifact metadata objects, or a empty list, if no artifact exists for this version. 682 * @throws MetadataResolutionException if the retrieval failed. 683 */ 684 List<ArtifactMetadata> getArtifacts( RepositorySession session, String repoId, String namespace, String projectId, 685 String projectVersion ) 686 throws MetadataResolutionException; 687 688 /** 689 * Removes the project metadata and metadata for all stored versions, artifacts and facets of this project. 690 * 691 * @param session The repository session. 692 * @param repositoryId The repository id. 693 * @param namespace The namespace '.'-separated. 694 * @param projectId The project name. 695 * @throws MetadataRepositoryException if the removal failed. 696 * @since 1.4-M4 697 */ 698 void removeProject( RepositorySession session, String repositoryId, String namespace, String projectId ) 699 throws MetadataRepositoryException; 700 701 /** 702 * Closes the repository. 703 * Repositories are normally opened during startup and closed on shutdown. The closing of a repository stops all 704 * invalidates all connections to it. 705 * Sessions that are open are invalidated too. The repository will throw exceptions if it is used after closing. 706 * 707 * @throws MetadataRepositoryException if the something went wrong or if the repository was closed already. 708 */ 709 void close( ) 710 throws MetadataRepositoryException; 711 712 713 /** 714 * Full text artifacts search. Searches for the given string in all metadata and returns artifacts where the 715 * text was found. 716 * 717 * @param session The repository session. 718 * @param repositoryId can be <code>null</code> to search in all repositories 719 * @param text The search text 720 * @param exact if true, the value must exactly match the text. 721 * @return a list of artifacts or empty list if no results where found. 722 * @throws MetadataRepositoryException if the retrieval failed. 723 */ 724 List<ArtifactMetadata> searchArtifacts( RepositorySession session, String repositoryId, String text, boolean exact ) 725 throws MetadataRepositoryException; 726 727 /** 728 * Full text artifacts search inside the specified key. Searches for the given text in all attributes with the given 729 * name. 730 * 731 * @param session The repository session. 732 * @param repositoryId can be <code>null</code> to search in all repositories 733 * @param key search only inside this attribute. 734 * @param text The search string. 735 * @param exact if true, the value must exactly match the text. 736 * @return a list of artifacts or empty list if no results were found. 737 * @throws MetadataRepositoryException if the retrieval failed. 738 */ 739 List<ArtifactMetadata> searchArtifacts( RepositorySession session, String repositoryId, String key, String text, boolean exact ) 740 throws MetadataRepositoryException; 741 742 }