001package org.eclipse.aether.resolution;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 * 
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 * 
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import org.eclipse.aether.RepositorySystem;
023import org.eclipse.aether.RepositorySystemSession;
024import org.eclipse.aether.RequestTrace;
025import org.eclipse.aether.metadata.Metadata;
026import org.eclipse.aether.repository.RemoteRepository;
027
028/**
029 * A request to resolve metadata from either a remote repository or the local repository.
030 * 
031 * @see RepositorySystem#resolveMetadata(RepositorySystemSession, java.util.Collection)
032 * @see Metadata#getFile()
033 */
034public final class MetadataRequest
035{
036
037    private Metadata metadata;
038
039    private RemoteRepository repository;
040
041    private String context = "";
042
043    private boolean deleteLocalCopyIfMissing;
044
045    private boolean favorLocalRepository;
046
047    private RequestTrace trace;
048
049    /**
050     * Creates an uninitialized request.
051     */
052    public MetadataRequest()
053    {
054        // enables default constructor
055    }
056
057    /**
058     * Creates a request to resolve the specified metadata from the local repository.
059     * 
060     * @param metadata The metadata to resolve, may be {@code null}.
061     */
062    public MetadataRequest( Metadata metadata )
063    {
064        setMetadata( metadata );
065    }
066
067    /**
068     * Creates a request with the specified properties.
069     * 
070     * @param metadata The metadata to resolve, may be {@code null}.
071     * @param repository The repository to resolve the metadata from, may be {@code null} to resolve from the local
072     *            repository.
073     * @param context The context in which this request is made, may be {@code null}.
074     */
075    public MetadataRequest( Metadata metadata, RemoteRepository repository, String context )
076    {
077        setMetadata( metadata );
078        setRepository( repository );
079        setRequestContext( context );
080    }
081
082    /**
083     * Gets the metadata to resolve.
084     * 
085     * @return The metadata or {@code null} if not set.
086     */
087    public Metadata getMetadata()
088    {
089        return metadata;
090    }
091
092    /**
093     * Sets the metadata to resolve.
094     * 
095     * @param metadata The metadata, may be {@code null}.
096     * @return This request for chaining, never {@code null}.
097     */
098    public MetadataRequest setMetadata( Metadata metadata )
099    {
100        this.metadata = metadata;
101        return this;
102    }
103
104    /**
105     * Gets the repository from which the metadata should be resolved.
106     * 
107     * @return The repository or {@code null} to resolve from the local repository.
108     */
109    public RemoteRepository getRepository()
110    {
111        return repository;
112    }
113
114    /**
115     * Sets the repository from which the metadata should be resolved.
116     * 
117     * @param repository The repository, may be {@code null} to resolve from the local repository.
118     * @return This request for chaining, never {@code null}.
119     */
120    public MetadataRequest setRepository( RemoteRepository repository )
121    {
122        this.repository = repository;
123        return this;
124    }
125
126    /**
127     * Gets the context in which this request is made.
128     * 
129     * @return The context, never {@code null}.
130     */
131    public String getRequestContext()
132    {
133        return context;
134    }
135
136    /**
137     * Sets the context in which this request is made.
138     * 
139     * @param context The context, may be {@code null}.
140     * @return This request for chaining, never {@code null}.
141     */
142    public MetadataRequest setRequestContext( String context )
143    {
144        this.context = ( context != null ) ? context : "";
145        return this;
146    }
147
148    /**
149     * Indicates whether the locally cached copy of the metadata should be removed if the corresponding file does not
150     * exist (any more) in the remote repository.
151     * 
152     * @return {@code true} if locally cached metadata should be deleted if no corresponding remote file exists,
153     *         {@code false} to keep the local copy.
154     */
155    public boolean isDeleteLocalCopyIfMissing()
156    {
157        return deleteLocalCopyIfMissing;
158    }
159
160    /**
161     * Controls whether the locally cached copy of the metadata should be removed if the corresponding file does not
162     * exist (any more) in the remote repository.
163     * 
164     * @param deleteLocalCopyIfMissing {@code true} if locally cached metadata should be deleted if no corresponding
165     *            remote file exists, {@code false} to keep the local copy.
166     * @return This request for chaining, never {@code null}.
167     */
168    public MetadataRequest setDeleteLocalCopyIfMissing( boolean deleteLocalCopyIfMissing )
169    {
170        this.deleteLocalCopyIfMissing = deleteLocalCopyIfMissing;
171        return this;
172    }
173
174    /**
175     * Indicates whether the metadata resolution should be suppressed if the corresponding metadata of the local
176     * repository is up-to-date according to the update policy of the remote repository. In this case, the metadata
177     * resolution will even be suppressed if no local copy of the remote metadata exists yet.
178     * 
179     * @return {@code true} to suppress resolution of remote metadata if the corresponding metadata of the local
180     *         repository is up-to-date, {@code false} to resolve the remote metadata normally according to the update
181     *         policy.
182     */
183    public boolean isFavorLocalRepository()
184    {
185        return favorLocalRepository;
186    }
187
188    /**
189     * Controls resolution of remote metadata when already corresponding metadata of the local repository exists. In
190     * cases where the local repository's metadata is sufficient and going to be preferred, resolution of the remote
191     * metadata can be suppressed to avoid unnecessary network access.
192     * 
193     * @param favorLocalRepository {@code true} to suppress resolution of remote metadata if the corresponding metadata
194     *            of the local repository is up-to-date, {@code false} to resolve the remote metadata normally according
195     *            to the update policy.
196     * @return This request for chaining, never {@code null}.
197     */
198    public MetadataRequest setFavorLocalRepository( boolean favorLocalRepository )
199    {
200        this.favorLocalRepository = favorLocalRepository;
201        return this;
202    }
203
204    /**
205     * Gets the trace information that describes the higher level request/operation in which this request is issued.
206     * 
207     * @return The trace information about the higher level operation or {@code null} if none.
208     */
209    public RequestTrace getTrace()
210    {
211        return trace;
212    }
213
214    /**
215     * Sets the trace information that describes the higher level request/operation in which this request is issued.
216     * 
217     * @param trace The trace information about the higher level operation, may be {@code null}.
218     * @return This request for chaining, never {@code null}.
219     */
220    public MetadataRequest setTrace( RequestTrace trace )
221    {
222        this.trace = trace;
223        return this;
224    }
225
226    @Override
227    public String toString()
228    {
229        return getMetadata() + " < " + getRepository();
230    }
231
232}