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.impl;
20  
21  import java.io.File;
22  import java.nio.file.Path;
23  
24  import org.eclipse.aether.RepositoryException;
25  import org.eclipse.aether.repository.RemoteRepository;
26  
27  /**
28   * A request to check if an update of an artifact/metadata from a remote repository is needed.
29   *
30   * @param <T>
31   * @param <E>
32   * @see UpdateCheckManager
33   * @provisional This type is provisional and can be changed, moved or removed without prior notice.
34   */
35  public final class UpdateCheck<T, E extends RepositoryException> {
36  
37      private long localLastUpdated;
38  
39      private T item;
40  
41      private Path path;
42  
43      private boolean fileValid = true;
44  
45      private String artifactPolicy;
46  
47      private String metadataPolicy;
48  
49      private RemoteRepository repository;
50  
51      private RemoteRepository authoritativeRepository;
52  
53      private boolean required;
54  
55      private E exception;
56  
57      /**
58       * Creates an uninitialized update check request.
59       */
60      public UpdateCheck() {}
61  
62      /**
63       * Gets the last-modified timestamp of the corresponding item produced by a local installation. If non-zero, a
64       * remote update will be surpressed if the local item is up-to-date, even if the remote item has not been cached
65       * locally.
66       *
67       * @return The last-modified timestamp of the corresponding item produced by a local installation or {@code 0} to
68       *         ignore any local item.
69       */
70      public long getLocalLastUpdated() {
71          return localLastUpdated;
72      }
73  
74      /**
75       * Sets the last-modified timestamp of the corresponding item produced by a local installation. If non-zero, a
76       * remote update will be surpressed if the local item is up-to-date, even if the remote item has not been cached
77       * locally.
78       *
79       * @param localLastUpdated The last-modified timestamp of the corresponding item produced by a local installation or
80       *            {@code 0} to ignore any local item.
81       * @return This object for chaining.
82       */
83      public UpdateCheck<T, E> setLocalLastUpdated(long localLastUpdated) {
84          this.localLastUpdated = localLastUpdated;
85          return this;
86      }
87  
88      /**
89       * Gets the item of the check.
90       *
91       * @return The item of the check, never {@code null}.
92       */
93      public T getItem() {
94          return item;
95      }
96  
97      /**
98       * Sets the item of the check.
99       *
100      * @param item The item of the check, must not be {@code null}.
101      * @return This object for chaining.
102      */
103     public UpdateCheck<T, E> setItem(T item) {
104         this.item = item;
105         return this;
106     }
107 
108     /**
109      * Returns the local file of the item.
110      *
111      * @return The local file of the item.
112      * @deprecated Use {@link #getPath()} instead.
113      */
114     @Deprecated
115     public File getFile() {
116         return path != null ? path.toFile() : null;
117     }
118 
119     /**
120      * Returns the local file of the item.
121      *
122      * @return The local file of the item.
123      * @since 2.0.0
124      */
125     public Path getPath() {
126         return path;
127     }
128 
129     /**
130      * Sets the local file of the item.
131      *
132      * @param file The file of the item, never {@code null} .
133      * @return This object for chaining.
134      * @deprecated Use {@link #setPath(Path)} instead.
135      */
136     @Deprecated
137     public UpdateCheck<T, E> setFile(File file) {
138         return setPath(file != null ? file.toPath() : null);
139     }
140 
141     /**
142      * Sets the local file of the item.
143      *
144      * @param path The file of the item, never {@code null} .
145      * @return This object for chaining.
146      * @since 2.0.0
147      */
148     public UpdateCheck<T, E> setPath(Path path) {
149         this.path = path;
150         return this;
151     }
152 
153     /**
154      * Indicates whether the local file given by {@link #getFile()}, if existent, should be considered valid or not. An
155      * invalid file is equivalent to a physically missing file.
156      *
157      * @return {@code true} if the file should be considered valid if existent, {@code false} if the file should be
158      *         treated as if it was missing.
159      */
160     public boolean isFileValid() {
161         return fileValid;
162     }
163 
164     /**
165      * Controls whether the local file given by {@link #getFile()}, if existent, should be considered valid or not. An
166      * invalid file is equivalent to a physically missing file.
167      *
168      * @param fileValid {@code true} if the file should be considered valid if existent, {@code false} if the file
169      *            should be treated as if it was missing.
170      * @return This object for chaining.
171      */
172     public UpdateCheck<T, E> setFileValid(boolean fileValid) {
173         this.fileValid = fileValid;
174         return this;
175     }
176 
177     /**
178      * Gets the policy to use for the artifact check.
179      *
180      * @return The policy to use for the artifact check.
181      * @see org.eclipse.aether.repository.RepositoryPolicy
182      * @since 2.0.0
183      */
184     public String getArtifactPolicy() {
185         return artifactPolicy;
186     }
187 
188     /**
189      * Gets the policy to use for the metadata check.
190      *
191      * @return The policy to use for the metadata check.
192      * @see org.eclipse.aether.repository.RepositoryPolicy
193      * @since 2.0.0
194      */
195     public String getMetadataPolicy() {
196         return metadataPolicy;
197     }
198 
199     /**
200      * Sets the artifact policy to use for the check.
201      *
202      * @param artifactPolicy The policy to use for the artifact check, may be {@code null}.
203      * @return This object for chaining.
204      * @see org.eclipse.aether.repository.RepositoryPolicy
205      * @since 2.0.0
206      */
207     public UpdateCheck<T, E> setArtifactPolicy(String artifactPolicy) {
208         this.artifactPolicy = artifactPolicy;
209         return this;
210     }
211 
212     /**
213      * Sets the metadata policy to use for the check.
214      *
215      * @param metadataPolicy The policy to use for the metadata check, may be {@code null}.
216      * @return This object for chaining.
217      * @see org.eclipse.aether.repository.RepositoryPolicy
218      * @since 2.0.0
219      */
220     public UpdateCheck<T, E> setMetadataPolicy(String metadataPolicy) {
221         this.metadataPolicy = metadataPolicy;
222         return this;
223     }
224 
225     /**
226      * Gets the repository from which a potential update/download will performed.
227      *
228      * @return The repository to use for the check.
229      */
230     public RemoteRepository getRepository() {
231         return repository;
232     }
233 
234     /**
235      * Sets the repository from which a potential update/download will performed.
236      *
237      * @param repository The repository to use for the check, must not be {@code null}.
238      * @return This object for chaining.
239      */
240     public UpdateCheck<T, E> setRepository(RemoteRepository repository) {
241         this.repository = repository;
242         return this;
243     }
244 
245     /**
246      * Gets the repository which ultimately hosts the metadata to update. This will be different from the repository
247      * given by {@link #getRepository()} in case the latter denotes a repository manager.
248      *
249      * @return The actual repository hosting the authoritative copy of the metadata to update, never {@code null} for a
250      *         metadata update check.
251      */
252     public RemoteRepository getAuthoritativeRepository() {
253         return authoritativeRepository != null ? authoritativeRepository : repository;
254     }
255 
256     /**
257      * Sets the repository which ultimately hosts the metadata to update. This will be different from the repository
258      * given by {@link #getRepository()} in case the latter denotes a repository manager.
259      *
260      * @param authoritativeRepository The actual repository hosting the authoritative copy of the metadata to update,
261      *            must not be {@code null} for a metadata update check.
262      * @return This object for chaining.
263      */
264     public UpdateCheck<T, E> setAuthoritativeRepository(RemoteRepository authoritativeRepository) {
265         this.authoritativeRepository = authoritativeRepository;
266         return this;
267     }
268 
269     /**
270      * Gets the result of a check, denoting whether the remote repository should be checked for updates.
271      *
272      * @return The result of a check.
273      */
274     public boolean isRequired() {
275         return required;
276     }
277 
278     /**
279      * Sets the result of an update check.
280      *
281      * @param required The result of an update check. In case of {@code false} and the local file given by
282      *            {@link #getFile()} does actually not exist, {@link #setException(RepositoryException)} should be used
283      *            to provide the previous/cached failure that explains the absence of the file.
284      * @return This object for chaining.
285      */
286     public UpdateCheck<T, E> setRequired(boolean required) {
287         this.required = required;
288         return this;
289     }
290 
291     /**
292      * Gets the exception that occurred during the update check.
293      *
294      * @return The occurred exception or {@code null} if the update check was successful.
295      */
296     public E getException() {
297         return exception;
298     }
299 
300     /**
301      * Sets the exception for this update check.
302      *
303      * @param exception The exception for this update check, may be {@code null} if the check was successful.
304      * @return This object for chaining.
305      */
306     public UpdateCheck<T, E> setException(E exception) {
307         this.exception = exception;
308         return this;
309     }
310 
311     @Override
312     public String toString() {
313         return getArtifactPolicy() + "/" + getMetadataPolicy() + ": " + getFile() + " < " + getRepository();
314     }
315 }