001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether.spi.connector;
020
021import java.io.File;
022import java.nio.file.Path;
023import java.util.Collection;
024import java.util.Collections;
025import java.util.List;
026
027import org.eclipse.aether.RequestTrace;
028import org.eclipse.aether.artifact.Artifact;
029import org.eclipse.aether.repository.RemoteRepository;
030import org.eclipse.aether.transfer.ArtifactTransferException;
031import org.eclipse.aether.transfer.TransferListener;
032
033/**
034 * A download of an artifact from a remote repository. A repository connector processing this download has to use
035 * {@link #setException(ArtifactTransferException)} and {@link #setSupportedContexts(Collection)} (if applicable) to
036 * report the results of the transfer.
037 */
038public final class ArtifactDownload extends ArtifactTransfer {
039
040    private boolean existenceCheck;
041
042    private String checksumPolicy = "";
043
044    private String context = "";
045
046    private Collection<String> contexts;
047
048    private List<RemoteRepository> repositories = Collections.emptyList();
049
050    /**
051     * Creates a new uninitialized download.
052     */
053    public ArtifactDownload() {
054        // enables default constructor
055    }
056
057    /**
058     * Creates a new download with the specified properties.
059     *
060     * @param artifact The artifact to download, may be {@code null}.
061     * @param context The context in which this download is performed, may be {@code null}.
062     * @param file The local file to download the artifact to, may be {@code null}.
063     * @param checksumPolicy The checksum policy, may be {@code null}.
064     * @deprecated Use {@link ArtifactDownload(Artifact, String, Path, String)} instead.
065     */
066    @Deprecated
067    public ArtifactDownload(Artifact artifact, String context, File file, String checksumPolicy) {
068        setArtifact(artifact);
069        setRequestContext(context);
070        setFile(file);
071        setChecksumPolicy(checksumPolicy);
072    }
073
074    /**
075     * Creates a new download with the specified properties.
076     *
077     * @param artifact The artifact to download, may be {@code null}.
078     * @param context The context in which this download is performed, may be {@code null}.
079     * @param path The local file to download the artifact to, may be {@code null}.
080     * @param checksumPolicy The checksum policy, may be {@code null}.
081     * @deprecated Use {@link ArtifactDownload(Artifact, String, Path, String)} instead.
082     * @since 2.0.0
083     */
084    public ArtifactDownload(Artifact artifact, String context, Path path, String checksumPolicy) {
085        setArtifact(artifact);
086        setRequestContext(context);
087        setPath(path);
088        setChecksumPolicy(checksumPolicy);
089    }
090
091    @Override
092    public ArtifactDownload setArtifact(Artifact artifact) {
093        super.setArtifact(artifact);
094        return this;
095    }
096
097    @Deprecated
098    @Override
099    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}