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
26 import org.eclipse.aether.artifact.Artifact;
27 import org.eclipse.aether.metadata.Metadata;
28
29 /**
30 * The layout for a remote repository whose artifacts/metadata can be addressed via URIs.
31 * <p>
32 * <strong>Note:</strong> Implementations must be stateless.
33 */
34 public interface RepositoryLayout
35 {
36
37 /**
38 * A descriptor for a checksum file. This descriptor simply associates the location of a checksum file with the
39 * underlying algorithm used to calculate/verify it. Checksum algorithms are denoted by names as used with
40 * {@link java.security.MessageDigest#getInstance(String)}, e.g. {@code "SHA-1"} or {@code "MD5"}.
41 */
42 static final class Checksum
43 {
44
45 private final String algorithm;
46
47 private final URI location;
48
49 /**
50 * Creates a new checksum file descriptor with the specified algorithm and location. The method
51 * {@link #forLocation(URI, String)} is usually more convenient though.
52 *
53 * @param algorithm The algorithm used to calculate the checksum, must not be {@code null}.
54 * @param location The relative URI to the checksum file within a repository, must not be {@code null}.
55 */
56 public Checksum( String algorithm, URI location )
57 {
58 verify( algorithm, location );
59 this.algorithm = algorithm;
60 this.location = location;
61 }
62
63 /**
64 * Creates a checksum file descriptor for the specified artifact/metadata location and algorithm. The location
65 * of the checksum file itself is derived from the supplied resource URI by appending the file extension
66 * corresponding to the algorithm. The file extension in turn is derived from the algorithm name by stripping
67 * out any hyphen ('-') characters and lower-casing the name, e.g. "SHA-1" is mapped to ".sha1".
68 *
69 * @param location The relative URI to the artifact/metadata whose checksum file is being obtained, must not be
70 * {@code null} and must not have a query or fragment part.
71 * @param algorithm The algorithm used to calculate the checksum, must not be {@code null}.
72 * @return The checksum file descriptor, never {@code null}.
73 */
74 public static Checksum forLocation( URI location, String algorithm )
75 {
76 verify( algorithm, location );
77 if ( location.getRawQuery() != null )
78 {
79 throw new IllegalArgumentException( "resource location must not have query parameters: " + location );
80 }
81 if ( location.getRawFragment() != null )
82 {
83 throw new IllegalArgumentException( "resource location must not have a fragment: " + location );
84 }
85 String extension = '.' + algorithm.replace( "-", "" ).toLowerCase( Locale.ENGLISH );
86 return new Checksum( algorithm, URI.create( location.toString() + extension ) );
87 }
88
89 private static void verify( String algorithm, URI location )
90 {
91 if ( algorithm == null || algorithm.length() <= 0 )
92 {
93 throw new IllegalArgumentException( "checksum algorithm has not been specified" );
94 }
95 if ( location == null )
96 {
97 throw new IllegalArgumentException( "checksum location has not been specified" );
98 }
99 if ( location.isAbsolute() )
100 {
101 throw new IllegalArgumentException( "checksum location must be relative" );
102 }
103 }
104
105 /**
106 * Gets the name of the algorithm that is used to calculate the checksum.
107 *
108 * @return The algorithm name, never {@code null}.
109 * @see java.security.MessageDigest#getInstance(String)
110 */
111 public String getAlgorithm()
112 {
113 return algorithm;
114 }
115
116 /**
117 * Gets the location of the checksum file with a remote repository. The URI is relative to the root directory of
118 * the repository.
119 *
120 * @return The relative URI to the checksum file, never {@code null}.
121 */
122 public URI getLocation()
123 {
124 return location;
125 }
126
127 @Override
128 public String toString()
129 {
130 return location + " (" + algorithm + ")";
131 }
132
133 }
134
135 /**
136 * Gets the location within a remote repository where the specified artifact resides. The URI is relative to the
137 * root directory of the repository.
138 *
139 * @param artifact The artifact to get the URI for, must not be {@code null}.
140 * @param upload {@code false} if the artifact is being downloaded, {@code true} if the artifact is being uploaded.
141 * @return The relative URI to the artifact, never {@code null}.
142 */
143 URI getLocation( Artifact artifact, boolean upload );
144
145 /**
146 * Gets the location within a remote repository where the specified metadata resides. The URI is relative to the
147 * root directory of the repository.
148 *
149 * @param metadata The metadata to get the URI for, must not be {@code null}.
150 * @param upload {@code false} if the metadata is being downloaded, {@code true} if the metadata is being uploaded.
151 * @return The relative URI to the metadata, never {@code null}.
152 */
153 URI getLocation( Metadata metadata, boolean upload );
154
155 /**
156 * Gets the checksums files that a remote repository keeps to help detect data corruption during transfers of the
157 * specified artifact.
158 *
159 * @param artifact The artifact to get the checksum files for, must not be {@code null}.
160 * @param upload {@code false} if the checksums are being downloaded/verified, {@code true} if the checksums are
161 * being uploaded/created.
162 * @param location The relative URI to the artifact within the repository as previously obtained from
163 * {@link #getLocation(Artifact, boolean)}, must not be {@code null}.
164 * @return The checksum files for the given artifact, possibly empty but never {@code null}.
165 */
166 List<Checksum> getChecksums( Artifact artifact, boolean upload, URI location );
167
168 /**
169 * Gets the checksums files that a remote repository keeps to help detect data corruption during transfers of the
170 * specified metadata.
171 *
172 * @param metadata The metadata to get the checksum files for, must not be {@code null}.
173 * @param upload {@code false} if the checksums are being downloaded/verified, {@code true} if the checksums are
174 * being uploaded/created.
175 * @param location The relative URI to the metadata within the repository as previously obtained from
176 * {@link #getLocation(Metadata, boolean)}, must not be {@code null}.
177 * @return The checksum files for the given metadata, possibly empty but never {@code null}.
178 */
179 List<Checksum> getChecksums( Metadata metadata, boolean upload, URI location );
180
181 }