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 import java.util.Locale;
25 import static java.util.Objects.requireNonNull;
26
27 import org.eclipse.aether.artifact.Artifact;
28 import org.eclipse.aether.metadata.Metadata;
29
30 /**
31 * The layout for a remote repository whose artifacts/metadata can be addressed via URIs.
32 * <p>
33 * <strong>Note:</strong> Implementations must be stateless.
34 */
35 public interface RepositoryLayout
36 {
37
38 /**
39 * A descriptor for a checksum file. This descriptor simply associates the location of a checksum file with the
40 * underlying algorithm used to calculate/verify it. Checksum algorithms are denoted by names as used with
41 * {@link java.security.MessageDigest#getInstance(String)}, e.g. {@code "SHA-1"} or {@code "MD5"}.
42 */
43 final class Checksum
44 {
45
46 private final String algorithm;
47
48 private final URI location;
49
50 /**
51 * Creates a new checksum file descriptor with the specified algorithm and location. The method
52 * {@link #forLocation(URI, String)} is usually more convenient though.
53 *
54 * @param algorithm The algorithm used to calculate the checksum, must not be {@code null}.
55 * @param location The relative URI to the checksum file within a repository, must not be {@code null}.
56 */
57 public Checksum( String algorithm, URI location )
58 {
59 verify( algorithm, location );
60 this.algorithm = algorithm;
61 this.location = location;
62 }
63
64 /**
65 * Creates a checksum file 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 * corresponding to the algorithm. The file extension in turn is derived from the algorithm name by stripping
68 * out any hyphen ('-') characters and lower-casing the name, e.g. "SHA-1" is mapped to ".sha1".
69 *
70 * @param location The relative URI to the artifact/metadata whose checksum file is being obtained, must not be
71 * {@code null} and must not have a query or fragment part.
72 * @param algorithm 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 Checksum forLocation( URI location, String algorithm )
76 {
77 verify( algorithm, location );
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 String extension = '.' + algorithm.replace( "-", "" ).toLowerCase( Locale.ENGLISH );
87 return new Checksum( algorithm, URI.create( location.toString() + extension ) );
88 }
89
90 private static void verify( String algorithm, URI location )
91 {
92 requireNonNull( algorithm, "checksum algorithm cannot be null" );
93 if ( algorithm.length() == 0 )
94 {
95 throw new IllegalArgumentException( "checksum algorithm cannot be empty" );
96 }
97 requireNonNull( location, "checksum location cannot be null" );
98 if ( location.isAbsolute() )
99 {
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 }