1 /*******************************************************************************
2 * Copyright (c) 2010, 2013 Sonatype, Inc.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
9 * Sonatype, Inc. - initial API and implementation
10 *******************************************************************************/
11 package org
.eclipse
.aether
.transfer
;
13 import java
.nio
.ByteBuffer
;
15 import org
.eclipse
.aether
.RepositorySystemSession
;
18 * An event fired to a transfer listener during an artifact/metadata transfer.
20 * @see TransferListener
21 * @see TransferEvent.Builder
23 public final class TransferEvent
27 * The type of the event.
33 * @see TransferListener#transferInitiated(TransferEvent)
38 * @see TransferListener#transferStarted(TransferEvent)
43 * @see TransferListener#transferProgressed(TransferEvent)
48 * @see TransferListener#transferCorrupted(TransferEvent)
53 * @see TransferListener#transferSucceeded(TransferEvent)
58 * @see TransferListener#transferFailed(TransferEvent)
65 * The type of the request/transfer being performed.
67 public enum RequestType
71 * Download artifact/metadata.
76 * Check artifact/metadata existence only.
81 * Upload artifact/metadata.
87 private final EventType type
;
89 private final RequestType requestType
;
91 private final RepositorySystemSession session
;
93 private final TransferResource resource
;
95 private final ByteBuffer dataBuffer
;
97 private final long transferredBytes
;
99 private final Exception exception
;
101 TransferEvent( Builder builder
)
104 requestType
= builder
.requestType
;
105 session
= builder
.session
;
106 resource
= builder
.resource
;
107 dataBuffer
= builder
.dataBuffer
;
108 transferredBytes
= builder
.transferredBytes
;
109 exception
= builder
.exception
;
113 * Gets the type of the event.
115 * @return The type of the event, never {@code null}.
117 public EventType
getType()
123 * Gets the type of the request/transfer.
125 * @return The type of the request/transfer, never {@code null}.
127 public RequestType
getRequestType()
133 * Gets the repository system session during which the event occurred.
135 * @return The repository system session during which the event occurred, never {@code null}.
137 public RepositorySystemSession
getSession()
143 * Gets the resource that is being transferred.
145 * @return The resource being transferred, never {@code null}.
147 public TransferResource
getResource()
153 * Gets the total number of bytes that have been transferred since the download/upload of the resource was started.
154 * If a download has been resumed, the returned count includes the bytes that were already downloaded during the
155 * previous attempt. In other words, the ratio of transferred bytes to the content length of the resource indicates
156 * the percentage of transfer completion.
158 * @return The total number of bytes that have been transferred since the transfer started, never negative.
159 * @see #getDataLength()
160 * @see TransferResource#getResumeOffset()
162 public long getTransferredBytes()
164 return transferredBytes
;
168 * Gets the byte buffer holding the transferred bytes since the last event. A listener must assume this buffer to be
169 * owned by the event source and must not change any byte in this buffer. Also, the buffer is only valid for the
170 * duration of the event callback, i.e. the next event might reuse the same buffer (with updated contents).
171 * Therefore, if the actual event processing is deferred, the byte buffer would have to be cloned to create an
172 * immutable snapshot of its contents.
174 * @return The (read-only) byte buffer or {@code null} if not applicable to the event, i.e. if the event type is not
175 * {@link EventType#PROGRESSED}.
177 public ByteBuffer
getDataBuffer()
179 return ( dataBuffer
!= null ) ? dataBuffer
.asReadOnlyBuffer() : null;
183 * Gets the number of bytes that have been transferred since the last event.
185 * @return The number of bytes that have been transferred since the last event, possibly zero but never negative.
186 * @see #getTransferredBytes()
188 public int getDataLength()
190 return ( dataBuffer
!= null ) ? dataBuffer
.remaining() : 0;
194 * Gets the error that occurred during the transfer.
196 * @return The error that occurred or {@code null} if none.
198 public Exception
getException()
204 public String
toString()
206 return getRequestType() + " " + getType() + " " + getResource();
210 * A builder to create transfer events.
212 public static final class Builder
217 RequestType requestType
;
219 RepositorySystemSession session
;
221 TransferResource resource
;
223 ByteBuffer dataBuffer
;
225 long transferredBytes
;
230 * Creates a new transfer event builder for the specified session and the given resource.
232 * @param session The repository system session, must not be {@code null}.
233 * @param resource The resource being transferred, must not be {@code null}.
235 public Builder( RepositorySystemSession session
, TransferResource resource
)
237 if ( session
== null )
239 throw new IllegalArgumentException( "session not specified" );
241 if ( resource
== null )
243 throw new IllegalArgumentException( "transfer resource not specified" );
245 this.session
= session
;
246 this.resource
= resource
;
247 type
= EventType
.INITIATED
;
248 requestType
= RequestType
.GET
;
251 private Builder( Builder prototype
)
253 session
= prototype
.session
;
254 resource
= prototype
.resource
;
255 type
= prototype
.type
;
256 requestType
= prototype
.requestType
;
257 dataBuffer
= prototype
.dataBuffer
;
258 transferredBytes
= prototype
.transferredBytes
;
259 exception
= prototype
.exception
;
263 * Creates a new transfer event builder from the current values of this builder. The state of this builder
266 * @return The new event builder, never {@code null}.
268 public Builder
copy()
270 return new Builder( this );
274 * Sets the type of the event and resets event-specific fields. In more detail, the data buffer and the
275 * exception fields are set to {@code null}. Furthermore, the total number of transferred bytes is set to
276 * {@code 0} if the event type is {@link EventType#STARTED}.
278 * @param type The type of the event, must not be {@code null}.
279 * @return This event builder for chaining, never {@code null}.
281 public Builder
resetType( EventType type
)
285 throw new IllegalArgumentException( "event type not specified" );
294 transferredBytes
= 0;
301 * Sets the type of the event. When re-using the same builder to generate a sequence of events for one transfer,
302 * {@link #resetType(TransferEvent.EventType)} might be more handy.
304 * @param type The type of the event, must not be {@code null}.
305 * @return This event builder for chaining, never {@code null}.
307 public Builder
setType( EventType type
)
311 throw new IllegalArgumentException( "event type not specified" );
318 * Sets the type of the request/transfer.
320 * @param requestType The request/transfer type, must not be {@code null}.
321 * @return This event builder for chaining, never {@code null}.
323 public Builder
setRequestType( RequestType requestType
)
325 if ( requestType
== null )
327 throw new IllegalArgumentException( "request type not specified" );
329 this.requestType
= requestType
;
334 * Sets the total number of bytes that have been transferred so far during the download/upload of the resource.
335 * If a download is being resumed, the count must include the bytes that were already downloaded in the previous
336 * attempt and from which the current transfer started. In this case, the event type {@link EventType#STARTED}
337 * should indicate from what byte the download resumes.
339 * @param transferredBytes The total number of bytes that have been transferred so far during the
340 * download/upload of the resource, must not be negative.
341 * @return This event builder for chaining, never {@code null}.
342 * @see TransferResource#setResumeOffset(long)
344 public Builder
setTransferredBytes( long transferredBytes
)
346 if ( transferredBytes
< 0 )
348 throw new IllegalArgumentException( "number of transferred bytes cannot be negative" );
350 this.transferredBytes
= transferredBytes
;
355 * Increments the total number of bytes that have been transferred so far during the download/upload.
357 * @param transferredBytes The number of bytes that have been transferred since the last event, must not be
359 * @return This event builder for chaining, never {@code null}.
361 public Builder
addTransferredBytes( long transferredBytes
)
363 if ( transferredBytes
< 0 )
365 throw new IllegalArgumentException( "number of transferred bytes cannot be negative" );
367 this.transferredBytes
+= transferredBytes
;
372 * Sets the byte buffer holding the transferred bytes since the last event.
374 * @param buffer The byte buffer holding the transferred bytes since the last event, may be {@code null} if not
375 * applicable to the event.
376 * @param offset The starting point of valid bytes in the array.
377 * @param length The number of valid bytes, must not be negative.
378 * @return This event builder for chaining, never {@code null}.
380 public Builder
setDataBuffer( byte[] buffer
, int offset
, int length
)
382 return setDataBuffer( ( buffer
!= null ) ? ByteBuffer
.wrap( buffer
, offset
, length
) : null );
386 * Sets the byte buffer holding the transferred bytes since the last event.
388 * @param dataBuffer The byte buffer holding the transferred bytes since the last event, may be {@code null} if
389 * not applicable to the event.
390 * @return This event builder for chaining, never {@code null}.
392 public Builder
setDataBuffer( ByteBuffer dataBuffer
)
394 this.dataBuffer
= dataBuffer
;
399 * Sets the error that occurred during the transfer.
401 * @param exception The error that occurred during the transfer, may be {@code null} if none.
402 * @return This event builder for chaining, never {@code null}.
404 public Builder
setException( Exception exception
)
406 this.exception
= exception
;
411 * Builds a new transfer event from the current values of this builder. The state of the builder itself remains
414 * @return The transfer event, never {@code null}.
416 public TransferEvent
build()
418 return new TransferEvent( this );