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