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}