1 package org.eclipse.aether.spi.connector.layout; 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 java.net.URI; 23 import java.util.List; 24 25 import static java.util.Objects.requireNonNull; 26 27 import org.eclipse.aether.artifact.Artifact; 28 import org.eclipse.aether.metadata.Metadata; 29 import org.eclipse.aether.spi.connector.checksum.ChecksumAlgorithmFactory; 30 31 /** 32 * The layout for a remote repository whose artifacts/metadata can be addressed via URIs. 33 * <p> 34 * <strong>Note:</strong> Implementations must be stateless. 35 */ 36 public interface RepositoryLayout 37 { 38 39 /** 40 * A descriptor for a checksum location. This descriptor simply associates the location of a checksum file with the 41 * underlying checksum algorithm used to calculate/verify it. 42 */ 43 final class ChecksumLocation 44 { 45 private final URI location; 46 47 private final ChecksumAlgorithmFactory checksumAlgorithmFactory; 48 49 /** 50 * Creates a new checksum file descriptor with the specified algorithm and location. The method 51 * {@link #forLocation(URI, ChecksumAlgorithmFactory)} is usually more convenient though. 52 * 53 * @param location The relative URI to the checksum file within a repository, must not be {@code 54 * null}. 55 * @param checksumAlgorithmFactory The checksum type used to calculate the checksum, must not be {@code null}. 56 */ 57 public ChecksumLocation( URI location, ChecksumAlgorithmFactory checksumAlgorithmFactory ) 58 { 59 verify( location, checksumAlgorithmFactory ); 60 this.location = location; 61 this.checksumAlgorithmFactory = checksumAlgorithmFactory; 62 } 63 64 /** 65 * Creates a checksum descriptor for the specified artifact/metadata location and algorithm. The location 66 * of the checksum file itself is derived from the supplied resource URI by appending the file extension 67 * specified by the algorithm factory. See {@link ChecksumAlgorithmFactory#getFileExtension()}. 68 * 69 * @param location The relative URI to the artifact/metadata whose checksum file is being 70 * obtained, must not be 71 * {@code null} and must not have a query or fragment part. 72 * @param checksumAlgorithmFactory The algorithm used to calculate the checksum, must not be {@code null}. 73 * @return The checksum file descriptor, never {@code null}. 74 */ 75 public static ChecksumLocation forLocation( URI location, ChecksumAlgorithmFactory checksumAlgorithmFactory ) 76 { 77 verify( location, checksumAlgorithmFactory ); 78 if ( location.getRawQuery() != null ) 79 { 80 throw new IllegalArgumentException( "resource location must not have query parameters: " + location ); 81 } 82 if ( location.getRawFragment() != null ) 83 { 84 throw new IllegalArgumentException( "resource location must not have a fragment: " + location ); 85 } 86 return new ChecksumLocation( URI.create( location + "." + checksumAlgorithmFactory.getFileExtension() ), 87 checksumAlgorithmFactory ); 88 } 89 90 private static void verify( URI location, ChecksumAlgorithmFactory checksumAlgorithmFactory ) 91 { 92 requireNonNull( location, "checksum location cannot be null" ); 93 if ( location.isAbsolute() ) 94 { 95 throw new IllegalArgumentException( "checksum location must be relative" ); 96 } 97 requireNonNull( checksumAlgorithmFactory, "checksum algorithm factory cannot be null" ); 98 } 99 100 /** 101 * Gets the {@link ChecksumAlgorithmFactory} that is used to calculate the checksum. 102 * 103 * @return The checksum factory, never {@code null}. 104 */ 105 public ChecksumAlgorithmFactory getChecksumAlgorithmFactory() 106 { 107 return checksumAlgorithmFactory; 108 } 109 110 /** 111 * Gets the location of the checksum file with a remote repository. The URI is relative to the root directory of 112 * the repository. 113 * 114 * @return The relative URI to the checksum file, never {@code null}. 115 */ 116 public URI getLocation() 117 { 118 return location; 119 } 120 121 @Override 122 public String toString() 123 { 124 return location + " (" + checksumAlgorithmFactory.getName() + ")"; 125 } 126 } 127 128 /** 129 * Returns immutable list of {@link ChecksumAlgorithmFactory} this instance of layout uses, never {@code null}. 130 * The order also represents the order how remote external checksums are retrieved and validated. 131 * 132 * @see org.eclipse.aether.spi.connector.checksum.ChecksumPolicy.ChecksumKind 133 * @since 1.8.0 134 */ 135 List<ChecksumAlgorithmFactory> getChecksumAlgorithmFactories(); 136 137 /** 138 * Tells whether given artifact have remote external checksums according to current layout or not. If it returns 139 * {@code true}, then layout configured checksums will be expected: on upload they will be calculated and deployed 140 * along artifact, on download they will be retrieved and validated. 141 * 142 * If it returns {@code false} the given artifacts will have checksums omitted: on upload they will not be 143 * calculated and deployed, and on download they will be not retrieved nor validated. 144 * 145 * The result affects only layout provided checksums. See 146 * {@link org.eclipse.aether.spi.connector.checksum.ChecksumPolicy.ChecksumKind#REMOTE_EXTERNAL}. 147 * On download, the {@link org.eclipse.aether.spi.connector.layout.RepositoryLayout#getChecksumAlgorithmFactories()} 148 * layout required checksums are calculated, and non layout-provided checksums are still utilized. 149 * 150 * Typical case to return {@code false} (to omit checksums) is for artifact signatures, that are already a 151 * "sub-artifact" of some main artifact (for example a JAR), and they can be validated by some other means. 152 * 153 * @see org.eclipse.aether.spi.connector.checksum.ChecksumPolicy.ChecksumKind 154 * @see #getChecksumAlgorithmFactories() 155 * @since 1.8.0 156 */ 157 boolean hasChecksums( Artifact artifact ); 158 159 /** 160 * Gets the location within a remote repository where the specified artifact resides. The URI is relative to the 161 * root directory of the repository. 162 * 163 * @param artifact The artifact to get the URI for, must not be {@code null}. 164 * @param upload {@code false} if the artifact is being downloaded, {@code true} if the artifact is being 165 * uploaded. 166 * @return The relative URI to the artifact, never {@code null}. 167 */ 168 URI getLocation( Artifact artifact, boolean upload ); 169 170 /** 171 * Gets the location within a remote repository where the specified metadata resides. The URI is relative to the 172 * root directory of the repository. 173 * 174 * @param metadata The metadata to get the URI for, must not be {@code null}. 175 * @param upload {@code false} if the metadata is being downloaded, {@code true} if the metadata is being 176 * uploaded. 177 * @return The relative URI to the metadata, never {@code null}. 178 */ 179 URI getLocation( Metadata metadata, boolean upload ); 180 181 /** 182 * Gets the checksums files that a remote repository keeps to help detect data corruption during transfers of the 183 * specified artifact. 184 * 185 * @param artifact The artifact to get the checksum files for, must not be {@code null}. 186 * @param upload {@code false} if the checksums are being downloaded/verified, {@code true} if the checksums are 187 * being uploaded/created. 188 * @param location The relative URI to the artifact within the repository as previously obtained from 189 * {@link #getLocation(Artifact, boolean)}, must not be {@code null}. 190 * @return The checksum files for the given artifact, possibly empty but never {@code null}. If empty, that means 191 * that this layout does not provide checksums for given artifact. 192 */ 193 List<ChecksumLocation> getChecksumLocations( Artifact artifact, boolean upload, URI location ); 194 195 /** 196 * Gets the checksums files that a remote repository keeps to help detect data corruption during transfers of the 197 * specified metadata. 198 * 199 * @param metadata The metadata to get the checksum files for, must not be {@code null}. 200 * @param upload {@code false} if the checksums are being downloaded/verified, {@code true} if the checksums are 201 * being uploaded/created. 202 * @param location The relative URI to the metadata within the repository as previously obtained from 203 * {@link #getLocation(Metadata, boolean)}, must not be {@code null}. 204 * @return The checksum files for the given metadata, possibly empty but never {@code null}. If empty, that means 205 * that this layout does not provide checksums for given artifact. 206 */ 207 List<ChecksumLocation> getChecksumLocations( Metadata metadata, boolean upload, URI location ); 208 209 }