View Javadoc
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  
23  import org.eclipse.aether.RequestTrace;
24  
25  /**
26   * Describes a resource being uploaded or downloaded by the repository system.
27   */
28  public final class TransferResource {
29  
30      private final String repositoryId;
31  
32      private final String repositoryUrl;
33  
34      private final String resourceName;
35  
36      private final File file;
37  
38      private final long startTime;
39  
40      private final RequestTrace trace;
41  
42      private long contentLength = -1L;
43  
44      private long resumeOffset;
45  
46      /**
47       * Creates a new transfer resource with the specified properties.
48       *
49       * @param repositoryUrl The base URL of the repository, may be {@code null} or empty if unknown. If not empty, a
50       * trailing slash will automatically be added if missing.
51       * @param resourceName The relative path to the resource within the repository, may be {@code null}. A leading slash
52       * (if any) will be automatically removed.
53       * @param file The source/target file involved in the transfer, may be {@code null}.
54       * @param trace The trace information, may be {@code null}.
55       *
56       * @deprecated As of 1.1.0, replaced by {@link #TransferResource(java.lang.String, java.lang.String,
57       * java.lang.String, java.io.File, org.eclipse.aether.RequestTrace)}
58       */
59      @Deprecated
60      public TransferResource(String repositoryUrl, String resourceName, File file, RequestTrace trace) {
61          this(null, repositoryUrl, resourceName, file, trace);
62      }
63  
64      /**
65       * Creates a new transfer resource with the specified properties.
66       *
67       * @param repositoryId The ID of the repository used to transfer the resource, may be {@code null} or
68       *                     empty if unknown.
69       * @param repositoryUrl The base URL of the repository, may be {@code null} or empty if unknown. If not empty, a
70       *            trailing slash will automatically be added if missing.
71       * @param resourceName The relative path to the resource within the repository, may be {@code null}. A leading slash
72       *            (if any) will be automatically removed.
73       * @param file The source/target file involved in the transfer, may be {@code null}.
74       * @param trace The trace information, may be {@code null}.
75       *
76       * @since 1.1.0
77       */
78      public TransferResource(
79              String repositoryId, String repositoryUrl, String resourceName, File file, RequestTrace trace) {
80          if (repositoryId == null || repositoryId.isEmpty()) {
81              this.repositoryId = "";
82          } else {
83              this.repositoryId = repositoryId;
84          }
85  
86          if (repositoryUrl == null || repositoryUrl.isEmpty()) {
87              this.repositoryUrl = "";
88          } else if (repositoryUrl.endsWith("/")) {
89              this.repositoryUrl = repositoryUrl;
90          } else {
91              this.repositoryUrl = repositoryUrl + '/';
92          }
93  
94          if (resourceName == null || resourceName.isEmpty()) {
95              this.resourceName = "";
96          } else if (resourceName.startsWith("/")) {
97              this.resourceName = resourceName.substring(1);
98          } else {
99              this.resourceName = resourceName;
100         }
101 
102         this.file = file;
103 
104         this.trace = trace;
105 
106         startTime = System.currentTimeMillis();
107     }
108 
109     /**
110      * The ID of the repository, e.g., "central".
111      *
112      * @return The ID of the repository or an empty string if unknown, never {@code null}.
113      *
114      * @since 1.1.0
115      */
116     public String getRepositoryId() {
117         return repositoryId;
118     }
119 
120     /**
121      * The base URL of the repository, e.g. "http://repo1.maven.org/maven2/". Unless the URL is unknown, it will be
122      * terminated by a trailing slash.
123      *
124      * @return The base URL of the repository or an empty string if unknown, never {@code null}.
125      */
126     public String getRepositoryUrl() {
127         return repositoryUrl;
128     }
129 
130     /**
131      * The path of the resource relative to the repository's base URL, e.g. "org/apache/maven/maven/3.0/maven-3.0.pom".
132      *
133      * @return The path of the resource, never {@code null}.
134      */
135     public String getResourceName() {
136         return resourceName;
137     }
138 
139     /**
140      * Gets the local file being uploaded or downloaded. When the repository system merely checks for the existence of a
141      * remote resource, no local file will be involved in the transfer.
142      *
143      * @return The source/target file involved in the transfer or {@code null} if none.
144      */
145     public File getFile() {
146         return file;
147     }
148 
149     /**
150      * The size of the resource in bytes. Note that the size of a resource during downloads might be unknown to the
151      * client which is usually the case when transfers employ compression like gzip. In general, the content length is
152      * not known until the transfer has {@link TransferListener#transferStarted(TransferEvent) started}.
153      *
154      * @return The size of the resource in bytes or a negative value if unknown.
155      */
156     public long getContentLength() {
157         return contentLength;
158     }
159 
160     /**
161      * Sets the size of the resource in bytes.
162      *
163      * @param contentLength The size of the resource in bytes or a negative value if unknown.
164      * @return This resource for chaining, never {@code null}.
165      */
166     public TransferResource setContentLength(long contentLength) {
167         this.contentLength = contentLength;
168         return this;
169     }
170 
171     /**
172      * Gets the byte offset within the resource from which the download starts. A positive offset indicates a previous
173      * download attempt is being resumed, {@code 0} means the transfer starts at the first byte.
174      *
175      * @return The zero-based index of the first byte being transferred, never negative.
176      */
177     public long getResumeOffset() {
178         return resumeOffset;
179     }
180 
181     /**
182      * Sets the byte offset within the resource at which the download starts.
183      *
184      * @param resumeOffset The zero-based index of the first byte being transferred, must not be negative.
185      * @return This resource for chaining, never {@code null}.
186      */
187     public TransferResource setResumeOffset(long resumeOffset) {
188         if (resumeOffset < 0L) {
189             throw new IllegalArgumentException("resume offset cannot be negative");
190         }
191         this.resumeOffset = resumeOffset;
192         return this;
193     }
194 
195     /**
196      * Gets the timestamp when the transfer of this resource was started.
197      *
198      * @return The timestamp when the transfer of this resource was started.
199      */
200     public long getTransferStartTime() {
201         return startTime;
202     }
203 
204     /**
205      * Gets the trace information that describes the higher level request/operation during which this resource is
206      * transferred.
207      *
208      * @return The trace information about the higher level operation or {@code null} if none.
209      */
210     public RequestTrace getTrace() {
211         return trace;
212     }
213 
214     @Override
215     public String toString() {
216         return getRepositoryUrl() + getResourceName() + " <> " + getFile();
217     }
218 }