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
26 import org.eclipse.aether.artifact.Artifact;
27 import org.eclipse.aether.metadata.Metadata;
28 import org.eclipse.aether.repository.ArtifactRepository;
29
30 /**
31 * An event describing an action performed by the repository system. Note that events which indicate the end of an
32 * action like {@link EventType#ARTIFACT_RESOLVED} are generally fired in both the success and the failure case. Use
33 * {@link #getException()} to check whether an event denotes success or failure.
34 *
35 * @see RepositoryListener
36 * @see RepositoryEvent.Builder
37 */
38 public final class RepositoryEvent
39 {
40
41 /**
42 * The type of the repository event.
43 */
44 public enum EventType
45 {
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
144 private final EventType type;
145
146 private final RepositorySystemSession session;
147
148 private final Artifact artifact;
149
150 private final Metadata metadata;
151
152 private final ArtifactRepository repository;
153
154 private final File file;
155
156 private final List<Exception> exceptions;
157
158 private final RequestTrace trace;
159
160 RepositoryEvent( Builder builder )
161 {
162 type = builder.type;
163 session = builder.session;
164 artifact = builder.artifact;
165 metadata = builder.metadata;
166 repository = builder.repository;
167 file = builder.file;
168 exceptions = builder.exceptions;
169 trace = builder.trace;
170 }
171
172 /**
173 * Gets the type of the event.
174 *
175 * @return The type of the event, never {@code null}.
176 */
177 public EventType getType()
178 {
179 return type;
180 }
181
182 /**
183 * Gets the repository system session during which the event occurred.
184 *
185 * @return The repository system session during which the event occurred, never {@code null}.
186 */
187 public RepositorySystemSession getSession()
188 {
189 return session;
190 }
191
192 /**
193 * Gets the artifact involved in the event (if any).
194 *
195 * @return The involved artifact or {@code null} if none.
196 */
197 public Artifact getArtifact()
198 {
199 return artifact;
200 }
201
202 /**
203 * Gets the metadata involved in the event (if any).
204 *
205 * @return The involved metadata or {@code null} if none.
206 */
207 public Metadata getMetadata()
208 {
209 return metadata;
210 }
211
212 /**
213 * Gets the file involved in the event (if any).
214 *
215 * @return The involved file or {@code null} if none.
216 */
217 public File getFile()
218 {
219 return file;
220 }
221
222 /**
223 * Gets the repository involved in the event (if any).
224 *
225 * @return The involved repository or {@code null} if none.
226 */
227 public ArtifactRepository getRepository()
228 {
229 return repository;
230 }
231
232 /**
233 * Gets the exception that caused the event (if any). As a rule of thumb, an event accompanied by an exception
234 * indicates a failure of the corresponding action. If multiple exceptions occurred, this method returns the first
235 * exception.
236 *
237 * @return The exception or {@code null} if none.
238 */
239 public Exception getException()
240 {
241 return exceptions.isEmpty() ? null : exceptions.get( 0 );
242 }
243
244 /**
245 * Gets the exceptions that caused the event (if any). As a rule of thumb, an event accompanied by exceptions
246 * indicates a failure of the corresponding action.
247 *
248 * @return The exceptions, never {@code null}.
249 */
250 public List<Exception> getExceptions()
251 {
252 return exceptions;
253 }
254
255 /**
256 * Gets the trace information about the request during which the event occurred.
257 *
258 * @return The trace information or {@code null} if none.
259 */
260 public RequestTrace getTrace()
261 {
262 return trace;
263 }
264
265 @Override
266 public String toString()
267 {
268 StringBuilder buffer = new StringBuilder( 256 );
269 buffer.append( getType() );
270 if ( getArtifact() != null )
271 {
272 buffer.append( " " ).append( getArtifact() );
273 }
274 if ( getMetadata() != null )
275 {
276 buffer.append( " " ).append( getMetadata() );
277 }
278 if ( getFile() != null )
279 {
280 buffer.append( " (" ).append( getFile() ).append( ")" );
281 }
282 if ( getRepository() != null )
283 {
284 buffer.append( " @ " ).append( getRepository() );
285 }
286 return buffer.toString();
287 }
288
289 /**
290 * A builder to create events.
291 */
292 public static final class Builder
293 {
294
295 EventType type;
296
297 RepositorySystemSession session;
298
299 Artifact artifact;
300
301 Metadata metadata;
302
303 ArtifactRepository repository;
304
305 File file;
306
307 List<Exception> exceptions = Collections.emptyList();
308
309 RequestTrace trace;
310
311 /**
312 * Creates a new event builder for the specified session and event type.
313 *
314 * @param session The repository system session, must not be {@code null}.
315 * @param type The type of the event, must not be {@code null}.
316 */
317 public Builder( RepositorySystemSession session, EventType type )
318 {
319 if ( session == null )
320 {
321 throw new IllegalArgumentException( "session not specified" );
322 }
323 this.session = session;
324 if ( type == null )
325 {
326 throw new IllegalArgumentException( "event type not specified" );
327 }
328 this.type = type;
329 }
330
331 /**
332 * Sets the artifact involved in the event.
333 *
334 * @param artifact The involved artifact, may be {@code null}.
335 * @return This event builder for chaining, never {@code null}.
336 */
337 public Builder setArtifact( Artifact artifact )
338 {
339 this.artifact = artifact;
340 return this;
341 }
342
343 /**
344 * Sets the metadata involved in the event.
345 *
346 * @param metadata The involved metadata, may be {@code null}.
347 * @return This event builder for chaining, never {@code null}.
348 */
349 public Builder setMetadata( Metadata metadata )
350 {
351 this.metadata = metadata;
352 return this;
353 }
354
355 /**
356 * Sets the repository involved in the event.
357 *
358 * @param repository The involved repository, may be {@code null}.
359 * @return This event builder for chaining, never {@code null}.
360 */
361 public Builder setRepository( ArtifactRepository repository )
362 {
363 this.repository = repository;
364 return this;
365 }
366
367 /**
368 * Sets the file involved in the event.
369 *
370 * @param file The involved file, may be {@code null}.
371 * @return This event builder for chaining, never {@code null}.
372 */
373 public Builder setFile( File file )
374 {
375 this.file = file;
376 return this;
377 }
378
379 /**
380 * Sets the exception causing the event.
381 *
382 * @param exception The exception causing the event, may be {@code null}.
383 * @return This event builder for chaining, never {@code null}.
384 */
385 public Builder setException( Exception exception )
386 {
387 if ( exception != null )
388 {
389 this.exceptions = Collections.singletonList( exception );
390 }
391 else
392 {
393 this.exceptions = Collections.emptyList();
394 }
395 return this;
396 }
397
398 /**
399 * Sets the exceptions causing the event.
400 *
401 * @param exceptions The exceptions causing the event, may be {@code null}.
402 * @return This event builder for chaining, never {@code null}.
403 */
404 public Builder setExceptions( List<Exception> exceptions )
405 {
406 if ( exceptions != null )
407 {
408 this.exceptions = exceptions;
409 }
410 else
411 {
412 this.exceptions = Collections.emptyList();
413 }
414 return this;
415 }
416
417 /**
418 * Sets the trace information about the request during which the event occurred.
419 *
420 * @param trace The trace information, may be {@code null}.
421 * @return This event builder for chaining, never {@code null}.
422 */
423 public Builder setTrace( RequestTrace trace )
424 {
425 this.trace = trace;
426 return this;
427 }
428
429 /**
430 * Builds a new event from the current values of this builder. The state of the builder itself remains
431 * unchanged.
432 *
433 * @return The event, never {@code null}.
434 */
435 public RepositoryEvent build()
436 {
437 return new RepositoryEvent( this );
438 }
439
440 }
441
442 }