Method Details

• getTransferContext

  protected abstract TransferContext getTransferContext(T transferEvent)

  This method is used to get the transfer context from the transfer events (e.g. DownloadEvent).

  Parameters:

  transferEvent - the transfer event

  Returns:

  the transfer context

• addTransferProgressListener

  protected Registration addTransferProgressListener(TransferProgressListener listener)

  Adds a listener to be notified of data transfer progress events, such as:

  • TransferProgressListener.onStart(TransferContext)
  • TransferProgressListener.onProgress(TransferContext, long, long)
  • TransferProgressListener.onError(TransferContext, IOException)
  • TransferProgressListener.onComplete(TransferContext, long)

  The calls of the given listener's methods are wrapped by the UI.access(Command) to send UI changes defined here asynchronously when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

  Custom download/upload handler implementations can change this method to be public or use it in handler's constructor.

  Parameters:

  listener - progress listener to be added to this handler

  Returns:

  a Registration object that can be used to remove the added listener

• whenStart

  public R whenStart(SerializableRunnable startHandler)

  Adds a listener to be notified when the transfer starts.

  The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

  Parameters:

  startHandler - the handler to be called when the transfer starts

  Returns:

  this instance for method chaining

• whenStart

  public R whenStart(SerializableConsumer<TransferContext> startHandler)

  Adds a listener to be notified when the transfer starts that receives the transfer context as input.

  The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

  Parameters:

  startHandler - the handler to be called when the transfer starts

  Returns:

  this instance for method chaining

• onProgress

  public R onProgress(SerializableTriConsumer<TransferContext,Long,Long> progressHandler, long progressIntervalInBytes)

  Adds a listener to be notified of transfer progress with giving the transfer context object and with the given interval.

  The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

  Parameters:

  progressHandler - the handler to be called with the transfer context, current and total bytes

  progressIntervalInBytes - the interval in bytes for reporting progress

  Returns:

  this instance for method chaining

• onProgress

  public R onProgress(SerializableTriConsumer<TransferContext,Long,Long> progressHandler)

  Adds a listener to be notified of transfer progress with giving the transfer context object and with the default progress interval.

  The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

  Parameters:

  progressHandler - the handler to be called with the transfer context, current and total bytes

  Returns:

  this instance for method chaining

• onProgress

  public R onProgress(SerializableBiConsumer<Long,Long> progressHandler, long progressIntervalInBytes)

  Adds a listener to be notified of transfer progress with the given interval.

  The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

  Parameters:

  progressHandler - the handler to be called with the current and total bytes

  progressIntervalInBytes - the interval in bytes for reporting progress

  Returns:

  this instance for method chaining

• onProgress

  public R onProgress(SerializableBiConsumer<Long,Long> progressHandler)

  Adds a listener to be notified of transfer progress with a default interval.

  The first long parameter is the current number of bytes transferred, and the second is the total number of bytes.

  The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

  The default progress report internal is 65536 bytes. To change it, use onProgress(SerializableBiConsumer, long).

  Parameters:

  progressHandler - the handler to be called with the current and total bytes

  Returns:

  this instance for method chaining

• whenComplete

  public R whenComplete(SerializableConsumer<Boolean> completeOrTerminateHandler)

  Adds a listener to be notified when the transfer is completed successfully or with an error.

  Gives a Boolean indicating whether the transfer was completed successfully (true) or not (false).

  The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

  Parameters:

  completeOrTerminateHandler - the handler to be called when the transfer is completed

  Returns:

  this instance for method chaining

• whenComplete

  public R whenComplete(SerializableBiConsumer<TransferContext,Boolean> completeOrTerminateHandler)

  Adds a listener to be notified when the transfer is completed successfully or with an error with the transfer context object given as an input.

  Gives a Boolean indicating whether the transfer was completed successfully (true) or not (false) and transfer context to obtain more meta-data.

  The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

  Parameters:

  completeOrTerminateHandler - the handler to be called when the transfer is completed

  Returns:

  this instance for method chaining

• getListeners

  protected List<TransferProgressListener> getListeners()

  Get the listeners that are registered to this handler.

  For the custom data transfer implementation, one may need to notify listeners manually. This method can be used like getListeners().forEach(listener -> listener.onStart(getTransferContext(event))).

  The listeners are kept in order of registration.

  Returns:

  a list of listeners that are registered to this handler

• notifyError

  protected void notifyError(T transferEvent, IOException ioe)

  Notifies all registered listeners about an error that occurred during a data transfer operation.

  Custom download/upload handler implementations can use this method to notify listeners in the catch block, e.g.:

   try () {
       // handler download/upload request
   } catch (IOException ioe) {
       // process the error
       notifyError(event, ioe);
       throw ioe;
   }
   

  Parameters:

  transferEvent - the meta-data associated with the operation where the error occurred

  ioe - the exception that describes the error