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 }