1 package org.eclipse.aether.transfer;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 /**
23 * A listener being notified of artifact/metadata transfers from/to remote repositories. The listener may be called from
24 * an arbitrary thread. Reusing common regular expression syntax, the sequence of events is roughly as follows:
25 *
26 * <pre>
27 * INITIATED ( STARTED PROGRESSED* CORRUPTED? )* ( SUCCEEDED | FAILED )
28 * </pre>
29 *
30 * <em>Note:</em> Implementors are strongly advised to inherit from {@link AbstractTransferListener} instead of directly
31 * implementing this interface.
32 *
33 * @see org.eclipse.aether.RepositorySystemSession#getTransferListener()
34 * @see org.eclipse.aether.RepositoryListener
35 * @noimplement This interface is not intended to be implemented by clients.
36 * @noextend This interface is not intended to be extended by clients.
37 */
38 public interface TransferListener
39 {
40
41 /**
42 * Notifies the listener about the initiation of a transfer. This event gets fired before any actual network access
43 * to the remote repository and usually indicates some thread is now about to perform the transfer. For a given
44 * transfer request, this event is the first one being fired and it must be emitted exactly once.
45 *
46 * @param event The event details, must not be {@code null}.
47 * @throws TransferCancelledException If the transfer should be aborted.
48 */
49 void transferInitiated( TransferEvent event )
50 throws TransferCancelledException;
51
52 /**
53 * Notifies the listener about the start of a data transfer. This event indicates a successful connection to the
54 * remote repository. In case of a download, the requested remote resource exists and its size is given by
55 * {@link TransferResource#getContentLength()} if possible. This event may be fired multiple times for given
56 * transfer request if said transfer needs to be repeated (e.g. in response to an authentication challenge).
57 *
58 * @param event The event details, must not be {@code null}.
59 * @throws TransferCancelledException If the transfer should be aborted.
60 */
61 void transferStarted( TransferEvent event )
62 throws TransferCancelledException;
63
64 /**
65 * Notifies the listener about some progress in the data transfer. This event may even be fired if actually zero
66 * bytes have been transferred since the last event, for instance to enable cancellation.
67 *
68 * @param event The event details, must not be {@code null}.
69 * @throws TransferCancelledException If the transfer should be aborted.
70 */
71 void transferProgressed( TransferEvent event )
72 throws TransferCancelledException;
73
74 /**
75 * Notifies the listener that a checksum validation failed. {@link TransferEvent#getException()} will be of type
76 * {@link ChecksumFailureException} and can be used to query further details about the expected/actual checksums.
77 *
78 * @param event The event details, must not be {@code null}.
79 * @throws TransferCancelledException If the transfer should be aborted.
80 */
81 void transferCorrupted( TransferEvent event )
82 throws TransferCancelledException;
83
84 /**
85 * Notifies the listener about the successful completion of a transfer. This event must be fired exactly once for a
86 * given transfer request unless said request failed.
87 *
88 * @param event The event details, must not be {@code null}.
89 */
90 void transferSucceeded( TransferEvent event );
91
92 /**
93 * Notifies the listener about the unsuccessful termination of a transfer. {@link TransferEvent#getException()} will
94 * provide further information about the failure.
95 *
96 * @param event The event details, must not be {@code null}.
97 */
98 void transferFailed( TransferEvent event );
99
100 }