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.resolution;
020
021import org.eclipse.aether.RepositorySystem;
022import org.eclipse.aether.RequestTrace;
023import org.eclipse.aether.metadata.Metadata;
024import org.eclipse.aether.repository.RemoteRepository;
025
026/**
027 * A request to resolve metadata from either a remote repository or the local repository.
028 *
029 * @see RepositorySystem#resolveMetadata(org.eclipse.aether.RepositorySystemSession, java.util.Collection)
030 * @see Metadata#getFile()
031 */
032public final class MetadataRequest {
033
034    private Metadata metadata;
035
036    private RemoteRepository repository;
037
038    private String context = "";
039
040    private boolean deleteLocalCopyIfMissing;
041
042    private boolean favorLocalRepository;
043
044    private RequestTrace trace;
045
046    /**
047     * Creates an uninitialized request.
048     */
049    public MetadataRequest() {
050        // enables default constructor
051    }
052
053    /**
054     * Creates a request to resolve the specified metadata from the local repository.
055     *
056     * @param metadata The metadata to resolve, may be {@code null}.
057     */
058    public MetadataRequest(Metadata metadata) {
059        setMetadata(metadata);
060    }
061
062    /**
063     * Creates a request with the specified properties.
064     *
065     * @param metadata The metadata to resolve, may be {@code null}.
066     * @param repository The repository to resolve the metadata from, may be {@code null} to resolve from the local
067     *            repository.
068     * @param context The context in which this request is made, may be {@code null}.
069     */
070    public MetadataRequest(Metadata metadata, RemoteRepository repository, String context) {
071        setMetadata(metadata);
072        setRepository(repository);
073        setRequestContext(context);
074    }
075
076    /**
077     * Gets the metadata to resolve.
078     *
079     * @return The metadata or {@code null} if not set.
080     */
081    public Metadata getMetadata() {
082        return metadata;
083    }
084
085    /**
086     * Sets the metadata to resolve.
087     *
088     * @param metadata The metadata, may be {@code null}.
089     * @return This request for chaining, never {@code null}.
090     */
091    public MetadataRequest setMetadata(Metadata metadata) {
092        this.metadata = metadata;
093        return this;
094    }
095
096    /**
097     * Gets the repository from which the metadata should be resolved.
098     *
099     * @return The repository or {@code null} to resolve from the local repository.
100     */
101    public RemoteRepository getRepository() {
102        return repository;
103    }
104
105    /**
106     * Sets the repository from which the metadata should be resolved.
107     *
108     * @param repository The repository, may be {@code null} to resolve from the local repository.
109     * @return This request for chaining, never {@code null}.
110     */
111    public MetadataRequest setRepository(RemoteRepository repository) {
112        this.repository = repository;
113        return this;
114    }
115
116    /**
117     * Gets the context in which this request is made.
118     *
119     * @return The context, never {@code null}.
120     */
121    public String getRequestContext() {
122        return context;
123    }
124
125    /**
126     * Sets the context in which this request is made.
127     *
128     * @param context The context, may be {@code null}.
129     * @return This request for chaining, never {@code null}.
130     */
131    public MetadataRequest setRequestContext(String context) {
132        this.context = (context != null) ? context : "";
133        return this;
134    }
135
136    /**
137     * Indicates whether the locally cached copy of the metadata should be removed if the corresponding file does not
138     * exist (any more) in the remote repository.
139     *
140     * @return {@code true} if locally cached metadata should be deleted if no corresponding remote file exists,
141     *         {@code false} to keep the local copy.
142     */
143    public boolean isDeleteLocalCopyIfMissing() {
144        return deleteLocalCopyIfMissing;
145    }
146
147    /**
148     * Controls whether the locally cached copy of the metadata should be removed if the corresponding file does not
149     * exist (any more) in the remote repository.
150     *
151     * @param deleteLocalCopyIfMissing {@code true} if locally cached metadata should be deleted if no corresponding
152     *            remote file exists, {@code false} to keep the local copy.
153     * @return This request for chaining, never {@code null}.
154     */
155    public MetadataRequest setDeleteLocalCopyIfMissing(boolean deleteLocalCopyIfMissing) {
156        this.deleteLocalCopyIfMissing = deleteLocalCopyIfMissing;
157        return this;
158    }
159
160    /**
161     * Indicates whether the metadata resolution should be suppressed if the corresponding metadata of the local
162     * repository is up-to-date according to the update policy of the remote repository. In this case, the metadata
163     * resolution will even be suppressed if no local copy of the remote metadata exists yet.
164     *
165     * @return {@code true} to suppress resolution of remote metadata if the corresponding metadata of the local
166     *         repository is up-to-date, {@code false} to resolve the remote metadata normally according to the update
167     *         policy.
168     */
169    public boolean isFavorLocalRepository() {
170        return favorLocalRepository;
171    }
172
173    /**
174     * Controls resolution of remote metadata when already corresponding metadata of the local repository exists. In
175     * cases where the local repository's metadata is sufficient and going to be preferred, resolution of the remote
176     * metadata can be suppressed to avoid unnecessary network access.
177     *
178     * @param favorLocalRepository {@code true} to suppress resolution of remote metadata if the corresponding metadata
179     *            of the local repository is up-to-date, {@code false} to resolve the remote metadata normally according
180     *            to the update policy.
181     * @return This request for chaining, never {@code null}.
182     */
183    public MetadataRequest setFavorLocalRepository(boolean favorLocalRepository) {
184        this.favorLocalRepository = favorLocalRepository;
185        return this;
186    }
187
188    /**
189     * Gets the trace information that describes the higher level request/operation in which this request is issued.
190     *
191     * @return The trace information about the higher level operation or {@code null} if none.
192     */
193    public RequestTrace getTrace() {
194        return trace;
195    }
196
197    /**
198     * Sets the trace information that describes the higher level request/operation in which this request is issued.
199     *
200     * @param trace The trace information about the higher level operation, may be {@code null}.
201     * @return This request for chaining, never {@code null}.
202     */
203    public MetadataRequest setTrace(RequestTrace trace) {
204        this.trace = trace;
205        return this;
206    }
207
208    @Override
209    public String toString() {
210        return getMetadata() + " < " + getRepository();
211    }
212}