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