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