1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.eclipse.aether.transfer;
20
21 import java.io.File;
22 import java.nio.file.Path;
23 import java.time.Clock;
24 import java.time.Instant;
25
26 import org.eclipse.aether.RequestTrace;
27
28 /**
29 * Describes a resource being uploaded or downloaded by the repository system.
30 */
31 public final class TransferResource {
32
33 private static Clock clock = Clock.systemUTC();
34
35 private final String repositoryId;
36
37 private final String repositoryUrl;
38
39 private final String resourceName;
40
41 private final Object resource;
42
43 private final Path path;
44
45 private final Instant startTime;
46
47 private final RequestTrace trace;
48
49 private volatile long contentLength = -1L;
50
51 private volatile long resumeOffset;
52
53 /**
54 * Gets the clock used to determine the start time of transfers.
55 *
56 * @return The clock currently in use, never {@code null}.
57 */
58 public static Clock getClock() {
59 return clock;
60 }
61
62 /**
63 * Sets the clock used to determine the start time of transfers. Intended for testing purposes.
64 *
65 * @param clock The clock to use, must not be {@code null}.
66 */
67 public static void setClock(Clock clock) {
68 TransferResource.clock = clock;
69 }
70
71 /**
72 * Creates a new transfer resource with the specified properties.
73 *
74 * @param repositoryId The ID of the repository used to transfer the resource, may be {@code null} or
75 * empty if unknown.
76 * @param repositoryUrl The base URL of the repository, may be {@code null} or empty if unknown. If not empty, a
77 * trailing slash will automatically be added if missing.
78 * @param resourceName The relative path to the resource within the repository, may be {@code null}. A leading slash
79 * (if any) will be automatically removed.
80 * @param file The source/target file involved in the transfer, may be {@code null}.
81 * @param trace The trace information, may be {@code null}.
82 *
83 * @since 1.1.0
84 * @deprecated Use {@link TransferResource(String, String, String, Path, Object, RequestTrace)} instead.
85 */
86 @Deprecated
87 public TransferResource(
88 String repositoryId, String repositoryUrl, String resourceName, File file, RequestTrace trace) {
89 this(repositoryId, repositoryUrl, resourceName, file != null ? file.toPath() : null, null, trace);
90 }
91
92 /**
93 * Creates a new transfer resource with the specified properties.
94 *
95 * @param repositoryId The ID of the repository used to transfer the resource, may be {@code null} or
96 * empty if unknown.
97 * @param repositoryUrl The base URL of the repository, may be {@code null} or empty if unknown. If not empty, a
98 * trailing slash will automatically be added if missing.
99 * @param resourceName The relative path to the resource within the repository, may be {@code null}. A leading slash
100 * (if any) will be automatically removed.
101 * @param path The source/target file involved in the transfer, may be {@code null}.
102 * @param resource The representation of this resource, may be {@code null}.
103 * @param trace The trace information, may be {@code null}.
104 *
105 * @since 2.0.0
106 */
107 public TransferResource(
108 String repositoryId,
109 String repositoryUrl,
110 String resourceName,
111 Path path,
112 Object resource,
113 RequestTrace trace) {
114 if (repositoryId == null || repositoryId.isEmpty()) {
115 this.repositoryId = "";
116 } else {
117 this.repositoryId = repositoryId;
118 }
119
120 if (repositoryUrl == null || repositoryUrl.isEmpty()) {
121 this.repositoryUrl = "";
122 } else if (repositoryUrl.endsWith("/")) {
123 this.repositoryUrl = repositoryUrl;
124 } else {
125 this.repositoryUrl = repositoryUrl + '/';
126 }
127
128 if (resourceName == null || resourceName.isEmpty()) {
129 this.resourceName = "";
130 } else if (resourceName.startsWith("/")) {
131 this.resourceName = resourceName.substring(1);
132 } else {
133 this.resourceName = resourceName;
134 }
135
136 this.path = path;
137 this.resource = resource;
138 this.trace = trace;
139 this.startTime = getClock().instant();
140 }
141
142 /**
143 * The ID of the repository, e.g., "central".
144 *
145 * @return The ID of the repository or an empty string if unknown, never {@code null}.
146 *
147 * @since 1.1.0
148 */
149 public String getRepositoryId() {
150 return repositoryId;
151 }
152
153 /**
154 * The base URL of the repository, e.g. "https://repo1.maven.org/maven2/". Unless the URL is unknown, it will be
155 * terminated by a trailing slash.
156 *
157 * @return The base URL of the repository or an empty string if unknown, never {@code null}.
158 */
159 public String getRepositoryUrl() {
160 return repositoryUrl;
161 }
162
163 /**
164 * The path of the resource relative to the repository's base URL, e.g. "org/apache/maven/maven/3.0/maven-3.0.pom".
165 *
166 * @return The path of the resource, never {@code null}.
167 */
168 public String getResourceName() {
169 return resourceName;
170 }
171
172 /**
173 * The representation of "resource", if any. The content of this field may be
174 * {@link org.eclipse.aether.artifact.Artifact} or {@link org.eclipse.aether.metadata.Metadata} or {@code null}
175 * in case of some legacy flow. Preferred way to handle returned value is with {@code instanceof}.
176 *
177 * @return The representation of this resource, may be {@code null}.
178 * @since 2.0.0
179 */
180 public Object getResource() {
181 return resource;
182 }
183
184 /**
185 * Gets the local file being uploaded or downloaded. When the repository system merely checks for the existence of a
186 * remote resource, no local file will be involved in the transfer.
187 *
188 * @return The source/target file involved in the transfer or {@code null} if none.
189 * @deprecated Use {@link #getPath()} instead.
190 */
191 @Deprecated
192 public File getFile() {
193 return path != null ? path.toFile() : null;
194 }
195
196 /**
197 * Gets the local file being uploaded or downloaded. When the repository system merely checks for the existence of a
198 * remote resource, no local file will be involved in the transfer.
199 *
200 * @return The source/target file involved in the transfer or {@code null} if none.
201 * @since 2.0.0
202 */
203 public Path getPath() {
204 return path;
205 }
206
207 /**
208 * The size of the resource in bytes. Note that the size of a resource during downloads might be unknown to the
209 * client which is usually the case when transfers employ compression like gzip. In general, the content length is
210 * not known until the transfer has {@link TransferListener#transferStarted(TransferEvent) started}.
211 *
212 * @return The size of the resource in bytes or a negative value if unknown.
213 */
214 public long getContentLength() {
215 return contentLength;
216 }
217
218 /**
219 * Sets the size of the resource in bytes.
220 *
221 * @param contentLength The size of the resource in bytes or a negative value if unknown.
222 * @return This resource for chaining, never {@code null}.
223 */
224 public TransferResource setContentLength(long contentLength) {
225 this.contentLength = contentLength;
226 return this;
227 }
228
229 /**
230 * Gets the byte offset within the resource from which the download starts. A positive offset indicates a previous
231 * download attempt is being resumed, {@code 0} means the transfer starts at the first byte.
232 *
233 * @return The zero-based index of the first byte being transferred, never negative.
234 */
235 public long getResumeOffset() {
236 return resumeOffset;
237 }
238
239 /**
240 * Sets the byte offset within the resource at which the download starts.
241 *
242 * @param resumeOffset The zero-based index of the first byte being transferred, must not be negative.
243 * @return This resource for chaining, never {@code null}.
244 */
245 public TransferResource setResumeOffset(long resumeOffset) {
246 if (resumeOffset < 0L) {
247 throw new IllegalArgumentException("resume offset cannot be negative");
248 }
249 this.resumeOffset = resumeOffset;
250 return this;
251 }
252
253 /**
254 * Gets the timestamp when the transfer of this resource was started.
255 *
256 * @return The timestamp when the transfer of this resource was started.
257 * @deprecated use {@link #getStartTime()}
258 */
259 @Deprecated
260 public long getTransferStartTime() {
261 return startTime.toEpochMilli();
262 }
263
264 /**
265 * Gets the timestamp when the transfer of this resource was started.
266 *
267 * @return The timestamp when the transfer of this resource was started.
268 */
269 public Instant getStartTime() {
270 return startTime;
271 }
272
273 /**
274 * Gets the trace information that describes the higher level request/operation during which this resource is
275 * transferred.
276 *
277 * @return The trace information about the higher level operation or {@code null} if none.
278 */
279 public RequestTrace getTrace() {
280 return trace;
281 }
282
283 @Override
284 public String toString() {
285 return getRepositoryUrl() + getResourceName() + " <> " + getPath();
286 }
287 }