1 package org.sonatype.aether.transfer;
2
3 /*******************************************************************************
4 * Copyright (c) 2010-2011 Sonatype, Inc.
5 * All rights reserved. This program and the accompanying materials
6 * are made available under the terms of the Eclipse Public License v1.0
7 * which accompanies this distribution, and is available at
8 * http://www.eclipse.org/legal/epl-v10.html
9 *******************************************************************************/
10
11 import java.nio.ByteBuffer;
12
13 /**
14 * An event fired to a transfer listener during an artifact/metadata transfer.
15 *
16 * @author Benjamin Bentmann
17 * @see TransferListener
18 */
19 public interface TransferEvent
20 {
21
22 /**
23 * The type of the event.
24 */
25 enum EventType
26 {
27 INITIATED, STARTED, PROGRESSED, CORRUPTED, SUCCEEDED, FAILED
28 }
29
30 /**
31 * The type of the request/transfer.
32 */
33 enum RequestType
34 {
35 GET, PUT,
36 }
37
38 /**
39 * Gets the type of the event.
40 *
41 * @return The type of the event, never {@code null}.
42 */
43 EventType getType();
44
45 /**
46 * Gets the type of the request/transfer.
47 *
48 * @return The type of the request/transfer, never {@code null}.
49 */
50 RequestType getRequestType();
51
52 /**
53 * Gets the resource that is being transferred.
54 *
55 * @return The resource being transferred, never {@code null}.
56 */
57 TransferResource getResource();
58
59 /**
60 * Gets the total number of bytes that have been transferred since the download/upload was started.
61 *
62 * @return The total number of bytes that have been transferred since the transfer started, never negative.
63 * @see #getDataLength()
64 */
65 long getTransferredBytes();
66
67 /**
68 * Gets the byte buffer holding the transferred bytes since the last event. A listener must assume this buffer to be
69 * owned by the event source and must not change any byte in this buffer. Also, the buffer is only valid for the
70 * duration of the event callback, i.e. the next event might reuse the same buffer (with updated contents).
71 * Therefore, if the actual event processing is deferred, the byte buffer would have to be cloned to create an
72 * immutable snapshot of its contents.
73 *
74 * @return The (read-only) byte buffer or {@code null} if not applicable to the event, i.e. if the event type is not
75 * {@link EventType#PROGRESSED}.
76 */
77 ByteBuffer getDataBuffer();
78
79 /**
80 * Gets the number of bytes that have been transferred since the last event.
81 *
82 * @return The number of bytes that have been transferred since the last event, possibly zero but never negative.
83 * @see #getTransferredBytes()
84 */
85 int getDataLength();
86
87 /**
88 * Gets the error that occurred during the transfer.
89 *
90 * @return The error that occurred or {@code null} if none.
91 */
92 Exception getException();
93
94 }