org.argeo.slc.repo/src/org/eclipse/aether/RepositoryEvent.java

   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 }