001package org.eclipse.aether.spi.connector.layout;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 * 
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 * 
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.net.URI;
023import java.util.List;
024import java.util.Locale;
025import static java.util.Objects.requireNonNull;
026
027import org.eclipse.aether.artifact.Artifact;
028import org.eclipse.aether.metadata.Metadata;
029
030/**
031 * The layout for a remote repository whose artifacts/metadata can be addressed via URIs.
032 * <p>
033 * <strong>Note:</strong> Implementations must be stateless.
034 */
035public interface RepositoryLayout
036{
037
038    /**
039     * A descriptor for a checksum file. This descriptor simply associates the location of a checksum file with the
040     * underlying algorithm used to calculate/verify it. Checksum algorithms are denoted by names as used with
041     * {@link java.security.MessageDigest#getInstance(String)}, e.g. {@code "SHA-1"} or {@code "MD5"}.
042     */
043    final class Checksum
044    {
045
046        private final String algorithm;
047
048        private final URI location;
049
050        /**
051         * Creates a new checksum file descriptor with the specified algorithm and location. The method
052         * {@link #forLocation(URI, String)} is usually more convenient though.
053         * 
054         * @param algorithm The algorithm used to calculate the checksum, must not be {@code null}.
055         * @param location The relative URI to the checksum file within a repository, must not be {@code null}.
056         */
057        public Checksum( String algorithm, URI location )
058        {
059            verify( algorithm, location );
060            this.algorithm = algorithm;
061            this.location = location;
062        }
063
064        /**
065         * Creates a checksum file descriptor for the specified artifact/metadata location and algorithm. The location
066         * of the checksum file itself is derived from the supplied resource URI by appending the file extension
067         * corresponding to the algorithm. The file extension in turn is derived from the algorithm name by stripping
068         * out any hyphen ('-') characters and lower-casing the name, e.g. "SHA-1" is mapped to ".sha1".
069         * 
070         * @param location The relative URI to the artifact/metadata whose checksum file is being obtained, must not be
071         *            {@code null} and must not have a query or fragment part.
072         * @param algorithm The algorithm used to calculate the checksum, must not be {@code null}.
073         * @return The checksum file descriptor, never {@code null}.
074         */
075        public static Checksum forLocation( URI location, String algorithm )
076        {
077            verify( algorithm, location );
078            if ( location.getRawQuery() != null )
079            {
080                throw new IllegalArgumentException( "resource location must not have query parameters: " + location );
081            }
082            if ( location.getRawFragment() != null )
083            {
084                throw new IllegalArgumentException( "resource location must not have a fragment: " + location );
085            }
086            String extension = '.' + algorithm.replace( "-", "" ).toLowerCase( Locale.ENGLISH );
087            return new Checksum( algorithm, URI.create( location.toString() + extension ) );
088        }
089
090        private static void verify( String algorithm, URI location )
091        {
092            requireNonNull( algorithm, "checksum algorithm cannot be null" );
093            if ( algorithm.length() == 0 )
094            {
095                throw new IllegalArgumentException( "checksum algorithm cannot be empty" );
096            }
097            requireNonNull( location, "checksum location cannot be null" );
098            if ( location.isAbsolute() )
099            {
100                throw new IllegalArgumentException( "checksum location must be relative" );
101            }
102        }
103
104        /**
105         * Gets the name of the algorithm that is used to calculate the checksum.
106         * 
107         * @return The algorithm name, never {@code null}.
108         * @see java.security.MessageDigest#getInstance(String)
109         */
110        public String getAlgorithm()
111        {
112            return algorithm;
113        }
114
115        /**
116         * Gets the location of the checksum file with a remote repository. The URI is relative to the root directory of
117         * the repository.
118         * 
119         * @return The relative URI to the checksum file, never {@code null}.
120         */
121        public URI getLocation()
122        {
123            return location;
124        }
125
126        @Override
127        public String toString()
128        {
129            return location + " (" + algorithm + ")";
130        }
131
132    }
133
134    /**
135     * Gets the location within a remote repository where the specified artifact resides. The URI is relative to the
136     * root directory of the repository.
137     * 
138     * @param artifact The artifact to get the URI for, must not be {@code null}.
139     * @param upload {@code false} if the artifact is being downloaded, {@code true} if the artifact is being uploaded.
140     * @return The relative URI to the artifact, never {@code null}.
141     */
142    URI getLocation( Artifact artifact, boolean upload );
143
144    /**
145     * Gets the location within a remote repository where the specified metadata resides. The URI is relative to the
146     * root directory of the repository.
147     * 
148     * @param metadata The metadata to get the URI for, must not be {@code null}.
149     * @param upload {@code false} if the metadata is being downloaded, {@code true} if the metadata is being uploaded.
150     * @return The relative URI to the metadata, never {@code null}.
151     */
152    URI getLocation( Metadata metadata, boolean upload );
153
154    /**
155     * Gets the checksums files that a remote repository keeps to help detect data corruption during transfers of the
156     * specified artifact.
157     * 
158     * @param artifact The artifact to get the checksum files for, must not be {@code null}.
159     * @param upload {@code false} if the checksums are being downloaded/verified, {@code true} if the checksums are
160     *            being uploaded/created.
161     * @param location The relative URI to the artifact within the repository as previously obtained from
162     *            {@link #getLocation(Artifact, boolean)}, must not be {@code null}.
163     * @return The checksum files for the given artifact, possibly empty but never {@code null}.
164     */
165    List<Checksum> getChecksums( Artifact artifact, boolean upload, URI location );
166
167    /**
168     * Gets the checksums files that a remote repository keeps to help detect data corruption during transfers of the
169     * specified metadata.
170     * 
171     * @param metadata The metadata to get the checksum files for, must not be {@code null}.
172     * @param upload {@code false} if the checksums are being downloaded/verified, {@code true} if the checksums are
173     *            being uploaded/created.
174     * @param location The relative URI to the metadata within the repository as previously obtained from
175     *            {@link #getLocation(Metadata, boolean)}, must not be {@code null}.
176     * @return The checksum files for the given metadata, possibly empty but never {@code null}.
177     */
178    List<Checksum> getChecksums( Metadata metadata, boolean upload, URI location );
179
180}