001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether.resolution;
020
021import org.eclipse.aether.RepositorySystemSession;
022import org.eclipse.aether.artifact.Artifact;
023import org.eclipse.aether.metadata.Metadata;
024
025/**
026 * Controls the caching of resolution errors for artifacts/metadata from remote repositories. If caching is enabled for
027 * a given resource, a marker will be set (usually somewhere in the local repository) to suppress repeated resolution
028 * attempts for the broken resource, thereby avoiding expensive but useless network IO. The error marker is considered
029 * stale once the repository's update policy has expired at which point a future resolution attempt will be allowed.
030 * Error caching considers the current network settings such that fixes to the configuration like authentication or
031 * proxy automatically trigger revalidation with the remote side regardless of the time elapsed since the previous
032 * resolution error.
033 *
034 * @see RepositorySystemSession#getResolutionErrorPolicy()
035 */
036public interface ResolutionErrorPolicy {
037
038    /**
039     * Bit mask indicating that resolution errors should not be cached in the local repository. This forces the system
040     * to always query the remote repository for locally missing artifacts/metadata.
041     */
042    int CACHE_DISABLED = 0x00;
043
044    /**
045     * Bit flag indicating whether missing artifacts/metadata should be cached in the local repository. If caching is
046     * enabled, resolution will not be reattempted until the update policy for the affected resource has expired.
047     */
048    int CACHE_NOT_FOUND = 0x01;
049
050    /**
051     * Bit flag indicating whether connectivity/transfer errors (e.g. unreachable host, bad authentication) should be
052     * cached in the local repository. If caching is enabled, resolution will not be reattempted until the update policy
053     * for the affected resource has expired.
054     */
055    int CACHE_TRANSFER_ERROR = 0x02;
056
057    /**
058     * Bit mask indicating that all resolution errors should be cached in the local repository.
059     */
060    int CACHE_ALL = CACHE_NOT_FOUND | CACHE_TRANSFER_ERROR;
061
062    /**
063     * Gets the error policy for an artifact.
064     *
065     * @param session The repository session during which the policy is determined, must not be {@code null}.
066     * @param request The policy request holding further details, must not be {@code null}.
067     * @return The bit mask describing the desired error policy.
068     */
069    int getArtifactPolicy(RepositorySystemSession session, ResolutionErrorPolicyRequest<Artifact> request);
070
071    /**
072     * Gets the error policy for some metadata.
073     *
074     * @param session The repository session during which the policy is determined, must not be {@code null}.
075     * @param request The policy request holding further details, must not be {@code null}.
076     * @return The bit mask describing the desired error policy.
077     */
078    int getMetadataPolicy(RepositorySystemSession session, ResolutionErrorPolicyRequest<Metadata> request);
079}