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.spi.connector;
20  
21  import java.io.File;
22  import java.nio.file.Path;
23  import java.util.Collection;
24  import java.util.Collections;
25  import java.util.List;
26  
27  import org.eclipse.aether.RequestTrace;
28  import org.eclipse.aether.artifact.Artifact;
29  import org.eclipse.aether.repository.RemoteRepository;
30  import org.eclipse.aether.transfer.ArtifactTransferException;
31  import org.eclipse.aether.transfer.TransferListener;
32  
33  /**
34   * A download of an artifact from a remote repository. A repository connector processing this download has to use
35   * {@link #setException(ArtifactTransferException)} and {@link #setSupportedContexts(Collection)} (if applicable) to
36   * report the results of the transfer.
37   */
38  public final class ArtifactDownload extends ArtifactTransfer {
39  
40      private boolean existenceCheck;
41  
42      private String checksumPolicy = "";
43  
44      private String context = "";
45  
46      private Collection<String> contexts;
47  
48      private List<RemoteRepository> repositories = Collections.emptyList();
49  
50      /**
51       * Creates a new uninitialized download.
52       */
53      public ArtifactDownload() {
54          // enables default constructor
55      }
56  
57      /**
58       * Creates a new download with the specified properties.
59       *
60       * @param artifact The artifact to download, may be {@code null}.
61       * @param context The context in which this download is performed, may be {@code null}.
62       * @param file The local file to download the artifact to, may be {@code null}.
63       * @param checksumPolicy The checksum policy, may be {@code null}.
64       * @deprecated Use {@link ArtifactDownload(Artifact, String, Path, String)} instead.
65       */
66      @Deprecated
67      public ArtifactDownload(Artifact artifact, String context, File file, String checksumPolicy) {
68          setArtifact(artifact);
69          setRequestContext(context);
70          setFile(file);
71          setChecksumPolicy(checksumPolicy);
72      }
73  
74      /**
75       * Creates a new download with the specified properties.
76       *
77       * @param artifact The artifact to download, may be {@code null}.
78       * @param context The context in which this download is performed, may be {@code null}.
79       * @param path The local file to download the artifact to, may be {@code null}.
80       * @param checksumPolicy The checksum policy, may be {@code null}.
81       * @deprecated Use {@link ArtifactDownload(Artifact, String, Path, String)} instead.
82       * @since 2.0.0
83       */
84      public ArtifactDownload(Artifact artifact, String context, Path path, String checksumPolicy) {
85          setArtifact(artifact);
86          setRequestContext(context);
87          setPath(path);
88          setChecksumPolicy(checksumPolicy);
89      }
90  
91      @Override
92      public ArtifactDownload setArtifact(Artifact artifact) {
93          super.setArtifact(artifact);
94          return this;
95      }
96  
97      @Deprecated
98      @Override
99      public ArtifactDownload setFile(File file) {
100         super.setFile(file);
101         return this;
102     }
103 
104     @Override
105     public ArtifactDownload setPath(Path path) {
106         super.setPath(path);
107         return this;
108     }
109 
110     /**
111      * Indicates whether this transfer shall only verify the existence of the artifact in the remote repository rather
112      * than actually downloading the file. Just like with an actual transfer, a connector is expected to signal the
113      * non-existence of the artifact by associating an {@link org.eclipse.aether.transfer.ArtifactNotFoundException
114      * ArtifactNotFoundException} with this download. <em>Note:</em> If an existence check is requested,
115      * {@link #getFile()} may be {@code null}, i.e. the connector must not try to access the local file.
116      *
117      * @return {@code true} if only the artifact existence shall be verified, {@code false} to actually download the
118      *         artifact.
119      */
120     public boolean isExistenceCheck() {
121         return existenceCheck;
122     }
123 
124     /**
125      * Controls whether this transfer shall only verify the existence of the artifact in the remote repository rather
126      * than actually downloading the file.
127      *
128      * @param existenceCheck {@code true} if only the artifact existence shall be verified, {@code false} to actually
129      *            download the artifact.
130      * @return This transfer for chaining, never {@code null}.
131      */
132     public ArtifactDownload setExistenceCheck(boolean existenceCheck) {
133         this.existenceCheck = existenceCheck;
134         return this;
135     }
136 
137     /**
138      * Gets the checksum policy for this transfer.
139      *
140      * @return The checksum policy, never {@code null}.
141      */
142     public String getChecksumPolicy() {
143         return checksumPolicy;
144     }
145 
146     /**
147      * Sets the checksum policy for this transfer.
148      *
149      * @param checksumPolicy The checksum policy, may be {@code null}.
150      * @return This transfer for chaining, never {@code null}.
151      */
152     public ArtifactDownload setChecksumPolicy(String checksumPolicy) {
153         this.checksumPolicy = (checksumPolicy != null) ? checksumPolicy : "";
154         return this;
155     }
156 
157     /**
158      * Gets the context of this transfer.
159      *
160      * @return The context id, never {@code null}.
161      */
162     public String getRequestContext() {
163         return context;
164     }
165 
166     /**
167      * Sets the context of this transfer.
168      *
169      * @param context The context id, may be {@code null}.
170      * @return This transfer for chaining, never {@code null}.
171      */
172     public ArtifactDownload setRequestContext(String context) {
173         this.context = (context != null) ? context : "";
174         return this;
175     }
176 
177     /**
178      * Gets the set of request contexts in which the artifact is generally available. Repository managers can indicate
179      * that an artifact is available in more than the requested context to avoid future remote trips for the same
180      * artifact in a different context.
181      *
182      * @return The set of requests context in which the artifact is available, never {@code null}.
183      */
184     public Collection<String> getSupportedContexts() {
185         return (contexts != null) ? contexts : Collections.singleton(context);
186     }
187 
188     /**
189      * Sets the set of request contexts in which the artifact is generally available. Repository managers can indicate
190      * that an artifact is available in more than the requested context to avoid future remote trips for the same
191      * artifact in a different context. The set of supported contexts defaults to the original request context if not
192      * overridden by the repository connector.
193      *
194      * @param contexts The set of requests context in which the artifact is available, may be {@code null}.
195      * @return This transfer for chaining, never {@code null}.
196      */
197     public ArtifactDownload setSupportedContexts(Collection<String> contexts) {
198         if (contexts == null || contexts.isEmpty()) {
199             this.contexts = Collections.singleton(context);
200         } else {
201             this.contexts = contexts;
202         }
203         return this;
204     }
205 
206     /**
207      * Gets the remote repositories that are being aggregated by the physically contacted remote repository (i.e. a
208      * repository manager).
209      *
210      * @return The remote repositories being aggregated, never {@code null}.
211      */
212     public List<RemoteRepository> getRepositories() {
213         return repositories;
214     }
215 
216     /**
217      * Sets the remote repositories that are being aggregated by the physically contacted remote repository (i.e. a
218      * repository manager).
219      *
220      * @param repositories The remote repositories being aggregated, may be {@code null}.
221      * @return This transfer for chaining, never {@code null}.
222      */
223     public ArtifactDownload setRepositories(List<RemoteRepository> repositories) {
224         if (repositories == null) {
225             this.repositories = Collections.emptyList();
226         } else {
227             this.repositories = repositories;
228         }
229         return this;
230     }
231 
232     @Override
233     public ArtifactDownload setException(ArtifactTransferException exception) {
234         super.setException(exception);
235         return this;
236     }
237 
238     @Override
239     public ArtifactDownload setListener(TransferListener listener) {
240         super.setListener(listener);
241         return this;
242     }
243 
244     @Override
245     public ArtifactDownload setTrace(RequestTrace trace) {
246         super.setTrace(trace);
247         return this;
248     }
249 
250     @Override
251     public String toString() {
252         return getArtifact() + " - " + (isExistenceCheck() ? "?" : "") + getPath();
253     }
254 }