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