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
022/**
023 * A listener being notified of events from the repository system. In general, the system sends events upon termination
024 * of an operation like {@link #artifactResolved(RepositoryEvent)} regardless whether it succeeded or failed so
025 * listeners need to inspect the event details carefully. Also, the listener may be called from an arbitrary thread.
026 * <em>Note:</em> Implementors are strongly advised to inherit from {@link AbstractRepositoryListener} instead of
027 * directly implementing this interface.
028 * 
029 * @see org.eclipse.aether.RepositorySystemSession#getRepositoryListener()
030 * @see org.eclipse.aether.transfer.TransferListener
031 * @noimplement This interface is not intended to be implemented by clients.
032 * @noextend This interface is not intended to be extended by clients.
033 */
034public interface RepositoryListener
035{
036
037    /**
038     * Notifies the listener of a syntactically or semantically invalid artifact descriptor.
039     * {@link RepositoryEvent#getArtifact()} indicates the artifact whose descriptor is invalid and
040     * {@link RepositoryEvent#getExceptions()} carries the encountered errors. Depending on the session's
041     * {@link org.eclipse.aether.resolution.ArtifactDescriptorPolicy}, the underlying repository operation might abort
042     * with an exception or ignore the invalid descriptor.
043     * 
044     * @param event The event details, must not be {@code null}.
045     */
046    void artifactDescriptorInvalid( RepositoryEvent event );
047
048    /**
049     * Notifies the listener of a missing artifact descriptor. {@link RepositoryEvent#getArtifact()} indicates the
050     * artifact whose descriptor is missing. Depending on the session's
051     * {@link org.eclipse.aether.resolution.ArtifactDescriptorPolicy}, the underlying repository operation might abort
052     * with an exception or ignore the missing descriptor.
053     * 
054     * @param event The event details, must not be {@code null}.
055     */
056    void artifactDescriptorMissing( RepositoryEvent event );
057
058    /**
059     * Notifies the listener of syntactically or semantically invalid metadata. {@link RepositoryEvent#getMetadata()}
060     * indicates the invalid metadata and {@link RepositoryEvent#getExceptions()} carries the encountered errors. The
061     * underlying repository operation might still succeed, depending on whether the metadata in question is actually
062     * needed to carry out the resolution process.
063     * 
064     * @param event The event details, must not be {@code null}.
065     */
066    void metadataInvalid( RepositoryEvent event );
067
068    /**
069     * Notifies the listener of an artifact that is about to be resolved. {@link RepositoryEvent#getArtifact()} denotes
070     * the artifact in question. Unlike the {@link #artifactDownloading(RepositoryEvent)} event, this event is fired
071     * regardless whether the artifact already exists locally or not.
072     * 
073     * @param event The event details, must not be {@code null}.
074     */
075    void artifactResolving( RepositoryEvent event );
076
077    /**
078     * Notifies the listener of an artifact whose resolution has been completed, either successfully or not.
079     * {@link RepositoryEvent#getArtifact()} denotes the artifact in question and
080     * {@link RepositoryEvent#getExceptions()} indicates whether the resolution succeeded or failed. Unlike the
081     * {@link #artifactDownloaded(RepositoryEvent)} event, this event is fired regardless whether the artifact already
082     * exists locally or not.
083     * 
084     * @param event The event details, must not be {@code null}.
085     */
086    void artifactResolved( RepositoryEvent event );
087
088    /**
089     * Notifies the listener of some metadata that is about to be resolved. {@link RepositoryEvent#getMetadata()}
090     * denotes the metadata in question. Unlike the {@link #metadataDownloading(RepositoryEvent)} event, this event is
091     * fired regardless whether the metadata already exists locally or not.
092     * 
093     * @param event The event details, must not be {@code null}.
094     */
095    void metadataResolving( RepositoryEvent event );
096
097    /**
098     * Notifies the listener of some metadata whose resolution has been completed, either successfully or not.
099     * {@link RepositoryEvent#getMetadata()} denotes the metadata in question and
100     * {@link RepositoryEvent#getExceptions()} indicates whether the resolution succeeded or failed. Unlike the
101     * {@link #metadataDownloaded(RepositoryEvent)} event, this event is fired regardless whether the metadata already
102     * exists locally or not.
103     * 
104     * @param event The event details, must not be {@code null}.
105     */
106    void metadataResolved( RepositoryEvent event );
107
108    /**
109     * Notifies the listener of an artifact that is about to be downloaded from a remote repository.
110     * {@link RepositoryEvent#getArtifact()} denotes the artifact in question and
111     * {@link RepositoryEvent#getRepository()} the source repository. Unlike the
112     * {@link #artifactResolving(RepositoryEvent)} event, this event is only fired when the artifact does not already
113     * exist locally.
114     * 
115     * @param event The event details, must not be {@code null}.
116     */
117    void artifactDownloading( RepositoryEvent event );
118
119    /**
120     * Notifies the listener of an artifact whose download has been completed, either successfully or not.
121     * {@link RepositoryEvent#getArtifact()} denotes the artifact in question and
122     * {@link RepositoryEvent#getExceptions()} indicates whether the download succeeded or failed. Unlike the
123     * {@link #artifactResolved(RepositoryEvent)} event, this event is only fired when the artifact does not already
124     * exist locally.
125     * 
126     * @param event The event details, must not be {@code null}.
127     */
128    void artifactDownloaded( RepositoryEvent event );
129
130    /**
131     * Notifies the listener of some metadata that is about to be downloaded from a remote repository.
132     * {@link RepositoryEvent#getMetadata()} denotes the metadata in question and
133     * {@link RepositoryEvent#getRepository()} the source repository. Unlike the
134     * {@link #metadataResolving(RepositoryEvent)} event, this event is only fired when the metadata does not already
135     * exist locally.
136     * 
137     * @param event The event details, must not be {@code null}.
138     */
139    void metadataDownloading( RepositoryEvent event );
140
141    /**
142     * Notifies the listener of some metadata whose download has been completed, either successfully or not.
143     * {@link RepositoryEvent#getMetadata()} denotes the metadata in question and
144     * {@link RepositoryEvent#getExceptions()} indicates whether the download succeeded or failed. Unlike the
145     * {@link #metadataResolved(RepositoryEvent)} event, this event is only fired when the metadata does not already
146     * exist locally.
147     * 
148     * @param event The event details, must not be {@code null}.
149     */
150    void metadataDownloaded( RepositoryEvent event );
151
152    /**
153     * Notifies the listener of an artifact that is about to be installed to the local repository.
154     * {@link RepositoryEvent#getArtifact()} denotes the artifact in question.
155     * 
156     * @param event The event details, must not be {@code null}.
157     */
158    void artifactInstalling( RepositoryEvent event );
159
160    /**
161     * Notifies the listener of an artifact whose installation to the local repository has been completed, either
162     * successfully or not. {@link RepositoryEvent#getArtifact()} denotes the artifact in question and
163     * {@link RepositoryEvent#getExceptions()} indicates whether the installation succeeded or failed.
164     * 
165     * @param event The event details, must not be {@code null}.
166     */
167    void artifactInstalled( RepositoryEvent event );
168
169    /**
170     * Notifies the listener of some metadata that is about to be installed to the local repository.
171     * {@link RepositoryEvent#getMetadata()} denotes the metadata in question.
172     * 
173     * @param event The event details, must not be {@code null}.
174     */
175    void metadataInstalling( RepositoryEvent event );
176
177    /**
178     * Notifies the listener of some metadata whose installation to the local repository has been completed, either
179     * successfully or not. {@link RepositoryEvent#getMetadata()} denotes the metadata in question and
180     * {@link RepositoryEvent#getExceptions()} indicates whether the installation succeeded or failed.
181     * 
182     * @param event The event details, must not be {@code null}.
183     */
184    void metadataInstalled( RepositoryEvent event );
185
186    /**
187     * Notifies the listener of an artifact that is about to be uploaded to a remote repository.
188     * {@link RepositoryEvent#getArtifact()} denotes the artifact in question and
189     * {@link RepositoryEvent#getRepository()} the destination repository.
190     * 
191     * @param event The event details, must not be {@code null}.
192     */
193    void artifactDeploying( RepositoryEvent event );
194
195    /**
196     * Notifies the listener of an artifact whose upload to a remote repository has been completed, either successfully
197     * or not. {@link RepositoryEvent#getArtifact()} denotes the artifact in question and
198     * {@link RepositoryEvent#getExceptions()} indicates whether the upload succeeded or failed.
199     * 
200     * @param event The event details, must not be {@code null}.
201     */
202    void artifactDeployed( RepositoryEvent event );
203
204    /**
205     * Notifies the listener of some metadata that is about to be uploaded to a remote repository.
206     * {@link RepositoryEvent#getMetadata()} denotes the metadata in question and
207     * {@link RepositoryEvent#getRepository()} the destination repository.
208     * 
209     * @param event The event details, must not be {@code null}.
210     */
211    void metadataDeploying( RepositoryEvent event );
212
213    /**
214     * Notifies the listener of some metadata whose upload to a remote repository has been completed, either
215     * successfully or not. {@link RepositoryEvent#getMetadata()} denotes the metadata in question and
216     * {@link RepositoryEvent#getExceptions()} indicates whether the upload succeeded or failed.
217     * 
218     * @param event The event details, must not be {@code null}.
219     */
220    void metadataDeployed( RepositoryEvent event );
221
222}