View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.eclipse.aether;
20  
21  /**
22   * A listener being notified of events from the repository system. In general, the system sends events upon termination
23   * of an operation like {@link #artifactResolved(RepositoryEvent)} regardless whether it succeeded or failed so
24   * listeners need to inspect the event details carefully. Also, the listener may be called from an arbitrary thread.
25   * <em>Note:</em> Implementors are strongly advised to inherit from {@link AbstractRepositoryListener} instead of
26   * directly implementing this interface.
27   *
28   * @see org.eclipse.aether.RepositorySystemSession#getRepositoryListener()
29   * @see org.eclipse.aether.transfer.TransferListener
30   * @noimplement This interface is not intended to be implemented by clients.
31   * @noextend This interface is not intended to be extended by clients.
32   */
33  public interface RepositoryListener {
34  
35      /**
36       * Notifies the listener of a syntactically or semantically invalid artifact descriptor.
37       * {@link RepositoryEvent#getArtifact()} indicates the artifact whose descriptor is invalid and
38       * {@link RepositoryEvent#getExceptions()} carries the encountered errors. Depending on the session's
39       * {@link org.eclipse.aether.resolution.ArtifactDescriptorPolicy}, the underlying repository operation might abort
40       * with an exception or ignore the invalid descriptor.
41       *
42       * @param event The event details, must not be {@code null}.
43       */
44      void artifactDescriptorInvalid(RepositoryEvent event);
45  
46      /**
47       * Notifies the listener of a missing artifact descriptor. {@link RepositoryEvent#getArtifact()} indicates the
48       * artifact whose descriptor is missing. Depending on the session's
49       * {@link org.eclipse.aether.resolution.ArtifactDescriptorPolicy}, the underlying repository operation might abort
50       * with an exception or ignore the missing descriptor.
51       *
52       * @param event The event details, must not be {@code null}.
53       */
54      void artifactDescriptorMissing(RepositoryEvent event);
55  
56      /**
57       * Notifies the listener of syntactically or semantically invalid metadata. {@link RepositoryEvent#getMetadata()}
58       * indicates the invalid metadata and {@link RepositoryEvent#getExceptions()} carries the encountered errors. The
59       * underlying repository operation might still succeed, depending on whether the metadata in question is actually
60       * needed to carry out the resolution process.
61       *
62       * @param event The event details, must not be {@code null}.
63       */
64      void metadataInvalid(RepositoryEvent event);
65  
66      /**
67       * Notifies the listener of an artifact that is about to be resolved. {@link RepositoryEvent#getArtifact()} denotes
68       * the artifact in question. Unlike the {@link #artifactDownloading(RepositoryEvent)} event, this event is fired
69       * regardless whether the artifact already exists locally or not.
70       *
71       * @param event The event details, must not be {@code null}.
72       */
73      void artifactResolving(RepositoryEvent event);
74  
75      /**
76       * Notifies the listener of an artifact whose resolution has been completed, either successfully or not.
77       * {@link RepositoryEvent#getArtifact()} denotes the artifact in question and
78       * {@link RepositoryEvent#getExceptions()} indicates whether the resolution succeeded or failed. Unlike the
79       * {@link #artifactDownloaded(RepositoryEvent)} event, this event is fired regardless whether the artifact already
80       * exists locally or not.
81       *
82       * @param event The event details, must not be {@code null}.
83       */
84      void artifactResolved(RepositoryEvent event);
85  
86      /**
87       * Notifies the listener of some metadata that is about to be resolved. {@link RepositoryEvent#getMetadata()}
88       * denotes the metadata in question. Unlike the {@link #metadataDownloading(RepositoryEvent)} event, this event is
89       * fired regardless whether the metadata already exists locally or not.
90       *
91       * @param event The event details, must not be {@code null}.
92       */
93      void metadataResolving(RepositoryEvent event);
94  
95      /**
96       * Notifies the listener of some metadata whose resolution has been completed, either successfully or not.
97       * {@link RepositoryEvent#getMetadata()} denotes the metadata in question and
98       * {@link RepositoryEvent#getExceptions()} indicates whether the resolution succeeded or failed. Unlike the
99       * {@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 }