src/java/org/apache/ivy/core/cache/RepositoryCacheManager.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 */
package org.apache.ivy.core.cache;

import java.text.ParseException;

import org.apache.ivy.core.module.descriptor.Artifact;
import org.apache.ivy.core.module.descriptor.DependencyDescriptor;
import org.apache.ivy.core.module.descriptor.ModuleDescriptor;
import org.apache.ivy.core.module.id.ModuleRevisionId;
import org.apache.ivy.core.report.ArtifactDownloadReport;
import org.apache.ivy.core.resolve.ResolvedModuleRevision;
import org.apache.ivy.plugins.repository.ArtifactResourceResolver;
import org.apache.ivy.plugins.repository.Repository;
import org.apache.ivy.plugins.repository.Resource;
import org.apache.ivy.plugins.repository.ResourceDownloader;
import org.apache.ivy.plugins.resolver.DependencyResolver;
import org.apache.ivy.plugins.resolver.util.ResolvedResource;

public interface RepositoryCacheManager {

    /**
     * Returns the name of the repository cache manager.
     *
     * @return the name of the repository cache manager.
     */
    String getName();

    /**
     * Saves the information of which resolvers were used to resolve a module (both for metadata and
     * artifact), so that this info can be loaded later (even after a jvm restart) for the use of
     * {@link #findModuleInCache(DependencyDescriptor, ModuleRevisionId, CacheMetadataOptions, String)}.
     *
     * @param descriptor           the module descriptor resolved
     * @param metadataResolverName metadata resolver name
     * @param artifactResolverName artifact resolver name
     */
    void saveResolvers(ModuleDescriptor descriptor, String metadataResolverName,
                       String artifactResolverName);

    /**
     * Returns the artifact origin of the given artifact as saved in this cache.
     * <p>
     * If the origin is unknown, the returned ArtifactOrigin instance will return true when
     * {@link ArtifactOrigin#isUnknown(ArtifactOrigin)} is called.
     *
     * @param artifact the artifact for which the saved artifact origin should be returned.
     * @return the artifact origin of the given artifact as saved in this cache
     */
    ArtifactOrigin getSavedArtifactOrigin(Artifact artifact);

    /**
     * Search a module descriptor in cache for a mrid
     *
     * @param dd                  the dependency descriptor identifying the module to search
     * @param requestedRevisionId the requested dependency module revision id identifying the module
     *                            to search
     * @param options             options on how caching should be handled
     * @param expectedResolver    the resolver with which the md in cache must have been resolved to
     *                            be returned, null if this doesn't matter
     * @return the ResolvedModuleRevision corresponding to the module found, null if none correct
     * has been found in cache
     */
    ResolvedModuleRevision findModuleInCache(DependencyDescriptor dd,
                                             ModuleRevisionId requestedRevisionId,
                                             CacheMetadataOptions options,
                                             String expectedResolver);

    /**
     * Downloads an artifact to this cache.
     *
     * @param artifact           the artifact to download
     * @param resourceResolver   a resource resolver to use if the artifact needs to be resolved to
     *                           a Resource for downloading
     * @param resourceDownloader a resource downloader to use if actual download of the resource is
     *                           needed
     * @param options            a set of options to adjust the download
     * @return a report indicating how the download was performed
     */
    ArtifactDownloadReport download(Artifact artifact,
                                    ArtifactResourceResolver resourceResolver,
                                    ResourceDownloader resourceDownloader,
                                    CacheDownloadOptions options);

    /**
     * Download some repository resource and put it in the cache.
     * <p>
     * If the cached version is considered enough up to date, no downloading is done.
     *
     * @param resource   the resource of the file to put in cache
     * @param name       the descriptive name of the resource (helps while manually looking into the
     *                   cache files)
     * @param type       the type of the resource (helps while manually looking into the cache files)
     * @param extension  the extension of the resource (helps while manually looking into the cache
     *                   files)
     * @param options    a set of options to adjust the download
     * @param repository the repository which resolve the content of the resource
     * @return a report indicating how the download was performed
     */
    ArtifactDownloadReport downloadRepositoryResource(Resource resource, String name,
                                                      String type, String extension,
                                                      CacheResourceOptions options,
                                                      Repository repository);

    /**
     * Caches an original module descriptor.
     * <p>
     * After this call, the original module descriptor file (with no modification nor conversion)
     * should be available as a local file.
     * </p>
     *
     * @param resolver                  the dependency resolver from which the cache request comes
     *                                  from
     * @param originalMetadataRef       a resolved resource pointing to the remote original module
     *                                  descriptor
     * @param dd                        the dependency descriptor for which the module descriptor
     *                                  should be cached
     * @param requestedMetadataArtifact the module descriptor artifact as requested originally
     * @param downloader                a ResourceDownloader able to download the original module
     *                                  descriptor resource if required by this cache implementation
     * @param options                   options to apply to cache this module descriptor
     * @return a {@link ResolvedModuleRevision} representing the local cached module descriptor, or
     * null if it failed
     * @throws ParseException if an exception occurred while parsing the module descriptor
     */
    ResolvedModuleRevision cacheModuleDescriptor(DependencyResolver resolver,
                                                 ResolvedResource originalMetadataRef,
                                                 DependencyDescriptor dd,
                                                 Artifact requestedMetadataArtifact,
                                                 ResourceDownloader downloader,
                                                 CacheMetadataOptions options) throws ParseException;

    /**
     * Stores a standardized version of an original module descriptor in the cache for later use.
     *
     * @param resolver                  the dependency resolver from which the cache request comes
     *                                  from
     * @param originalMetadataRef       a resolved resource pointing to the remote original module
     *                                  descriptor
     * @param requestedMetadataArtifact the module descriptor artifact as requested originally
     * @param rmr                       the {@link ResolvedModuleRevision} representing the local
     *                                  cached module descriptor
     * @param writer                    a {@link ModuleDescriptorWriter} able to write the module
     *                                  descriptor to a stream.
     */
    void originalToCachedModuleDescriptor(DependencyResolver resolver,
                                          ResolvedResource originalMetadataRef,
                                          Artifact requestedMetadataArtifact,
                                          ResolvedModuleRevision rmr, ModuleDescriptorWriter writer);

    /**
     * Cleans the whole cache.
     */
    void clean();

    /**
     * Caches a dynamic revision constraint resolution.
     *
     * @param dynamicMrid the dynamic module revision id
     * @param revision    the resolved revision
     * @deprecated See {@link #saveResolvedRevision(String, ModuleRevisionId, String)} which
     * prevents cache + * thrashing when multiple resolvers store the same dynamicMrid
     */
    @Deprecated
    void saveResolvedRevision(ModuleRevisionId dynamicMrid, String revision);

    /**
     * Caches a dynamic revision constraint resolution for a specific resolver.
     *
     * @param resolverName the resolver in which this dynamic revision was resolved
     * @param dynamicMrid  the dynamic module revision id
     * @param revision     the resolved revision
     */
    void saveResolvedRevision(String resolverName, ModuleRevisionId dynamicMrid,
                              String revision);

}