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 final EventType type;
297
298 final 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 }