001package org.eclipse.aether; 002 003/* 004 * Licensed to the Apache Software Foundation (ASF) under one 005 * or more contributor license agreements. See the NOTICE file 006 * distributed with this work for additional information 007 * regarding copyright ownership. The ASF licenses this file 008 * to you under the Apache License, Version 2.0 (the 009 * "License"); you may not use this file except in compliance 010 * with the License. You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, 015 * software distributed under the License is distributed on an 016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 017 * KIND, either express or implied. See the License for the 018 * specific language governing permissions and limitations 019 * under the License. 020 */ 021 022import java.io.File; 023import java.util.Collections; 024import java.util.List; 025import static java.util.Objects.requireNonNull; 026 027import org.eclipse.aether.artifact.Artifact; 028import org.eclipse.aether.metadata.Metadata; 029import org.eclipse.aether.repository.ArtifactRepository; 030 031/** 032 * An event describing an action performed by the repository system. Note that events which indicate the end of an 033 * action like {@link EventType#ARTIFACT_RESOLVED} are generally fired in both the success and the failure case. Use 034 * {@link #getException()} to check whether an event denotes success or failure. 035 * 036 * @see RepositoryListener 037 * @see RepositoryEvent.Builder 038 */ 039public final class RepositoryEvent 040{ 041 042 /** 043 * The type of the repository event. 044 */ 045 public enum EventType 046 { 047 048 /** 049 * @see RepositoryListener#artifactDescriptorInvalid(RepositoryEvent) 050 */ 051 ARTIFACT_DESCRIPTOR_INVALID, 052 053 /** 054 * @see RepositoryListener#artifactDescriptorMissing(RepositoryEvent) 055 */ 056 ARTIFACT_DESCRIPTOR_MISSING, 057 058 /** 059 * @see RepositoryListener#metadataInvalid(RepositoryEvent) 060 */ 061 METADATA_INVALID, 062 063 /** 064 * @see RepositoryListener#artifactResolving(RepositoryEvent) 065 */ 066 ARTIFACT_RESOLVING, 067 068 /** 069 * @see RepositoryListener#artifactResolved(RepositoryEvent) 070 */ 071 ARTIFACT_RESOLVED, 072 073 /** 074 * @see RepositoryListener#metadataResolving(RepositoryEvent) 075 */ 076 METADATA_RESOLVING, 077 078 /** 079 * @see RepositoryListener#metadataResolved(RepositoryEvent) 080 */ 081 METADATA_RESOLVED, 082 083 /** 084 * @see RepositoryListener#artifactDownloading(RepositoryEvent) 085 */ 086 ARTIFACT_DOWNLOADING, 087 088 /** 089 * @see RepositoryListener#artifactDownloaded(RepositoryEvent) 090 */ 091 ARTIFACT_DOWNLOADED, 092 093 /** 094 * @see RepositoryListener#metadataDownloading(RepositoryEvent) 095 */ 096 METADATA_DOWNLOADING, 097 098 /** 099 * @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}