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