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.transfer; 20 21 /** 22 * A listener being notified of artifact/metadata transfers from/to remote repositories. The listener may be called from 23 * an arbitrary thread. Reusing common regular expression syntax, the sequence of events is roughly as follows: 24 * 25 * <pre> 26 * INITIATED ( STARTED PROGRESSED* CORRUPTED? )* ( SUCCEEDED | FAILED ) 27 * </pre> 28 * 29 * <em>Note:</em> Implementors are strongly advised to inherit from {@link AbstractTransferListener} instead of directly 30 * implementing this interface. 31 * 32 * @see org.eclipse.aether.RepositorySystemSession#getTransferListener() 33 * @see org.eclipse.aether.RepositoryListener 34 * @noimplement This interface is not intended to be implemented by clients. 35 * @noextend This interface is not intended to be extended by clients. 36 */ 37 public interface TransferListener { 38 39 /** 40 * Notifies the listener about the initiation of a transfer. This event gets fired before any actual network access 41 * to the remote repository and usually indicates some thread is now about to perform the transfer. For a given 42 * transfer request, this event is the first one being fired and it must be emitted exactly once. 43 * 44 * @param event The event details, must not be {@code null}. 45 * @throws TransferCancelledException If the transfer should be aborted. 46 */ 47 void transferInitiated(TransferEvent event) throws TransferCancelledException; 48 49 /** 50 * Notifies the listener about the start of a data transfer. This event indicates a successful connection to the 51 * remote repository. In case of a download, the requested remote resource exists and its size is given by 52 * {@link TransferResource#getContentLength()} if possible. This event may be fired multiple times for given 53 * transfer request if said transfer needs to be repeated (e.g. in response to an authentication challenge). 54 * 55 * @param event The event details, must not be {@code null}. 56 * @throws TransferCancelledException If the transfer should be aborted. 57 */ 58 void transferStarted(TransferEvent event) throws TransferCancelledException; 59 60 /** 61 * Notifies the listener about some progress in the data transfer. This event may even be fired if actually zero 62 * bytes have been transferred since the last event, for instance to enable cancellation. 63 * 64 * @param event The event details, must not be {@code null}. 65 * @throws TransferCancelledException If the transfer should be aborted. 66 */ 67 void transferProgressed(TransferEvent event) throws TransferCancelledException; 68 69 /** 70 * Notifies the listener that a checksum validation failed. {@link TransferEvent#getException()} will be of type 71 * {@link ChecksumFailureException} and can be used to query further details about the expected/actual checksums. 72 * 73 * @param event The event details, must not be {@code null}. 74 * @throws TransferCancelledException If the transfer should be aborted. 75 */ 76 void transferCorrupted(TransferEvent event) throws TransferCancelledException; 77 78 /** 79 * Notifies the listener about the successful completion of a transfer. This event must be fired exactly once for a 80 * given transfer request unless said request failed. 81 * 82 * @param event The event details, must not be {@code null}. 83 */ 84 void transferSucceeded(TransferEvent event); 85 86 /** 87 * Notifies the listener about the unsuccessful termination of a transfer. {@link TransferEvent#getException()} will 88 * provide further information about the failure. 89 * 90 * @param event The event details, must not be {@code null}. 91 */ 92 void transferFailed(TransferEvent event); 93 }