source.dussan.org Git - archiva.git/blob

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