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;
20  
21  import java.io.File;
22  import java.nio.file.Path;
23  import java.util.Collections;
24  import java.util.List;
25  
26  import org.eclipse.aether.artifact.Artifact;
27  import org.eclipse.aether.metadata.Metadata;
28  import org.eclipse.aether.repository.ArtifactRepository;
29  
30  import static java.util.Objects.requireNonNull;
31  
32  /**
33   * An event describing an action performed by the repository system. Note that events which indicate the end of an
34   * action like {@link EventType#ARTIFACT_RESOLVED} are generally fired in both the success and the failure case. Use
35   * {@link #getException()} to check whether an event denotes success or failure.
36   *
37   * @see RepositoryListener
38   * @see RepositoryEvent.Builder
39   */
40  public final class RepositoryEvent {
41  
42      /**
43       * The type of the repository event.
44       */
45      public enum EventType {
46  
47          /**
48           * @see RepositoryListener#artifactDescriptorInvalid(RepositoryEvent)
49           */
50          ARTIFACT_DESCRIPTOR_INVALID,
51  
52          /**
53           * @see RepositoryListener#artifactDescriptorMissing(RepositoryEvent)
54           */
55          ARTIFACT_DESCRIPTOR_MISSING,
56  
57          /**
58           * @see RepositoryListener#metadataInvalid(RepositoryEvent)
59           */
60          METADATA_INVALID,
61  
62          /**
63           * @see RepositoryListener#artifactResolving(RepositoryEvent)
64           */
65          ARTIFACT_RESOLVING,
66  
67          /**
68           * @see RepositoryListener#artifactResolved(RepositoryEvent)
69           */
70          ARTIFACT_RESOLVED,
71  
72          /**
73           * @see RepositoryListener#metadataResolving(RepositoryEvent)
74           */
75          METADATA_RESOLVING,
76  
77          /**
78           * @see RepositoryListener#metadataResolved(RepositoryEvent)
79           */
80          METADATA_RESOLVED,
81  
82          /**
83           * @see RepositoryListener#artifactDownloading(RepositoryEvent)
84           */
85          ARTIFACT_DOWNLOADING,
86  
87          /**
88           * @see RepositoryListener#artifactDownloaded(RepositoryEvent)
89           */
90          ARTIFACT_DOWNLOADED,
91  
92          /**
93           * @see RepositoryListener#metadataDownloading(RepositoryEvent)
94           */
95          METADATA_DOWNLOADING,
96  
97          /**
98           * @see RepositoryListener#metadataDownloaded(RepositoryEvent)
99           */
100         METADATA_DOWNLOADED,
101 
102         /**
103          * @see RepositoryListener#artifactInstalling(RepositoryEvent)
104          */
105         ARTIFACT_INSTALLING,
106 
107         /**
108          * @see RepositoryListener#artifactInstalled(RepositoryEvent)
109          */
110         ARTIFACT_INSTALLED,
111 
112         /**
113          * @see RepositoryListener#metadataInstalling(RepositoryEvent)
114          */
115         METADATA_INSTALLING,
116 
117         /**
118          * @see RepositoryListener#metadataInstalled(RepositoryEvent)
119          */
120         METADATA_INSTALLED,
121 
122         /**
123          * @see RepositoryListener#artifactDeploying(RepositoryEvent)
124          */
125         ARTIFACT_DEPLOYING,
126 
127         /**
128          * @see RepositoryListener#artifactDeployed(RepositoryEvent)
129          */
130         ARTIFACT_DEPLOYED,
131 
132         /**
133          * @see RepositoryListener#metadataDeploying(RepositoryEvent)
134          */
135         METADATA_DEPLOYING,
136 
137         /**
138          * @see RepositoryListener#metadataDeployed(RepositoryEvent)
139          */
140         METADATA_DEPLOYED
141     }
142 
143     private final EventType type;
144 
145     private final RepositorySystemSession session;
146 
147     private final Artifact artifact;
148 
149     private final Metadata metadata;
150 
151     private final ArtifactRepository repository;
152 
153     private final Path path;
154 
155     private final List<Exception> exceptions;
156 
157     private final RequestTrace trace;
158 
159     RepositoryEvent(Builder builder) {
160         type = builder.type;
161         session = builder.session;
162         artifact = builder.artifact;
163         metadata = builder.metadata;
164         repository = builder.repository;
165         path = builder.path;
166         exceptions = builder.exceptions;
167         trace = builder.trace;
168     }
169 
170     /**
171      * Gets the type of the event.
172      *
173      * @return The type of the event, never {@code null}.
174      */
175     public EventType getType() {
176         return type;
177     }
178 
179     /**
180      * Gets the repository system session during which the event occurred.
181      *
182      * @return The repository system session during which the event occurred, never {@code null}.
183      */
184     public RepositorySystemSession getSession() {
185         return session;
186     }
187 
188     /**
189      * Gets the artifact involved in the event (if any).
190      *
191      * @return The involved artifact or {@code null} if none.
192      */
193     public Artifact getArtifact() {
194         return artifact;
195     }
196 
197     /**
198      * Gets the metadata involved in the event (if any).
199      *
200      * @return The involved metadata or {@code null} if none.
201      */
202     public Metadata getMetadata() {
203         return metadata;
204     }
205 
206     /**
207      * Gets the file involved in the event (if any).
208      *
209      * @return The involved file or {@code null} if none.
210      * @deprecated Use {@link #getPath()} instead.
211      */
212     @Deprecated
213     public File getFile() {
214         return path != null ? path.toFile() : null;
215     }
216 
217     /**
218      * Gets the file involved in the event (if any).
219      *
220      * @return The involved file or {@code null} if none.
221      * @since 2.0.0
222      */
223     public Path getPath() {
224         return path;
225     }
226 
227     /**
228      * Gets the repository involved in the event (if any).
229      *
230      * @return The involved repository or {@code null} if none.
231      */
232     public ArtifactRepository getRepository() {
233         return repository;
234     }
235 
236     /**
237      * Gets the exception that caused the event (if any). As a rule of thumb, an event accompanied by an exception
238      * indicates a failure of the corresponding action. If multiple exceptions occurred, this method returns the first
239      * exception.
240      *
241      * @return The exception or {@code null} if none.
242      */
243     public Exception getException() {
244         return exceptions.isEmpty() ? null : exceptions.get(0);
245     }
246 
247     /**
248      * Gets the exceptions that caused the event (if any). As a rule of thumb, an event accompanied by exceptions
249      * indicates a failure of the corresponding action.
250      *
251      * @return The exceptions, never {@code null}.
252      */
253     public List<Exception> getExceptions() {
254         return exceptions;
255     }
256 
257     /**
258      * Gets the trace information about the request during which the event occurred.
259      *
260      * @return The trace information or {@code null} if none.
261      */
262     public RequestTrace getTrace() {
263         return trace;
264     }
265 
266     @Override
267     public String toString() {
268         StringBuilder buffer = new StringBuilder(256);
269         buffer.append(getType());
270         if (getArtifact() != null) {
271             buffer.append(" ").append(getArtifact());
272         }
273         if (getMetadata() != null) {
274             buffer.append(" ").append(getMetadata());
275         }
276         if (getPath() != null) {
277             buffer.append(" (").append(getPath()).append(")");
278         }
279         if (getRepository() != null) {
280             buffer.append(" @ ").append(getRepository());
281         }
282         return buffer.toString();
283     }
284 
285     /**
286      * A builder to create events.
287      */
288     public static final class Builder {
289 
290         final EventType type;
291 
292         final RepositorySystemSession session;
293 
294         Artifact artifact;
295 
296         Metadata metadata;
297 
298         ArtifactRepository repository;
299 
300         Path path;
301 
302         List<Exception> exceptions = Collections.emptyList();
303 
304         RequestTrace trace;
305 
306         /**
307          * Creates a new event builder for the specified session and event type.
308          *
309          * @param session The repository system session, must not be {@code null}.
310          * @param type The type of the event, must not be {@code null}.
311          */
312         public Builder(RepositorySystemSession session, EventType type) {
313             this.session = requireNonNull(session, "session cannot be null");
314             this.type = requireNonNull(type, "event type cannot be null");
315         }
316 
317         /**
318          * Sets the artifact involved in the event.
319          *
320          * @param artifact The involved artifact, may be {@code null}.
321          * @return This event builder for chaining, never {@code null}.
322          */
323         public Builder setArtifact(Artifact artifact) {
324             this.artifact = artifact;
325             return this;
326         }
327 
328         /**
329          * Sets the metadata involved in the event.
330          *
331          * @param metadata The involved metadata, may be {@code null}.
332          * @return This event builder for chaining, never {@code null}.
333          */
334         public Builder setMetadata(Metadata metadata) {
335             this.metadata = metadata;
336             return this;
337         }
338 
339         /**
340          * Sets the repository involved in the event.
341          *
342          * @param repository The involved repository, may be {@code null}.
343          * @return This event builder for chaining, never {@code null}.
344          */
345         public Builder setRepository(ArtifactRepository repository) {
346             this.repository = repository;
347             return this;
348         }
349 
350         /**
351          * Sets the file involved in the event.
352          *
353          * @param file The involved file, may be {@code null}.
354          * @return This event builder for chaining, never {@code null}.
355          * @deprecated Use {@link #setPath(Path)} instead.
356          */
357         @Deprecated
358         public Builder setFile(File file) {
359             return setPath(file != null ? file.toPath() : null);
360         }
361 
362         /**
363          * Sets the file involved in the event.
364          *
365          * @param path The involved file, may be {@code null}.
366          * @return This event builder for chaining, never {@code null}.
367          * @since 2.0.0
368          */
369         public Builder setPath(Path path) {
370             this.path = path;
371             return this;
372         }
373 
374         /**
375          * Sets the exception causing the event.
376          *
377          * @param exception The exception causing the event, may be {@code null}.
378          * @return This event builder for chaining, never {@code null}.
379          */
380         public Builder setException(Exception exception) {
381             if (exception != null) {
382                 this.exceptions = Collections.singletonList(exception);
383             } else {
384                 this.exceptions = Collections.emptyList();
385             }
386             return this;
387         }
388 
389         /**
390          * Sets the exceptions causing the event.
391          *
392          * @param exceptions The exceptions causing the event, may be {@code null}.
393          * @return This event builder for chaining, never {@code null}.
394          */
395         public Builder setExceptions(List<Exception> exceptions) {
396             if (exceptions != null) {
397                 this.exceptions = exceptions;
398             } else {
399                 this.exceptions = Collections.emptyList();
400             }
401             return this;
402         }
403 
404         /**
405          * Sets the trace information about the request during which the event occurred.
406          *
407          * @param trace The trace information, may be {@code null}.
408          * @return This event builder for chaining, never {@code null}.
409          */
410         public Builder setTrace(RequestTrace trace) {
411             this.trace = trace;
412             return this;
413         }
414 
415         /**
416          * Builds a new event from the current values of this builder. The state of the builder itself remains
417          * unchanged.
418          *
419          * @return The event, never {@code null}.
420          */
421         public RepositoryEvent build() {
422             return new RepositoryEvent(this);
423         }
424     }
425 }